> ## 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.

# dLocal

> Connect dLocal to Payrails for payment processing, covering API credentials, webhooks, and the payment methods you enable.

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

> [!NOTE]
>
> **Who should use this guide**
>
> This guide is intended for merchants who:
>
> * Use **Payrails** as a payment orchestrator
> * Use **dLocal Payments** for payment processing
> * Have an active dLocal account with API access enabled
>
> *If these requirements are not met, payments may fail in production.*

***

## Create a dLocal integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

> [!NOTE]
>
> **About workspaces**
>
> Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **dLocal**.
* Continue to the next step.

***

## Step 3: Configure your dLocal integration

> [!TIP]
>
> **What you'll need from dLocal**
>
> Before you begin, make sure you have access to:
>
> * API credentials (keys, certificates, or secrets)
> * Webhook or notification signing secret (if applicable)
>
> You'll need to log in to the dLocal dashboard to complete this step.

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration.

![Payrails dLocal integration instance name field](https://mintcdn.com/payrails-42074109/6ZmkK5ZUHpx1-EP_/images/docs/dlocal-basic-information.png?fit=max\&auto=format\&n=6ZmkK5ZUHpx1-EP_\&q=85\&s=b9a43582acab50b93394ecc2898d5ecf)

* Use a name that is easy to remember, especially for routing purposes
* Example: `merchant_dlocal` (or another descriptive name)

***

### API credentials

> [!TIP]
>
> Use restricted or scoped credentials where possible to limit access and reduce
> risk.

**In dLocal**

* Log in to the dLocal dashboard
* Enable **Test Mode** at the top of the page when working in staging (this switches the environment to staging)
* Go to **Developers**
* Click **Integration**
* Create a new pair of API keys by selecting **Create new**
* Copy the following parameters:
  * `X-Login`
  * `X-Trans-Key`
  * `Secret Key`

**In Payrails**

* Paste the three parameters into the respective fields

![Payrails dLocal API credential fields for X-Login, X-Trans-Key, and Secret Key](https://mintcdn.com/payrails-42074109/6ZmkK5ZUHpx1-EP_/images/docs/dlocal-image-02.png?fit=max\&auto=format\&n=6ZmkK5ZUHpx1-EP_\&q=85\&s=0acc446b37ad0873f73c6b9599c33052)

***

### Webhooks or notifications

> [!NOTE]
>
> Payrails uses provider webhooks or notifications to receive asynchronous
> payment status updates.

> [!WARNING]
>
> Create webhooks in the same mode (test or live) as your Payrails integration.

**In Payrails**

* Copy the notification URL.

**In dLocal**

1. Go to **Integration** → **Endpoint**

2. Paste the Payrails notification URL into:
   * **Payins notification URL**
   * **Refunds**

3. Click **Save changes**

***

### Payment methods

**In Payrails**

* Select the payment methods that should be enabled for this integration.

![Payrails payment methods selection for dLocal integration](https://mintcdn.com/payrails-42074109/6ZmkK5ZUHpx1-EP_/images/docs/dlocal-image-03.png?fit=max\&auto=format\&n=6ZmkK5ZUHpx1-EP_\&q=85\&s=51e795f18d77752c6e0563c02262af3e)

***

## Request fields for dLocal

Send these fields in the [authorize request](https://docs.payrails.com/reference/authorizeaction.md) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to dLocal when you include them. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to dLocal as the amount and currency. |
| `meta.customer.country.code` | Required | Sent as the payment country. |
| `meta.customer.name` | Required | Sent as the payer name, with `meta.customer.lastName`. |
| `meta.customer.email` | Required | Sent as the payer email. |
| `merchantReference` | Optional | Sent as the order ID. |
| `meta.customer.birthDate`, `phone`, `reference` | Optional | Sent as the payer's date of birth, phone and user reference. |
| `meta.customer.identityCardNumber` | Optional | Sent as the payer document. |
| `meta.order.deliveryAddress` | Optional | Sent as the payer address. Payrails uses the billing address when it's missing. |
| `meta.order.description` | Optional | Sent as the payment description. |
| `meta.order.softDescriptor` | Optional | Sent as the card descriptor. |
| `meta.clientContext.clientType`, `ipAddress`, `deviceFingerprint`, `userAgent` | Optional | Sent as the device type, payer IP and device ID. |
| `meta.risk.threeDSMode` | Optional | `Force` requests 3D Secure. |
| `instrument.holderName` | Optional | Sent as the card holder name. |
| `meta.tags`, `holderReference` | Optional | Sent as basket risk data when you choose them as a source. Refer to [Basket risk data](#basket-risk-data). |

***

## Configure dLocal settings

Some dLocal integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting. You find them under **Account details**.

### Basket risk data

**Basket item reference**, **Basket category** and **Basket brand** choose what Payrails sends to dLocal as basket risk data (`additional_risk_data.basket`) with each payment, for every payment method.

| Option | Value Payrails sends |
| :- | :- |
| `holderReference` | The `holderReference` of the payment |
| `merchantReference` | The `merchantReference` of the payment |
| `metaTag` | The value of a key you choose in `meta.tags`. Enter the key in the matching **meta tag key** field. For example, enter `gameId` and send `meta.tags.gameId` in your request. |
| Blank | Nothing. The field isn't sent. |

When all three are blank, Payrails sends no basket risk data. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md).

***

## Enable the integration

**In Payrails**

* Save the configuration to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **dLocal** integration is now ready to process payments in test mode.

> [!NOTE]
>
> The dLocal production environment requires IP whitelisting. Contact the
> Payrails team to obtain the list of IP addresses that must be allowlisted in
> dLocal before going live.

***

## Next steps

1. Run a test payment using a dLocal [test card](https://docs.dlocal.com/docs/make-a-test-payment).

2. Verify that:
   * The payment appears in dLocal.
   * The payment status updates correctly in Payrails.

3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md)


## Related topics

- [dLocal](https://docs.payrails.com/docs/integrations/data-sources/dlocal.md)
- [BCP via dLocal](https://docs.payrails.com/docs/integrations/payment-methods/bcp/dlocal.md)
- [Maya via dLocal](https://docs.payrails.com/docs/integrations/payment-methods/maya/dlocal.md)


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