dLocal - UPI

dLocal is a global payments platform that helps you accept local payment methods and cards across emerging markets. UPI (Unified Payments Interface) is India’s instant payment system that enables real-time bank-to-bank transfers through mobile devices.

dLocal supports UPI for cross-border payments only, where your business is based outside India. It doesn’t offer domestic processing for businesses in India.

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.

Capabilities

Supported countries

Supported currencies

Integration

For UPI, the default integration is through a redirect to a hosted payments page. Start by creating a new transaction with the following required fields.

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "INR",
        Country = "IN",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "upi",
                    Country = "IN",
                    Currency = "INR",
                    RedirectUrl = "https://example.com/callback",
                }
            ),
    }
);

amount := int64(1299)
currency := "INR"
country := "IN"
method := components.RedirectPaymentMethodCreateMethodUpi
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method: method,
    Country: country,
    Currency: currency,
    RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    Country:       &country,
    PaymentMethod: &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("INR")
        .country("IN")
        .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
            .method(RedirectPaymentMethodCreateMethod.UPI)
            .country("IN")
            .currency("INR")
            .redirectUrl("https://example.com/callback")
            .build()))
        .build())
    .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'INR',
    country: 'IN',
    paymentMethod: new RedirectPaymentMethodCreate(
        method: 'upi',
        country: 'IN',
        currency: 'INR',
        redirectUrl: 'https://example.com/callback'
    )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="INR",
    country="IN",
    payment_method={
        "method": "upi",
        "country": "IN",
        "currency": "INR",
        "redirect_url": "https://example.com/callback",
    }
)

const transaction = await gr4vy.transactions.create({
    amount: 1299,
    currency: "INR",
    country: "IN",
    paymentMethod: {
        method: "upi",
        country: "IN",
        currency: "INR",
        redirectUrl: "https://example.com/callback"
    }
})

After the transaction is created, the API response includes payment_method.approval_url and the status is set to buyer_approval_pending. Redirect the buyer to the approval_url so they can complete the payment. After approval the buyer is redirected to the redirect_url you provided when creating the transaction. Do not rely solely on the redirect - either poll the transaction or (recommended) rely on webhooks to detect the final status (for example capture_succeeded or failure states).

Recurring transactions

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 waits for an asynchronous callback (webhook) to receive the final payment status. The same process applies to the tokenization of a payment method, which 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 errors with “Payment method tokenization is only supported for recurring transactions.”

Sandbox testing

When testing dLocal UPI in a sandbox environment, you are 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.

Introduction

Aggregators

Methods

Digital wallets

Anti-fraud

Browse

dLocal - UPI

Setup

Capabilities

Supported countries

Supported currencies

Integration

Recurring transactions

Usage with Embed

Sandbox testing

​Setup

​Capabilities

​Supported countries

​Supported currencies

​Integration

​Recurring transactions

​Usage with Embed

​Sandbox testing

Setup

Capabilities

Supported countries

Supported currencies

Integration

Recurring transactions

Usage with Embed

Sandbox testing