> ## 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 required dLocal reports and set up SFTP access to ingest payins and settlement data into Payrails.

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

### 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](/docs/orchestration/integrations/dlocal.md)
- [Pix Automático](/docs/orchestration/payment-methods/pix-automatico.md)
- [Nequi](/docs/orchestration/payment-methods/nequi.md)