Quickstart

Onboarding path

1. The restaurant owner registers your device in Sitora Biz against one station, declaring its capabilities and (for a smart POS) the launch reference for the co-resident payment application.
2. The owner issues a one-time enrollment code and reads it to you or types it into the device.
3. Your device claims the code once and receives its credential — shown exactly once.
4. Poll, act, report.
5. Pass the conformance suite. A passing run is recorded as a certification artifact per capability.

The sandbox

A Sitora installation can seed a complete sandbox filial:

backend/venv/bin/python backend/manage.py seed_payments_sandbox

It creates a station, a customer display, a smart-POS companion, a cashier who actually holds the payment permission, and a provider config in its test environment — then prints the device credentials and the cashier session once. Everything behaves exactly as production does: same endpoints, same throttles, same refusal codes, same kill switches.

First requests

# 1. Claim the one-time enrollment code (anonymous — the code is the secret)
curl -X POST -H 'Content-Type: application/json' \
  -d '{"code":"<enrollment-code>"}' \
  "https://<host>/api/payments/v1/devices/enroll/"

# 2. Check in. Do this on a timer — a silent device is treated as offline
#    and the routes that need it stop being offered to the cashier.
curl -X POST -H "Authorization: Bearer sit_pd_..." \
  -H 'Content-Type: application/json' -d '{"summary":{"battery":91}}' \
  "https://<host>/api/payments/v1/devices/heartbeat/"

# 3. Poll for work (smart POS)
curl -H "Authorization: Bearer sit_pd_..." \
  -H 'If-None-Match: "<last-etag>"' \
  "https://<host>/api/payments/v1/devices/assignment/"

# 3b. …or for what the guest should see (customer display)
curl -H "Authorization: Bearer sit_pd_..." \
  "https://<host>/api/payments/v1/devices/display/"

# 4. Report what the payment application returned
curl -X POST -H "Authorization: Bearer sit_pd_..." \
  -H 'Content-Type: application/json' \
  -d '{"intent_id":42,"outcome":"reported_success",
       "provider_reference":"RRN-000123","provider_code":"00",
       "client_idempotency_key":"collection-42-1"}' \
  "https://<host>/api/payments/v1/devices/assignment/report/"

Step 4 does not pay the order. See Smart POS handoff.

Polling etiquette

Both polling reads support If-None-Match; an unchanged state answers 304 with no body. Poll at a human cadence — around two seconds is right for a display, and a companion only needs to poll between collections. Throttles are per credential, and a device that needs more than one request per second is misbehaving, not busy.

Conformance

backend/venv/bin/python backend/manage.py run_payments_conformance --record

The suite drives the real API as a cashier, a device, and the filial’s owner, and exits non-zero on any failure. It verifies, among other scenarios:

• cash and attested-terminal collection settling through Sitora’s single payment seam;
• the smart-POS handoff, including that a reported success leaves the order unpaid until a cashier attests it;
• idempotent replay of a duplicate report;
• a dynamic-QR payment confirmed by a real provider callback, and a duplicate callback replaying identically;
• money a provider asserts for a transaction Sitora never registered surfacing as an unmatched-money issue rather than silently paying something;
• kill-switch compliance, including that cash keeps collecting through a platform freeze;
• an offline device removing its own routes, and a heartbeat restoring them;
• reconciliation against an imported provider statement giving every difference a name, and a closed difference not returning on the next run.

The run leaves nothing behind: it releases the station lease, revokes the device credential it minted, and ends its owner session, so you can run it as often as you need against one sandbox.

--record writes one immutable certification artifact per capability exercised. Certification is per provider × capability: passing for one hardware verb never certifies another.