> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 2. Fetch and Manage Tokens

> Retrieve tokens using Razorpay APIs to create subsequent payments.

Available in
🇮🇳 India
🇲🇾 Malaysia
🇸🇬 Singapore
🇺🇸 United States

Once you capture a payment, Razorpay Checkout returns a `razorpay_payment_id`. You can use this id to fetch the `token_id`, which is used to create and charge subsequent payments.

You can retrieve the `token_id` using the [Dashboard](https://razorpay.com/docs/my/payments/recurring-payments/create.md#3-search-for-the-token) or the APIs given below.

Know more about [Tokens](https://razorpay.com/docs/my/payments/recurring-payments/cards/integrate.md#2-fetch-card-mandate-registration-details).

## 2.1. Fetch Token by Payment ID

The following endpoint fetches a token id using the Payment id.

`GET /payments/:id`

```bash Curl theme={null}
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET https://api.razorpay.com/v1/payments/pay_1Aa00000000001
  
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String paymentId = "pay_1Aa00000000001";

Payment payment = razorpay.payments.fetch(paymentId)
```

```php PHP theme={null}
$api = new Api($key_id, $secret);

$api->payment->fetch($paymentId);
```

```javascript Node.js theme={null}
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.fetch(paymentId)
```

```python Python theme={null}
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.fetch(paymentId)
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

paymentId = "pay_1Aa00000000001"

Razorpay::Payment.fetch(paymentId)
```

```go Go theme={null}
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Payment.Fetch("<paymentId>", nil, nil)
```

```csharp .NET theme={null}
RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

string paymentId = "pay_Z6t7VFTb9xHeOs";

Payment payment = client.Payment.Fetch(paymentId);
```

```json Response theme={null}
{
  "id": "pay_FHfqtkRzWvxky4",
  "entity": "payment",
  "amount": 100,
  "currency": "MYR",
  "status": "captured",
  "order_id": "order_FHfnswDdfu96HQ",
  "invoice_id": null,
  "international": false,
  "method": "card",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": true,
  "description": null,
  "card_id": "card_F0zoXUp4IPPGoI",
  "bank": null,
  "wallet": null,
  "vpa": null,
  "email": "<email>",
  "contact": "<phone>",
  "customer_id": "cust_DtHaBuooGHTuyZ",
  "token_id": "token_FHfn3rIiM1Z8nr",
  "notes": {
    "note_key 1": "Beam me up Scotty",
    "note_key 2": "Tea. Earl Gray. Hot."
  },
  "fee": 0,
  "tax": 0,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "acquirer_data": {
    "auth_code": "541898"
  },
  "created_at": 1595449871
}
```

> [!NOTE]
>
> **Handy Tips**
>
> You can also retrieve the `token_id` from the [payment.authorized webhook](https://razorpay.com/docs/my/api/payments/recurring-payments/webhooks.md#payment-authorized).

> [accordion] Path Parameter
>
> `id` *mandatory*
> : `string` The unique identifier of the payment to be retrieved. For example, `pay_1Aa00000000002`.

> [accordion] Response Parameters
>
> `id`
> : `string` Unique identifier of the payment.
>
> `entity`
> : `string` Indicates the type of entity. Here, it is `payment`.
>
> `amount`
> : `integer` The payment amount represented in smallest unit of the currency passed. For example, `amount = 100` translates to `100` subunits, that is ₹1.
>
> `currency`
> : `string` The currency in which the payment is made.
>
> `status`
> : `string` The status of the payment. Possible values:
>
> * `created`
> * `authorized`
> * `captured`
> * `refunded`
> * `failed`
>
> `order_id`
> : `string` The unique identifier of the order.
>
> `invoice_id`
> : `string` The unique identifier of the invoice.
>
> `international`
> : `boolean` Indicates whether the payment is done via an international card or a domestic one. Possible values:
>
> * `true`: Payment made using international card.
> * `false`: Payment not made using international card.
>
> `method`
> : `string` The payment method used for making the payment. Possible values:
>
> * `card`
> * `wallet`
>
> `amount_refunded`
> : `integer` The amount refunded in smallest unit of the currency passed.
>
> `refund_status`
> : `string` The refund status of the payment. Possible values:
>
> * `null`
> * `partial`
> * `full`
>
> `captured`
> : `boolean` Indicates if the payment is captured. Possible values:
>
> * `true`: Payment has been captured.
> * `false`: Payment has not been captured.
>
> `description`
> : `string` Description of the payment, if any.
>
> `email`
> : `string` Customer email address used for the payment.
>
> `contact`
> : `integer` Customer contact number used for the payment.
>
> `customer_id`
> : `string` The unique identifier of the customer.
>
> `token_id`
> : `string` The unique identifier of the token.
>
> `notes`
> : `json object` Contains user-defined fields, stored for reference purposes.
>
> `fee`
> : `integer` Fee charged by Razorpay Curlec.
>
> `error_code`
> : `string` Error that occurred during payment. For example, `BAD_REQUEST_ERROR`.
>
> `error_description`
> : `string` Description of the error that occurred during payment. For example, `Payment processing failed because of incorrect OTP`.
>
> `error_source`
> : `string` The point of failure. For example, `customer`.
>
> `error_step`
> : `string` The stage where the transaction failure occurred. The stages can vary depending on the payment method used to complete the transaction. For example, `payment_authentication`.
>
> `error_reason`
> : `string` The exact error reason. For example, `incorrect_otp`.
>
> `created_at`
> : `integer` Timestamp, in UNIX format, on which the payment was created.

## 2.2. Fetch All Tokens by Customer ID

A customer can have multiple tokens and these tokens can be used to create subsequent payments for multiple products or services. The following endpoint fetches tokens linked to a customer.

> [!WARNING]
>
> **Watch Out!**
>
> This endpoint will not fetch the details of expired, rejected and unused tokens.

`GET /customers/:id/tokens`

```bash Curl theme={null}
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_DtHaBuooGHTuyZ";

List<Customer> customer = razorpay.customers.fetchTokens(customerId);
```

```php PHP theme={null}
$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)->tokens()->all();
```

```javascript Node.js theme={null}
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customer.fetchTokens(customerId)
```

```python Python theme={null}
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.all(customerId)
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000002"

Razorpay::Customer.fetch(customerId).fetchTokens
```

```go Go theme={null}
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Token.All("<customerId>", nil, nil)
```

```csharp .NET theme={null}
RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

string customerId = "cust_Z6t7VFTb9xHeOs";

List<Token> token = client.Customer.Fetch(customerId).Tokens();
```

```json Response theme={null}
{
   "entity":"collection",
   "count":1,
   "items":[
      {
         "id":"token_HouA2OQR5Z2jTL",
         "entity":"token",
         "token":"testtoken00001",
         "bank":null,
         "wallet":null,
         "method":"card",
         "card":{
            "entity":"card",
            "name":"<name>",
            "last4":"8950",
            "network":"Visa",
            "type":"credit",
            "issuer":"STCB",
            "international":false,
            "emi":false,
            "sub_type":"consumer",
            "expiry_month":12,
            "expiry_year":2030,
            "flows":{
               "otp":true,
               "recurring":true
            }
         },
         "recurring":true,
         "recurring_details":{
            "status":"confirmed",
            "failure_reason":null
         },
         "auth_type":null,
         "mrn":null,
         "used_at":1629779657,
         "created_at":1629779657,
         "expired_at":1640975399,
         "dcc_enabled":false,
         "billing_address":null
      }
   ]
}
```

> [accordion] Path Parameter
>
> `id` *mandatory*
> : `string` The unique identifier of the customer for whom tokens are to be retrieved. For example, `cust_1Aa00000000002`.

> [accordion] Response Parameters
>
> `entity`
> : `string` The entity being created. Here, it is a `collection`.
>
> `count`
> : `integer` The number of tokens to be fetched.
>
> `items`
> : `object` Details related to token such as `token id` and bank information.
>
> `id`
> : `string` The unique identifier linked to an item. In this example, it is `token_id`.
>
> `entity`
> : `string` The entity being created. Here, it is a `token`.
>
> `token`
> : `string` The token is being fetched.
>
> `bank`
> : `string` Card issuing bank details.
>
> `wallet`
> : `string` Provides wallet information.
>
> `method`
> : `string` The payment method used to make the transaction.
>
> `card`
> : `object` Details related to card used to make the transaction.
>
> `entity`
> : `string` The entity being created. Here, it is `card`.
>
> `name`
> : `string` Name of the cardholder.
>
> `last4`
> : `integer` Last 4 digits of the card.
>
> `network`
> : `string` Name of the payment processor. Here it is `Visa`.
>
> `type`
> : `string` Card type (debit or credit). In this example, it is `credit`.
>
> `issuer`
> : `string` Name of the card-issuing bank.
>
> `international`
> : `boolean` Card usage restriction. Possible values:
>
> * `true`: Supports international transactions.
> * `false`: International transactions are not supported.
>
> `emi`
> : `string` Card EMI status. Possible values.
>
> * `true`: The card is on EMI.
> * `false`: The card is not on EMI.
>
> `sub_type`
> : `string` Type of the customer.
>
> `expiry_month`
> : `integer` Month on which the card expires.
>
> `expiry_year`
> : `integer` Year on which the card expires.
>
> `flows`
> : `object` The transaction flow details.
>
> `otp`
> : `string` Whether the OTP function is enabled or not. Possible values:
>
> * `true`: The OTP function is enabled.
> * `false`: The OTP function is not enabled.
>
> `recurring`
> : `string` Whether the recurring for this payment method is enabled or not. Possible Values:
>
> * `true`: Recurring is enabled.
> * `false`: Recurring is not enabled.
>
> `recurring`
> : `string` This represents whether recurring is enabled for this token. Possible values:
>
> * `true`: Recurring is enabled.
> * `false`: Recurring is not enabled.
>
> `recurring_details`
> : `object` Details of the recurring transaction.
>
> `status`
> : `string` This represents the status of the recurring transaction. Possible values:
>
> * `initiated`
> * `confirmed`
> * `rejected`
> * `cancelled`
> * `paused`
>
> `failure_reason`
> : `string` This provides the reason why the recurring transaction failed.
>
> `auth_type`
> : `string` The authorisation type details.
>
> `mrn`
> : `string` The unique identifier issued by the payment gateway during customer registration. This can be Gateway Reference Number or Gateway Token.
>
> `used_at`
> : `integer` The VPA usage timestamp.
>
> `created_at`
> : `integer` The token creation timestamp.
>
> `expired_at`
> : `integer` The token expiry date timestamp.
>
> `dcc_enabled`
> : `string` Indicates whether the option to change currency is enabled or not. Possible values.
>
> * `true`: The option to change currency is enabled
> * `false`: The option to change currency is not enabled.

## 2.3 Fetch a Token by Customer ID

The following endpoint fetches a particular token linked to a customer.

`GET /customers/:customer_id/tokens/:token_id`

```bash Curl theme={null}
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET https://api.razorpay.com/v1/customers/cust_IjsVsJ7d27hxOs/tokens/token_J0BgMu8YDVusZa
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_IjsVsJ7d27hxOs";

String tokenId = "token_J0BgMu8YDVusZa";

List<Customer> customer = razorpay.customers.fetchTokens(customerId, tokenId);
```

```php PHP theme={null}
$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)->tokens()->fetch($tokenId);
```

```javascript Node.js theme={null}
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customer.fetchTokens(customerId, tokenId)
```

```python Python theme={null}
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.fetch(customerId, tokenId)
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_IjsVsJ7d27hxOs"

tokenId = "token_J0BgMu8YDVusZa"

Razorpay::Customer.fetch(customerId).fetchToken(tokenId)
```

```go Go theme={null}
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Token("<customerId>", "<tokenId>", nil, nil)
```

```csharp .NET theme={null}
RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

string customerId = "cust_Z6t7VFTb9xHeOs";

string tokenId = "token_J0BgMu8YDVusZa"

List<Token> token = client.Customer.Fetch(customerId).Tokens();
```

```json Response theme={null}
{
   "id":"token_J0BgMu8YDVusZa",
   "entity":"token",
   "token":"testtoken00006",
   "bank":null,
   "wallet":null,
   "method":"card",
   "card":{
      "entity":"card",
      "name":"<name>",
      "last4":"7558",
      "network":"Visa",
      "type":"credit",
      "issuer":"FDRL",
      "international":false,
      "emi":true,
      "sub_type":"consumer",
      "token_iin":null,
      "expiry_month":1,
      "expiry_year":2027,
      "flows":{
         "recurring":true
      }
   },
   "recurring":true,
   "recurring_details":{
      "status":"confirmed",
      "failure_reason":null
   },
   "auth_type":null,
   "mrn":null,
   "used_at":1645780406,
   "created_at":1645780188,
   "expired_at":2709971120,
   "status":null,
   "notes":[
      
   ],
   "dcc_enabled":false,
   "compliant_with_tokenisation_guidelines":false
}
```

> [accordion] Path Parameters
>
> `customer_id` *mandatory*
> : `string` The unique identifier of the customer for whom tokens are to be retrieved. For example, `cust_IjsVsJ7d27hxOs`.
>
> `token_id` *mandatory*
> : `string` The unique identifier of the token that should be retrieved. For example, `token_J0BgMu8YDVusZa`.

> [accordion] Response Parameters
>
> `entity`
> : `string` The entity being created. Here, it is a `collection`.
>
> `count`
> : `integer` The number of tokens to be fetched.
>
> `items`
> : `object` Details related to token such as `token id` and bank information.
>
> `id`
> : `string` The unique identifier linked to an item. In this example, it is `token_id`.
>
> `entity`
> : `string` The entity being created. Here, it is a `token`.
>
> `token`
> : `string` The token is being fetched.
>
> `bank`
> : `string` Card issuing bank details.
>
> `wallet`
> : `string` Provides wallet information.
>
> `method`
> : `string` The payment method used to make the transaction.
>
> `card`
> : `object` Details related to card used to make the transaction.
>
> `entity`
> : `string` The entity being created. Here, it is `card`.
>
> `name`
> : `string` Name of the cardholder.
>
> `last4`
> : `integer` Last 4 digits of the card.
>
> `network`
> : `string` Name of the payment processor. Here it is `Visa`.
>
> `type`
> : `string` Card type (debit or credit). In this example, it is `credit`.
>
> `issuer`
> : `string` Name of the card-issuing bank.
>
> `international`
> : `boolean` Card usage restriction. Possible values:
>
> * `true`: Supports international transactions.
> * `false`: International transactions are not supported.
>
> `emi`
> : `string` Card EMI status. Possible values.
>
> * `true`: The card is on EMI.
> * `false`: The card is not on EMI.
>
> `sub_type`
> : `string` Type of the customer.
>
> `expiry_month`
> : `integer` Month on which the card expires.
>
> `expiry_year`
> : `integer` Year on which the card expires.
>
> `flows`
> : `object` The transaction flow details.
>
> `otp`
> : `string` Whether the OTP function is enabled or not. Possible values:
>
> * `true`: The OTP function is enabled.
> * `false`: The OTP function is not enabled.
>
> `recurring`
> : `string` Whether the recurring for this payment method is enabled or not. Possible Values:
>
> * `true`: Recurring is enabled.
> * `false`: Recurring is not enabled.
>
> `recurring`
> : `string` This represents whether recurring is enabled for this token. Possible values:
>
> * `true`: Recurring is enabled.
> * `false`: Recurring is not enabled.
>
> `recurring_details`
> : `object` Details of the recurring transaction.
>
> `status`
> : `string` This represents the status of the recurring transaction. Possible values:
>
> * `initiated`
> * `confirmed`
> * `rejected`
> * `cancelled`
> * `paused`
>
> `failure_reason`
> : `string` This provides the reason why the recurring transaction failed.
>
> `auth_type`
> : `string` The authorisation type details.
>
> `mrn`
> : `string` The unique identifier issued by the payment gateway during customer registration. This can be Gateway Reference Number or Gateway Token.
>
> `used_at`
> : `integer` The VPA usage timestamp.
>
> `created_at`
> : `integer` The token creation timestamp.
>
> `expired_at`
> : `integer` The token expiry date timestamp.
>
> `dcc_enabled`
> : `string` Indicates whether the option to change currency is enabled or not. Possible values.
>
> * `true`: The option to change currency is enabled
> * `false`: The option to change currency is not enabled.

## 2.4. Delete Tokens

The following endpoint deletes a token.

`DELETE /customers/:customer_id/tokens/:token_id`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X DELETE https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens/token_1Aa00000000001
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_1Aa00000000002";

String tokenId = "token_1Aa00000000001";

Customer customer = razorpay.customers.deleteToken(customerId, tokenId);
```

```php PHP theme={null}
$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)->tokens()->delete($tokenId);
```

```javascript Node.js theme={null}
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.deleteToken(customerId, tokenId)
```

```python Python theme={null}
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.delete(customerId, tokenId)
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

Razorpay::Customer.fetch(customerId).deleteToken(tokenId)
```

```go Go theme={null}
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Token.Delete("<customerId>", "<tokenId>", nil, nil)
```

```ruby Ruby theme={null}
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

Razorpay::fetch(customerId).deleteToken(tokenId)
```

```java Java theme={null}
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_DtHaBuooGHTuyZ";

String tokenId = "token_HouA2OQR5Z2jTL";

Customer customer = instance.customers.deleteToken(customerId, tokenId);
```

```csharp .NET theme={null}
RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

string customerId = "cust_Z6t7VFTb9xHeOs";

string tokenId = "token_1Aa00000000001";

Customer customer = client.Customer.Fetch(customerId).DeleteToken(tokenId);
```

```json Response theme={null}
{
    "deleted": true
}
```

> [accordion] Path Parameters
>
> `customer_id` *mandatory*
> : `string` The unique identifier of the customer with whom the token is linked. For example, `cust_1Aa00000000002`.
>
> `token_id` *mandatory*
> : `string` The unique identifier of the token that is to be deleted. For example, `token_1Aa00000000001`.

> [accordion] Response Parameter
>
> `deleted`
> : `boolean` Indicates whether the token is deleted. Possible values:
>
> * `true`: The token is deleted successfully.
> * `false`: The token was not deleted.
