HomeGuidesAPI ReferenceStatus Page
Guides

India Network Tokenization

Suggest Edits

📘

This information only applies to merchants processing card payments locally in India.

New Card Details Storage Regulation in India

The Reserve Bank of India (RBI) mandated that merchants, Payment Gateways (PGs), and Payment Aggregators(PAs) can no longer store sensitive card data in their own infrastructure.

The only card information allowed to be stored for transaction tracking and reconciliation purposes, for all parties mentioned above, are the last four digits of the card number and the name of the card issuer.

From October 1st 2022, card integrations must comply with the new Reserve Bank of India (RBI) regulations restricting the storage of card data when processing payments in India.

What does tokenization mean?

Tokenization encrypts the sensitive card details into an alternate code called the ‘token’ that is not bound to any device but is mapped to a merchant and the actual saved card network.

Card networks such as Visa or Mastercard offer network tokens to replace the actual credit or debit card number for online payments. It reduces the risk of exposing sensitive card details such as card numbers while only the card networks can retain this information.

What dLocal has done about this

  • We have integrated with our respective acquiring/processing partners in India to implement the network tokenization feature in order to be compliant with the RBI Mandate.
  • We have also developed a Save card feature to enable the tokenization of existing and new cards to support the new regulation for merchants that are interested in integrating to our Save Card Feature in India.

What needs to be done to support the new regulation?

These requirements must be complete to implement network tokenization in India:

  • The consent of your customers must be requested in checkouts before saving their cards and this will require 2FA for authentication.
  • Adapt the current integration of saving cards with dLocal to be compliant with the new regulation.
  • Upon successful completion of implementation, perform tests with dLocal on Test Environment.
  • Upon successful tests on Test Environment, perform live tests with dLocal on Production Environment and go live.

Save card feature

🚧

This information only applies to merchants processing card payments locally in India.

Save card flow

Save cards with secure_payments

Mandatory parameters

Payer object

FieldDescription
name
emailRequired
phoneRequired

If you need more information about the Payer object, go to The Payer Object page.

Card object

FieldDescription
holder_nameCardholder's full name. Required if card_id not present.
number ​The card number, as a string without any separators. Required if card_id not present.
cvvCredit card verification value. Required.
expiration_monthTwo digit number representing the card's expiration month. Required if card_id not present.
expiration_yearFour digit number representing the card's expiration year. Required if card_id not present.
saveTrue to generate network token

If you need more information about the Payer object, go to The Card Object page.

Example request

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/secure_payments


{
    "amount": 120.00,
    "currency" : "INR",
    "country": "IN",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "document" : "53033315550",
        "phone": "9908734801",
        "user_reference": "12345",
        "address": {
            "state"  : "Rio de Janeiro",
            "city" : "Volta Redonda",
            "zip_code" : "27275-595",
            "street" : "Servidao B-1",
            "number" : "1106"
        }
    },
    "card":{
        "holder_name" : "Thiago Gabriel",
        "number" : "4111111111111111",
        "cvv" : "123",
        "expiration_month" : 10,
        "expiration_year" : 2040,
        "save" : true
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications",
    "callback_url": "http://merchant.com/callback" 
}

Synchronous response

{
 "id": "D-4-cf8eef6b",
 "amount": 120,
 "currency": "INR",
 "payment_method_id": "VD",
 "payment_method_type": "CARD",
 "payment_method_flow": "DIRECT",
 "country": "IN",
 "card": {
   "card_id": "CID-124c18a5",
   "brand": "VI",
   "last4": "1111",
   "status": "PENDING"
 },
 "three_dsecure" : { 
     "redirect_url" : "http://api.dlocal.com/three-ds/M-64356345634587b3495" 
  },
 "created_date": "2022-04-20T20:26:09",
 "status": "PENDING",
 "status_detail": "The payment is pending for 3ds authorization.",
 "status_code": "101",
 "order_id": "657434343",
 "notification_url": "http://merchant.com/notifications",
 "callback_url": "http://merchant.com/callback"
}

Asynchronous Payment Notification

{
 "id": "D-4-cf8eef6b",
 "amount": 120,
 "currency": "INR",
 "payment_method_id": "VD",
 "payment_method_type": "CARD",
 "payment_method_flow": "DIRECT",
 "country": "IN",
 "created_date": "2022-04-20T20:26:09",
 "status": "PAID",
 "status_detail": "Paid.",
 "status_code": "200",
 "order_id": "657434343",
 "notification_url": "http://merchant.com/notifications",
 "callback_url": "http://merchant.com/callback"
}

Expected Errors

StatusCodeMessageDescription
REJECTED5003Country not supportedMerchant use secure_cards to store a card in India.
REJECTED5008Token not found or inactiveUse a card_id that was stored before new regulation support.

Asynchronous Card Notification

{
 "card_id": "CID-124c18a5",
 "brand": "VI",
 "last4": "1111",
 "status": "ACTIVE"
}

Use Card Token

Mandatory parameters

Payer object

FieldDescription
namePayer's name. Required.
documentPayer's document. Required.
emailPayer's email address. Required.
phonePayer's phone. Required.

If you need more information about the Payer object, go to The Payer Object page.

Card object

FieldDescription
cvvCredit card verification value. Required.
card_idCredit card id returned when creating network token.

If you need more information about the Payer object, go to The Card Object page.

Example request

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/payments

{
    "amount": 120.00,
    "currency" : "INR",
    "country": "IN",
    "payment_method_id" : "VD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "document" : "53033315550",
        "phone": "9908734801",
        "user_reference": "12345",
        "address": {
            "state"  : "Rio de Janeiro",
            "city" : "Volta Redonda",
            "zip_code" : "27275-595",
            "street" : "Servidao B-1",
            "number" : "1106"
        }
    },
    "card":{
         "card_id" : "CID-124c18a5-874d-4982-89d7-b9c256e647b5",
         "cvv" : "123"
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications",
    "callback_url": "http://merchant.com/callback" 
}

Synchronous Response

{
 "id": "D-4-cf8eef6b",
 "amount": 120,
 "currency": "INR",
 "payment_method_id": "VD",
 "payment_method_type": "CARD",
 "payment_method_flow": "DIRECT",
 "country": "IN",
 "card": {
   "card_id": "CID-124c18a5",
   "brand": "VI",
   "last4": "1111",
   "status": "ACTIVE"
 },
 "three_dsecure" : { 
     "redirect_url" : "http://api.dlocal.com/three-ds/M-64356345634587b3495" 
  },
 "created_date": "2022-04-20T20:26:09",
 "status": "PENDING",
 "status_detail": "The payment is pending for 3ds authorization.",
 "status_code": "101",
 "order_id": "657434343",
 "notification_url": "http://merchant.com/notifications",
 "callback_url": "http://merchant.com/callback"
}

Get card information

Example request

curl -X GET \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/cards/CID-124c18a5-874d-4982-89d7-b9c256e647b5?country=IN

Synchronous Response

{
    "card_id": CID-124c18a5-874d-4982-89d7-b9c256e647b5,
    "holder_name": NULL,
    "expiration_month": NULL,
    "expiration_year": NULL,
    "last4": "1111",
    "brand": "VI"
}

Delete card information

curl -X DELETE \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/cards/CID-124c18a5-874d-4982-89d7-b9c256e647b5?country=IN

Synchronous Response

{
    "card_id": "CID-124c18a5-874d-4982-89d7-b9c256e647b5",
    "deleted": true
}

IPN for Card status notification

It is common that the card_id obtained from the synchronous response of a payment with save as true, shows status=PENDING. This happens because the card can take up to 10 minutes to be tokenized.

When the card becomes active the merchant will be notified and the card_id is ready to be used for future payments.

The notification URL can be set by:

  • Merchants indicating a special URL on their side to which dLocal will send status notifications with the body shown below (card_notification_url).
  • If there is no card_notification_url defined, the notification will reach the same notification_url where the associated payment that gave rise to the creation of the card_id is notified.
  • If there is no URL indicated in the payment, then it will try to notify the global URL of notifications that the merchant has.

In case of not being able to deliver the notification at its destination, it will be retried every hour for 7 days. If you do not receive the notification, you will always have the option to use the Get Card endpoint.

IPN notification payload

{
    "card_id": "CID-124c18a5-874d-4982-89d7-b9c256e647b5",
    "brand": "VI",
    "last4": "0136",
    "status": "ACTIVE"
}

Updated over 1 year ago

© 2024 DLOCAL. ALL RIGHTS RESERVED

Dlocal LLP (Company Number UK OC413287) is a limited liability partnership incorporated in England and Wales. DLocal Limited (Company Registration Number C77538) is authorised by the Malta Financial Services Authority under the Financial Institutions Act for the issuance of electronic money and the provision of payment services. Dlocal Corp LLP (Company Number UK OC 424987) is registered as a Money Service Business (MSB) with Financial Crime Enforcement Network in United States of America (USA) under MSB Registration Numbers 31000193620515. Dlocal Corp LLP acts as agent of e-commerce merchants based in the USA, and collects payments from end users based in emerging markets, on behalf of the merchants.