Payment Device API
Sitora’s Payment Device API lets a smart POS terminal or a customer-facing
display take part in collecting money at the counter. This section is the
vendor-facing contract; the machine-readable half is the OpenAPI document
served live at GET /api/payments/v1/openapi.json (no authentication
required) and rendered in the API reference pages of this site.
The model: Sitora describes the collection, never performs it
Section titled “The model: Sitora describes the collection, never performs it”Sitora does not move money and never touches card data. Banks, payment providers, and certified payment applications execute payments. Sitora is the workflow authority: it owns the order, the amount, the payment intent, the resulting transaction, and the audit trail.
A payment intent is a backend-authored request to collect one order’s total at one station. It is the only object a device ever acts on, and every money field in it comes from order truth:
The backend authors every amount. No device, client, or provider payload can set or amend it. A device that sends an amount is not integrating — it is being ignored.
The one rule
Section titled “The one rule”Everything else in this section follows from a single constraint:
A device may report what a payment application returned. It may never declare that money was received.
A reported success moves the intent to processing and shows the cashier
what your application said. The cashier then attests it, and only that
attestation creates the confirmed transaction that marks the order paid. A
reported decline does not kill the intent either — a wrong decline would
free the order for a second collection, so the rule is symmetric.
This is the same boundary Sitora draws for robots (they serve food but never write order state) and for its AI assistant (it drafts but never executes). Applied to money, it means a compromised or buggy device cannot fabricate a payment.
Device kinds
Section titled “Device kinds”| Kind | Runs software | Typical role |
|---|---|---|
smart_pos |
yes | Companion workspace; hands collection to a co-resident certified payment app |
customer_display |
yes | Shows the guest the total, a dynamic QR, and the paid moment |
external_terminal |
no | A bank terminal used beside Sitora; outcomes are attested by the cashier |
fiscal_register |
no | A register bound to a fiscal operator |
Only smart_pos and customer_display hold machine credentials. The other
two are registry entries — real hardware Sitora knows about but does not
talk to.
Capabilities, not brands
Section titled “Capabilities, not brands”What a device may do is a capability set, declared when the owner registers it and validated against Sitora’s platform registry. Policy, routing, and every client affordance reason over capabilities; a brand name never appears anywhere in Sitora’s logic.
| Capability | Meaning |
|---|---|
payment_app_handoff |
Can hand an intent to a co-resident payment app and return the outcome correlation |
companion_workspace |
Runs Sitora Pro as an enrolled device |
qr_dynamic_present |
Renders a provider charge as a dynamic QR for one intent |
customer_total_display |
Shows the order total and payment progress to the guest |
card_present_attested |
Charges collected out of band; outcome attested by staff |
receipt_print |
Prints non-fiscal customer receipts |
Your credential’s scopes are derived from these capabilities, so a display
never receives handoff verbs and a companion without
payment_app_handoff never receives them either.
Two further capabilities exist in the platform registry but have no device
plane behind them today: fiscalize belongs to fiscal registers, which
Sitora drives through a fiscal operator rather than through this API, and
card_present_push is reserved for semi-integrated terminals — no payment
provider Sitora integrates publishes a cloud API for pushing an amount to a
terminal, so nothing accepts it yet. Declaring either changes no behaviour
on this surface.
What Sitora will never accept from a device
Section titled “What Sitora will never accept from a device”- Any cardholder data. No PAN, track, EMV, CVV, OTP, or wallet credential. There is no field to put one in, and adding one is not a roadmap item.
- An amount, currency, or order reference of your choosing. You are told what to collect.
- A settlement claim. See “the one rule” above.
- Free text for staff to read. Reports carry a structured reference and your own coded result; Sitora maps codes to its own vocabulary.