Skip to main content
You can retrieve the token_id using the Dashboard or the APIs given below. Know more about Tokens.

2.1. Fetch Token by Payment ID

The following endpoint fetches the token_id using a payment_id. /payments/:id
Curl
Debit Payment
Handy Tips
You can also retrieve the token_id via 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 retrieves tokens linked to a customer.
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.
/customers/:id/tokens
Curl
Response

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. 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. 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. 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. 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. 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. 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
Request

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. The following endpoint deletes a token. /customers/:customer_id/tokens/:token_id
Curl
Response

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.