2. Fetch and Manage Tokens

Available in🇮🇳 India

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 or the APIs given below.

2.1. Fetch Token by Payment ID

The following endpoint fetches the token_id using a payment_id. GET /payments/:id

Curl

curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET https://api.razorpay.com/v1/payments/pay_1Aa00000000002

Java

RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String paymentId = "pay_1Aa00000000002";

Payment payment = razorpay.payments.fetch(paymentId)

PHP

$api = new Api($key_id, $secret);

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

Node.js

var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.payments.fetch(paymentId)

Python

client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.payment.fetch(paymentId)

Ruby

require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

paymentId = "pay_FHfAzEJ51k8NLj"

Razorpay::Payment.fetch(paymentId)

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

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

.NET

RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

string paymentid = "pay_FHfqtkRzWvxky4";

Payment payment = client.Payment.Fetch(paymentid);

Debit Payment

{
  "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
}

Authorisation Payment

{
  "id": "pay_QDhVJ5M23wt4rh",
  "entity": "payment",
  "amount": 1000,
  "currency": "INR",
  "status": "failed",
  "order_id": "order_QDhT2PqFJvtg4y",
  "invoice_id": null,
  "international": false,
  "method": "upi",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": false,
  "description": null,
  "card_id": null,
  "bank": null,
  "wallet": null,
  "vpa": "success@razorpay",
  "email": "gaurav.kumar@example.com",
  "contact": "+919123456780",
  "customer_id": "cust_Q0g6LTYw3obZEn",
  "token_id": "token_QDhVJHYr5m87fF",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey\u2026 decaf.",
    "note_key 1": "Beam me up Scotty",
    "note_key 2": "Tea. Earl Gray. Hot.",
    "optimizer_provider_name": "razorpay"
  },
  "fee": null,
  "tax": null,
  "error_code": "BAD_REQUEST_ERROR",
  "error_description": "Payment was a dummy payment for one time mandate registration.",
  "error_source": "business",
  "error_step": "payment_initiation",
  "error_reason": "upi_dummy_payment",
  "acquirer_data": {
    "rrn": null
  },
  "gateway_provider": "Razorpay",
  "created_at": 1743490280,
  "upi": {
    "vpa": "success@razorpay"
  }
}

Handy TipsYou can also retrieve the token_id via the payment.failed webhook.

Path Parameters

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

2.2. Fetch 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.

Watch Out!

This endpoint will not fetch the details of expired and unused tokens.
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.

The following endpoint retrieves tokens linked to a customer. GET /customers/:id/tokens

Curl

curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X GET https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens

Java

RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_1Aa00000000002";

List<Token> tokens = razorpay.customers.fetchTokens(customerId);

PHP

$api = new Api($key_id, $secret);

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

Node.js

var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.fetchTokens(customerId)

Python

client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.all(customerId)

Ruby

require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

Razorpay::Customer.fetch(customerId).fetchTokens

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

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

.NET

RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

string customerId = "cust_1Aa00000000001";

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

Response

{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "token_RtOSr9o9lZwv5C",
      "entity": "token",
      "token": "9uZG3CE8KsVG9J",
      "bank": null,
      "wallet": null,
      "method": "upi",
      "vpa": {
        "username": "9876543210",
        "handle": "upi",
        "name": "GAURAV KUMAR",
        "status": "valid",
        "received_at": 1757596287
      },
      "recurring": true,
      "recurring_details": {
        "status": "confirmed",
        "failure_reason": null,
        "amount_blocked": 200,
        "amount_debited": 100
      },
      "auth_type": null,
      "mrn": null,
      "used_at": 1766131328,
      "created_at": 1766130600,
      "start_time": 1766130592,
      "notes": [],
      "error_description": null,
      "entity_id": null,
      "dcc_enabled": false,
      "max_amount": 200,
      "expired_at": 1767091469
    },
    {
      "id": "token_RtO5dfKe1AbBqd",
      "entity": "token",
      "token": "F6YFhWQ1SZSYLl",
      "bank": null,
      "wallet": null,
      "method": "upi",
      "vpa": {
        "username": "9325938054",
        "handle": "upi",
        "name": null,
        "status": null,
        "received_at": 1759590546
      },
      "recurring": true,
      "recurring_details": {
        "status": "confirmed",
        "failure_reason": null
      },
      "auth_type": null,
      "mrn": null,
      "used_at": null,
      "created_at": 1766129281,
      "start_time": 1766129266,
      "notes": [],
      "error_description": null,
      "entity_id": null,
      "dcc_enabled": false
    }
  ]
}

Path Parameters

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

2.3. Cancel Token

The following endpoint initiates cancellation of the mandate from NPCI. PUT /customers/:customer_id/tokens/:token_id/cancel

Request

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X PUT https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens/token_1Aa00000000001/cancel

Response

{
      "status": "cancellation_initiated"
}

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.

invalid_request_timing

Description: The cancellation request was received outside the allowed cancellation window or for an unsupported mandate type.
Next Steps: Please ensure the cancel request is sent within the valid cancellation window and that the mandate type supports this operation. Retry after verifying mandate details.

2.4. Delete Tokens

Watch Out!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 cancel the mandate from NPCI, use the Cancel Token API.

The following endpoint deletes a token. DELETE /customers/:customer_id/tokens/:token_id

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X DELETE https://api.razorpay.com/v1/customers/cust_1Aa00000000002/tokens/token_1Aa00000000001

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

$api = new Api($key_id, $secret);

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

Node.js

var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.deleteToken(customerId, tokenId)

Python

client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.delete(customerId, tokenId)

Ruby

require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

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

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

require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

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

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);

.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);

Response

{
    "deleted": true
}

Path Parameters

​2.1. Fetch Token by Payment ID

​2.2. Fetch Tokens by Customer ID

​2.3. Cancel Token

​Error Response Parameters

​2.4. Delete Tokens

2.1. Fetch Token by Payment ID

2.2. Fetch Tokens by Customer ID

2.3. Cancel Token

Error Response Parameters

2.4. Delete Tokens