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

> Enable the dLocal payins and settlement reports, set up SFTP access with your dLocal TAM, and connect dLocal as a data source in Payrails.

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

This guide will help you enable the required dLocal reports and set up SFTP access and connect dLocal as a data source in Payrails to ingest payins and settlement data. With the self-serve flow you configure the integration yourself in the Payrails dashboard — you no longer share credentials with Payrails.

## Prerequisites

* An active dLocal merchant account
* A point of contact with your **dLocal Technical Account Manager (TAM)**
* SFTP access to dLocal's reporting server (set up with your TAM, see Step 2)

***

## Step-by-step instructions

### Step 1: Enable the required reports in dLocal

Ask your dLocal Technical Account Manager to enable the following **Payins reports** for your account. dLocal tailors reports to your processing model (cross-border or local-to-local), so enable the ones that match your setup:

* **Daily Payins — Cross-border Model** - daily breakdown of cleared transactions for the cross-border model (non-local legal entity setup).
* **Daily Payins — Local-to-local Model** - daily summary of cleared transactions for the local-to-local model (local legal entity setup).
* **Settlement — Cross-border Payins Model** - settlement breakdown of cleared transactions for cross-border operations.
* **Settlement — Local-to-local Payins Model** - settlement breakdown of cleared transactions for local-to-local operations.

These reports cover charges, settlements, fees, authorizations and failure reasons, which Payrails maps into its unified datasets for analytics and reconciliation.

### Step 2: Set up SFTP access with dLocal

dLocal delivers these reports over **SFTP**. Coordinate with your TAM to set up access:

1. Provide the following to your dLocal TAM:
   * The **IP address(es)** Payrails will connect from, to be whitelisted on dLocal's SFTP server. *(Payrails provides these connection IPs - request them from your Payrails contact.)*
   * The **public key** of an SSH key pair (must be OpenSSH-compatible; generate with `ssh-keygen -t rsa -b 4096` or PuTTYgen). Keep the matching **private key** - you will enter it in Payrails in Step 3.
2. Once your TAM confirms the SFTP setup is complete, they will share your SFTP connection details:
   * **Host**
   * **Port**
   * **Username**

> [!NOTE]
>
> Backfilling historical dLocal reports is arranged through your TAM and can take **1–2 weeks** to provision. Self-serve backfilling is not available yet.

### Step 3: Add the dLocal integration in the Payrails dashboard (self-serve)

1. Log in to the Payrails dashboard and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In **New instance**, select the **dLocal**, then continue.
4. On the **Configure dLocal account** screen, fill in (all fields are required):
   * **Integration instance name** - a unique name that helps you identify this account.
   * **Start Date** - the date of today or tomorrow (currently we can not backfill over the sel-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
   * Under **SFTP Credentials**, enter the details shared by your dLocal TAM:
     * **Host**
     * **Port**
     * **Username**
     * **Private Key** — the private key matching the SSH public key you shared with dLocal in Step 2.
5. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.


## Related topics

- [dLocal](https://docs.payrails.com/docs/integrations/payment-providers/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.