Start here
Quickstart
This walks through the whole loop in the sandbox: sync a merchant, give it a product and stock, let a terminal sell it, send the bank's record of the payment, and watch
the two reconcile. You need curl, openssl and jq.
0. Get sandbox credentials#
Ask us for a sandbox operator (or create one if you run the platform: POST /v1/organizations with "sandbox": true). Sign in as its admin and create an API key with the scopes
sync:write terminals:session catalog:write inventory:write sales:read transactions:write webhooks:write. You get an API key (tsk_test_…) and a signing secret. Both are shown once.
export BASE=https://sandbox.example.com # your sandbox URL
export API_KEY=tsk_test_...
export SIGNING_SECRET=...1. A helper that signs writes#
Writes from an operator are signed so nobody can replay or alter them. The signature is an HMAC-SHA256 of "<unix-seconds>.<exact body>".
signed() { # method path body
t=$(date +%s)
sig=$(printf '%s.%s' "$t" "$3" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')
curl -fsS -X "$1" "$BASE$2" -H "X-Api-Key: $API_KEY" -H "X-Tillstack-Signature: t=$t,v1=$sig" \
-H 'Content-Type: application/json' --data-binary "$3"
}2. Sync a merchant, a branch and a terminal#
M=$(signed PUT /v1/sync/merchants '{"items":[{"externalId":"m-1","name":"Demo Shop","mid":"MID0001"}]}' | jq -r '.items[0].id')
B=$(signed PUT /v1/sync/branches '{"items":[{"externalId":"b-1","merchantExternalId":"m-1","name":"Main","code":"MAIN"}]}' | jq -r '.items[0].id')
signed PUT /v1/sync/terminals '{"items":[{"tid":"TID0001","merchantExternalId":"m-1","branchExternalId":"b-1"}]}'3. Give it something to sell#
V=$(curl -fsS -X POST $BASE/v1/merchants/$M/products -H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' \
-d '{"name":"Rice 5kg","variants":[{"sku":"RICE-5","priceKobo":500000,"costKobo":300000}]}' | jq -r '.variants[0].id')
curl -fsS -X POST $BASE/v1/merchants/$M/inventory/receipts -H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' \
-d "{\"branchId\":\"$B\",\"lines\":[{\"variantId\":\"$V\",\"quantity\":50,\"unitCostKobo\":300000}]}"4. A terminal session, then a sale#
Your backend mints a short-lived token for the device. The device uses it for everything else.
TOKEN=$(signed POST /v1/terminals/TID0001/sessions "" | jq -r '.accessToken')
SALE=$(uuidgen | tr A-Z a-z)
curl -fsS -X POST $BASE/v1/terminal/sales -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "{
\"saleId\":\"$SALE\", \"occurredAt\":\"$(date -u +%FT%TZ)\",
\"lines\":[{\"variantId\":\"$V\",\"quantity\":2,\"unitPriceKobo\":500000}],
\"tenders\":[{\"type\":\"Card\",\"amountKobo\":1000000,\"rrn\":\"230715123456\",\"stan\":\"000321\",\"tid\":\"TID0001\",\"maskedPan\":\"506100******1234\",\"authCode\":\"A1B2C3\"}]}" | jq .receiptThe response is a print-ready receipt. Run the same command again with the same saleId: you get the same receipt back and stock is not touched twice.
5. The bank's record, and the match#
signed POST /v1/transactions '{"items":[{"tid":"TID0001","type":"Purchase","rrn":"230715123456","stan":"000321","amountKobo":1000000,"responseCode":"00","occurredAt":"'$(date -u +%FT%TZ)'"}]}'
curl -fsS "$BASE/v1/merchants/$M/reconciliation/summary" -H "X-Api-Key: $API_KEY" | jqexceptionCount is 0: the card sale and the approved payment paired up on TID + RRN. If the amounts differed, or one side was missing, it would show here as an exception.
Everything in one script#
The repository ships this flow as scripts/sandbox-flow.sh, and a Postman collection that signs requests for you. Both are linked from the API reference.
Where to next#
- Authentication for the three kinds of caller.
- Ingesting data to load your real merchants and terminals.
- Webhooks to hear about sales as they happen.