# 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).

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

```json
{ "id": "019a…" }
```

## List

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

```json
{
  "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`).

```json
{ "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).

```json
{
  "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`.