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

Use the below endpoint to fetch 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_FHfqtkRzWvxky4";

Payment payment = instance.payments.fetch(paymentids);

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

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

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

paymentId = "pay_FHfqtkRzWvxky4"

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)

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

Use the below endpoint to fetch all tokens linked to a customer. A customer can have multiple tokens tied to them. These tokens can be used to create subsequent payments for multiple products or services. 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_1Aa00000000002";

String tokenId = "token_FHfn3rIiM1Z8nr";

Customer customer = instance.customers.fetchToken(customerId, tokenId)

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

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

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

customerId = "cust_1Aa00000000002"

tokenId = "token_FHfn3rIiM1Z8nr"

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

{
  "entity": "collection",
  "count": 1,
  "items": [
    {
      "id": "token_FHfn3rIiM1Z8nr",
      "entity": "token",
      "token": "2aqzyte2EqvuDr",
      "bank": null,
      "wallet": null,
      "method": "card",
      "card": {
        "entity": "card",
        "name": "<name>",
        "last4": "2002",
        "network": "Visa",
        "type": "credit",
        "issuer": "CITI",
        "international": false,
        "emi": true,
        "sub_type": "consumer",
        "expiry_month": 5,
        "expiry_year": 2030,
        "flows": {
          "otp": true,
          "recurring": true
        }
      },
      "vpa": null,
      "recurring": true,
      "auth_type": null,
      "mrn": null,
      "used_at": 1595449871,
      "created_at": 1595449652,
      "expired_at": 1748716199,
      "dcc_enabled": false
    }
  ]
}

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

​2.1. Fetch Token by Payment id

​2.2. Fetch Tokens by Customer id

​2.3. Delete Tokens

2.1. Fetch Token by Payment id

2.2. Fetch Tokens by Customer id

2.3. Delete Tokens