HomeGuidesAPI ReferenceStatus Page
Guides

India Recurring Wallet Payments

Learn how to manage mandates.

Suggest Edits

dLocal can help merchants deal with the complexity of mandate management in India for recurring wallet payments.

This documentation will explain how to create a mandate (subscription), and how to charge users on a recurring basis, with variable amounts.

Flow Diagram

3538

Flow Overview

Subscription Creation

  1. The user initiates the subscription registration on the merchant's site.
  2. The merchant triggers the Create a subscription method in dLocal’s API, including information such as subscription frequency, and start/end date.
  3. dLocal will respond with a URL which the merchant will use to redirect the user to dLocal’s hosted payment page.
  4. There, the user will select the payment method, and complete the authentication process with the issuer.
  5. Once the issuer approved the authentication, the merchant will receive a confirmation via API, alongside a subscription_id.

Go to Create a subscription.

Recurring Charge

  1. The merchant is required to trigger the pre-notification (aka pre-debit notification) 24 hours prior to the payment due date through dLocal’s API, specifying the amount to charge (up to 15k INR). dLocal will return an asynchronously ACK message while the issuer confirms the pre-notification.
  2. Once the issuer confirms the pre-notification, dLocal will notify the merchant via API.
  3. 24 hours later, dLocal will automatically trigger the charge (aka mandate execution).
  4. Once the charge is successful, dLocal will notify the merchant via API.

Go to Recurring payments.

Retries (Optional)

  1. In case the charge is rejected, the merchant has the option to retry the payments via dLocal’s API, without performing the pre-notification again. dLocal will return an asynchronously ACK message while the issuer confirms the charge.
  2. Once the issuer confirms the charge, dLocal will notify the merchant via API.

Go to Retry payments

Create a subscription

Generate a subscription with all the settings you need.

Subscription Creation Flow

  1. The user initiates the subscription registration on the merchant's site.
  2. The merchant triggers the Create a subscription method in dLocal's API, including information such as subscription frequency, and start/end date.
  3. dLocal will respond with a URL which the merchant will use to redirect the user to dLocal's hosted payment page.
  4. There, the user will select the payment method, and complete the authentication process with the issuer.
  5. Once the issuer approved the authentication, the merchant will receive a confirmation via API, alongside the subscription ID in the wallet.token field.

3538

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": 0,
   "currency": "INR",
   "country": "IN",
   "payment_method_id": "IR",
   "payment_method_flow": "REDIRECT",
   "payer": {
       "name": "Ram Devi",
       "email": "[email protected]",
       "phone": "+919000123456",
       "document": "HSECT4378A",
       "address": {
            "country": "IN",
            "state": "Goa",
            "city": "Calangute",
            "street": "Maddo Vaddo",
            "number": "1207"
        }
   },
   "wallet": {
       "save": true,
       "verify": true,
       "recurring_info": {
           "subscription_frequency_unit": "MONTH",
           "subscription_frequency": 1,
           "subscription_start_at": "20210101",
           "subscription_end_at": "20220101"
       },
       "capture": false
   },
   "order_id": "5346523564",
   "notification_url": "http://merchant.com/notifications",
   "callback_url": "http://merchant.com/callback"
}

Synchronous Response

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 0,
   "currency": "INR",
   "payment_method_id": "IR",
   "payment_method_type": "WALLET",
   "payment_method_flow": "REDIRECT",
   "country": "IN",
   "created_date": "2018-12-26T20:37:20.000+0000",
   "status": "PENDING",
   "status_detail": "The payment is pending",
   "status_code": "100",
   "order_id": "5346523564",
   "notification_url": "http://merchant.com/notifications",
   "redirect_url": "https://api.dlocal.com/collect/pay/pay/M-0aa0cc00-094e-11e9-9f92-dbdad3ad0963?xtid=CATH-ST-1545856640-602791137"
}

✅

Complete authentication

The user shall be redirected to the redirect_url to complete the authentication.

Asynchronous notifications

When there is a change of status in the subscriptions, we will send you a notification to the provided notification_url indicating wallet.token.

The wallet.token it’s the subscription token that needs to be passed on each recurring charge.

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 0.00,
   "status": "VERIFIED",
   "status_detail": "The wallet was verified.",
   "status_code": "700",
   "currency": "INR",
   "country": "IN",
   "payment_method_id": "IR",
   "payment_method_type": "WALLET",
   "payment_method_flow": "REDIRECT",
   "payer": {
       "name": "Ram Devi",
       "email": "[email protected]",
       "phone": "+919000123456",
       "document": "HSECT4378A",
       "address": {
            "country": "IN",
            "state": "Goa",
            "city": "Calangute",
            "street": "Maddo Vaddo",
            "number": "1207"
        }
   },
   "wallet": {
       "token": "W-yu23y4ibnyiu23y4"
   },
   "order_id": "5346523564",
   "notification_url": "http://www.merchant.com/notifications",
   "created_date": "2018-12-26T20:37:20.000+0000"
}

Recurring payment

24 hours before the payment is due, the merchant must trigger the pre-debit notification (prenotification).

After the prenotification is approved by the issuer, the user will be notified that they will be charged the amount specified in the request. 24 hours after the prenotification is approved, dLocal will automatically trigger the charge.

Recurring payment flow

  1. For subscriptions with variable amounts, the merchant is required to trigger the pre-notification (aka pre-debit notification) 24 hours prior to the payment due date through dLocal's API, specifying the amount to charge (up to 5k INR). dLocal will return an asynchronously ACK message while the issuer confirms the pre-notification.
  2. Once the issuer confirms the pre-notification, dLocal will notify the merchant via API.
  3. 24 hours later, dLocal will automatically trigger the charge (aka mandate execution).
  4. Once the charge is successful, dLocal will notify the merchant via API.

The amount can change from payment to payment, as long as it’s under 5k INR.

3538

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": 750,
   "currency": "INR",
   "country": "IN",
   "payment_method_id": "IR",
   "payment_method_flow": "DIRECT",
   "payer": {
       "name": "Ram Devi",
       "email": "[email protected]",
       "phone": "+919000123456",
       "document": "HSECT4378A",
       "address": {
            "country": "IN",
            "state": "Goa",
            "city": "Calangute",
            "street": "Maddo Vaddo",
            "number": "1207"
        }
   },
   "wallet": {
       "token": "W-yu23y4ibnyiu23y4",
       "recurring_info": {
           "prenotify": TRUE
       }
   },
   "order_id": "5346523565",
   "notification_url": "http://merchant.com/notifications"
}

Synchronous Response

1. Prenotify approved by issuer

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 750.00,
   "currency": "INR",
   "payment_method_id": "IR",
   "payment_method_type": "WALLET",
   "payment_method_flow": "DIRECT",
   "country": "IN",
   "created_date": "2018-12-26T20:37:20.000+0000",
   "status": "PENDING",
   "status_detail": "The payment is pending",
   "status_code": "100",
   "order_id": "5346523565",
   "notification_url": "http://merchant.com/notifications",
   "recurring_info": {
        "prenotify_approved": TRUE
    }
}

Asynchronous notification

2. Payment success

Should be received 24hs after the prenotify has been approved.

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 750.00,
   "currency": "INR",
   "payment_method_id": "IR",
   "payment_method_type": "WALLET",
   "payment_method_flow": "DIRECT",
   "country": "IN",
   "created_date": "2018-12-26T20:37:20.000+0000",
   "status": "PAID",
   "status_detail": "The payment was paid",
   "status_code": "200",
   "order_id": "5346523565",
   "notification_url": "http://merchant.com/notifications",
   "recurring_info": {
        "prenotify_approved": TRUE
    }
}

Retry payments

In case the charge failed (after a successful prenotification), the merchant can retry the payment up to 48hrs before the following charge date.

To do so, the payment request is the same as in the Recurring Payment, but with prenotify = FALSE.

For UPI payments, a renewal can be retried a maximum of 2 times.

Retry Payment Flow

3538

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": 750,
   "currency": "INR",
   "country": "IN",
   "payment_method_id": "IR",
   "payment_method_flow": "DIRECT",
   "payer": {
       "name": "Ram Devi",
       "email": "[email protected]",
       "phone": "+919000123456",
       "document": "HSECT4378A",
       "address": {
            "country": "IN",
            "state": "Goa",
            "city": "Calangute",
            "street": "Maddo Vaddo",
            "number": "1207"
        }
   },
   "wallet": {
       "token": "W-yu23y4ibnyiu23y4",
       "recurring_info": {
        "prenotify": FALSE
       }
   },
   "order_id": "5346523565",
   "notification_url": "http://merchant.com/notifications"
}

Asynchronous notifications

When there is a change of status for the payment, we will send you a notification to confirm the transaction.

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 750.00,
   "currency": "INR",
   "payment_method_id": "IR",
   "payment_method_type": "WALLET",
   "payment_method_flow": "DIRECT",
   "country": "IN",
   "created_date": "2018-12-26T20:37:20.000+0000",
   "status": "PAID",
   "status_detail": "The payment was paid",
   "status_code": "200",
   "order_id": "5346523565",
   "notification_url": "http://merchant.com/notifications",
}

Updated 3 months ago