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

<Warning>This integration is in beta</Warning>

Below is the mapping of Nuvei's settlement report to the system. This data is pulled from Nuvei's `movement report`.
This report is imported on a daily basis and allows for full end to end reconciliation between a bank account and Nuvei's payables.

The report contains transaction level settlement information including fees, chargebacks and refunds.
Nuvei reports on all movements of funds, also settlements that have occurred externally from the Nuvei platform.
Since settlement data is imported that pertains to movements of funds in the Nuvei platform, line items where the `settlement amount` : `0` are filtered out.

All journal types from the movement report are imported which by Nuvei standards are notated by the `movement type` and `movement details`.
In the report these two columns are concatenated in the `raw_journal_type` column.
Transactions with `journal_type: settled` are taken from the Nuvei `raw_journal_type: sale-sale`.

In the Nuvei movement report the fees are deducted from the processing amount in the processing currency.
In the report however the fees are provided in the settlement currency. Therefore the fees in the report are modified as `fee * conversion rate`.

<Note>
  Nuvei's movement report needs to be scheduled via their dashboard to be able
  to import. Please follow their **Back Office Operations - Reports**
  guidelines on how to set up a new schedule for the Movement Report. Make sure
  to set the delivery type to **SFTP**. To be able to import the report
  please set the following naming convention:
  `settlement-report-YYYY-MM-DD.csv`.
</Note>

| Settlement report                               | Nuvei field? | Nuvei report                                                                        |
| :---------------------------------------------- | :----------- | :---------------------------------------------------------------------------------- |
| `payment_service_transaction_reconciliation_id` | Yes          | `Client Unique ID`                                                                  |
| `transaction_id`                                | No           | -                                                                                   |
| `payment_service_transaction_id`                | Yes          | `Transaction ID` (for `settlement` only)                                            |
| `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          | `Movement Type \| Movement Details`                                                 |
| `payment_service_transaction_created_at`        | Yes          | Always `null`                                                                       |
| `posted_at`                                     | Yes          | `Movement Date`                                                                     |
| `processing_amount_plain`                       | Yes          | `End User Amount`                                                                   |
| `processing_currency`                           | Yes          | `End User Currency`                                                                 |
| `exchange_rate`                                 | Yes          | `(Amount / End User Amount) * Conversion Rate` (only for `refund` and `settlement`) |
| `currency`                                      | Yes          | `Settlement Currency`                                                               |
| `gross_credit_plain`                            | Yes          | `ABS(Amount) * Conversion Rate` if `Settlement Amount > 0` else `0`                 |
| `net_credit_plain`                              | Yes          | `ABS(Settlement Amount)` if `Settlement Amount > 0` else `0`                        |
| `gross_debit_plain`                             | Yes          | `ABS(Amount) * Conversion Rate` if `Settlement Amount < 0` else `0`                 |
| `net_debit_plain`                               | Yes          | `ABS(Settlement Amount)` if `Settlement Amount < 0` else `0`                        |
| `fee_markup_plain`                              | Yes          | `ABS(Plus Commission) * Conversion Rate`                                            |
| `fee_interchange_plain`                         | Yes          | `ABS(Interchange Fee) * Conversion Rate`                                            |
| `fee_scheme_plain`                              | Yes          | `ABS(Scheme Fee) * Conversion Rate`                                                 |
| `fee_total_plain`                               | Yes          | `ABS(Amount - Net Amount) * Conversion Rate`                                        |
| `method`                                        | Yes          | Standardized value of `raw_method`                                                  |
| `raw_method`                                    | Yes          | `Payment Method`                                                                    |
| `scheme`                                        | Yes          | Standardized value of `raw_scheme`                                                  |
| `raw_scheme`                                    | Yes          | `null` if `Card Type IS NULL` else `Payment Method`                                 |
| `batch`                                         | Yes          | `Batch ID`                                                                          |
| `report_id`                                     | No           | -                                                                                   |
| `raw_report_ids`                                | No           | -                                                                                   |
| `ingested_at`                                   | No           | -                                                                                   |
| `description`                                   | Yes          | Always `null`                                                                       |
| `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          | `Movement ID`                                                                       |
| `payment_service_refund_reconciliation_id`      | Yes          | Always `null`                                                                       |

### Notes

* `payment_service_transaction_created_at` is set to `null` since, unfortunately, no creation date of the transaction is given, only the `posted_at` date is available. It's therefore not possible to see from the report on which date the original transaction took place on the Nuvei platform.
* `ABS()` means absolute value transformation is applied to the original value

### Journal type mapping

| Nuvei raw journal type                | Journal type          |
| :------------------------------------ | :-------------------- |
| `Cancelled CB \| Recalled Chargeback` | `chargeback_reversal` |
| `Chargeback \| Chargeback Regular`    | `chargeback`          |
| `Credits \| Credit`                   | `refund`              |
| `Sales \| Sale`                       | `settlement`          |
| any other value                       | `other`               |

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