dLocal - PIX

dLocal is a global payments platform that helps you accept local payment methods and cards across emerging markets.

PIX is Brazil’s instant payment system, created by the Central Bank of Brazil, enabling real-time transfers and payments 24/7.

Setup

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

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

Features

• Tokenization - Save payment methods for future use
• Partial refunds - Refund a portion of the captured amount
• Refunds - Full refund support
• Settlement reporting - Access to settlement reports
• Transaction sync - Automatic transaction status synchronization

Supported countries

dLocal supports transactions from buyers in BR.

Supported currencies

dLocal supports processing payments in BRL.

Limitations

• Capture - Delayed capture is not supported
• Delete tokens - Token deletion is not supported
• Void - Transaction void is not supported

Integration

For PIX, the default integration is through a redirect to a hosted payments page.

Start by creating a new transaction with the following required fields.

C#

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "BRL",
        Country = "BR",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "pix",
                    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

Enrollment

To enroll a buyer in Pix Automático, create an initial payment with tokenization enabled and pass dlocal-pix connection options.

• Set store to true to save the payment method.
• Pass connection_options.dlocal-pix.subscription with the recurring enrollment details.

Use one of the following SDK requests:

C#

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "BRL",
        Country = "BR",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "pix",
                    RedirectUrl = "https://example.com/callback",
                }
            ),
        Store = true,
        ConnectionOptions = new Dictionary<string, object>()
        {
            ["dlocal-pix"] = new Dictionary<string, object>()
            {
                ["subscription"] = new Dictionary<string, object>()
                {
                    ["frequency"] = "MONTHLY",
                    ["amount"] = new Dictionary<string, string>()
                    {
                        ["type"] = "FIXED",
                        ["value"] = "10.00"
                    },
                    ["start_date"] = "2026-03-01",
                    ["end_date"] = "2027-03-01"
                }
            }
        }
    }
);

After you create the enrollment transaction, redirect the buyer to the approval_url to complete the Pix Automático enrollment. Once the buyer approves it, the payment method is saved and available for subsequent recurring charges.

Subsequent payment

After enrollment succeeds, create subsequent charges with the saved payment method ID.

• Set payment_method.method to id and pass the saved payment method ID.
• Set payment_source to recurring.
• Set merchant_initiated and is_subsequent_payment to true.
• Optionally set connection_options.dlocal-pix.scheduled_date in YYYY-MM-DD format.

C#

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "BRL",
        Country = "BR",
        PaymentMethod = TransactionCreatePaymentMethod.CreatePaymentMethodIdRequest(
            new PaymentMethodIdRequest()
            {
                Method = PaymentMethodIdRequest.MethodEnum.Id,
                Id = "f758d736-9a81-4bd0-85a9-2d3ee361b863"
            }
        ),
        IsSubsequentPayment = true,
        MerchantInitiated = true,
        PaymentSource = TransactionCreate.PaymentSourceEnum.Recurring,
        ConnectionOptions = new Dictionary<string, object>()
        {
            ["dlocal-pix"] = new Dictionary<string, string>()
            {
                ["scheduled_date"] = "2026-03-05"
            }
        }
    }
);

Connection options

• subscription.frequency - Recurrence interval. Supported values are WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUAL, and ANNUAL.
• subscription.amount.type - Amount model. Use FIXED for a fixed amount or VARIABLE for a variable amount.
• subscription.amount.value - Fixed amount in local currency. Use this when subscription.amount.type is FIXED.
• subscription.amount.min_value - Minimum enrollment limit in local currency. Use this when subscription.amount.type is VARIABLE.
• subscription.start_date - Subscription start date in YYYY-MM-DD format.
• subscription.end_date - Subscription end date in YYYY-MM-DD format.

For subsequent recurring charges, you can pass connection_options.dlocal-pix.scheduled_date in YYYY-MM-DD format. If you omit it, dLocal defaults to 2 days in the future.

Sandbox testing

In production, Gr4vy passes merchant_reference to dLocal as the payment description.

In sandbox, Gr4vy sends 100:approved as the payment description so dLocal can return an approved transaction.