📘
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

Field	Description
`name`
`email`	Required
`phone`	Required

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

Card object

Field	Description
`holder_name`	Cardholder'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.
`cvv`	Credit card verification value. Required.
`expiration_month`	Two digit number representing the card's expiration month. Required if `card_id` not present.
`expiration_year`	Four digit number representing the card's expiration year. Required if `card_id` not present.
`save`	`True` 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

Status	Code	Message	Description
`REJECTED`	`5003`	Country not supported	Merchant use `secure_cards` to store a card in India.
`REJECTED`	`5008`	Token not found or inactive	Use 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

Field	Description
`name`	Payer's name. Required.
`document`	Payer's document. Required.
`email`	Payer's email address. Required.
`phone`	Payer's phone. Required.

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

Card object

Field	Description
`cvv`	Credit card verification value. Required.
`card_id`	Credit 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"
}