> ## 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 Checkout.com mapping

> [!WARNING]
>
> This integration is currently in beta and the exact mapping of fields might still change.

## Configuration

Settlement reporting for Checkout.com uses the [`SettlementBreakdown` report](https://www.checkout.com/docs/funds-management/retrieve-financial-reports/settlement-reports/settlement-breakdown-report), which Gr4vy retrieves automatically through the Checkout.com Reporting API (REST). Unlike some other integrations, you do not need to set up SFTP access; Gr4vy fetches the report using the API credentials you already configured on the connector.

To enable settlement reporting, go to the "Connections" tab, select the Checkout.com connector, and then open the "Settlement" tab. Enable settlement reporting on this tab.

### Enabling the report generated webhook

Report ingestion is triggered by Checkout.com's `report_generated` webhook: each time Checkout.com issues a `SettlementBreakdown` report, it notifies Gr4vy, which then fetches and ingests the corresponding `SettlementBreakdown` report. Enable this webhook in the Checkout.com Dashboard:

1. In the Gr4vy dashboard, go to **Connections**, select your Checkout.com connection, open the **Synchronization** tab and copy the webhook URL. This is the same endpoint used for your Checkout.com transaction webhooks.
2. In the Checkout.com Dashboard, go to **Developers** -> **Webhooks**.
3. Edit the existing webhook configuration that points to Gr4vy. If you have not registered it yet, first complete the [Checkout.com webhook setup](https://docs.gr4vy.com/connections/payments/checkout.md#webhooks), including saving its signature key in your Gr4vy connection.
4. Confirm that the **Endpoint URL** matches the Gr4vy webhook URL and uses HTTPS.
5. Enable **Report** -> **Report generated** while preserving the existing payment event selections.
6. Select **Save changes**.

> [!NOTE]
>
> The `report_generated` webhook is delivered to the same endpoint as your Checkout.com
> transaction webhooks, so any security header already configured for the
> connector applies to it as well.

## Fields mapping

Below is the mapping of Checkout.com's settlement report to the consolidated settlement report. This data is pulled from the Checkout.com `SettlementBreakdown` report.

| Settlement report | Checkout.com field? | Checkout.com report |
| :- | :- | :- |
| `payment_service_transaction_reconciliation_id` | Yes | `Reference` (only for non-`refund` journal types) |
| `transaction_id` | No | - |
| `payment_service_transaction_id` | Yes | `Payment ID` |
| `payment_service_id` | No | - |
| `payment_service_definition_id` | No | - |
| `payment_service_display_name` | No | - |
| `journal_type` | Yes | See the journal type mapping table below. |
| `raw_journal_type` | Yes | `Type` or `Type \| +/-ve net` for chargeback journal types depending on `Net In Holding Currency` polarity |
| `payment_service_transaction_created_at` | Yes | Always `null` |
| `posted_at` | Yes | `Available On UTC` |
| `processing_amount_plain` | Yes | `ABS(Gross In Processing Currency)` |
| `processing_currency` | Yes | `Processing Currency` |
| `exchange_rate` | Yes | `FX Rate Applied` |
| `currency` | Yes | `Holding Currency` |
| `gross_credit_plain` | Yes | `Gross In Holding Currency` if `Gross In Holding Currency > 0`, else `0` |
| `net_credit_plain` | Yes | `Net In Holding Currency` if `Net In Holding Currency > 0`, else `0` |
| `gross_debit_plain` | Yes | `ABS(Gross In Holding Currency)` if `Gross In Holding Currency < 0`, else `0` |
| `net_debit_plain` | Yes | `ABS(Net In Holding Currency)` if `Net In Holding Currency < 0`, else `0` |
| `fee_markup_plain` | Yes | `(-1) * Processing Fee In Holding Currency` |
| `fee_interchange_plain` | Yes | `(-1) * Interchange In Holding Currency` |
| `fee_scheme_plain` | Yes | `(-1) * Scheme Fee In Holding Currency` |
| `fee_total_plain` | Yes | `(-1) * Deduction In Holding Currency` |
| `method` | Yes | Calculated from `Payment Method` |
| `raw_method` | Yes | `Payment Method` |
| `scheme` | Yes | Calculated from `Payment Method` |
| `raw_scheme` | Yes | `Payment Method` |
| `batch` | Yes | `Payout ID` |
| `report_id` | No | - |
| `raw_report_ids` | No | - |
| `ingested_at` | No | - |
| `description` | Yes | `null` or 'ARN: `Acquirer Reference Number`' if `Acquirer Reference Number` present |
| `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 | `Action ID` |
| `payment_service_refund_reconciliation_id` | Yes | Always `null` |
| `refund_external_identifier` | No | - |

### Journal type mapping

| Checkout.com raw journal type | Journal type |
| :- | :- |
| `Charge` | `settlement` |
| `Partial Charge` | `settlement` |
| `Clearing Failed` | `settlement_failure` |
| `Refund` | `refund` |
| `Partial Refund` | `refund` |
| `Chargeback (*) \| -ve net` | `chargeback` |
| `Chargeback (*) \| +ve net` | `chargeback_reversal` |
| any other value | `other` |

> [!NOTE]
>
> Fields marked as not being a **Checkout.com field** are populated from internal
> data and not from the imported payment service report.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.