Pix Automático

Pix Automático is Brazil's recurring-payment scheme, built on top of Pix and launched by the Banco Central do Brasil. 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 authorizes the mandate and confirms an initial payment via a redirect to their bank.
Merchant-initiated recurring charges (MIT) — subsequent charges are made against the stored enrollment, with no customer interaction required.

Both phases return a PENDING payment synchronously; the final result arrives asynchronously via 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`.
`meta.subscription.scheduledDate`	MIT	✅ Yes	The date the recurring charge is scheduled for. Required on every MIT.
`meta.order.description`	CIT + MIT	Optional	Used as the enrollment/payment description.
`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.

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

⚠️
Sandbox testing note: Keep meta.order.description set to 100:approved for every happy-path test. In the dLocal sandbox, the description forwarded as the dLocal description field is what 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/declined scenario.

Phase 1 — Enrollment + initial payment (CIT)

Parse Pix Automático from the lookup response

With a server-to-server integration, you can call our lookup payment options endpoint to get available payment options. As shown in the example below, pixAutomatico is returned as an option of the paymentCompositionOptions.

{
  "name": "lookup",
  "actionId": "0bb6413e-cabb-4074-99e6-9e815c69f25b",
  "executedAt": "2026-03-26T12:00:00.000000000Z",
  "data": {
    "paymentCompositionOptions": [
      {
        "integrationType": "redirect",
        "paymentMethodCode": "pixAutomatico",
        "description": "Pix Automático"
      }
    ]
  }
}

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": "[email protected]",
      "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": "Monthly subscription",
      "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": "[email protected]"
      },
      "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"
}

Note: 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.

Note: 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": "[email protected]",
      "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"
}

Supported currencies

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

BRL — Brazilian Real

Supported regions / countries

Customer regions

Pix Automático is available to customers based in:

Brazil 🇧🇷

Merchant regions

Merchants enabled for Brazil can accept Pix Automático payments via dLocal.