Settlements
Settlements are the Payment Reporting layer in instellix: money that a payment provider or bank has settled on a merchant account.
A settlement is the hard anchor for accounting. A successful charge can still be cancelled or disputed before settlement — bookkeeping typically follows settled amounts.
Core objects
| Object | Meaning |
|---|---|
| Settlement Report | A statement / account statement from a PSP or bank for one payout or statement cycle (also called settlement batch, statement, etc. at the provider) |
| Settlement Item | One financial movement inside that report (payment, refund, chargeback, fee, payout, adjustment, …) |
| Payment Transaction | Operational transaction record. Creating a settlement item creates (or settles) a payment transaction in status SETTLED |
In reporting-only setups, transaction and settlement volumes often align. In full-service (instellix also charges), you may see transactions that are not settled yet, or that never settle.
How settlement data enters instellix
- Automatic provider intake (preferred for supported PSPs)
- API push — create a settlement report, then create settlement items (typical for hybrid / custom integrations)
Every settlement item belongs to a Merchant Payment Account.
Processing flow
After a settlement item is created:
- A Payment Transaction is created/updated as SETTLED
- Categorization runs (payment categorization rules), if configured
- Payment assignment to open invoices / documents may run (OPOS), if the category is assignable and matching succeeds
If no rule matches, the transaction stays uncategorized. Further processing depends on tenant configuration (categories, assignment configuration on the merchant payment account).
Work in the webportal
Go to: Payment > Settlements (and Settlement Reports)
Use the overviews to:
- Inspect settlement reports (statements) per merchant payment account
- Open settlement items and linked payment transactions
- Support reconciliation for accounting (report = statement to match against the PSP/bank)
Create via API (hybrid / custom intake)
1. Create Settlement Report
POST /v2/merchant-payment-accounts/{merchantPaymentAccountIdent}/settlement-reports
Required fields:
| Field | Purpose |
|---|---|
ident | Unique report ID on the merchant payment account |
fileName | Original statement / file name from the PSP or bank |
statementReference | Business reference of the statement / payout |
statementCreationDate | When the PSP/bank created the statement |
2. Create Settlement Items
POST /v2/merchant-payment-accounts/{merchantPaymentAccountIdent}/settlement-reports/{settlementReportIdent}/settlement-items
Minimum fields:
| Field | Purpose |
|---|---|
externalIdent | Unique ID within the merchant payment account (often the PSP transaction ID) |
bookingDate | Booking timestamp |
creditDebitIndicator | CREDIT or DEBIT |
baseAmount | Amount in the settlement currency (MPA currency) |
Recommended for matching: text (description / remittance) — categorization and assignment often key off this field.
Creating an item results in a Payment Transaction in status SETTLED.
Amount model (baseAmount vs originalAmount)
baseAmount vs originalAmount)| Field | Meaning |
|---|---|
baseAmount | Gross amount in the settlement currency (currency of the merchant payment account / payout). Must match the MPA currency. |
originalAmount | Amount in the original transaction currency (what the customer paid). If omitted, instellix treats it as equal to baseAmount. |
exchangeRate | Required when currencies differ. Formula: originalAmount / exchangeRate ≈ baseAmount (tolerance applies). Max 5 decimal places. |
fees[] | Fee lines (COMMISSION, MARKUP, SCHEME_FEES, INTERCHANGE, STANDARD_FEE). Fee currency must match baseAmount.currency. |
baseAmountis not “net after fees”.
For payment-like movements, report the gross amount in settlement currency. List fees separately infees[]for transparency — do not subtract fees frombaseAmountand put “gross” only inoriginalAmount.
Example (same currency): customer pays €148.26, fees €2.91 → baseAmount = 148.26 EUR, fees listed in fees[].
Example (FX): customer pays 108.27 DKK, merchant settles in EUR → originalAmount in DKK, baseAmount in EUR, exchangeRate set accordingly.
Related articles
Updated about 1 hour ago