Token repeat transaction flow

Token transactions

The token transaction will be processed exactly as saved card transaction is processed. There will be no change in merchant integration


Saved token transaction

1. List the stored card

Call List Card API to show the cards on Payment Page, the same API will also give the tokenized cards in the current format.

2. Show card to user

The card_number parameter is used to show the masked card information to the user. Currently the format for this field is "4012-XXXXXXXX-9454", once repeat token transaction is enabled for the merchant the format will change to "XXXX-XXXXXXXX-9454".

End users are not exposed to tokens, they will still see card details on payment page. Hence, the card_expiry and card_last_four digits will still be stored even after card is tokenized.

3. Start Transaction

There is no change in /txns API for a stored token transactions.

API specification

List Card API

curl --location --request GET '' \
--header 'Authorization: Basic RjJEMTU0QkNBRkY0NkY4QjE0MUQ5REZBREZCNkZBOg==' \
   "customer_id": "cth_6MXbUUSECcxrswgT",
   "merchantId": "paypal",
   "cards": [
           "card_token": "tkn_d5de7e878465407a9a8ad8d71b58923e",
           "card_reference": "d1714874aa102eb8bc933b8f26992225",
           "card_number": "XXXX-XXXXXXXX-9454",
           "card_isin": "123456",
           "card_exp_year": "2025",
           "card_exp_month": "02",
           "card_type": "DEBIT",
           "card_issuer": "HDFC Bank",
           "card_brand": "MASTERCARD",
           "nickname": "",
           "name_on_card": "Imdad",
           "expired": false,
           "card_fingerprint": "4ip95rsikuprlcojscp3p0b7pq",
           "juspay_bank_code": "JP_HDFC",
           "card_sub_type": "NA",
           "card_issuer_country": "INDIA",
             "tokenize_support": false,
           "provider_category": "VAULT",
           "provider": "JUSPAY"
provider_categoryStringCard storage provider category. Example: VAULT | NETWORK_TOKEN | ISSUER_TOKEN
providerStringProvider's name. Example: JUSPAY | VISA | SODEXO


New masked card format

After Token Repeat Transactions are enabled for merchant_id then for all cards (tokenized/ non tokenized) the List Card API will return back card_number in new masked format.
This is to ensure consistency on UI for the end user

/txns API

There is not change in the /txns API for a current saved card vs a saved token flow

curl -X POST \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=CARD" \
-d "card_token=:card_token" \
-d "card_security_code=111" \
-d "redirect_after_payment=true" \
-d "format=json"
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "GET",
       "url": ""

Order Status API

In the existing card block merchant will receive two new parameters using_token = true and a new token block. Merchant will continue to receive all other existing parameter.

If there is a use case to show the Payment Instrument used then card. last_four_digits should be used.

curl \
-u your_api_key: \
-H 'version: 2018-10-25' \
-H 'Content-Type: application/x-www-form-urlencoded'\
-H 'x-merchantid: merchant_id'
  "card": {
    "expiry_year": "2023",
    "saved_to_locker": false,
    "expiry_month": "06",
    "name_on_card": "test",
    "card_issuer": "Axis Bank",
    "last_four_digits": "5449",
    "using_saved_card": true,
    "card_fingerprint": "41d30s3jus955dj9yyhe5is91",
    "card_isin": "526731",
    "card_type": "DEBIT",
    "card_brand": "MASTERCARD",
    "card_sub_type": null,    
    "using_token": "true",
    "token": {
      "card_reference": "77efb38f3721930e60dby754865619",
      "last_four_digits": "5449",
      "card_fingerprint": "41d30s3jus955dj9yyhe5is91",
      "card_isin": "525876",
      "expiry_year": "2023",
      "expiry_month": "06",
      "par": "6fgd63jus955dj9yyheg4gh6",
      "tokenization_status": "SUCCESS"

Order Status extra fields descriptin

using_tokenbooleantrue if the transaction was done via token, else false
tokenJSONtoken block is sent back to merchant if it was a saved token transaction
token.card_referenceStringJuspay's permanent reference to the token generated.
token.last_four_digitsStringToken's last four. Should not be shown to the user. If there is a requirement then card's last_four_digits should be shown
token.card_fingerprintStringA string that uniquely identifies the card/tpken across the board. When the same card/token is stored across multiple accounts, same fingerprint will be returned. This can be used to identify duplicates.
token.card_isinStringToken's BIN. Should not be shown to user. Can be used for routing etc
token.expiry_yearStringToken's expiry year. This can be different from card's expiry year. Merchant should still use card's expiry year
token.expiry_monthStringToken's expiry month. This can be different from card's expiry month. Merchant should still use card's expiry month
token.parStringThe PAR value as is received from the network. Can be used to check uniqueness of cards for use case of Offers, EMI etc.
token.tokenization_statusStringThe current status of token.


The extra parameters/blocks added in Order Status API will be added in webhooks also.

What’s Next

Please visit FAQ for all the questions around tokenization