Getting data in
Reconciliation
A sale says "the customer paid ₦X by card". The bank/acquirer says "we approved ₦X on terminal T". Reconciliation proves the two agree and surfaces the cases where they do not (money taken but no sale; a sale with no approved payment; different amounts).
1. Sending transactions (Operator → us)#
POST /v1/transactions — an operator (or reseller) API key with transactions:write, body signed like every operator write
(X-Tillstack-Signature). A merchant's own users and keys are refused: this is the evidence their sales are checked against.
{ "items": [ {
"externalId": "bank-tx-9981", // optional; your own id. Without it we fingerprint tid+rrn+stan+type+amount+time
"tid": "2035AB01", "mid": "2035AB0000123",
"type": "Purchase", // Purchase (default) | Refund | Reversal
"rrn": "230715123456", "stan": "000321", "amountKobo": 150000,
"responseCode": "00", // "00" approved; anything else is stored as Declined and never matched
"occurredAt": "2026-11-16T10:04:11+01:00",
"maskedPan": "506100******1234", "authCode": "A1B2C3", "scheme": "Verve"
} ] }- Up to 500 per call. Each item is judged alone →
200withitems[i].outcome=Created | Duplicate | Failed(+matchStatus,error). - The merchant is found from the TID (inside your scope); you never name it. Unknown TID →
Failed: terminal_unknown(sync the terminal, re-send). Unassigned terminal →terminal_unassigned. A MID that is not the owning merchant's →mid_mismatch. - Card numbers are refused, never stored:
maskedPanmay show at most the first 6 and last 4; any field that looks like a PAN fails the item (pan_refused). - Re-sending is safe (same
externalId, or same fields) →Duplicate. - Push one at a time instead with the sync webhook:
{"eventId":"…","type":"transaction.created","data":{ …item… }}(needssync:writeandtransactions:write). - A Reversal (needs
rrn) removes its original purchase from the exceptions if no sale claimed it yet (Reversed); if a sale had, the original is flaggedReversedAfterMatch. Arriving before the original works too.
2. Matching#
Runs after every ingest, on POST /v1/merchants/{id}/reconciliation/run, and every minute in ReconciliationWorker
(for a terminal that sold offline and delivered its sale after the bank record).
- TID + RRN against card/transfer tenders (tender TID, or the sale's terminal if the tender has none). Same amount →
Matched; different →AmountMismatch. - Heuristic, only for tenders with no RRN: same terminal, same amount, within ±5 minutes — and only when exactly one tender and no other waiting transaction fit. Otherwise it stays unmatched (
ambiguous) for a person. - Refunds match a return's card/transfer refund by RRN.
A tender is paid for by at most one transaction (database-enforced). People can resolve the rest:
POST …/transactions/{id}/match {saleTenderId, note} (409 if the tender is taken) and POST …/transactions/{id}/ignore {note}
(a matched transaction cannot be ignored). Needs Owner/Manager/Admin (transactions:write).
3. Reading it#
All under /v1/merchants/{id}, readable by any role of that merchant (and its operator/reseller). Dates are Nigerian days (WAT).
| Endpoint | What |
|---|---|
GET transactions?status&type&terminalId&branchId&from&to&rrn |
The bank's records and where each stands |
GET reconciliation/summary?date= |
Purchase totals by status, tender totals (paid / without a transaction), exception counts by kind |
GET reconciliation/exceptions?kind= |
UnmatchedTransaction, UnmatchedTender, AmountMismatch, ReversedAfterMatch |
POST reconciliation/run |
Match now |
GET reports/sales?groupBy=day|branch|terminal|cashier|product|tender&format=csv |
Sales net of returns; tender is the payment mix (cash net of change); product includes quantity and cost |
graceMinutes (default 30, 0–1440): how long a sale or transaction may be missing its other half before it is an exception.
CSV export neutralises spreadsheet formulas ('=…).
4. Not here yet#
Outbound transaction.unmatched webhooks (outbox, Phase 7), bank-statement/settlement-file reconciliation (net of fees), chargebacks,
NIBSS session ids for transfers.