Pix Automático

It lets a payer authorize a recurring mandate (“enrollment”) once from their banking app, after which the merchant can charge that mandate on a schedule without any further customer interaction—the Pix equivalent of a card-on-file subscription or a direct debit.

Introduction

Unlike regular Pix (a single-use QR code / redirect per payment), Pix Automático is a two-phase payment method:

Customer-initiated enrollment + initial payment (CIT)—the customer selects Pix Automático at checkout. Payrails calls dLocal POST /payments with a nested enrollment object carrying the subscription schedule. dLocal returns a PENDING payment (D-…), a PENDING enrollment (E-…), and a redirect_url. The customer follows the redirect to their bank to authorize the mandate.
Merchant-initiated recurring charges (MIT)—once the enrollment is active, Payrails stores it as a payment instrument. Subsequent charges call dLocal POST /payments in the DIRECT flow, referencing the enrollment id—no redirect, no customer present.

Both phases return a PENDING payment synchronously; the final result arrives asynchronously via notification. The Payrails result and provider reference track the payment (D-…). The enrollment (E-…) is surfaced as the reusable credential (provider token) and is advanced by its own notification. This guide explains the process of integrating Pix Automático into your app or website using Payrails via dLocal.

Pre-requisites

Before you start accepting Pix Automático payments with Payrails, there are a few requirements you must meet:

Integrate with Payrails using one of our SDKs or our API.
Configure a new integration account for Pix Automático via dLocal as a Payment Service Provider. If you do not already have a dLocal integration configured in your workspace, complete the dLocal integration setup guide first.
Enable Pix Automático as a payment method in your dLocal integration configuration. In the Payrails portal, navigate to Settings → Integrations, select your dLocal integration instance, and enable the Pix Automático checkbox under Payment methods, then save the account.
Enable Pix Automático as a payment option in your workflow.
Make sure you’re sending the Pix Automático-specific meta fields (meta.customer, meta.subscription) in your requests (see Required meta fields below).

Ways to integrate Pix Automático

Payrails SDK

The simplest way to use Pix Automático with Payrails is to use our drop-in in your checkout flow. With this integration type, no additional work is required to accept the initial payment except for handling success/failure screens for your users, and passing meta.subscription. For a more flexible implementation using our SDK, you can use our genericRedirectButton element.

Server-to-server integration

You can integrate Pix Automático by completely managing your own client-side implementation, and using Payrails APIs with a server-to-server integration to process both phases.

Required meta fields

Field	Phase	Required	Notes
`meta.customer.name`	CIT + MIT	✅ Yes	Payer name.
`meta.customer.email`	CIT	✅ Yes	Rejected with `customer.email is missing` when absent on enrollment.
`meta.customer.identityCardNumber`	CIT + MIT	✅ Yes	Payer CPF/CNPJ. dLocal rejects Pix Automático without it.
`meta.customer.country.code`	CIT + MIT	✅ Yes	Must be `BR`. Payrails pins the dLocal `country` to `BR` regardless.
`meta.subscription.startDate`	CIT	Optional	Mandate start date, sent to dLocal as `YYYY-MM-DD`. If absent, defaults to the same day as the initial payment.
`meta.subscription.expiration`	CIT	Optional	Mandate end date, sent as `YYYY-MM-DD`. If absent, the subscription has no end date.
`meta.subscription.chargeFrequency`	CIT	✅ Yes	ISO 8601 duration. See the frequency mapping below.
`meta.subscription.amountType`	CIT	✅ Yes	`FIXED` or `VARIABLE`.
`meta.subscription.fixedAmount`	CIT	Conditional	Required when `amountType = FIXED`.
`meta.subscription.minAmount`	CIT	Conditional	Required when `amountType = VARIABLE`. See Amount limits below—this is a ceiling, not a floor.
`meta.subscription.scheduledDate`	MIT	✅ Yes	The date the recurring charge is scheduled for. Required on every MIT. Must fall 2–10 days after the request is sent—see Submission window below.
`meta.order.description`	CIT + MIT	Optional	Used as the enrollment/payment description. In the dLocal sandbox this value drives the simulated outcome—keep it `100:approved` for successful test scenarios. See Staging tests below.
`meta.clientContext`	CIT	Optional	Forwarded as device/IP/user-agent when present.

Charge frequency mapping

meta.subscription.chargeFrequency is an ISO 8601 duration and is mapped to dLocal’s fixed set of cadences. Any value outside this list is rejected. WEEKLY is the shortest supported cadence—there is no 3- or 5-day option.

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

Phase 1: Enrollment + initial payment (CIT)

Parse Pix Automático from the lookup response

Sample CIT request (drop-in / create execution)

{
  "type": "dropIn",
  "workflowCode": "payment-acceptance",
  "merchantReference": "tp_13c4da90-bfb3-4778-aa55-6c63cc960f6a",
  "holderReference": "tp_5b20e63f-0307-4ef0-acca-1bf30852460e",
  "amount": {
    "value": "100",
    "currency": "BRL"
  },
  "meta": {
    "source": "portal",
    "subscription": {
      "startDate": "2026-12-01T00:00:00Z",
      "expiration": "2027-12-01T00:00:00Z",
      "chargeFrequency": "P1M",
      "amountType": "VARIABLE",
      "minAmount": "300"
    },
    "customer": {
      "name": "John",
      "lastName": "Doe",
      "email": "john.doe@payrails.com",
      "reference": "tp_5b20e63f-0307-4ef0-acca-1bf30852460e",
      "identityCardNumber": "00000000000191",
      "country": {
        "code": "BR"
      }
    },
    "billingAddress": {
      "city": "Berlin",
      "country": { "code": "DE" },
      "postalCode": "10405",
      "street": "Straßburger Straße",
      "doorNumber": "1"
    },
    "order": {
      "description": "100:approved",
      "deliveryAddress": {
        "city": "Berlin",
        "country": { "code": "DE" },
        "postalCode": "10405",
        "street": "Straßburger Straße",
        "doorNumber": "1"
      },
      "billingAddress": {
        "city": "Berlin",
        "country": { "code": "DE" },
        "postalCode": "10405",
        "street": "Straßburger Straße",
        "doorNumber": "1",
        "name": "John",
        "lastName": "Doe",
        "email": "john.doe@payrails.com"
      },
      "lines": [
        {
          "id": "533cce54-d4fc-4f96-9bfc-bf1070eec3ad",
          "quantity": 1,
          "name": "e613d094-20a9-4fbc-a337-6edbfb2cd37a",
          "unitPrice": { "value": "100", "currency": "BRL" }
        }
      ]
    },
    "clientContext": {
      "ipAddress": "217.110.239.132",
      "osType": "web",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "en-US",
      "colorDepth": 24,
      "screenHeight": 723,
      "screenWidth": 1536,
      "timeZoneOffset": 0,
      "javaEnabled": false,
      "javaScriptEnabled": false
    }
  },
  "workflowVersion": 36
}

Synchronous response

dLocal returns a PENDING payment plus a PENDING enrollment and a redirect_url:

{
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca5",
    "external_id": "31231jj225",
    "status": "PENDING",
    "status_code": "100",
    "status_detail": "The enrollment is pending."
  },
  "id": "D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb5",
  "amount": 286,
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "XA",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "status": "PENDING",
  "status_code": "100",
  "status_detail": "The payment is pending.",
  "order_id": "payment-221124442ab",
  "redirect_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-9a2d174d-25e8-4412-af03-acc36d340df5",
  "notification_url": "http://merchantsite.com/notifications"
}

Payrails maps this to a pending authorize result with a redirect required action. The enrollment id (E-…) is surfaced as the provider token immediately—even on the pending response—so the instrument can be stored right away rather than waiting for a notification. The stored instrument carries only the enrollment country and external_id; there is no PAN- or MSISDN-equivalent account identity for Pix.

Handle the redirect

After the customer authorizes the mandate in their banking app and returns to your site, verify the payment status via the Payrails API or by listening to webhook notifications.

Phase 2: Recurring charge (MIT)

Once the enrollment is active and stored as an instrument, charge it by passing the paymentInstrumentId with pixAutomatico and integrationType: api. No redirect is returned—the payment goes straight to PENDING and is confirmed by notification.

meta.subscription.scheduledDate is mandatory on every MIT. A MIT without a resolvable enrollment reference on the instrument is rejected—Payrails never silently creates a new enrollment for a charge that is meant to reuse an existing mandate.

Sample MIT request

{
  "amount": { "value": "285.00", "currency": "BRL" },
  "returnInfo": {
    "success": "https://yoursite.com/return/success",
    "cancel": "https://yoursite.com/return/cancel",
    "pending": "https://yoursite.com/return/pending",
    "error": "https://yoursite.com/return/error"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "pixAutomatico",
      "paymentInstrumentId": "18635e5c-06b9-4180-9885-6f84e246d1ef",
      "amount": { "value": "285.00", "currency": "BRL" }
    }
  ],
  "meta": {
    "subscription": {
      "scheduledDate": "2027-01-05T00:00:00Z"
    },
    "customer": {
      "name": "Thiago Gabriel",
      "email": "thiago@example.com",
      "identityCardNumber": "53033315550",
      "country": { "code": "BR" }
    },
    "order": { "processingType": "Subscription" }
  }
}

Synchronous response

{
  "id": "D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb0",
  "amount": 588,
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "XA",
  "payment_method_type": "TICKET",
  "payment_method_flow": "DIRECT",
  "created_date": "2027-01-05T20:37:20.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "5346523566",
  "notification_url": "http://merchantsite.com/notifications"
}

Operational rules for recurring charges

These rules govern how a live mandate behaves day to day. They don’t change the request/response shapes above, but they do determine whether a given MIT will be accepted.

Submission window: 2 to 10 days before the billing date

Every recurring payment request must reach dLocal 2 to 10 days before the scheduledDate it is billing for—this reflects a Central Bank of Brazil requirement for all Pix Automático payments. For example, a billing date of 5 August expects the request between 26 July and 3 August. A same-day request is not supported and comes back:

Field	Value
`status`	`REJECTED`
`status_code`	`300`
`status_detail`	Scheduling not allowed for the current recurrence window

The request is rejected outright—it is not silently queued to the next valid date.

Payrails does not currently enforce this windowThe connector only checks that scheduledDate is present, not that it falls 2–10 days out. An out-of-window MIT will be built and sent to dLocal as-is, and will come back REJECTED / 300. Until this validation is added, merchants are responsible for scheduling MITs correctly.

What `scheduledDate` means, and how you learn the outcome

meta.subscription.scheduledDate is the day dLocal should collect the charge, not the day you call the API. The MIT POST returns a synchronous PENDING; the final PAID or REJECTED outcome arrives asynchronously through the same payment-notification webhook used by other dLocal payment methods. There is no separate “renewal” notification type. Track the outcome against the payment’s provider reference (D-…).

Amount limits: there is no `maxAmount`

For a VARIABLE subscription, dLocal’s API has exactly one amount field: minAmount (forwarded as dLocal’s min_value). There is no maxAmount field. The naming is misleading: min_value is the minimum authorization limit the payer can set during enrollment. The payer chooses the real ceiling in their banking app but can never set it below this value. dLocal’s own guidance is to send the highest amount you expect to charge in a single cycle as minAmount. For FIXED subscriptions, this doesn’t apply: fixedAmount is charged exactly.

Free trials: do not model as a R$0 payment

A free trial must not be modelled as a R$0 initial payment in the enrollment-plus-payment flow; dLocal’s Pix capability also enforces a 1 BRL minimum transaction amount. The supported pattern is:

Create the enrollment without an initial payment.
Set subscription.startDate to the date the trial ends.
Submit the first billing request for that date once the trial is over, respecting the 2–10 day submission window.

The same pattern applies to a paid trial: submit the first non-zero payment for the trial-end date, inside the window.

Retry a rejected recurring charge (not currently supported)

dLocal offers a retry service for a failed renewal (POST /payments carrying the failed payment’s retry_payment_id, up to 3 retries within a 7-day window, intended for the same billing cycle rather than a new request). Payrails does not currently support invoking this service. There is no way today to submit a dLocal retry or to learn how many attempts remain. The only current option after a rejected renewal is to submit a fresh recurring payment request with a new scheduledDate, subject to the same 2–10 day window.

`startDate` and how trials actually work

Setting subscription.startDate in the future is supported and is the recommended way to model a trial period. With MONTHLY frequency, subsequent payments follow the monthly cadence from that start date. For example, “charge today, startDate = today + 7 days, chargeFrequency = P1M” puts the first recurring charge roughly one month after startDate, not 7 days out. dLocal does not auto-fire a recurring charge. For every cycle, including the first, the merchant (via Payrails) must call the recurring-payment endpoint 2–10 days ahead of the scheduled date. If omitted, startDate defaults to the day of the initial payment.

Known limitations

Limitation	Impact
No validation of the 2–10 day submission window	An out-of-window MIT is sent as-is and comes back `REJECTED / 300` instead of failing validation early
dLocal’s retry service is not yet wired up	No compliant way to retry a rejected renewal within the same billing cycle
No zero-amount guard	A R$0 Pix Automático request is built and sent, even though it isn’t a valid way to model a free trial and Pix has a 1 BRL minimum

Staging tests

Test values

Field	Value
`customer.identityCardNumber`	`53033315550` (CPF) or `00000000000191` (CNPJ)
`customer.country.code`	`BR`
Currency	`BRL` (only supported currency)
dLocal `payment_method_id`	`XA`
`meta.order.description`	`100:approved` (for successful scenarios)

Sandbox testing noteKeep meta.order.description set to 100:approved for every happy-path test. In the dLocal sandbox, the description forwarded as the dLocal description field drives the simulated outcome. It follows a <status_code>:<status> convention. Anything else (or an omitted description) leaves the sandbox free to return a non-approved status, so the enrollment or payment will not settle as approved and the run will look like a product bug when it isn’t. This applies to both phases: the CIT enrollment + initial payment and every MIT recurring charge. Use a different value only when you are deliberately testing a negative or declined scenario.

CIT test steps

Create an execution / open the drop-in with the CIT payload above. Make sure meta.subscription is present and complete.
Select Pix Automático in the drop-in → you’re redirected to dLocal’s hosted page.
On the dLocal sandbox page, click approve to simulate a successful enrollment, or cancel to simulate enrollment abandonment.
You’re redirected back to the drop-in success/fail screen.
Verify in the portal that a payment instrument was created for the holder, carrying the enrollment id as its token.
Wait for the payment notification and confirm the execution moves to its final state.

MIT test steps

Take the paymentInstrumentId created by the CIT run.
POST the MIT payload above to the authorize endpoint of a fresh execution.
Expect a pending result with no redirect action.
Confirm the final state via the payment notification.

Supported currencies

Pix Automático via dLocal supports the following presentment currency:

BRL: Brazilian Real

Supported regions / countries

_{(via dLocal)}

Supported workflows and services

For Save Instruments, the enrollment is the stored credential.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Introduction

Pre-requisites

Ways to integrate Pix Automático

Payrails SDK

Server-to-server integration

Required meta fields

Charge frequency mapping

Phase 1: Enrollment + initial payment (CIT)

Parse Pix Automático from the lookup response

Sample CIT request (drop-in / create execution)

Synchronous response

Handle the redirect

Phase 2: Recurring charge (MIT)

Sample MIT request

Synchronous response

Operational rules for recurring charges

Submission window: 2 to 10 days before the billing date

What `scheduledDate` means, and how you learn the outcome

Amount limits: there is no `maxAmount`

Free trials: do not model as a R$0 payment

Retry a rejected recurring charge (not currently supported)

`startDate` and how trials actually work

Known limitations

Staging tests

Test values

CIT test steps

MIT test steps

Supported currencies

Supported regions / countries

Supported workflows and services

​Introduction

​Pre-requisites

​Ways to integrate Pix Automático

​Payrails SDK

​Server-to-server integration

​Required meta fields

​Charge frequency mapping

​Phase 1: Enrollment + initial payment (CIT)

​Parse Pix Automático from the lookup response

​Sample CIT request (drop-in / create execution)

​Synchronous response

​Handle the redirect

​Phase 2: Recurring charge (MIT)

​Sample MIT request

​Synchronous response

​Operational rules for recurring charges

​Submission window: 2 to 10 days before the billing date

​What scheduledDate means, and how you learn the outcome

​Amount limits: there is no maxAmount

​Free trials: do not model as a R$0 payment

​Retry a rejected recurring charge (not currently supported)

​startDate and how trials actually work

​Known limitations

​Staging tests

​Test values

​CIT test steps

​MIT test steps

​Supported currencies

​Supported regions / countries

​Supported workflows and services

Introduction

Pre-requisites

Ways to integrate Pix Automático

Payrails SDK

Server-to-server integration

Required meta fields

Charge frequency mapping

Phase 1: Enrollment + initial payment (CIT)

Parse Pix Automático from the lookup response

Sample CIT request (drop-in / create execution)

Synchronous response

Handle the redirect

Phase 2: Recurring charge (MIT)

Sample MIT request

Synchronous response

Operational rules for recurring charges

Submission window: 2 to 10 days before the billing date

What `scheduledDate` means, and how you learn the outcome

Amount limits: there is no `maxAmount`

Free trials: do not model as a R$0 payment

Retry a rejected recurring charge (not currently supported)

`startDate` and how trials actually work

Known limitations

Staging tests

Test values

CIT test steps

MIT test steps

Supported currencies

Supported regions / countries

Supported workflows and services