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

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:

  1. You send us the provider's records (see below).
  2. 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.
  3. 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.