> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Pix Automático via dLocal

> Set up recurring Pix Automático payments through dLocal in Payrails, from the enrollment to each scheduled recurring charge.

<picture noZoom>
  ![Pix Automático logo](https://assets.payrails.io/img/logos/pixautomatico/logo.svg)
</picture>

<picture noZoom>
  ![dLocal logo](https://assets.payrails.io/img/logos/dlocal/logo-full-bleed.svg)
</picture>

Accept [Pix Automático](https://docs.payrails.com/docs/integrations/payment-methods/pix-automatico) 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

<table>
  <thead>
    <tr><th>Workflow</th><th>Supported</th></tr>
  </thead>

  <tbody>
    <tr><td>Payrails SDK</td><td>✔</td></tr>
    <tr><td>Payrails API</td><td>✔</td></tr>
    <tr><td>[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✖</td></tr>
    <tr><td>[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)</td><td>✖</td></tr>
    <tr><td>[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)</td><td>✔</td></tr>
    <tr><td>[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)</td><td>✔</td></tr>
  </tbody>
</table>

## Before you begin

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

1. Set up a dLocal integration in your workspace. Follow the [dLocal integration setup guide](https://docs.payrails.com/docs/integrations/payment-providers/dlocal.md) if you don't have one yet.
2. Ask dLocal to enable Pix Automático on your dLocal account.
3. In the Payrails Portal, go to **Settings → Integrations**, open your dLocal integration, select **Pix Automático** under **Payment methods**, and save.
4. Add Pix Automático as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md) in your workflow.

## Request fields for dLocal

Send these fields in the authorize request, in addition to the standard [authorize fields](https://docs.payrails.com/reference/authorizeaction.md). **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](#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](#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](#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](https://docs.payrails.com/reference/authorizeaction.md) 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.

```json Enrollment request theme={null}
{
  "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](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md) or the execution status.

### Charge the enrollment

For each billing cycle, call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) on a new execution with the stored `paymentInstrumentId`. The response is pending, with no redirect.

```json Recurring charge request theme={null}
{
  "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](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md) 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, and doesn't send a separate notification for the enrollment. Use the first payment's outcome instead: when it's paid, the customer has authorized the enrollment. When it fails or expires, the enrollment isn't usable.
* 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`.


## Related topics

- [Pix Automático](https://docs.payrails.com/docs/integrations/payment-methods/pix-automatico.md)
- [Pix via dLocal](https://docs.payrails.com/docs/integrations/payment-methods/pix/dlocal.md)
- [SmartPix via dLocal](https://docs.payrails.com/docs/integrations/payment-methods/smart-pix/dlocal.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.