Token onboarding flow

Token onboarding or Token generation can be done during two flows:

  1. Add Card flow
  2. Existing Saved Card flow

This onboarding flow is applicable to both.

RBI has mandated that explicit user consent should be taken for token generation. Forced consent / default checkbox are no longer applicable.
For the existing stored cards (card-on-file), bulk migration CANNOT be done.

User consent and AFA (additional factor of authentication) are mandatory for tokenizing a card.

To seamlessly without any integration effort from Merchant's end, Juspay manages consent and 2FA during the first transaction of a customer once tokenization is enabled for the merchant.

Onboarding architecture

Typical token onboarding architectureTypical token onboarding architecture

Typical token onboarding architecture

Juspay Managed Consent

Juspay consent flow - sampleJuspay consent flow - sample

Juspay consent flow - sample

In current transaction flow, user will be asked for tokenization consent on the webpage before the bank page loads. Consent page would support both mobile, web and landscape form factors.

The same consent page will be shown for both saved card and new card entry.

📘

Enable tokenization

Please contact your Juspay KAM to enable Juspay managed consent and tokenization configurations.

Merchant managed consent

In the case that Merchant wishes to design and take this consent themselves, they may do so after signing an agreement with Juspay to take onus of tokenizing cards only after user consent, as this is mandated by the RBI.

Transaction Flow when Consent is taken by MerchantTransaction Flow when Consent is taken by Merchant

Transaction Flow when Consent is taken by Merchant

The Transaction Flow changes required when Merchant is taking consent themselves are listed below:

1. Check for eligibility

New card flow
The Card Info API will give one extra parameter in response (tokenize_support) which signifies if the card BIN can be tokenized.

Stored card flow
The List Card API will give one extra parameter in response (tokenize_support) which signifies if that card entry can be tokenized.

2. Take user consent

Merchant to show the consent UI to user according to the response of Card Info API / List Card API.

3. Start the transaction

Send a new parameter (tokenize = true / false) in /txns API according to user preference given in consent UI.

Value of tokenize parameter

Flow

true

Consent webpage will not be shown and at the end of transaction, card will be tokenized with card network

false

Consent webpage will not be shown and at the end of transaction, card will be not tokenized with card network

null

Consent webpage will be shown in case Juspay_web_consent is enabled for the merchant.

📘

Support of existing card storage

Pass save_to_locker = true for tokenize = true to support existing stored card flows, till the RBI mandate on stored card kicks in.

📘

Out of band tokenization

Merchant can also introduce consent flows on payment management screen. After collecting consent a penny rupee transaction has to be done to tokenize the saved card.

API Specification

Card Info API
For details about existing specification: specification

curl --location --request GET 'https://sandbox.juspay.in/cardbins/541919?options.check_mandate_support=true&merchant_id=bbstaging&options.check_atm_pin_auth_support=true&options.check_direct_otp_support=true&options.check_tokenize_support=true'
{
   "id": "541919",
   "object": "cardbin",
   "brand": "MASTERCARD",
   "bank": "HDFC Bank",
   "country": "INDIA",
   "type": "DEBIT",
   "card_sub_type": "PLATINUM",
   "juspay_bank_code": "JP_HDFC",
   "tokenize_support”: true
}

List Card API
For details about existing request parameters: specification

curl --location --request GET 'https://sandbox.juspay.in/cards?customer_id=cth_6MXbUUSECcxrswgT' \
--header 'Authorization: Basic RjJEMTU0QkNBRkY0NkY4QjE0MUQ5REZBREZCNkZBOg==' \
{
    "customer_id": "cth_6MXbUUSECcxrswgT",
    "merchantId": "guest",
    "cards": [{
            "card_token": "tkn_24c960735fd64cb9b8c0221102392914",
            "card_reference": "e46b3e15384db06d446fed103cfeec24",
            "card_number": "4335-XXXXXXXX-2216",
            "card_isin": "433587",
            "card_exp_year": "2023",
            "card_exp_month": "04",
            "card_type": "CREDIT",
            "card_issuer": "SBI",
            "card_brand": "VISA",
            "nickname": "",
            "name_on_card": "name",
            "expired": false,
            "card_fingerprint": "6uvve3h71mpgrr88848hr4vsat",
            "juspay_bank_code": "JP_SBI",
            "card_sub_type": "NA",
            "card_issuer_country": "INDIA",
            "tokenize_support": false,
            "provider_category": "CONTAINER",
            "provider": "JUSPAY",
            "token": {
                "card_reference": "e46b3e15384db06d446fed103cfeec24",
                "last_four_digits": null,
                "card_fingerprint": "6uvve3h71mpgrr88848hr4vsat",
                "card_isin": "441962",
                "expiry_month": "04",
                "expiry_year": "2023",
                "par": "4ufhxxw6uvve3h71mpgrr88848hr4vsat23r",
                "tokenization_status": "ACTIVE"
            }
        }]
}

Field level description

Name

Format

Description

tokenization_user_consent

boolean

Tells if the consent was given by user to tokenize the card.

token

JSON

The details of token generated. Present only if the token is generated at end of 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
Optional in case of certain networks.

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, offers etc.
Optional in case of certain networks.

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. INITIATED | ACTIVE | INACTIVE | SUSPENDED

/txns API

  1. New Card
    For details about existing specification: specification
curl --location --request POST 'https://api.juspay.in/txns' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'order_id=null' \
--data-urlencode 'merchant_id={{merchant_id}}' \
--data-urlencode 'payment_method_type=CARD' \
--data-urlencode 'payment_method=CARD' \
--data-urlencode 'card_number=4242424242424242' \
--data-urlencode 'card_exp_month=07' \
--data-urlencode 'card_exp_year=24' \
--data-urlencode 'name_on_card=Juspay' \
--data-urlencode 'card_security_code=111' \
--data-urlencode 'save_to_locker=true' \
--data-urlencode 'redirect_after_payment=true' \
--data-urlencode 'format=json' \
--data-urlencode 'tokenize=true'\
{
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "GET",
       "url": "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507"
     }
   }
}
  1. Saved Card
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 "tokenize=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

The "card" block in existing Order Status API will also have the parameters tokenization_user_consent and token JSON block

For details about existing specification: specification

Flow

Order Status API response

Merchant enabled for tokenization, user gives consent (either on Juspay webpage or merchant page)

"tokenization_user_consent" and "token_created" are sent back to merchant

Merchant enabled for tokenization, user rejects consent (either on Juspay webpage or merchant page)

"tokenization_user_consent" is sent back to merchant

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,
        "tokenization_user_consent": true,
    "token": {
      "card_reference": "77efb38f3721930e60dby754865619",
      "last_four_digits": "7656",
      "card_fingerprint": "41d30s3jus955dj9yyhe5is91",
      "card_isin": "525876",
      "expiry_year": "2023",
      "expiry_month": "06",
      "par": "6fgd63jus955dj9yyheg4gh6",
      "tokenization_status": "ACTIVE"
    },
        "using_token": false
    }
}

Field level description

Name

Format

Description

tokenization_user_consent

boolean

Tells if the consent was given by user to tokenize the card.

token

JSON

The details of token generated. Present only if the token is generated at end of 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
Optional in case of certain networks.

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, offers etc.
Optional in case of certain networks.

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.

INITIATED | ACTIVE | INACTIVE | SUSPENDED

Webhook

The new fields added in Order Status API will be also sent in the current webhooks


What’s Next

Next section describes transaction flow using token

Did this page help you?