Pix Automático via dLocal

Accept Pix Automático payments from customers in Brazil with dLocal as the payment service provider (PSP). The customer authorizes an enrollment and pays the first payment in their banking app. You then charge the enrollment for each billing cycle as a merchant-initiated transaction (MIT).

Supported workflows

Before you begin

Complete these steps before you send your first Pix Automático payment through dLocal:

Set up a dLocal integration in your workspace. Follow the dLocal integration setup guide if you don’t have one yet.
Ask dLocal to enable Pix Automático on your dLocal account.
In the Payrails Portal, go to Settings → Integrations, open your dLocal integration, select Pix Automático under Payment methods, and save.
Add Pix Automático as a payment option in your workflow.

Request fields for dLocal

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to the PSP when you include them.

Enrollment and first payment

Field	Status	Description
`amount.currency`	Required	Must be `BRL`. Payrails rejects other currencies.
`holderReference`	Required	Set on the execution. Payrails stores the enrollment as an instrument for this holder.
`paymentComposition[].storeInstrument`	Required	Set to `true` so Payrails stores the enrollment for recurring charges.
`meta.customer.country`	Required	The customer’s country object. Payrails sends `BR` to dLocal for every Pix Automático payment, whatever `country.code` you send.
`meta.customer.name`	Required	Sent to dLocal as the payer name, together with `meta.customer.lastName`.
`meta.customer.email`	Required	Sent to dLocal as the payer email.
`meta.customer.identityCardNumber`	Required	The customer’s CPF or CNPJ. Sent to dLocal as the payer document.
`meta.subscription.chargeFrequency`	Required	An ISO 8601 duration for the billing cycle. See charge frequency.
`meta.subscription.amountType`	Required	`FIXED` or `VARIABLE`.
`meta.subscription.fixedAmount`	Required	Needed when `amountType` is `FIXED`. The amount of each recurring charge.
`meta.subscription.minAmount`	Required	Needed when `amountType` is `VARIABLE`. See amount limits.
`meta.subscription.startDate`	Optional	The start of the mandate, sent to dLocal as a date (`YYYY-MM-DD`). dLocal uses the day of the first payment when you leave it out.
`meta.subscription.expiration`	Optional	The end of the mandate, sent to dLocal as a date (`YYYY-MM-DD`). Without it, the mandate has no end date.
`meta.customer.lastName`	Optional	Added to the payer name.
`meta.customer.phone`	Optional	Sent to dLocal as the payer phone number.
`meta.order.billingAddress`	Optional	Sent to dLocal as the payer address. `meta.order.deliveryAddress` takes priority when both are present.
`meta.order.description`	Optional	Sent to dLocal as the enrollment and payment description.
`meta.clientContext`	Optional	Payrails sends the client type, IP address, and user agent to dLocal.

Recurring charges

Field	Status	Description
`amount.currency`	Required	Must be `BRL`. Payrails rejects other currencies.
`paymentComposition[].paymentInstrumentId`	Required	The instrument Payrails stored for the enrollment. Payrails sends its enrollment ID to dLocal.
`meta.order.processingType`	Required	`Subscription` or `Unscheduled`, so Payrails processes the payment as an MIT.
`meta.subscription.scheduledDate`	Required	The date dLocal collects the charge, sent as `YYYY-MM-DD`. See schedule recurring charges.
`meta.customer.country`	Required	The customer’s country object. Payrails sends `BR` to dLocal.
`meta.customer.name`	Required	Sent to dLocal as the payer name.
`meta.customer.identityCardNumber`	Required	The customer’s CPF or CNPJ. Sent to dLocal as the payer document.
`meta.customer.email`	Optional	Sent to dLocal as the payer email.
`meta.order.description`	Optional	Sent to dLocal as the payment description.

Charge frequency

meta.subscription.chargeFrequency maps to the dLocal billing cycles below. Payrails rejects any other value.

`chargeFrequency`	dLocal frequency
`P7D` or `P1W`	`WEEKLY`
`P1M`	`MONTHLY`
`P3M`	`QUARTERLY`
`P6M`	`SEMI_ANNUAL`
`P1Y` or `P12M`	`ANNUAL`

Amount limits

For a FIXED subscription, dLocal charges fixedAmount exactly. For a VARIABLE subscription, Payrails sends minAmount to dLocal as the minimum authorization limit. The customer sets the real limit in their banking app, and can’t set it below this value. Send the highest amount you expect to charge in a single billing cycle.

Authorize a Pix Automático payment

Enroll the customer

Call authorize a payment with pixAutomatico as the paymentMethodCode and meta.subscription set. The response is pending and includes the redirect to the customer’s bank, where the customer authorizes the enrollment.

Enrollment request

{
  "amount": {
    "value": "100.00",
    "currency": "BRL"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "pixAutomatico",
      "amount": {
        "value": "100.00",
        "currency": "BRL"
      },
      "storeInstrument": true
    }
  ],
  "meta": {
    "customer": {
      "name": "Ana",
      "lastName": "Souza",
      "email": "ana.souza@example.com",
      "identityCardNumber": "12345678909",
      "country": {
        "code": "BR"
      }
    },
    "subscription": {
      "startDate": "2026-12-01T00:00:00Z",
      "expiration": "2027-12-01T00:00:00Z",
      "chargeFrequency": "P1M",
      "amountType": "VARIABLE",
      "minAmount": "300.00"
    },
    "order": {
      "description": "Monthly plan"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

After the customer authorizes the enrollment, the bank returns them to your success or error URL. Confirm the result through webhook notifications or the execution status.

Charge the enrollment

For each billing cycle, call authorize a payment on a new execution with the stored paymentInstrumentId. The response is pending, with no redirect.

Recurring charge request

{
  "amount": {
    "value": "285.00",
    "currency": "BRL"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "pixAutomatico",
      "paymentInstrumentId": "18635e5c-06b9-4180-9885-6f84e246d1ef",
      "amount": {
        "value": "285.00",
        "currency": "BRL"
      }
    }
  ],
  "meta": {
    "customer": {
      "name": "Ana",
      "lastName": "Souza",
      "email": "ana.souza@example.com",
      "identityCardNumber": "12345678909",
      "country": {
        "code": "BR"
      }
    },
    "subscription": {
      "scheduledDate": "2027-01-05T00:00:00Z"
    },
    "order": {
      "processingType": "Subscription"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

Payrails updates the payment when the dLocal notification arrives. Track the outcome through webhook notifications or the execution status.

How dLocal handles Pix Automático

Enrollment and stored instrument

dLocal creates the enrollment and the first payment in one request, and returns a redirect URL to the customer’s bank. Payrails returns a pending result with a redirect required action.
Payrails tracks the payment, not the enrollment, as the provider reference. dLocal confirms the payment and the enrollment through separate notifications.
Payrails stores the dLocal enrollment ID as the PSP token on the instrument as soon as dLocal returns it, on the pending response. The instrument has no account number. It holds the enrollment country and its external reference.
Payrails captures the first payment immediately, whatever startDate you set. startDate only sets when the billing cycles begin.

Schedule recurring charges

dLocal doesn’t charge the enrollment on its own. Send a recurring charge for every billing cycle, including the first one after the enrollment.
meta.subscription.scheduledDate is the day dLocal collects the charge, not the day you send the request. Send each request two to ten days before its scheduledDate, as the Central Bank of Brazil requires. dLocal rejects a request outside this window with status code 300.
Each recurring charge returns a pending payment. The final result arrives through the same dLocal payment notification as other dLocal payments.
To offer a trial period, set startDate to the day the trial ends, then send the first recurring charge for that date. dLocal’s minimum Pix amount is 1 BRL.

Test in the dLocal sandbox

In the dLocal sandbox, the payment description sets the simulated outcome. Send 100:approved in meta.order.description on both the enrollment and each recurring charge to get an approved result. Use the CPF 53033315550 or the CNPJ 00000000000191 as meta.customer.identityCardNumber.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Pix Automático via dLocal

Supported workflows

Before you begin

Request fields for dLocal

Enrollment and first payment

Recurring charges

Charge frequency

Amount limits

Authorize a Pix Automático payment

Enroll the customer

Charge the enrollment

How dLocal handles Pix Automático

Enrollment and stored instrument

Schedule recurring charges

Test in the dLocal sandbox

​Supported workflows

​Before you begin

​Request fields for dLocal

​Enrollment and first payment

​Recurring charges

​Charge frequency

​Amount limits

​Authorize a Pix Automático payment

​Enroll the customer

​Charge the enrollment

​How dLocal handles Pix Automático

​Enrollment and stored instrument

​Schedule recurring charges

​Test in the dLocal sandbox

Supported workflows

Before you begin

Request fields for dLocal

Enrollment and first payment

Recurring charges

Charge frequency

Amount limits

Authorize a Pix Automático payment

Enroll the customer

Charge the enrollment

How dLocal handles Pix Automático

Enrollment and stored instrument

Schedule recurring charges

Test in the dLocal sandbox