rl-docs-hub

Home · Apps · rl-bank-mvp

---

Terminal API specs

Status: Draft, intended for the breadboard terminal slice.

API style recommendation

For terminal/device traffic, prefer REST over GraphQL.

Why:

• simpler firmware implementation in Pico C++
• clearer request/response contracts
• easier retry/idempotency behavior
• easier later separation between app traffic and device traffic

Proposed endpoints

POST /api/terminals/payments/authorize

Create and authorize a terminal payment attempt.

Request body:

• terminalId: string
• requestId: string — idempotency key generated by terminal per attempt
• merchantRef: string | null
• amountMinor: number
• currency: string
• paymentToken: string — fake-bank demo token/card id read from NFC
• capturedAt: string — ISO timestamp
• firmwareVersion: string | null

Response body:

• result: APPROVED | DECLINED | ERROR
• reference: string | null
• transactionId: string | null
• message: string
• approvedAmountMinor: number | null
• debugCorrelationId: string | null

Behavior:

• idempotent on terminalId + requestId
• on success, create or reuse backend card_payment transaction
• if token/card/account is invalid, return DECLINED, not server crash semantics

POST /api/terminals/payments/cancel

Cancel an in-flight local session that has not been finalized.

Request body:

• terminalId: string
• requestId: string
• reason: string

Response body:

• result: CANCELLED | NOOP
• debugCorrelationId: string | null

GET /api/terminals/:terminalId/bootstrap

Return minimal terminal bootstrap/config payload.

Response body:

• terminalId
• merchantLabel
• currency
• status
• nfcMode
• uiTheme optional
• pollIntervalsMs optional

Validation rules

• amountMinor must be > 0
• currency should be restricted to supported fake-bank currencies, likely SGD first
• terminal identity must be authenticated separately from customer/staff auth
• unknown or disabled terminal returns 403/404 style error
• paymentToken must map to a supported fake-bank card/token representation

Transaction mapping

Recommended mapping into current backend concepts:

• create transaction type: card_payment
• attach metadata:
  • terminalId
  • merchantRef
  • requestId
  • paymentTokenFingerprint or safe masked token reference
  • channel = terminal_nfc

Error semantics

Terminal-friendly errors should be compact and deterministic:

• DECLINED — business rule or token/card issue
• ERROR — backend/server/integration problem
• TIMEOUT — local terminal UX state, usually not an API response enum

Avoid verbose stack-trace style responses. Firmware needs short messages and stable codes.

Auth recommendation

Do not reuse customer bearer tokens.

Use one of:

• terminal static secret exchanged for short-lived token
• HMAC-signed requests
• provisioned device token with rotation path later

For the breadboard phase, a per-device secret is good enough if:

• stored outside source control
• rotatable
• scoped only to terminal endpoints