Token Vault

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_id shared in the create order request. Merchants need to ensure that they do not pass any PII as a part of customer_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"
}

API Overview

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

🚧Customer Id

Order pay

Pay and save card details

Payment for a saved card

Pay using a raw tokenized card

Fetch saved instruments

Get all saved cards for a customer

Get specific card for a customer

Delete saved Instrument

Fetch cryptogram for 3rd party processing

🚧
Customer Id