dLocal

Who should use this guideThis 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

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

About workspacesWorkspaces 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

What you’ll need from dLocalBefore 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

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

API credentials

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

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

Create webhooks in the same mode (test or live) as your Payrails integration.

In Payrails

Copy the notification URL.

In dLocal

Go to Integration → Endpoint
Paste the Payrails notification URL into:
- Payins notification URL
- Refunds
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

Request fields for dLocal

Send these fields in the authorize request 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.

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.

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.

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.

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

Run a test payment using a dLocal test card.
Verify that:
- The payment appears in dLocal.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a dLocal integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider