UPI via dLocal

Setup

Please follow the common dLocal instructions to get set up with UPI.

Next, make sure to enable UPI as a payment method on your configured account.

Recurring transactions

Please note that recurring UPI payments are not confirmed in real-time. A transaction takes at least 24 hours (up to 48 hours) to be confirmed due to a mandatory upcoming payment notification rule in India. As a result, the UPI integration will wait for an asynchronous callback (webhook) to receive the final payment status. Same works for the tokenization of a payment method, that only works for recurring or installments transactions.

You can specify the payment frequency using the dLocal UPI connection options. The example below demonstrates how to configure a monthly payment that recurs for one year.

  "connectionOptions": {
    "dlocal-upi": {
      "wallet": {
        "recurring_info": {
          "subscription_end_at": "20261016",
          "subscription_frequency": 1,
          "subscription_frequency_unit": "MONTH",
          "subscription_start_at": "20251016"
        }
      }
    }
  }

Usage with Embed

When storing a UPI payment method with Embed, dLocal requires it to be set up as a recurring transaction. You can do this by setting the paymentSource to recurring. If this isn’t configured correctly, the transaction will error with “Payment method tokenization is only supported for recurring transactions.”.

Sandbox testing

When testing dLocal UPI in a sandbox environment, you will be redirected to an enrollment experience for recurring transactions. This process may not return immediately and can take several minutes to begin processing the transaction. You may need to refresh the approval URL multiple times before the transaction is successfully initiated.