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

25042504

Typical token onboarding architecture

Juspay Managed Consent

10551055

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.

38763876

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 parameterFlow
trueConsent webpage will not be shown and at the end of transaction, card will be tokenized with card network
falseConsent webpage will not be shown and at the end of transaction, card will be not tokenized with card network
nullConsent 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

NameFormatDescription
tokenization_user_consentbooleanTells if the consent was given by user to tokenize the card.
tokenJSONThe details of token generated. Present only if the token is generated at end of 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
Optional in case of certain networks.
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, offers etc.
Optional in case of certain networks.
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. 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

FlowOrder 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

NameFormatDescription
tokenization_user_consentbooleanTells if the consent was given by user to tokenize the card.
tokenJSONThe details of token generated. Present only if the token is generated at end of 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
Optional in case of certain networks.
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, offers etc.
Optional in case of certain networks.
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.

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