> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-60c89f9a-mintlify-audit-missing-sections-1778528421.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 2. Fetch and Manage Tokens

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

## 2.1. Fetch Token by Payment ID

Use the below endpoint to fetch the `token_id` using a `payment_id`.

/payments/:id

````cURL: Curl theme={null}
curl -u : \
-X GET https://api.razorpay.com/v1/payments/pay_1Aa00000000002

```php: PHP
$api = new Api($key_id, $secret);

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

```json: Response
{
  "id": "pay_FHfAzEJ51k8NLj",
  "entity": "payment",
  "amount": 100,
  "currency": "INR",
  "status": "captured",
  "order_id": "order_FHfANdTUYeP8lb",
  "invoice_id": null,
  "international": false,
  "method": "upi",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": true,
  "description": null,
  "card_id": null,
  "bank": null,
  "wallet": null,
  "vpa": "gaurav.kumar@upi",
  "email": "gaurav.kumar@example.com",
  "contact": "+919876543210",
  "customer_id": "cust_DtHaBuooGHTuyZ",
  "token_id": "token_FHfAzGzREc1ug6",
  "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": {
    "rrn": "854977234911",
    "upi_transaction_id": "D0BED5A062ECDB3E9B3A1071C96BB273"
  },
  "created_at": 1595447490
}
````

<Info>
  **Note**
</Info>

You can also retrieve the `token_id` via the [payment.authorized webhook](/api/payments/recurring-payments/webhooks#payment-authorized).

### Path Parameter

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

## 2.2. Fetch Tokens by Customer ID

<Warning>
  **Watch Out!**

  The UPI tokens are not populated in the API response if the `save_vpa` feature is not enabled in your account. Please raise a request with our Support team to get this activated.

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

  ```php: PHP
  $api = new Api($key_id, $secret);

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

  ```json: Response
  {
    "entity": "collection",
    "count": 1,
    "items": [
      {
        "id": "token_FHfAzGzREc1ug6",
        "entity": "token",
        "token": "9KHsdPaCELeQ0t",
        "bank": null,
        "wallet": null,
        "method": "upi",
        "vpa": {
          "username": "gaurav.kumar",
          "handle": "upi",
          "name": null
        },
        "recurring": true,
        "recurring_details": {
          "status": "confirmed",
          "failure_reason": null
        },
        "auth_type": null,
        "mrn": null,
        "used_at": 1595447490,
        "created_at": 1595447490,
        "start_time": 1595447455,
        "dcc_enabled": false
      }
    ]
  }
  ````
</Warning>

### Path Parameter

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

## 2.3. Cancel Token

You can cancel tokens that are in the `initiated`, `confirmed` or `paused` state. Razorpay does not perform any additional validation checks before forwarding the cancellation request to NPCI.

Cancellations can fail if NPCI returns a failure response. This typically happens due to an internal issue on the remitter's side. Use the following endpoint to cancel a token. This initiates the cancellation of the mandate from NPCI.

/customers/:customer\_id/tokens/:token\_id/cancel

````curl: Request theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X PUT https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens/token_1Aa00000000001/cancel
```json: Response
{
      "status": "cancellation_initiated”
}
```python: Python
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

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

### 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 cancelled. For example, `token_1Aa00000000001`.

### Error Response Parameters

Given below is a list of possible errors you may face while cancelling a token.

### token\_not\_recurring

* **Description**: The token provided is not a recurring/autopay token and is not eligible for cancellation via this API.
* **Next Steps**: Please ensure you are passing a valid UPI Autopay recurring token. Non-recurring tokens cannot be cancelled using this API.

### invalid\_mandate\_state

* **Description**: The UPI mandate linked to this token is not in a cancellable state. The mandate may already be revoked or failed.
* **Next Steps**: Please check the current status of the mandate before attempting cancellation. Cancellation is only allowed when the mandate is in confirmed or active state.

### token\_customer\_mismatch

* **Description**: The token provided does not belong to the authenticated customer. Cross-customer token access is not permitted.
* **Next Steps**: Please verify that the `token_id` belongs to the customer in context and retry with the correct token.

### token\_merchant\_mismatch

* **Description**: The token provided was not created under your merchant account. Cross-merchant token access is not permitted.
* **Next Steps**: Please ensure you are using tokens created under your own merchant account and retry with the correct `token_id`.

### concurrent\_request\_in\_progress

* **Description**: A cancellation or update operation is already in progress for this token. Simultaneous requests on the same token are not allowed.
* **Next Steps**: Please wait at least 60 seconds before retrying the cancellation request. Avoid sending duplicate or parallel cancel requests for the same token.

## 2.4. Delete Tokens

Deleting a token removes it from Razorpay's database. The deleted token will not appear on the Dashboard or when all tokens are fetched. However, it does not cancel the mandate. If you wish to delete the mandate with Razorpay, you must first cancel it using the [Cancel Token API](#23-cancel-token).

The following endpoint deletes a token.

/customers/:customer\_id/tokens/:token\_id

````curl: 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
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
$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)->tokens()->delete($tokenId);
```javascript: Node.js
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.deleteToken(customerId, tokenId)

```python: Python
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.delete(customerId, tokenId)

```ruby: Ruby
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

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

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

body, err := client.Token.Delete("", "", nil, nil)

```ruby: Ruby
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

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

```java: Java
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
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
}
```

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

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

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