> ## 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 BlueSnap mapping
This integration is currently in beta and the exact mapping of fields might still change.
## Configuration
Settlement reporting for BlueSnap uses the [`PayoutDetail` report](https://support.bluesnap.com/docs/payout-detail), which Gr4vy retrieves automatically through the BlueSnap 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 BlueSnap connector, and then open the "Settlement" tab. Enable settlement reporting on this tab.
Settlement reporting is only supported on the `bluesnap-card` connector. Both
Credit Card and Electronic Check rows are ingested regardless of payment
method, and are stamped with the `bluesnap-card` payment service.
If both `bluesnap-card` and `bluesnap-ach` are configured for the same
BlueSnap account, only enable settlement reporting on one of them to avoid
ingesting the same report twice.
### Enabling the payout webhook
Report ingestion is triggered by BlueSnap's `PAYOUT` webhook (IPN): each time BlueSnap issues a payout, it notifies Gr4vy, which then fetches and ingests the corresponding `PayoutDetail` report. Enable this webhook in the BlueSnap Merchant Portal:
1. In the Gr4vy dashboard, go to **Connections**, select your BlueSnap connection, open the **Synchronization** tab and copy the webhook URL. This is the same endpoint used for your BlueSnap transaction webhooks.
2. In the BlueSnap Merchant Portal, go to **Settings** -> **Webhook Settings**.
3. Select **Add Endpoint URL**, or edit the existing endpoint that already points to Gr4vy.
4. In the **Endpoint URL** field, paste the Gr4vy webhook URL. It must use the HTTPS protocol.
5. Toggle the **Payout** webhook on, so that it displays blue.
6. Select **Save**, then use **Test** to confirm that BlueSnap can reach the endpoint.
The payout webhook is delivered to the same endpoint as your BlueSnap
transaction webhooks, so any security header already configured for the
connector applies to it as well.
If a payout is scheduled but there are insufficient funds to generate it,
BlueSnap does not send a payout webhook, so no report is ingested for that
cycle.
## Fields mapping
Below is the mapping of BlueSnap's settlement report to the consolidated settlement report. This data is pulled from the BlueSnap `PayoutDetail` report.
| Settlement report | BlueSnap field? | BlueSnap report |
| :---------------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `payment_service_transaction_reconciliation_id` | Yes | `Merchant Transaction ID` |
| `transaction_id` | No | - |
| `payment_service_transaction_id` | Yes | `Invoice 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 | `Transaction Type` |
| `payment_service_transaction_created_at` | Yes | `Authorized on` and `Authorization time (PST)`, converted from PST to UTC (only for `settlement`) |
| `posted_at` | Yes | `Captured on` and `Capture Time (PST)`, converted from PST to UTC |
| `processing_amount_plain` | Yes | `ABS(Transaction Amount)` (only for `settlement` and `refund`) |
| `processing_currency` | Yes | `Transaction Currency` |
| `exchange_rate` | Yes | Always `null` |
| `currency` | Yes | `Payout Currency` |
| `gross_credit_plain` | Yes | `ABS(Gross Payout Amount)` for credit journal types (`settlement`, `chargeback_reversal`), else `0` |
| `net_credit_plain` | Yes | `ABS(Total Disbursement)` for credit journal types (`settlement`, `chargeback_reversal`), else `0` |
| `gross_debit_plain` | Yes | `ABS(Gross Payout Amount)` for debit journal types (`refund`, `chargeback`), else `0` |
| `net_debit_plain` | Yes | `ABS(Total Disbursement)` for debit journal types (`refund`, `chargeback`), else `0` |
| `fee_markup_plain` | Yes | Always `null` |
| `fee_interchange_plain` | Yes | Always `null` |
| `fee_scheme_plain` | Yes | Always `null` |
| `fee_total_plain` | Yes | `gross_credit_plain - net_credit_plain` for credit journal types, `net_debit_plain - gross_debit_plain` for debit journal types |
| `method` | Yes | Calculated from `Payment Type` |
| `raw_method` | Yes | `Payment Type` |
| `scheme` | Yes | Calculated from `Payment Method` |
| `raw_scheme` | Yes | `Payment Method` |
| `batch` | Yes | `Payment 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 | Always `null` |
| `payment_service_refund_reconciliation_id` | Yes | Always `null` |
| `refund_external_identifier` | No | - |
### Notes
* `payment_service_transaction_created_at` and `posted_at` are provided in Pacific Standard Time (PST) by BlueSnap and are converted to UTC by applying a fixed UTC-8 offset.
* No fee breakdown is available from BlueSnap, so `fee_interchange`, `fee_markup`, and `fee_scheme` are always `null`. `fee_total` is derived from the difference between the gross and net amounts. For charges, this equals `ABS(BlueSnap Processing Fees)`; for refunds, the fee is returned, so the net debit is lower than the gross debit and `fee_total` is negative.
* `scheme` is derived from the `Payment Method` column (for example `Visa CREDIT`). Non-card values (for example Electronic Check rows) and card schemes with no equivalent are set to `null`.
* `Surcharge Amount` is documented by BlueSnap but is not currently included in the settlement report.
### Journal type mapping
| BlueSnap raw journal type | Journal type |
| :------------------------ | :-------------------- |
| `CHARGE` | `settlement` |
| `REFUND` | `refund` |
| `CHARGEBACK` | `chargeback` |
| `CHARGEBACK WIN` | `chargeback_reversal` |
| `Second Chargeback` | `chargeback` |
| `RDR Reversal` | `other` |
| any other value | `other` |
Fields marked as not being a **BlueSnap field** are populated from internal
data and not from the imported payment service report.