2. Fetch and Manage Tokens

Retrieve tokens using Razorpay APIs to create subsequent payments.


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.

Note

You can also search for the Token on your Dashboard.

.

Token Sharing for Partner Auth Model

If 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"
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
{
"id": "pay_FHfqtkRzWvxky4",
"entity": "payment",
"amount": 100,
"currency": "MYR",
"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": "nur.aisyah@example.com",
"contact": "+60123456789",
"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 Tips

You can also retrieve the token_id from the

.

id

mandatory

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

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
{
"entity":"collection",
"count":1,
"items":[
{
"id":"token_HouA2OQR5Z2jTL",
"entity":"token",
"token":"2JPRk664pZHUWG",
"bank":null,
"wallet":null,
"method":"card",
"card":{
"entity":"card",
"name":"Nur Aisyah",
"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
}
]
}

id

mandatory

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

The following endpoint deletes a token.

DELETE
/customers/:customer_id/tokens/:token_id

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.


Is this integration guide useful?