Skip to main content
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

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

​
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

  1. Run a test payment using a dLocal test card.
  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
Last modified on September 28, 2026