Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Cashfree’s Token Vault is an industry-leading solution that enables you to offer customers a secure save card functionality whilst remaining RBI compliant. The solution provides a fast and secure checkout experience that delivers higher conversion rates and improved payment success rates.
Saved card transactions have approximately 10% better success rates compared to guest checkout transactions.

​
Key benefits of Cashfree’s token vault

The following features make Cashfree’s Token Vault solution comprehensive:
  • Full compliance: Cashfree Payments is a certified and compliant Token Requestor supporting all card types and schemes (Visa, Mastercard, RuPay, AmEx, Diners).
  • Enhanced performance: Saved card payments deliver ~10% better success rates and increased conversions.
  • Seamless experience: Integration with CVV-Less and Native OTP features for frictionless checkout.
  • Interoperability: Support for cross-platform scenarios where you can save cards via one payment aggregator and process via another.

​
Tokenisation

Tokenisation is the process of replacing sensitive card details such as card number, expiry, and CVV with a unique, non-sensitive identifier called a token. This process ensures that actual card data is never stored or exposed during transactions.

​
Key concepts

Understanding these terms helps you implement tokenisation effectively:
  • Token Requestor: The merchant or payment gateway (like Cashfree Payments) that initiates tokenisation requests on behalf of merchants
  • Token Service Provider: The card network or issuing bank that generates and manages tokens
  • Token: A unique identifier specific to each combination of card, merchant, customer, and Token Requestor
Each token is cryptographically secure and can’t be reverse-engineered to reveal the original card details, unlike standard encryption methods.

​
Customer journey

The tokenisation process provides a seamless experience for customers across their payment lifecycle:

​
First-time payment with guest checkout

The initial tokenisation process works as follows:
  1. Customer enters full card details and consents to save the card
  2. Customer completes payment authentication using OTP
  3. Cashfree generates an Alt ID and cryptogram to process the transaction
  4. After successful transaction processing, Cashfree tokenises the card with the card network/issuer
  5. Cashfree receives the token and the card is saved for future use

​
Repeat payment with saved card

Subsequent payments use the saved token for enhanced security and speed:
  1. Saved cards appear at checkout with identifiers (last 4 digits, issuing bank, card network)
  2. Customer selects a previously saved card
  3. Cashfree fetches the token and generates a cryptogram from the network/issuer
  4. Customer completes OTP authentication
  5. Payment processes securely using the token without exposing actual card data

​
Integrating with Cashfree’s Token Vault

Cashfree offers different integration methods for its Token Vault:

​
Merchants with CF-hosted checkout

Merchants using Cashfree hosted checkout will be able to use tokenisation functionality with zero additional effort. It’s enabled by default for all checkout merchants, and Cashfree handles tokenisation and payment processing end-to-end.
  • Customers can save their card by opting for tokenisation on the checkout. The checkout also displays a nudge highlighting the benefits of saving the card.
  • For repeat customers there’s OTP based authentication for the first time, before displaying saved cards, for added layer of security.
  • Repeat customers can select a saved card and have a CVV-Less payment experience with just a single click!

​
Seamless merchants with merchant-hosted checkout

Merchants using the seamless flow, can integrate Cashfree’s Token Vault APIs with their platform. Once integrated, Cashfree Payments handles both saving cards and processing payments via saved cards.

​
Saving the card with Cashfree as Token Requestor

  • In the Create Order API, the merchant needs to pass customer_id, against which the token is generated and stored.
  • For card payments, request customer consent on the UI to save the card. In the Order Pay API, pass save_instrument: true. You can also add a nudge highlighting tokenisation benefits to encourage customers to save their card.
cURL
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__someidwhichislongandhasnumbers1232132andcharacterscn",
  "payment_method": {
    "card": {
      "channel": "link",
      "card_number": "4111111111111111",
      "card_expiry_mm": "06",
      "card_expiry_yy": "22",
      "card_cvv": "900",
      "card_holder_name": "Tushar Gupta"
    }
  },
  "save_instrument": true
}'
  • Cashfree first processes the plain card transaction via alt ID and cryptogram. If the transaction succeeds, Cashfree tokenises and saves the card. If the transaction fails, Cashfree does not attempt tokenisation or save the card, because a successfully authenticated transaction is a prerequisite for tokenisation.
  • You can also configure tokenisation webhooks to receive callbacks on whether the card was saved.

​
Using Cashfree as Token Requestor and processing payment via Cashfree

  • To display saved cards for a customer at checkout, call the Fetch All Saved Card Instruments API with customer_id. The response includes details for each saved card, such as card type, issuing bank, card scheme, and last 4 digits. Display these details at checkout so the customer can identify and select a card for payment.
  • To process a payment with a saved card, call the Order Pay API and pass the instrument_id from the Fetch All Saved Card Instruments response. Cashfree fetches the token and cryptogram for the selected card and processes the payment.
cURL
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
  "payment_method": {
    "card": {
      "channel": "link",
      "instrument_id": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10",
	  "card_cvv": "900" // Optional
    }
  }
}'
  • Saved cards don’t require CVV to process the payment. For a more seamless checkout experience, avoid collecting CVV for saved cards. For more information, refer to CVV-Less Card Payments.
CVV-less flow has approximately 5% better success rates for saved cards.

​
Using external Token Requestor and processing payment via Cashfree

  • Cashfree’s Token Vault solution is interoperable. If you use an external Token Requestor, you can still process those tokenised cards through Cashfree.
For external guest checkout transaction:
  • Once a customer enters a plain card at checkout, retrieve the alt ID and cryptogram from your Token Requestor.
  • In the Order Pay API, pass the alt id number, alt id expiry, cryptogram, and CVV generated by your Token Requestor against the plain card details. Cashfree uses the alt ID and cryptogram to process the payment.
cURL
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
  "payment_method": {
    "card": {
      "channel": "link",
      "card_number": "4111111111111111", // alt id number
      "card_expiry_mm": "03", // alt id expiry mm
      "card_expiry_yy": "26", // alt id expiry yy
      "cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
      "card_cvv": "900",
      "token_type": "NETWORK_GC_TOKEN",
      "card_holder_name": "Tushar Gupta", //optional
      "card_display": "3243", // optional
      "token_reference_id": "22457512314" // conditional, required only for diners
    }
  }
}'
For external saved card transaction:
  • To process a payment with a card saved through an external Token Requestor, fetch all saved cards from the Token Requestor and display them at checkout. After the customer selects a card, retrieve the token and cryptogram from your Token Requestor. Only the originating Token Requestor can generate the cryptogram required for transaction processing.
  • In the Order Pay API, pass the token number, token expiry, and cryptogram for the card the customer selected at checkout. Cashfree uses the token and cryptogram to process the payment.
cURL
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
  "payment_method": {
    "card": {
      "channel": "link",
      "card_number": "4111111111111111", // token number
      "card_expiry_mm": "03", // token expiry mm
      "card_expiry_yy": "26", // token expiry yy
      "cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
      "token_requestor_id": "22457512314", 
      "card_cvv": "900", // optional
      "card_holder_name": "Tushar Gupta" // optional
      "card_display": "3243" // optional
    }
  }
}'
  • Saved cards don’t require CVV to process the payment. For a more seamless checkout experience, avoid collecting CVV for saved cards. CVV is an optional field in the API request. For more information about the CVV-less flow, refer to CVV-Less Card Payments.

​
Using Cashfree as Token Requestor and processing payment externally

  • Cashfree’s Token Vault solution is interoperable. To process a payment with an external PA for a card saved with Cashfree, retrieve the token and cryptogram from Cashfree. Only Cashfree, as the Token Requestor, can generate the cryptogram required for transaction processing.
  • Call the Fetch All Saved Card Instruments API with customer_id to get details of all saved cards and display them at checkout.
  • Once the customer selects a card, call the Fetch Cryptogram for a Saved Card Instrument API with customer_id and instrument_id to get the cryptogram.
  • You can then use this token and cryptogram to process the payment with any Payment Aggregator.

​
FAQs

Merchants are allowed to store only the card BIN, last 4 digits of the actual card number, and card expiry.They can’t store the entire plain card number or CVV.
No. A successfully authenticated transaction is a pre-requisite for tokenising the card.
Yes. Cashfree’s token vault solution is interoperable.A token generated with one payment aggregator can be processed via any PA, provided that the same PA generates and provides the cryptogram from the card network. That token + cryptogram can then be used by any PA to process the payment.
No. Tokens aren’t portable due to the ecosystem limitations.
  • Merchants can continue using their existing token vault and get the token + cryptogram from it to process with Cashfree.
  • Or, merchants must ask customers to save cards again, which would then be stored in Cashfree’s token vault.
Yes. Cashfree offers a standalone, plug and play token vault solution.
  • The merchant can act as the Token Requestor by procuring their own TRID (Token Requestor ID) directly from the card networks.
  • Cashfree enables merchants to tokenise cards, generate and retrieve cryptograms, and process transactions seamlessly through any payment aggregator (including Cashfree).
  • This ensures flexibility whilst maintaining compliance with network tokenisation standards.