> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement report dLocal mapping

<Warning>This integration is currently in beta and the exact mapping of fields might still change.</Warning>

To enable settlement reporting for dLocal, please follow [this guide](https://docs.dlocal.com/docs/reporting-payins#accessing-reports-via-sftp) to enable SFTP access.

Settlement reporting needs to be set up with dLocal with the following considerations:

1. The report must be a [Settlement - Cross-border Payins Model](https://docs.dlocal.com/docs/reporting-payins) report.
2. The report must be in CSV format to be delivered via SFTP.
3. Please contact support to get a list of IP addresses for dLocal to whitelist.
4. The report filename must follow the naming convention `<merchant_name>_cross_border_report_YYYYMMDD_HHMMSS.csv`.

After SFTP access has been set up, SFTP credentials are received from dLocal. These credentials are used when enabling settlement reporting in the dLocal connector configuration in the dashboard.

To set up these credentials, please go to the "Connections" tab, select the dLocal connector and navigate to the "Settlement" tab.
Here settlement reporting can be enabled, after which prompts are provided to fill out the following:

1. The SFTP username.
2. The SFTP SSH key.
3. The SFTP address, which should include a port number. If it is not provided, the port number is defaulted to `22`.
4. The filename prefix, which is the expected report filename without the `_YYYMMDD_HHMMSS.csv` part, for example `<merchant_name>_cross_border_report`.

Below is the mapping of dLocal's report to the consolidated settlement report. This data is pulled from dLocal's [Settlement - Cross-border Payins Model](https://docs.dlocal.com/docs/reporting-payins) report.

| Settlement report                               | dLocal field? | dLocal report                                                         |
| :---------------------------------------------- | :------------ | :-------------------------------------------------------------------- |
| `payment_service_transaction_reconciliation_id` | Yes           | `TRANSACTION_ID`                                                      |
| `transaction_id`                                | No            | -                                                                     |
| `payment_service_transaction_id`                | Yes           | `DLOCAL_TRANSACTION_ID` (only when starting with 'T-')                |
| `payment_service_id`                            | No            | -                                                                     |
| `payment_service_definition_id`                 | No            | -                                                                     |
| `payment_service_display_name`                  | No            | -                                                                     |
| `journal_type`                                  | Yes           | Check journal type mapping table below                                |
| `raw_journal_type`                              | Yes           | `ROW_TYPE`                                                            |
| `payment_service_transaction_created_at`        | Yes           | `CREATION_DATE` (only when `DLOCAL_TRANSACTION_ID` starts with 'T-')  |
| `posted_at`                                     | Yes           | `TRANSFER_DATE`                                                       |
| `processing_amount_plain`                       | Yes           | `LOCAL_AMOUNT`                                                        |
| `processing_currency`                           | Yes           | `LOCAL_CURRENCY`                                                      |
| `exchange_rate`                                 | Yes           | `FX_RATE`                                                             |
| `currency`                                      | Yes           | `SETTLEMENT_CURRENCY`                                                 |
| `gross_credit_plain`                            | Yes           | `GROSS_AMOUNT` (only for `chargeback_reversal` and `settlement`)      |
| `net_credit_plain`                              | Yes           | `NET_AMOUNT` (only for `chargeback_reversal` and `settlement`)        |
| `gross_debit_plain`                             | Yes           | `(-1) * GROSS_AMOUNT` (only for `chargeback` and `refund`)            |
| `net_debit_plain`                               | Yes           | `(-1) * NET_AMOUNT` (only for `chargeback` and `refund`)              |
| `fee_markup_plain`                              | Yes           | Always `null`                                                         |
| `fee_interchange_plain`                         | Yes           | Always `null`                                                         |
| `fee_scheme_plain`                              | Yes           | Always `null`                                                         |
| `fee_total_plain`                               | Yes           | `FEE_AMOUNT`                                                          |
| `method`                                        | Yes           | Standardized value of `raw_method`                                    |
| `raw_method`                                    | Yes           | `PAYMENT_TYPE` for card transactions, `PAYMENT_METHOD_CODE` otherwise |
| `scheme`                                        | Yes           | Standardized value of `raw_scheme`                                    |
| `raw_scheme`                                    | Yes           | `PAYMENT_METHOD_CODE` for card transactions, `null` otherwise         |
| `batch`                                         | Yes           | `TRANSFER_ID`                                                         |
| `report_id`                                     | No            | -                                                                     |
| `raw_report_ids`                                | No            | -                                                                     |
| `ingested_at`                                   | No            | -                                                                     |
| `description`                                   | Yes           | `DESCRIPTION`                                                         |
| `transaction_external_identifier`               | No            | -                                                                     |
| `transaction_metadata`                          | No            | -                                                                     |
| `report_payment_service_id`                     | No            | -                                                                     |
| `report_payment_service_definition_id`          | No            | -                                                                     |
| `report_payment_service_display_name`           | No            | -                                                                     |
| `payment_service_modification_reference`        | Yes           | `DLOCAL_TRANSACTION_ID`                                               |
| `payment_service_refund_reconciliation_id`      | Yes           | Always `null`                                                         |

### Notes

* Timestamp columns do not contain any timezone info, so they are assumed to be in the `UTC` timezone.

### Journal type mapping

| dLocal raw journal type | Journal type          |
| :---------------------- | :-------------------- |
| `CAPTURE`               | `settlement`          |
| `CHARGEBACK`            | `chargeback`          |
| `CHARGEBACK_REVERSAL`   | `chargeback_reversal` |
| `PAYMENT`               | `settlement`          |
| `REFUND`                | `refund`              |
| any other value         | `other`               |

<Note>
  Fields marked as not a **dLocal field** are populated from internal data and not
  from the imported payment service report.
</Note>