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

# Pix Automático via dLocal

> Let customers securely make recurring payments using Pix Automático via dLocal on your website or mobile application.

Pix Automático via dLocal lets you take recurring payments over Pix. On the first payment the customer is redirected to authorize a recurring mandate — an enrolment — in their banking app, and that same payment is charged. Subsequent payments are charged directly against the enrolment with no customer interaction. Pix Automático is a recurring bank transfer scheme developed by the Banco Central do Brasil and is available in Brazil in BRL only.

| One off payment | Refunds | Recurring | Cancel |
| - | - | - | - |
| x | ✓ | ✓ | x |

> [!WARNING]
>
> **Before you build**
>
> * Primer supports the **enrolment and initial payment** flow. Enrolment on its own, without charging the customer, is not supported.
> * Recurring payment requests must be submitted **between 2 and 10 days before** the scheduled billing date. For a billing date of 5 August, submit the request between 26 July and 3 August. This is a regulatory requirement from the Banco Central do Brasil that applies to all Pix Automático payments.
> * Pix Automático is available in Brazil only. Set `order.countryCode` to `BR` and `currencyCode` to `BRL` on every payment.
> * Every merchant-initiated payment after the enrolment must carry a `scheduled_date` in metadata.

## Get started with Pix Automático via dLocal

### Before you begin

If this is your first payment method, make sure to follow the [Get started guide](https://primer.io/docs/get-started/overview.md) to begin processing payments with Primer.

Pix Automático is not active on a dLocal account by default. Ask your dLocal contact to enable it before you activate it on the Checkout.

You need credentials from the [dLocal Merchant Dashboard](https://dashboard.dlocal.com/core-ui/sign-up). If you do not have an account, contact your dLocal account manager or [support@dlocal.com](mailto:support@dlocal.com). To get sandbox credentials, toggle **Test mode** in the top right of the dLocal dashboard — a blue bar appears across the top to confirm you are in test mode. Your **x\_login**, **x\_trans\_key** and **secret key** are under **Settings > Integration**, on the **Integration** tab.

### Configure in the Dashboard

1. **Add Pix Automático via dLocal payment method to your Dashboard** Go to the [integrations](https://dashboard.primer.io/integrations) section of the Dashboard, click on the 'New Integration' button and search for dLocal. Enter your **x\_login**, **x\_trans\_key** and **secret key**, then click **Connect**.
2. **Add your MID** Enter your dLocal **AccountId** in the MID box. You can find it at the top of the dLocal dashboard.
3. **Configure the webhooks in dLocal** Copy the callback URL that Primer shows you during setup. In the dLocal dashboard, under **Endpoint configuration**, paste it into both the **Refunds URL** field and the **Payins notification URL** field. The Payins notification URL is required for Pix Automático.
4. **Activate Pix Automático via dLocal on the Checkout** Go to the [Checkout](https://dashboard.primer.io/checkout) section of the Dashboard and toggle on Pix Automático. Add a display condition so it only appears where it can be paid — at a minimum, `Currency = BRL`.
5. **Configure a Workflow to process payments made with Pix Automático via dLocal** Go to [Workflows](https://primer.io/docs/workflows) and create a workflow with a **Payment created** trigger and an **Authorize payment** action with **Auto-continue** enabled. Pix Automático via dLocal is a web redirect connection, so no further steps are needed.

### Prepare the client session

dLocal leverages the following parameters to process a payment. Pass them when creating the client session.

| Parameter Name | Required | Description |
| - | - | - |
| [orderId](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-order-id) | ✓ | A unique identifier for the order. Maximum 255 characters. |
| [currencyCode](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-currency-code) | ✓ | The three-letter currency code in ISO 4217 format. Pix Automático supports `BRL` only. |
| [customer.nationalDocumentId](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-customer-national-document-id) | ✓ | The payer's CPF or CNPJ. Pix Automático payments do not process without it. |
| `customer.emailAddress` | ✓ | Sent to dLocal as the payer email. |
| `customer.firstName` and `customer.lastName` | ✓ | Combined and sent to dLocal as the payer name. |
| `order.countryCode` | ✓ | Determines which dLocal country entity processes the payment. Set it to `BR`. If it is absent, Primer falls back to the billing address country code. |
| `customer.billingAddress` | Recommended | Street, house number, city, state and postal code are passed to dLocal as the payer address. |

## Enrolment and initial payment

The first payment creates the mandate and charges the customer. Pass the subscription terms in the client session metadata — they dictate when and how much you are allowed to charge on the recurring payments that follow.

```json theme={"dark"}
{
  "subscription": {
    "frequency": "MONTHLY",
    "amount": {
      "type": "VARIABLE",
      "minValue": 200
    },
    "startDate": "2025-08-04",
    "endDate": "2025-12-01"
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `subscription.frequency` | String | ✓ | How often the customer is charged. One of `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, `ANNUAL`. |
| `subscription.amount.type` | String | ✓ | `FIXED` for a subscription charged the same amount each time, or `VARIABLE` for one where the amount changes. |
| `subscription.amount.value` | Integer (minor units) | Conditional | The amount charged each time, in BRL minor units. Applies to `FIXED` subscriptions only. |
| `subscription.amount.minValue` | Integer (minor units) | Conditional | The minimum amount that may be charged each time, in BRL minor units. Applies to `VARIABLE` subscriptions only. |
| `subscription.startDate` | String (`YYYY-MM-DD`) | Optional | The date the mandate becomes active. Defaults to the current date. |
| `subscription.endDate` | String (`YYYY-MM-DD`) | Optional | The date the mandate expires. If you omit it, the mandate does not expire. |

## Recurring payments

For each merchant-initiated payment after the enrolment, pass the date the payment is scheduled for in metadata. dLocal requires it.

```json theme={"dark"}
{
  "scheduled_date": "2025-10-04"
}
```

Submit the request between 2 and 10 days before the `scheduled_date`. The example above was submitted on 4 September for a 4 October billing date.

### Automatic retries

On the `scheduled_date`, between 00:00 and 08:00, dLocal attempts the debit. If it succeeds, the payment settles and Primer sends you a `SETTLED` webhook. If this first attempt fails, you are not notified.

If the first attempt failed because of insufficient funds or account limits, dLocal must retry the same day between 18:00 and 21:00 — a regulatory requirement from the Banco Central do Brasil. That retry is automatic and you do not need to trigger it. It produces a Primer webhook: `SETTLED` if it succeeds, `FAILED` if it does not.

## Prepare the SDK for payments

> [tab] Web
>
> > [!NOTE]
> >
> > Use the payment method type `DLOCAL_PIX_AUTOMATICO` wherever the code below references `YOUR_PAYMENT_METHOD_TYPE`.
>
> > [tab] Primer Checkout (recommended)
> >
> > Primer Checkout is our latest web SDK, built around declarative web components. Once Pix Automático via dLocal is enabled in your [Dashboard](https://dashboard.primer.io/checkout), the default `<primer-checkout>` layout renders it automatically alongside your other methods — no payment-method-specific markup is required.
> >
> > ```html theme={"dark"}
> > <primer-checkout client-token="your-client-token"></primer-checkout>
> > ```
> >
> > #### Custom layouts
> >
> > Only reach for [primer-payment-method](https://primer.io/docs/sdk/primer-checkout-web/components/primer-payment-method.md) if you're building a custom layout and need to place Pix Automático via dLocal at a specific position. The element only renders when the type is enabled in your Dashboard and returned by the server for this checkout.
> >
> > ```html theme={"dark"}
> > <primer-checkout client-token="your-client-token">
> >   <primer-main slot="main">
> >     <div slot="payments">
> >       <primer-payment-method type="YOUR_PAYMENT_METHOD_TYPE"></primer-payment-method>
> >     </div>
> >   </primer-main>
> > </primer-checkout>
> > ```
> >
> > For dynamic rendering based on what the server returns, listen to [primer:methods-update](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md) or use [primer-payment-method-container](https://primer.io/docs/sdk/primer-checkout-web/components/primer-payment-method-container.md) for declarative filtering.
>
> > [tab] Universal Checkout (legacy)
> >
> > ##### Set up redirects
> >
> > If Pix Automático via dLocal can't be shown in a popup, Universal Checkout redirects the customer back to your site using the `returnUrl` passed in the `redirect` options. See [Handle redirects & deep links](https://primer.io/docs/sdk/web/v2.x.x/handle-redirects-and-deeplinks.md#set-up-redirects) for the full flow.
> >
> > ```typescript theme={"dark"}
> > const options = {
> >   container: "#checkout-container",
> >   redirect: {
> >     returnUrl: "https://mystore.com/checkout",
> >   },
> >   onCheckoutComplete({ payment }) {
> >     console.log("Checkout complete.", payment);
> >   },
> > };
> > ```
> >
> > ##### Show Universal Checkout
> >
> > Pix Automático via dLocal is automatically presented when calling [Primer.showUniversalCheckout](https://primer.io/docs/sdk/web/v2.x.x/primer/methods/showUniversalCheckout.md).
> >
> > ```typescript theme={"dark"}
> > import { Primer } from "@primer-io/checkout-web";
> >
> > try {
> >   await Primer.showUniversalCheckout(clientToken, options);
> > } catch (e) {
> >   // handle error
> > }
> > ```
> >
> > Check the [customization guide](https://primer.io/docs/checkout/drop-in/customization.md#styling-payment-method-button) to learn how to customize payment method buttons.
>
> > [tab] Headless Universal Checkout (legacy)
> >
> > Create a `RedirectPaymentMethodManager` for Pix Automático via dLocal using [createPaymentMethodManager](https://primer.io/docs/sdk/web/v2.x.x/primer-headless-checkout/methods/createPaymentMethodManager.md#redirect), then call `start()` to begin the redirect flow.
> >
> > ```typescript theme={"dark"}
> > const manager = await headless.createPaymentMethodManager("YOUR_PAYMENT_METHOD_TYPE");
> >
> > if (manager) {
> >   manager.addEventListener("click", () => {
> >     // Optional: run custom logic before the redirect flow starts.
> >   });
> >
> >   await manager.start();
> > }
> > ```
> >
> > Refer to the full guide for [handling payment methods with redirect](https://primer.io/docs/checkout/headless.md#step-4c-handle-payment-methods-with-redirect).

> [tab] iOS
>
> > [!NOTE]
> >
> > Use the payment method type `DLOCAL_PIX_AUTOMATICO` wherever the code below references `YOUR_PAYMENT_METHOD_TYPE`.
>
> #### Set up redirects
>
> Redirect-based payment methods present a webpage or open a third-party app for the customer to authorize the payment. To return to your app once the customer has authorized the payment, include the `urlScheme` parameter when configuring `PrimerPaymentMethodOptions`.
>
> ```swift theme={"dark"}
> let settings = PrimerSettings(
>   // ...
>   paymentMethodOptions: PrimerPaymentMethodOptions(
>     urlScheme: "your-url-scheme://" // e.g. primer://, yourscheme://
>   )
>   // ...
> )
> ```
>
> When the customer is redirected back to your app, iOS calls `application(_:continue:restorationHandler:)`. Forward the call to the Primer SDK so the checkout can continue the flow.
>
> ```swift theme={"dark"}
> import PrimerSDK
> import UIKit
>
> @UIApplicationMain
> class AppDelegate: UIResponder, UIApplicationDelegate {
>   // ...
>   func application(
>     _ application: UIApplication,
>     continue userActivity: NSUserActivity,
>     restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
>   ) -> Bool {
>     return Primer.shared.application(
>       application,
>       continue: userActivity,
>       restorationHandler: restorationHandler
>     )
>   }
> }
> ```
>
> #### Show the payment method
>
> > [tab] Universal Checkout (drop-in)
> >
> > Pix Automático via dLocal is automatically presented when calling [Primer.shared.showUniversalCheckout](https://primer.io/docs/sdk/ios/v2.x.x/primer/methods/showUniversalCheckout.md).
> >
> > ```swift theme={"dark"}
> > class MyViewController: UIViewController {
> >   func startUniversalCheckout() {
> >     Primer.shared.showUniversalCheckout(clientToken: self.clientToken)
> >   }
> > }
> > ```
> >
> > Check the [customization guide](https://primer.io/docs/checkout/drop-in/customization.md#styling-payment-method-button) to learn how to customize payment method buttons.
>
> > [tab] Headless Universal Checkout
> >
> > Pix Automático via dLocal requires a [Native UI Manager](https://primer.io/docs/checkout/headless.md#native-ui-manager) to be presented to the customer.
> >
> > ```swift theme={"dark"}
> > // 👇 Create the payment method manager
> > let nativeUIPaymentMethodManager = try PrimerHeadlessUniversalCheckout.NativeUIManager(
> >   paymentMethodType: "YOUR_PAYMENT_METHOD_TYPE"
> > )
> >
> > // 👇 Show the payment method
> > try nativeUIPaymentMethodManager.showPaymentMethod(intent: .checkout)
> > ```
> >
> > See [NativeUIManager.init](https://primer.io/docs/sdk/ios/v2.x.x/primer-headless-checkout/native-ui-manager/init.md) for the full API. As many redirect-based payment methods share this approach, we recommend centralizing the implementation — see the worked example in the [Native UI Manager guide](https://primer.io/docs/checkout/headless.md#native-ui-manager).

> [tab] Android
>
> > [!NOTE]
> >
> > Use the payment method type `DLOCAL_PIX_AUTOMATICO` wherever the code below references `YOUR_PAYMENT_METHOD_TYPE`.
>
> > [tab] Universal Checkout (drop-in)
> >
> > Pix Automático via dLocal is automatically presented when calling [Primer.instance.showUniversalCheckout](https://primer.io/docs/sdk/android/v2.x.x/primer/methods/showUniversalCheckout.md).
> >
> > ```kotlin theme={"dark"}
> > class CheckoutActivity : AppCompatActivity() {
> >   private fun setupObservers() {
> >     viewModel.clientToken.observe(this) { clientToken ->
> >       showUniversalCheckout(clientToken)
> >     }
> >   }
> >
> >   private fun showUniversalCheckout(clientToken: String) {
> >     Primer.instance.showUniversalCheckout(this, clientToken)
> >   }
> > }
> > ```
> >
> > Check the [customization guide](https://primer.io/docs/checkout/drop-in/customization.md#styling-payment-method-button) to learn how to customize payment method buttons.
>
> > [tab] Headless Universal Checkout
> >
> > Pix Automático via dLocal requires a [Native UI Manager](https://primer.io/docs/checkout/headless.md#native-ui-manager) to be presented to the customer.
> >
> > ```kotlin theme={"dark"}
> > // 👇 Create the payment method manager
> > val nativeUiManager = PrimerHeadlessUniversalCheckoutNativeUiManager.newInstance("YOUR_PAYMENT_METHOD_TYPE")
> >
> > // 👇 Show the payment method
> > nativeUiManager.showPaymentMethod(this, PrimerSessionIntent.CHECKOUT)
> > ```
> >
> > See [NativeUiManager.newInstance](https://primer.io/docs/sdk/android/v2.x.x/primer-headless-checkout/native-ui-manager/newInstance.md) for the full API. As many redirect-based payment methods share this approach, we recommend centralizing the implementation — see the worked example in the [Native UI Manager guide](https://primer.io/docs/checkout/headless.md#native-ui-manager).

## Test in sandbox

Connect your dLocal **test** account to your Primer Sandbox environment. Toggle **Test mode** in the dLocal dashboard before copying your credentials — sandbox and production credentials are different.

## Go live

You don't need to do anything particular to go live — just make sure to use production credentials, and confirm with dLocal that Pix Automático is enabled on your production account. Both the **Refunds URL** and the **Payins notification URL** must be configured in your production dLocal dashboard.


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