Tokenisation APIs
List of APIs to tokenise customer cards.
According to recent Payment Acquirer (PA)/ Payment Gateway (PG) guidelines from RBI, businesses cannot save their customers' card numbers and other card data on their servers. Razorpay TokenHQ is a RBI-compliant solution that allows you to save customer credentials with card networks and card-issuing banks. You can use Razorpay Optimizer to route payments through the PA/PG of your choice.
Given below is the list of APIs:
- .
- .
- .
- .
- .
You can save customer card details in the form of tokens and then use these tokens to accept payments from customers.
Given below is a sample entity.
id
string
The unique identifier of the Razorpay token.
entity
string
The name of the entity. Here, it is token
.
customer_id
string
This is the Razorpay customer id. You can create token for a specific customer using their customer id. Use the
method
string
The type of object that was tokenised. Currently, it only supports card
.
card
object
The customer card details.
last4
string
The last 4 digits of the tokenised card.
network
string
The card network. Possible values:
Visa
RuPay
MasterCard
American Express
Diners Club
Bajaj Finserv
Maestro
JCB
Union Pay
issuer
string
The 4-character issuer code unique to each issuing bank in India. For example, HDFC
, SBIN
and so on.
type
string
The type of card. Possible values:
credit
debit
prepaid
international
boolean
Indicates whether the card is international (issued outside India) or domestic. Possible values:
true
: The card is international.false
: The card is domestic.
emi
boolean
Indicates whether the card is eligible for EMI payments or not. Possible values:
true
: The card is eligible for EMI payments.false
: The card is not eligible for EMI payments.
sub_type
string
The card sub_type for the given IIN. Pricing of card payment may change on the basis of card type. Possible values:
consumer
business
unknown
token_iin
string
The token IIN provided by the card network. When a token is created with card networks such as Visa or MasterCard, this field will have the token IIN. This will be useful to fetch all the token properties so that you can apply your existing IIN validations and processing. This field will be absent when the token is created by a token service provider other than the card network.
compliant_with_tokenisation_guidelines
boolean
Indicates whether the token is compliant with the RBI guidelines. Possible values:
true
: The token is compliant with RBI guidelines.false
: The token is not compliant with RBI guidelines.
service_provider_tokens
array
Every Razorpay token will have one or more token service providers(card networks, issuing banks or Razorpay). For each service provider, Razorpay will return a service provider token. This service provider token is the raw token returned by the token service provider (card network or issuer). Currently, we will have only card networks as token service providers. In future, a token may be created with more than one service provider. A token can be created with one or more of the following service providers:
The
service_provider_tokens
object is an on-demand feature, made available only to PCI DSS compliant businesses. id
string
The unique identifier of the token.
entity
string
The name of the entity. Here, it is service_provider_token
.
provider_type
string
The type of provider through which the token was created. Possible values:
network
issuer
aggregator
(When the token provider is Razorpay.)
provider_name
string
The name of the provider through which the token was created. Possible values:
Visa
MasterCard
HDFC
razorpay
interoperable
boolean
This field suggests if the token provided is interoperable across different acquirers. Possible values:
true
: The token is interoperable.false
: The token is not interoperable.
status
string
The current status for the token as provided by the token service provider. Possible values:
active
suspended
deactivated
failed
Know about the complete list of .
status_reason
string
When the token status is deactivated, this field will provide the reason for deactivation. Possible values:
expired
deactivated_by_bank
provider_data
object
Service provider data.
token_reference_number
string
The token reference number provider by the token provider.
payment_account_reference
string
The unique card identifier provided by the token provider. If the service_provider
is network
, this identifier will be consistent for a given card across the card network ecosystem.
token_iin
string
The IIN of the token thus created. The IIN will be helpful to fetch all the properties of the token and apply your existing IIN validations and processes.
token_expiry_month
string
The expiry date for the token. The format used is mm
.
token_expiry_year
string
The expiry year for the token. The format used is yyyy
.
token_requestor_id
string
The tr_merchant_id provided by HDFC. (Displayed only for Diners tokens).
error
object
Details of error.
code
string
Type of the error.
description
string
Description of the error.
field
string
Name of the parameter that caused the error.
source
string
The point of failure in token creation.
step
string
The stage where the failure occurred.
reason
string
The exact error reason.
metadata
object
Contains additional information about the request.
expired_at
string
The expiry timestamp for the token.
status
string
The overall status for the token. Possible values:
active
: The token attains this state if the token is activated for at least one of the token service providers.suspended
: The token attains this state if:- The token is not activated for any one of the token service providers.
- The token is suspended for at least one of the token service providers.
deactivated
: The token attains this state if the token is notactive
/suspended
for any one of the token service providers and is deactivated for at least one token service provider.
Know about the complete list of .
status_reason
string
When the token reaches the deactivated
state, this field will provide the reason for deactivation. Possible values:
expired
deactivated_by_bank
notes
object
Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scottyā€¯
.
A token is an alias for the actual card number. Use this API to save your customer's card.
As per RBI guidelines, customer consent and AFA (3ds authentication) are mandatory for saving a card.
- This API should be called only after authentication is complete. Authentication can be processed through any payment processor.
- You will receive a token as a response.
Handy Tips
If multiple tokenisation requests have been raised for the same card using this API, then for:
- MasterCard and RuPay Cards: Different tokens will be created for each request.
- Visa Cards: If a token has already been created, the API will return the same token for subsequent requests. This is in sync with the Network Tokenisation API.
Watch Out
This API is only available to businesses that are TRs and not available for Rupay payments.
customer_id
optional
string
The unique identifier of the customer created using
method
mandatory
string
The type of object that needs to be tokenised. Currently, card
is the only supported value.
card
mandatory
object
The card details.
number
string
The card number. If the card number has spaces, it will be trimmed by Razorpay for further processing.
cvv
string
The card's CVV number.
Handy Tips
- CVV is not required by default for tokenised cards across all networks.
- CVV is optional for tokenised card payments. Do not pass dummy CVV values.
- To implement this change, skip passing the
cvv
parameter entirely, or pass anull
or empty value in the CVV field. - We recommend removing the CVV field from your checkout UI/UX for tokenised cards.
- If CVV is still collected for tokenised cards and the customer enters a CVV, pass the entered CVV value to Razorpay.
expiry_month
string
The card expiry month in mm
format.
expiry_year
string
The card expiry year in yy
or yyyy
format.
name
string
The cardholder's name.
authentication
mandatory
object
Token authentication details.
provider
string
The platform through which authentication was processed. Possible values:
amex
axis_migs
cashfree
ccavenue
cybersource
first_data
fss
hdfc
mpgs
paysecure
paytm
payu
zaakpay
provider_reference_id
string
The unique payment identifier of the payment used to collect AFA on any PA/PG.
authentication_reference_number
conditional
string
A unique reference number generated for Amex and RuPay payments when the cardholder consents to tokenisation and AFA is successfully completed. This field is mandatory for RuPay (when provided by the gateway) and for all Amex token creation requests.
Watch Out!
To tokenise RuPay and Amex cards, the following information is required:
- authRefNo: Provided by NPCI for RuPay transactions.
- AeVV: Provided by Amex during payments where AFA was collected from the cardholder for tokenisation.
These values must be shared by the payment processor handling the transaction. For RuPay, this is required only if generated by the gateway. For Amex, it is mandatory for all payments.
Given below is a list of sample error codes:
- Code: BAD_REQUEST_ERROR
- Description: The
<field name>
is required - Source: internal
- Step: token_initiation
- Reason: input_validation_failed
- Code: BAD_REQUEST_ERROR
- Description: The
<field name>
is invalid - Source: internal
- Step: token_initiation
- Reason: input_validation_failed
Use this API to retrieve card details such as network, issuer and so on for a given token.
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]-X POST https://api.razorpay.com/v1/tokens/fetch-H "content-type: application/json"-d'{"id": "token_4lsdksD31GaZ09"}'
Use the following API to delete a token already saved with Razorpay.
Use this API to make the payment when a customer initiates a subsequent payment using the saved card. Pass the token ID from the previous API request to initiate a payment using the token.
amount
mandatory
integer
The payment amount you want to collect from the customer.
currency
mandatory
string
The 3-character ISO code of the currency. Here, it is INR
.
order_id
mandatory
string
The unique identifier of the order created for this payment. Create an order using the
mandatory
string
The customer's email address.
contact
mandatory
string
The customer's phone number.
method
mandatory
string
The payment method. Here, it is card
.
token
mandatory
string
The unique identifier of the token.
card
mandatory
object
The details of the card.
cvv
optional
string
The card's CVV number.
notes
optional
object
Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scottyā€¯
.
Handy Tips
Know more about the
.To process a payment on the tokenised card on another PA/PG, you will need the token and relevant additional data for each token.
- The data required may vary for different networks.
- Use the API given below to obtain the token and the relevant data.
- You can pass this data to any PA/PG to process the payment.
id
mandatory
string
The unique identifier of the token whose details are to be fetched.
token_number
string
The unique reference number generated for the token. For example, 4016981500100002
.
cryptogram_value
string
The token cryptogram value.
token_expiry_month
integer
The token expiry month in mm
format.
token_expiry_year
integer
The token expiry year in yyyy
format.
cvv
amex only
integer
A dynamic 4-digit number printed on the front of the Amex
card. This cvv should be passed in the CVV field to your PA/PG for processing the payment.
Use this API to create a payment with token saved on another PA/PG.
amount
mandatory
integer
The payment amount you want to collect from the customer.
currency
mandatory
string
The 3-character ISO code of the currency. Here, it is INR
.
order_id
mandatory
string
The unique identifier of the order created for this payment. Create an order using the
mandatory
string
The customer's email address.
contact
mandatory
string
The customer's phone number.
method
mandatory
string
The payment method. Here, it is card
.
card
mandatory
object
The details of the card.
number
mandatory
string
If payment is made using an actual card, then this field should have the entire actual card number. If card number has spaces, Razorpay will trim them for further processing. If payment is made using a network token, then this field should have the token number. If token number has spaces, Razorpay will trim them for further processing.
expiry_month
mandatory
string
If payment is made using an actual card, then this field should have the 2-digit expiry month for the card. If payment is made using a network token, then this field should have the 2-digit expiry month for the token.
expiry_year
mandatory
string
If payment is made using an actual card, then this field should have the 2 or 4-digit expiry year for the card. If payment is made using a network token, then this field should have the 2 or 4-digit expiry year for the token.
cryptogram_value
mandatory
string
The cryptogram value for the token. This will be provided by the entity which provided the token. This field is mandatory if tokenised=true
only for Visa, Mastercard and Rupay. Do not pass this for Amex cards.
tokenised
optional
boolean
Indicates if the payment is made using tokenised card or actual card. Possible values:
true
: Passtrue
when you are making the payment using a token.false
(default): Passfalse
when you are making the payment using a card.
token_provider
mandatory
string
The name of the aggregator that provided the token. Possible values:
amex
axis_migs
cashfree
ccavenue
cybersource
first_data
fss
hdfc
mpgs
paysecure
paytm
payu
zaakpay
Visa
RuPay
MasterCard
last4
mandatory
string
The last four digits of the original card number.
provider_type
optional
string
The type of provider through which the token was created. Possible values:
network
issuer
service_provider_token_data
mandatory for diners
object
Token service provider data created by the network/issuer.
requestor_id
string
The tr_merchant_id
provided by HDFC.
reference_number
string
The token reference number provided by HDFC.
cvv
string
The card's CVV number. For Amex tokenised cards, this will be a dynamic CVV provided by Amex for every payment on the tokenised card. Dynamic CVV is valid for about 20 minutes.
Handy Tips
- CVV is not required by default for tokenised cards across all networks.
- CVV is optional for tokenised card payments. Do not pass dummy CVV values.
- To implement this change, skip passing the
cvv
parameter entirely, or pass anull
or empty value in the CVV field. - We recommend removing the CVV field from your checkout UI/UX for tokenised cards.
- If CVV is still collected for tokenised cards and the customer enters a CVV, pass the entered CVV value to Razorpay.
notes
optional
object
Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scottyā€¯
.
Handy Tips
Know more about the
.If you are using Razorpay to process the first payment from a new card, do not call the tokenisation API. Instead, initiate the existing Razorpay Payment API, with an additional parameter save=true
. This avoids two API requests and processes payments faster.
Use the following API to save card details while making a payment:
Redirect the customer to the URL given in the response to complete the authentication.
The token will be created only if the cardholder successfully completes 3ds authentication.
Use the Fetch Payment API to fetch the token.
Was this page helpful?
ON THIS PAGE