Getting data in
Your payment provider
Most POS back offices come bundled with their own payment processing: you sell on their terminals, their rails settle the money, and the product is hard to leave. Tillstack is built the other way round. We are never in the payment path. Terminals take payments through your acquirer or payment provider exactly as they do today, and Tillstack is where the business side of the sale lives: what was sold, what stock moved, what the bank says happened, and where the two disagree.
What stays with you#
- The money. Authorisation, settlement and payouts stay with your acquirer. Tillstack never holds, moves or settles funds, and there is no Tillstack balance to trust.
- The merchant relationship. Your merchants, your MIDs, your terminals, your brand and domain.
- The choice of provider. Change acquirer, add a second one, or run different providers for different terminals. The back office does not change, because it only ever sees records, not rails.
- Card data. We never receive full card numbers. A first-6/last-4 mask is the most we accept, and anything that looks like a PAN is refused and not stored. That keeps Tillstack out of card-data scope.
What we do with the payment records#
A sale from a terminal says "the customer paid ₦15,000 by card". Your provider's record says "we approved ₦15,000 on terminal 2035AB01". Tillstack holds both and proves they agree:
- You send us the provider's records (see below).
- We match them to the sale tenders: first on TID + RRN; for tenders with no RRN, on the same terminal, same amount, within five minutes, and only when exactly one fits.
- You see the exceptions: money taken with no sale recorded, a sale that claims a card payment nobody approved, an amount that differs, a payment reversed after it was counted.
Each exception is something a person can act on that day, instead of a surprise at month end.
How to connect your provider#
Pick whichever fits what your provider can do.
A. Your platform posts them to us. If you operate the payment side, send transaction records as they happen, or in batches of up to 500:
POST /v1/transactions (API key with transactions:write, signed)
{ "items": [ {
"externalId": "bank-tx-9981",
"tid": "2035AB01", "mid": "2035AB0000123",
"type": "Purchase", // Purchase | 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"
} ] }B. Your provider calls a small adapter you own. Most providers can send a webhook for each transaction. Receive it on your server, map their field names to ours (the table
below), and forward it to POST /v1/transactions or POST /v1/sync/webhooks with type: "transaction.created". The adapter is ten lines and stays under your control.
C. A scheduled export. If all you get is a daily settlement file, convert it and post it in batches. Duplicates are harmless: the same externalId (or the same TID, RRN, STAN, type,
amount and time) is recognised and returns Duplicate.
| Their field (typical) | Ours |
|---|---|
| terminal id | tid |
| merchant id | mid (must match the merchant that owns the terminal) |
| retrieval reference number | rrn |
| system trace audit number | stan |
| amount (naira, decimal) | amountKobo (multiply by 100, integer) |
| response code | responseCode (00 = approved) |
| transaction time | occurredAt (ISO 8601 with offset) |
| transaction type | type (Purchase, Refund, Reversal) |
We find the merchant from the TID, so you never have to name it. An unknown TID is reported as terminal_unknown: sync the terminal and send it again.
Why this beats a bundled system#
| Bundled POS + payments | Tillstack | |
|---|---|---|
| Who settles the money | The vendor's rails | Your acquirer, unchanged |
| Switching provider | Replace the back office too | Change where records come from |
| Your merchants and terminals | In the vendor's system | In yours, mirrored by id; you can sync them out as easily as in |
| Card data in the product | Often in scope | Never received; masked numbers only |
| Branding | The vendor's | Yours, per reseller and per merchant, on your own domains |
| Integration | Their SDK, their way | Open HTTP API, signed and documented, a sandbox, webhooks out |
| Seeing disagreements | Whatever their report shows | Reconciliation against your bank records, by design |
The trade is honest: Tillstack does not take payments, so you keep a payment provider. If you already have one (and as an operator you do), you lose nothing and gain control.