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

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 'https://sandbox.juspay.in/cards?customer_id=cth_6MXbUUSECcxrswgT' \
--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"
       }
   ]
}

Name	Format	Description
provider_category	String	Card storage provider category. Example: VAULT \| NETWORK_TOKEN \| ISSUER_TOKEN
provider	String	Provider'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 https://api.juspay.in/txns \
-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": "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507"
     }
   }
}

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 https://api.juspay.in/orders/order1631087270 \
-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

Name	Format	Description
using_token	boolean	true if the transaction was done via token, else false
token	JSON	token block is sent back to merchant if it was a saved token transaction
token.card_reference	String	Juspay's permanent reference to the token generated.
token.last_four_digits	String	Token'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_fingerprint	String	A 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_isin	String	Token's BIN. Should not be shown to user. Can be used for routing etc
token.expiry_year	String	Token's expiry year. This can be different from card's expiry year. Merchant should still use card's expiry year
token.expiry_month	String	Token's expiry month. This can be different from card's expiry month. Merchant should still use card's expiry month
token.par	String	The 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_status	String	The current status of token.

Webhook

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

Token transactions

1. List the stored card

2. Show card to user

3. Start Transaction

API specification

🚧New masked card format

🚧
New masked card format