> ## Documentation Index
> Fetch the complete documentation index at: https://doc-test-my.mintlify.site/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.

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](/docs/payments/recurring-payments/create#3-search-for-the-token) or the APIs given below.

Know more about [Tokens](/docs/payments/recurring-payments/cards/integrate#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`

<CodeGroup>
  ```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": "wallet",
    "wallet": "touchngo",
    "amount_refunded": 0,
    "refund_status": null,
    "captured": true,
    "description": null,
    "card_id": null,
    "bank": null,
    "vpa": null,
    "email": "nur.aisyah@example.com",
    "contact": "60345675444",
    "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
  }
  ```
</CodeGroup>

<Info>
  **Handy Tips**

  You can also retrieve the `token_id` from the [payment.authorized webhook](/docs/api/payments/recurring-payments/webhooks#payment-authorized).
</Info>

### Path Parameter

`id` *mandatory*
: `string` The unique identifier of the payment to be retrieved. For example, `pay_1Aa00000000002`.

### 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:

* `wallet`

`wallet`
: `string` The wallet used for making the payment. Possible values:

* `touchngo` (default)
* `grabpay` (default)
* `shopback` (requires [approval](https://razorpay.com/support/#request))

`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 and unused tokens.
</Warning>

`GET /customers/:id/tokens`

<CodeGroup>
  ```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":"touchngo",
           "method":"wallet",
           "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
        }
     ]
  }
  ```
</CodeGroup>

### Path Parameter

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

### Response Parameters

`entity`
: `string` The entity being created. Here, it is a `collection`.

`count`
: `integer` The number of tokens to be fetched.

`items`
: 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.

`wallet`
: `string` Provides wallet information.

`method`
: `string` The payment method used to make the transaction.

`recurring`
: `string` This represents whether recurring is enabled for this token or not. 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`

<CodeGroup>
  ```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":"touchngo",
     "method":"wallet",
     "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
  }
  ```
</CodeGroup>

### 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`.

### Response Parameters

`entity`
: `string` The entity being created. Here, it is a `collection`.

`count`
: `integer` The number of tokens to be fetched.

`items`
: 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.

`wallet`
: `string` Provides wallet information.

`method`
: `string` The payment method used to make the transaction.

`recurring`
: `string` This represents whether recurring is enabled for this token or not. 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`

<CodeGroup>
  ```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
  }
  ```
</CodeGroup>

### 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`.

### Response Parameter

`deleted`
: `boolean` Indicates whether the token is deleted. Possible values:

* `true`: The token is deleted successfully.
* `false`: The token was not deleted.