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

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.

bash
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>".

bash
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#

bash
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#

bash
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.

bash
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 .receipt

The 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#

bash
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" | jq

exceptionCount 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#