Settlement Reporting

CrissCross produces a structured settlement report at the time of each settlement, delivered alongside the wire. Every report ties one bank credit you receive back to the individual transactions — collections, refunds, payouts, fees, FX, and adjustments — that produced it, so you can reconcile against your own ledger.

The reporting model is built on one guarantee:

One file = one SubMID = one settlement = one wire.

Each settlement produces exactly one report, sharing a single SettlementID with the wire it accompanies. There is no wire without a file, and no file without a wire.

MID and SubMID

Settlement is organised around a two-level merchant hierarchy. Understanding it is the key to reading a settlement report, because every report is scoped to a single SubMID.

A single MID typically has several SubMIDs — one per currency it collects in:

Acme                         ← MID (parent merchant)
├── AcmeKES  (KES → USD)     ← SubMID, settles in USD
├── AcmeNGN  (NGN → USD)     ← SubMID, settles in USD
└── AcmeZAR  (ZAR → USD)     ← SubMID, settles in USD

Because a SubMID is scoped to one processing currency, settlement always happens per SubMID: AcmeKES and AcmeNGN settle separately, each on its own schedule, each producing a distinct file and wire.

How settlement works

The settlement engine runs on each SubMID’s configured cadence (its settlement delay, e.g. T+2, is a per-SubMID property). For each cycle:

The settlement model

The net settlement amount is a rolling net, computed per SubMID per cycle:

NetSettlementAmount =
    (collections + refund_returned + payout_reversed + positive_adjustments + reserve_releases)
  − (refunds + payouts + negative_adjustments + reserve_holds)
  − processing_fees

Fees are netted internally on both inflows and outflows:

• Collections — the customer pays Gross. Net = Gross − Fee, and you receive Net.
• Refunds / payouts — the customer or beneficiary receives the full requested amount; the fee is an additional deduction from your balance. Gross is shown negative, Fee positive, and Net = Gross − Fee.

Each line carries its gross in the processing currency and its net already converted to the settlement currency at that transaction’s all-in rate — so the sum of the line Net values equals the header Net Settlement Amount, and the wire, with no further conversion. In the totals, Gross Total is in the processing currency while Fees Total and Net Settlement Amount are in the settlement currency; each total names its own currency.

The settlement report file

• Format: CSV, UTF-8, RFC 4180.
• Structure: self-describing. Every row starts with a RecordType column — a settlement-level HEADER row followed by N transaction LINE rows. Each section is preceded by its own field-name row, so the file can be parsed without an external schema.
• Naming: {SubMID}_{SettlementDate:YYYYMMDD}_{ProcessingCurrency}_{SettlementID}.csv

M1002345_20260416_NGN_STL000123456.csv

Reading the name: SubMID account M1002345, settled on 2026-04-16, processing currency NGN, settlement STL000123456.

Header fields

Every header field describes the settlement as a whole. Monetary totals are in the settlement currency.

How MID and SubMID appear in the file

The two-level hierarchy maps onto the file’s columns as follows:

Line fields

Each line represents one transaction. Monetary amounts are in the processing currency and are signed (+ inflow, − outflow).

Transaction types

Transaction statuses

AUTHORISED, CAPTURED, SALE, SETTLED, REVERSED, REFUNDED, RETURNED. Lines in a settlement file are typically in a terminal state.

Example file

An abbreviated report for SubMID AcmeNGN (M1002345), settling NGN → USD. Gross is in the processing currency (NGN); the Net, fees, and totals are in the settlement currency (USD). Every row is tagged with RecordType. Card-only columns, SessionID, RateLockCreatedAt, MidRateSource, and other fields are present in the real file but omitted here for readability.

1
RecordType,SettlementID,Company Account,Merchant Account,Merchant Name,Settlement Date,Processing Currency,Settlement Currency,AllInRate,RateSource,Gross Total,Gross Total Currency,Fees Total,Fees Total Currency,Net Settlement Amount,Net Settlement Amount Currency,Transaction Count
2
HEADER,STL000123456,Acme,M1002345,AcmeNGN,2026-04-16T00:00:00Z,NGN,USD,1577.02,Bloomberg,185400,NGN,3.75,USD,113.25,USD,3
3
4
RecordType,PSP Reference,Merchant Reference,Original PSP Reference,Payment Method,Booking Date,Gross,Gross Currency,Initiation Amount,Initiation Currency,Processing Fee,Fee Currency,AllInRate,RateLockId,Net,Settlement Currency,TransactionType,TransactionStatus,PayerID
5
LINE,TX_9a1b2c3d,ORDER-55001,,CARD,2026-04-16T00:00:00Z,150000,NGN,94.94,USD,2.37,USD,1580,rlk_550e8400-e29b-41d4-a716-446655440001,92.57,USD,COLLECTION,SETTLED,PAYER_7781
6
LINE,TX_9a1b2c3e,ORDER-55002,,MOBILE_MONEY,2026-04-16T00:00:00Z,85400,NGN,54.05,USD,1.35,USD,1580,rlk_550e8400-e29b-41d4-a716-446655440001,52.70,USD,COLLECTION,SETTLED,PAYER_7782
7
LINE,TX_9a1b2c3f,ORDER-54980,TX_88f0aa12,CARD,2026-04-16T00:00:00Z,-50000,NGN,-31.99,USD,0.03,USD,1563,rlk_550e8400-e29b-41d4-a716-446655440005,-32.02,USD,REFUND,REFUNDED,PAYER_7601

Reconciliation check: the line Net values are already in the settlement currency, so they sum directly — 92.57 + 52.70 − 32.02 = 113.25 USD — to the Net Settlement Amount, the exact amount of the wire. Because each line settles at its own locked rate (the refund here used 1563, the collections 1580), you reconcile by summing the per-line Net, not by applying the header AllInRate to the gross total. The header AllInRate (1577.02) is the amount-weighted average of the line rates, so it sits between them and won’t reproduce any single line exactly.

Delivery channels

Reports are available through two channels, configured per SubMID with one channel designated as primary.

SFTP push

CrissCross uploads the report to your configured SFTP directory as soon as the settlement is produced. To avoid partial reads, files are written with a .processing extension and atomically renamed to .csv only once the upload is complete — so a file appearing with its final .csv name is guaranteed to be whole.

API pull

Subscribe to the settlement.created webhook and use it as the signal that a new settlement is ready, then retrieve it via the settlement endpoints:

The settlement.created webhook fires when a settlement becomes available. Its payload carries enough to route and fetch the report:

1
{
2
  "event": "settlement.created",
3
  "settlement_id": "STL000123456",
4
  "mid": "Acme",
5
  "sub_mid": "M1002345",
6
  "settlement_date": "2026-04-16",
7
  "processing_currency": "NGN",
8
  "settlement_currency": "USD",
9
  "net_settlement_amount": 113.25,
10
  "file_url": "https://files.crisscross.money/settlements/STL000123456.csv"
11
}