Terminals

A terminal is a point of sale your shoppers pay through. It is identified by its terminal id, and that id can be encoded in anything the shopper can read — a QR code, an NFC tag, a deep link, a printed number. When the Fluense app reads it, it resolves the terminal's latest checkout and the shopper authorizes it.

Type	Behaviour
REUSABLE	A permanent terminal id for a counter or register — present it as a QR code, write it to an NFC tag, or link to it. One active checkout at a time: creating a new one supersedes the previous pending checkout.
USE_ONCE	Created automatically when a checkout is made without a terminal_id — useful for one-off payment links.

Create

Session or API key (the key's org must own the terminal).

curl -s https://api.fluense.social/terminals \
  -H "authorization: Bearer $SESSION" \
  -H 'content-type: application/json' \
  -d '{"title":"Front counter"}'

{ "id": "019a…" }

List

curl -s https://api.fluense.social/terminals -H "authorization: Bearer $SESSION"

{
  "terminals": [
    { "id": "019a…", "title": "Front counter", "terminal_type": "REUSABLE", "status": "ACTIVE", "created_at": "2026-10-08T09:12:00Z" }
  ]
}

Update

PATCH /terminals/{id} with title and/or status (ACTIVE or INACTIVE).

{ "ok": true }

Resolve the active checkout

GET /terminals/{id}/checkout returns the latest non-expired checkout for the terminal — the endpoint behind the terminal id, whether the shopper scanned a QR, tapped an NFC tag or opened a link. API keys see their own terminals; consumer sessions can read any terminal (they are the shopper paying).

{
  "id": "019a…",
  "merchant_id": "019a…",
  "terminal_id": "019a…",
  "items": [ { "product_id": "sku-1", "display_name": "Desk lamp", "unit_price": 8900, "qty": 1, "cashback_rate": 500 } ],
  "currency": "USD",
  "total": 9700,
  "status": "PENDING",
  "expires_at": "2026-10-09T09:12:00Z"
}

404 no active checkout on this terminal means the previous checkout expired, was paid, or was superseded — create a new one.

POS flow

1. POST /checkouts with terminal_id (your key).
2. Poll GET /terminals/{id}/checkout or let the shopper read the terminal id (QR, NFC, link).
3. The shopper authorizes; you capture with POST /charges/{auth_id}/capture.