Guides

Start here

What Tillstack isQuickstartAuthentication

Getting data in

How data gets inSync API referenceYour payment providerReconciliation

Building on it

Terminal integrationSales, returns, shiftsCatalog and stockInventory ledgerCatalog layout on devicesProduct picturesReportsWebhooksEmail and EngageRunning without our UI

Using the console

Operator portalMerchant guide

Reference

Sandbox, OpenAPI, PostmanErrors and limitsSecurity

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.

json
{ "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 → 200 with items[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: maskedPan may 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… }} (needs sync:write and transactions: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 flagged ReversedAfterMatch. 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).

  1. TID + RRN against card/transfer tenders (tender TID, or the sale's terminal if the tender has none). Same amount → Matched; different → AmountMismatch.
  2. 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.
  3. 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.