2. Fetch and Manage Tokens

Available in🇮🇳 India

Once you capture a payment, Razorpay returns a razorpay_payment_id that can be used to fetch the token_id. This is a manual process and can be done using either APIs or Webhooks. This token_id is used to create and charge subsequent payments.

Handy TipsYou can also search for the Token on your Dashboard.

Token States

As the authorisation transaction moves through its states, the token generated for the mandate also changes state.

token_status	Description	Next Step
`initiated`	Indicates that the bank is processing the mandate registration.	Wait for the `token.confirmed` webhook.
`confirmed`	Indicates that the bank has completed the mandate registration.	Create subsequent payments.
`rejected`	Indicates that the mandate registration has failed.	Create the authorisation transaction again.
`cancelled`	Indicates that the token has been cancelled.	Create the authorisation transaction again if you want to charge the customer.
`paused`	Indicates that the token has been paused by your customer.	The token is inactive. Ask your customer to resume it so you can charge them.

Only tokens in the confirmed state can be used to create subsequent payments.

2.1. Fetch Token by Payment id

Token Sharing for Partner Auth ModelIf you are a Razorpay Partner, who wants to use this API via Partner Auth, you must ensure the following:

Add the basic auth with partner credentials (client_id and client_secret).
Add the account_id of the sub-merchant using X-Razorpay-Account in the header. For example, -H “X-Razorpay-Account: acc_KBrJAIEqre5ucn”

Request

curl -X POST https://api.razorpay.com/v1/customers \
-u [YOUR_PARTNER_KEY_ID]:[YOUR_PARTNER_KEY_SECRET]\
-H "X-Razorpay-Account: acc_KBrJAIEqre5ucn" \

The following endpoint fetches a token id using the Payment id. GET /payments/:id

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

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

String paymentId = "pay_1Aa00000000001";

Payment payment = razorpay.payments.fetch(paymentId)

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

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

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

instance.payments.fetch(paymentId)

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

client.payment.fetch(paymentId)

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

paymentId = "pay_1Aa00000000001"

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)

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

string paymentId = "pay_Z6t7VFTb9xHeOs";

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

Response

{
  "id": "pay_FHfqtkRzWvxky4",
  "entity": "payment",
  "amount": 100,
  "currency": "INR",
  "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
}

Handy TipsYou can also retrieve the token_id from the payment.authorized webhook.

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. Refer to the list of international currencies that we support.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
netbanking
wallet
emi
upi

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 (including GST) charged by Razorpay.tax : integer GST charged for the payment.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 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.

Watch Out!This endpoint will not fetch the details of expired, rejected and unused tokens.

GET /customers/:id/tokens

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

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

String customerId = "cust_DtHaBuooGHTuyZ";

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

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

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

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

instance.customer.fetchTokens(customerId)

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

client.token.all(customerId)

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

customerId = "cust_1Aa00000000002"

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)

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

string customerId = "cust_Z6t7VFTb9xHeOs";

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

Response

{
   "entity":"collection",
   "count":1,
   "items":[
      {
         "id":"token_HouA2OQR5Z2jTL",
         "entity":"token",
         "token":"2JPRk664pZHUWG",
         "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
      }
   ]
}

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 : object Details related to token such as token id and bank information.

Show Child parameters

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.

Show Child parameters

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.

Show Child parameters

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.

vpa : object The VPA details.

Show Child parameters

username : string The username of the VPA holder. For example, gaurav.kumar.handle : string The VPA handle. Here it is upi.name : string The name of the VPA holder.

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.

Show Child parameters

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.

Fetch a Token by Token ID and Customer ID

The following endpoint fetches a particular token linked to a customer. GET /customers/:customer_id/tokens/:token_id

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

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

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

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

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

instance.customer.fetchTokens(customerId, tokenId)

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

client.token.fetch(customerId, tokenId)

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

customerId = "cust_IjsVsJ7d27hxOs"

tokenId = "token_J0BgMu8YDVusZa"

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

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

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

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

Response

{
   "id":"token_J0BgMu8YDVusZa",
   "entity":"token",
   "token":"ya5olMAYU0ap4F",
   "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
}

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

Show Child parameters

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.

Show Child parameters

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.

vpa : object The VPA details.

Show Child parameters

username : string The username of the VPA holder. For example, gaurav.kumar.handle : string The VPA handle. Here it is upi.name : string The name of the VPA holder.

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.

Show Child parameters

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.

true: The option to change currency is enabled
false: The option to change currency is not enabled.

2.3. Delete Tokens

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

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

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

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

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

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

instance.customers.deleteToken(customerId, tokenId)

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

client.token.delete(customerId, tokenId)

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)

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

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

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

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

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

{
    "deleted": true
}

Path Parameter

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.

Features

JSON

2. Fetch and Manage Tokens

Token States

2.1. Fetch Token by Payment id

2.2. Fetch Tokens by Customer id

Fetch a Token by Token ID and Customer ID

2.3. Delete Tokens

​Token States

​2.1. Fetch Token by Payment id

​2.2. Fetch Tokens by Customer id

​Fetch a Token by Token ID and Customer ID

​2.3. Delete Tokens

Token States

2.1. Fetch Token by Payment id

2.2. Fetch Tokens by Customer id

Fetch a Token by Token ID and Customer ID

2.3. Delete Tokens