Token Vault
Cashfree Token Vault helps you store your card credentials in a secure manner. For further processing, we create network tokens for these saved cards
With Token Vault, merchants can generate and store card tokens as a part of the save cards process. Merchants would also be able to fetch the saved cards (tokens) for a customer and display them to the customer to initiate subsequent transactions through saved cards. Cashfree Payments tokens are also interoperable, which means cards saved (tokenized) through us can be used to initiate payment through any payment processor.
API Overview
| API Name | Use Case |
|---|---|
| Create Order | To create an order for which card payments can be processed along with save card request for a customers |
| Order Pay | To save instrument (card) while processing payment for an order |
| Order Pay | To process payment for an order using instrument id of saved instruments (card) |
| Order Pay | To process payments using the card network token, token expiry and cryptogram |
| Fetch Saved Instruments | To get all saved instruments for a customer id |
| Fetch a saved Instrument | To get specific saved instrument for a customer id and instrument id |
| Delete a Saved Instrument | To delete saved instrument using the instrument id |
| Fetch cryptogram | To get the card network token, token expiry and cryptogram for a saved instrument using instrument id |
Save Instrument Workflow
Process payment through saved instrument workflow
Create Order
To create an order for which card payments can be processed along with save card request for a customers
In order to accept payments from customers, merchants first need to create an order with Cashfree Payments. The cards would be saved while processing payment for an order hence creating order is a necessary step in tokenizing and storing cards.
Customer Id
The tokenized cards would be stored for the
customer_idshared in the create order request. Merchants need to ensure that they do not pass any PII as a part ofcustomer_id.
See the detailed request for creating an order here.
Order pay
Pay and save card details
Merchant needs to pass save_instrument as true after taking consent from the customer. Cashfree will send generate token request to the card networks. On receiving the consent Cashfree will first process the payment and complete 2FA before sending token generation request to the card networks. If 2FA is not completed, that is if the payment for the order is not successful, Cashfree will not send token provisioning request to card networks and hence the card would not be tokenized.
curl --location --request POST 'https://sandbox.cashfree.com/pg/orders/sessions' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <<x-api-version>>' \
--header 'x-request-id: sIP3A1Vi9swEi8KF02cU' \
--data-raw '{
"payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD",
"payment_method": {
"card": {
"channel": "link",
"card_number": "4893274242424243",
"card_holder_name": "Tushar Gupta",
"card_expiry_mm": "06",
"card_expiry_yy": "22",
"card_cvv": "900"
}
},
"save_instrument": true
}
'
{
"payment_method": "card",
"channel": "link",
"action": "link",
"data": {
"url": "https://sandbox.cashfree.com/pg/view/gateway/BKNrBgLWeeFoGjschqa1req_h1omPvM0Yc",
"payload": null,
"content_type": null,
"method": null,
},
"cf_payment_id": 622739106
}
Payment for a saved card
Merchant can fetch the saved cards for a customer, using the customer_id and display those in an appropriate format. If customers choose from any of those displayed saved cards, merchants will have to pass the corresponding instrument_id in the pg/orders/pay to initiate payments using the saved cards.
curl --location --request POST 'https://sandbox.cashfree.com/pg/orders/sessions' \
--header 'Content-Type: application/json' \
--header 'x-api-version: 2021-05-21' \
--data-raw '{
"payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD",
"payment_method": {
"card": {
"channel": "link",
"instrument_id": "b43a75c1-bfda-4781-85a1-67915a19fcb6",
"card_cvv": "900"
}
}
}
'
{
"payment_method": "card",
"channel": "link",
"action": "link",
"data": {
"url": "https://sandbox.cashfree.com/pg/view/gateway/BNrBgLWeeFoGjschqa1req_h1omPvM0Yc",
"payload": null,
"content_type": null,
"method": null,
},
"cf_payment_id": 622739106
}
Pay using a raw tokenized card
If the merchant has implemented their own token generation and cryptogram generation process outside of Cashfree Payments, then they can use the pg/orders/pay api to process tokenized card payments using card networks tokens as mentioned in the below API.
curl --location --request POST 'https://sandbox.cashfree.com/pg/orders/sessions' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <<x-api-version>>' \
--header 'x-request-id: sIP3A1Vi9swEi8KF02cU' \
--data-raw '{
"payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD",
"payment_method": {
"card": {
"channel": "link",
"card_number": "4893274242424243",
"card_holder_name": "Tushar Gupta",
"card_expiry_mm": "03",
"card_expiry_yy": "26",
"cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
"card_cvv": "900",
"token_requestor_id": "22457512314",
"card_display": "1234"
}
}
}
'
{
"payment_method": "card",
"channel": "link",
"action": "link",
"data": {
"url": "https://sandbox.cashfree.com/pg/view/gateway/BNrBgLWeeFoGjschqa1req_h1omPvM0Yc",
"payload": null,
"content_type": null,
"method": null,
},
"cf_payment_id": 622739106
}
Fetch saved instruments
Get all saved cards for a customer
If a customer comes to the merchant platform to initiate a payment through already saved card with Cashfree Payments, then merchant should fetch all the saved cards using the customer_id associated with the customer.
curl --location --request GET 'https://sandbox.cashfree.com/pg/customers/customer001/instruments?instrument_type=card' \
--header 'Content-Type: application/json' \
--header 'X-client-id: <CLIENT_ID>' \
--header 'X-client-secret: <SECRET_KEY>' \
--header 'x-api-version: <<x-api-version>'
[
{
"instrument_id": "0ce6dc4c-b2d6-4adf-8307-22db4712e008",
"instrument_type": "card",
"instrument_uid": "046b6362289c49ce2f984af5bbaa66baa4d9693fdc528904f0486c034f5ac047",
"instrument_display": "XXXXXXXXXXXX5759",
"instrument_meta": {
"card_network": "visa",
"card_bank_name": "KOTAK MAHINDRA BANK",
"card_country": "IN",
"card_type": "debit_card",
"card_token_details": null
},
"instrument_status": "ACTIVE",
"created_at": "2022-02-22T09:13:06.000+00:00",
"afa_reference": "1343199",
"customer_id": "customer001"
}
]
Get specific card for a customer
curl --location --request GET 'https://sandbox.cashfree.com/pg/customers/customer001/instruments/b43a75c1-bfda-4781-85a1-67915a19fcb6' \
--header 'Content-Type: application/json' \
--header 'X-client-id: <CLIENT_ID>' \
--header 'X-client-secret: <SECRET_KEY>' \
--header 'x-api-version: <<x-api-version>>'
{
"instrument_id": "0ce6dc4c-b2d6-4adf-8307-22db4712e008",
"instrument_type": "card",
"instrument_uid": "046b6362289c49ce2f984af5bbaa66baa4d9693fdc528904f0486c034f5ac047",
"instrument_display": "XXXXXXXXXXXX5759",
"instrument_meta": {
"card_network": "visa",
"card_bank_name": "KOTAK MAHINDRA BANK",
"card_country": "IN",
"card_type": "debit_card",
"card_token_details": null
},
"instrument_status": "ACTIVE",
"created_at": "2022-02-22T09:13:06.000+00:00",
"afa_reference": "1343199",
"customer_id": "customer001"
}
Delete saved Instrument
If the customers wants to delete an already saved card, then merchant can call the delete instrument API using the instrument_id of the saved card.
curl --location --request DELETE 'https://sandbox.cashfree.com/pg/customers/customer001/instruments/b43a75c1-bfda-4781-85a1-67915a19fcb6' \
--header 'Content-Type: application/json' \
--header 'X-client-id: <CLIENT_ID>' \
--header 'X-client-secret: <SECRET_KEY>' \
--header 'x-api-version: <<x-api-version>>'
{
"instrument_id": "0ce6dc4c-b2d6-4adf-8307-22db4712e008",
"instrument_type": "card",
"instrument_uid": "046b6362289c49ce2f984af5bbaa66baa4d9693fdc528904f0486c034f5ac047",
"instrument_display": "XXXXXXXXXXXX5759",
"instrument_meta": {
"card_network": "visa",
"card_bank_name": "KOTAK MAHINDRA BANK",
"card_country": "IN",
"card_type": "debit_card",
"card_token_details": null
},
"instrument_status": "INACTIVE",
"created_at": "2022-02-22T09:13:06.000+00:00",
"afa_reference": "1343199",
"customer_id": "customer001"
}
Fetch cryptogram for 3rd party processing
Merchants can fetch the card network token, token expiry and cryptogram along with other details required for processing transactions using card network tokens. The fetch cryptogram request initiated for an instrument_id of the card saved with Cashfree Payments will return these details in response. The fetch cryptogram request should ideally be initialised only if merchant wants to process transactions outside Cashfree Payments PG.
curl --location --request GET 'https://sandbox.cashfree.com/pg/customers/customer001/instruments/b43a75c1-bfda-4781-85a1-67915a19fcb6/cryptogram' \
--header 'Content-Type: application/json' \
--header 'X-client-id: <CLIENT_ID>' \
--header 'X-client-secret: <SECRET_KEY>' \
--header 'x-api-version: <<x-api-version>>'
{
"instrument_id": "b43a75c1-bfda-4781-85a1-67915a19fcb6",
"token_requestor_id": "22457512314",
"card_number": "4893274242424243",
"card_expiry_mm": "06",
"card_expiry_yy": "2025",
"cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
"card_display": "1234"
}
Updated about 1 year ago