Adyen Settlement Mapping

This guide explains how Adyen Settlement Details report rows map to instellix Settlement Items.

Use it if you:

Integrate Adyen settlements via the Settlement Item API (hybrid / custom intake), or
Need to understand how automatic Adyen settlement intake appears in instellix

For settlement concepts and the amount model, see Settlements.
For Adyen provider setup, see Payment Provider Adyen.

API: POST /v2/merchant-payment-accounts/{merchantPaymentAccountIdent}/settlement-reports/{reportIdent}/settlement-items
→ Create settlement item

Amount model

instellix field	Meaning
`baseAmount`	Gross amount in settlement currency (Adyen Net Currency). Not net-after-fees.
`originalAmount`	Amount in original transaction currency (Adyen Gross Currency)
`exchangeRate`	How many units of original currency = 1 unit of settlement currency. Invert Adyen’s rate.
`fees[]`	Fee lines in settlement currency. Already reflected in reconstructing `baseAmount` for Settled/Refund/Chargeback.

🚧
Common mistake: putting net-after-fees in baseAmount and gross in originalAmount.
For Settled / Refunded / Chargeback: reconstruct gross in net currency as net ± Σ fees, and list fees separately.

CSV → Settlement Item

Adyen column	instellix field
`Type`	Drives the whole mapping (see journal types)
`Merchant Account`	Resolves Merchant Payment Account
`Gross Credit/Debit (GC)` + `Gross Currency`	`originalAmount`
`Net Credit/Debit (NC)` + fees	`baseAmount` (see rules below)
`Net Currency`	Currency of `baseAmount` and fees
`Exchange Rate`	`exchangeRate` = `1 / AdyenRate` (5 decimals, banker’s rounding)
`Commission / Markup / Scheme Fees / Interchange (NC)`	`fees[]` → `COMMISSION`, `MARKUP`, `SCHEME_FEES`, `INTERCHANGE`
`Modification Reference` / `Psp Reference`	`externalIdent` (type-dependent)
`Merchant Reference`	`text` + property `merchantReference`
`Batch Number`	property `batchNumber`
`Creation Date` + `TimeZone`	`bookingDate`, `valueDate`

Journal types

Adyen `Type`	Credit/Debit	`externalIdent`	Notes
`Balancetransfer`	—	—	Skipped — no Settlement Item
`Settled`	CREDIT	`modificationReference`	Customer payment
`Refunded`	DEBIT	`modificationReference`
`RefundedReversed`	CREDIT	`<modRef>-reversed`
`Chargeback` / `SecondChargeback`	DEBIT	`<modRef>-<pspRef>`	Category `CHARGEBACK`
`ChargebackReversed`	CREDIT	`<modRef>-<pspRef>-reversed`	Category `UNCATEGORISED`
`Fee`	CREDIT or DEBIT	normalised `modificationReference`*	No fee offsetting on `baseAmount`
`MerchantPayout`	CREDIT or DEBIT	normalised `modificationReference`*	No fee offsetting
`InvoiceDeduction`	CREDIT or DEBIT	normalised `modificationReference`*	No fee offsetting
`MerchantPayin`	CREDIT	`pspReference`
`DepositCorrection` / `ReserveAdjustment`	CREDIT or DEBIT	`<normalised modRef>-batch-<batchNumber>`	No fee offsetting

* Normalised: lowercase, commas removed, spaces → -.

📘
On the Settlement Item API payload, paymentCategory is only CHARGEBACK or UNCATEGORISED. Only Chargeback / SecondChargeback stay CHARGEBACK.

`baseAmount` rules

Settled / Refunded / Chargeback / ChargebackReversed: reconstruct gross in net currency
- Credit: netCredit + Σ fees
- Debit: netDebit − Σ fees
Fee / MerchantPayout / InvoiceDeduction / DepositCorrection / MerchantPayin / ReserveAdjustment: use net amount directly (no fee offsetting)

`exchangeRate`

Adyen reports Gross → Net. instellix expects original → settlement:

exchangeRate = 1 / AdyenExchangeRate

Example: Adyen 0.132261937748222 → instellix 7.56075 (1 EUR = 7.56075 DKK).

Examples

Settled — same currency (EUR)

Adyen net credit 145.35 + fees 0.89 + 0.30 + 1.72 → baseAmount = 148.26 EUR

{
  "creditDebitIndicator": "CREDIT",
  "bookingDate": "2025-10-17T13:40:59+02:00",
  "valueDate": "2025-10-17T13:40:59+02:00",
  "externalIdent": "X7GQ2MRT9KZP4W83",
  "text": "0000418902",
  "baseAmount": { "amount": 148.26, "currency": "EUR" },
  "originalAmount": { "amount": 148.26, "currency": "EUR" },
  "exchangeRate": 1.00000,
  "fees": [
    { "type": "MARKUP", "amount": { "amount": 0.89, "currency": "EUR" } },
    { "type": "SCHEME_FEES", "amount": { "amount": 0.30, "currency": "EUR" } },
    { "type": "INTERCHANGE", "amount": { "amount": 1.72, "currency": "EUR" } }
  ],
  "properties": [
    { "propertyIdent": "batchNumber", "propertyValue": "6" },
    { "propertyIdent": "merchantReference", "propertyValue": "0000418902" },
    { "propertyIdent": "modificationReference", "propertyValue": "X7GQ2MRT9KZP4W83" }
  ]
}

Settled - FX (DKK -> EUR)

baseAmount = 14.03 + 0.09 + 0.03 + 0.17 = 14.32 EUR
exchangeRate = 1 / 0.132261937748222 = 7.56075

{
  "creditDebitIndicator": "CREDIT",
  "externalIdent": "K9RPZ3XM7QTD2N48",
  "text": "0000418977",
  "baseAmount": { "amount": 14.32, "currency": "EUR" },
  "originalAmount": { "amount": 108.27, "currency": "DKK" },
  "exchangeRate": 7.56075,
  "fees": [
    { "type": "MARKUP", "amount": { "amount": 0.09, "currency": "EUR" } },
    { "type": "SCHEME_FEES", "amount": { "amount": 0.03, "currency": "EUR" } },
    { "type": "INTERCHANGE", "amount": { "amount": 0.17, "currency": "EUR" } }
  ]
}

Amount model

CSV → Settlement Item

Journal types

baseAmount rules

exchangeRate

Examples

Settled — same currency (EUR)

Settled - FX (DKK -> EUR)

`baseAmount` rules

`exchangeRate`