Skip to main content
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.

2.1. What is a Token?

A recurring token represents the mandate that the customer sets up on their card. Razorpay generates a token_id when the customer completes the authorisation transaction and links it to the customer_id. You use this token_id every time you create a subsequent payment. The recurring token is different from the card token, which the card network generates when the card is tokenised as required by RBI guidelines.

2.2. Token States

As the authorisation transaction moves through its states, the token generated for the mandate also changes state. Only tokens in the confirmed state can be used to create subsequent payments.

2.3. 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
The following endpoint fetches a token id using the Payment id. GET /payments/:id
Response
Handy TipsYou can also retrieve the token_id from the payment.authorized webhook.
string
required
The unique identifier of the payment to be retrieved. For example, pay_1Aa00000000002.
string
Unique identifier of the payment.
string
Indicates the type of entity. Here, it is payment.
integer
The payment amount represented in smallest unit of the currency passed. For example, amount = 100 translates to 100 subunits, that is ₹1.
string
The currency in which the payment is made. Refer to the list of international currencies that we support.
string
The status of the payment. Possible values:
  • created
  • authorized
  • captured
  • refunded
  • failed
string
The unique identifier of the order.
string
The unique identifier of the invoice.
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.
string
The payment method used for making the payment. Possible values:
  • card
  • netbanking
  • wallet
  • emi
  • upi
integer
The amount refunded in smallest unit of the currency passed.
string
The refund status of the payment. Possible values:
  • null
  • partial
  • full
boolean
Indicates if the payment is captured. Possible values:
  • true: Payment has been captured.
  • false: Payment has not been captured.
string
Description of the payment, if any.
string
Customer email address used for the payment.
integer
Customer contact number used for the payment.
string
The unique identifier of the customer.
string
The unique identifier of the token.
object
Contains user-defined fields, stored for reference purposes.
integer
Fee (including GST) charged by Razorpay.
integer
GST charged for the payment.
string
Error that occurred during payment. For example, BAD_REQUEST_ERROR.
string
Description of the error that occurred during payment. For example, Payment processing failed because of incorrect OTP.
string
The point of failure. For example, customer.
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.
string
The exact error reason. For example, incorrect_otp.
integer
Timestamp, in UNIX format, on which the payment was created.

2.4. 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
Response
string
required
The unique identifier of the customer for whom tokens are to be retrieved. For example, cust_1Aa00000000002.
string
The entity being created. Here, it is a collection.
integer
The number of tokens to be fetched.
object
Details related to token such as token id and bank information.
string
The unique identifier linked to an item. In this example, it is token_id.
string
The entity being created. Here, it is a token.
string
The token is being fetched.
string
Card issuing bank details.
string
Provides wallet information.
string
The payment method used to make the transaction.
object
Details related to card used to make the transaction.
string
The entity being created. Here, it is card.
string
Name of the cardholder.
integer
Last 4 digits of the card.
string
Name of the payment processor. Here it is Visa.
string
Card type (debit or credit). In this example, it is credit.
string
Name of the card-issuing bank.
boolean
Card usage restriction. Possible values:
  • true: Supports international transactions.
  • false: International transactions are not supported.
string
Card EMI status. Possible values.
  • true: The card is on EMI.
  • false: The card is not on EMI.
string
Type of the customer.
integer
Month on which the card expires.
integer
Year on which the card expires.
object
The transaction flow details.
string
Whether the OTP function is enabled or not. Possible values:
  • true: The OTP function is enabled.
  • false: The OTP function is not enabled.
string
Whether the recurring for this payment method is enabled or not. Possible Values:
  • true: Recurring is enabled.
  • false: Recurring is not enabled.
object
The VPA details.
string
The username of the VPA holder. For example, gaurav.kumar.
string
The VPA handle. Here it is upi.
string
The name of the VPA holder.
string
This represents whether recurring is enabled for this token. Possible values:
  • true: Recurring is enabled.
  • false: Recurring is not enabled.
object
Details of the recurring transaction.
string
This represents the status of the recurring transaction. Possible values:
  • initiated
  • confirmed
  • rejected
  • cancelled
  • paused
string
This provides the reason why the recurring transaction failed.
string
The authorisation type details.
string
The unique identifier issued by the payment gateway during customer registration. This can be Gateway Reference Number or Gateway Token.
integer
The VPA usage timestamp.
integer
The token creation timestamp.
integer
The token expiry date timestamp.
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.5. 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
Response
string
required
The unique identifier of the customer for whom tokens are to be retrieved. For example, cust_IjsVsJ7d27hxOs.
string
required
The unique identifier of the token that should be retrieved. For example, token_J0BgMu8YDVusZa.
string
The entity being created. Here, it is a collection.
integer
The number of tokens to be fetched.
object
Details related to token such as token id and bank information.
string
The unique identifier linked to an item. In this example, it is token_id.
string
The entity being created. Here, it is a token.
string
The token is being fetched.
string
Card issuing bank details.
string
Provides wallet information.
string
The payment method used to make the transaction.
object
Details related to card used to make the transaction.
string
The entity being created. Here, it is card.
string
Name of the cardholder.
integer
Last 4 digits of the card.
string
Name of the payment processor. Here it is Visa.
string
Card type (debit or credit). In this example, it is credit.
string
Name of the card-issuing bank.
boolean
Card usage restriction. Possible values:
  • true: Supports international transactions.
  • false: International transactions are not supported.
string
Card EMI status. Possible values.
  • true: The card is on EMI.
  • false: The card is not on EMI.
string
Type of the customer.
integer
Month on which the card expires.
integer
Year on which the card expires.
object
The transaction flow details.
string
Whether the OTP function is enabled or not. Possible values:
  • true: The OTP function is enabled.
  • false: The OTP function is not enabled.
string
Whether the recurring for this payment method is enabled or not. Possible Values:
  • true: Recurring is enabled.
  • false: Recurring is not enabled.
object
The VPA details.
string
The username of the VPA holder. For example, gaurav.kumar.
string
The VPA handle. Here it is upi.
string
The name of the VPA holder.
string
This represents whether recurring is enabled for this token. Possible values:
  • true: Recurring is enabled.
  • false: Recurring is not enabled.
object
Details of the recurring transaction.
string
This represents the status of the recurring transaction. Possible values:
  • initiated
  • confirmed
  • rejected
  • cancelled
  • paused
string
This provides the reason why the recurring transaction failed.
string
The authorisation type details.
string
The unique identifier issued by the payment gateway during customer registration. This can be Gateway Reference Number or Gateway Token.
integer
The VPA usage timestamp.
integer
The token creation timestamp.
integer
The token expiry date timestamp.
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.6. Delete Tokens

The following endpoint deletes a token. DELETE /customers/:customer_id/tokens/:token_id
string
required
The unique identifier of the customer with whom the token is linked. For example, cust_1Aa00000000002.
string
required
The unique identifier of the token that is to be deleted. For example, token_1Aa00000000001.
boolean
Indicates whether the token is deleted. Possible values:
  • true: The token is deleted successfully.
  • false: The token was not deleted.

2.7. Error Scenarios

If a token request fails, the API response carries an error object with code, description, source, step and reason. Use the reason to decide the next action. For the Cards Recurring error reasons, see Error Codes.
Last modified on November 19, 2026