rl-docs-hub

Home · Apps · rl-bank-mvp

Physical payment terminal workstream

Status: Draft, docs-first plan for breadboard prototyping.

Why this workstream

The fake-bank experience is already credible on the customer, staff, and API sides, but it still lacks a believable physical acceptance surface. A compact countertop payment terminal closes that realism gap and creates a concrete bridge between:

This workstream is intentionally software-first + breadboard-friendly:

It now sits alongside the draft fake shop / merchant ecosystem planning set, which defines the merchant/POS layer this terminal is expected to support.

Product / feature scope

In scope for this phase

Out of scope for this phase

Product design

Experience shape

The device should feel like a small, believable shop/stall payment terminal:

For prototype phase, keep the interaction model simple:

  1. terminal boots into ready state
  2. merchant enters amount or receives amount from future POS companion
  3. terminal shows amount, merchant label, and Tap card prompt
  4. NFC reader detects a fake-bank payment token/card id
  5. firmware sends authorization request to fake-bank API
  6. terminal shows Approved, Declined, or Try again
  7. terminal optionally shows short reference code and returns to ready state

Display direction

Preferred first-build display:

Why this is the best first choice:

Fallback acceptable range for experiments:

My opinion: start with the 1.3” ST7789 and resist scope creep. It matches the desired aesthetic and keeps the first prototype honest.

Business logic and rules

Terminal payment rules

  1. This terminal is fake-bank simulation hardware, not a real payment instrument.
  2. Terminal may authorize only against explicitly supported fake-bank accounts/cards/tokens.
  3. All amounts are demo amounts and must remain clearly inside the fake-bank sandbox context.
  4. Terminal should create or map to a backend transaction of type card_payment.
  5. Terminal must be idempotent for payment submission retries using a terminal-generated request id.
  6. Merchant-facing result states for phase 1:
    • APPROVED
    • DECLINED
    • CANCELLED
    • ERROR
    • TIMEOUT
  7. If network is unavailable, the device should fail closed rather than invent offline approval.
  8. Phase-1 NFC support should treat tags/cards as demo identifiers, not real EMV cards.
  9. A terminal session should expire quickly if no tap occurs.
  10. Each payment attempt should produce an auditable terminal event trail.

Safety / simulation rules

Technical design summary

Use a thin-terminal model:

Why this split is right

Technical architecture / data flow

flowchart LR
  Merchant[Merchant / stall operator] --> Terminal[Physical terminal\nPico 2 W firmware]
  Terminal --> Display[ST7789 UI]
  Terminal --> Keys[Buttons / keypad]
  Terminal --> NFC[PN532 or MFRC522 reader]
  Terminal --> WiFi[Wi-Fi]
  WiFi --> BankAPI[Fake-bank API]
  BankAPI --> Tx[(transactions)]
  BankAPI --> Cards[(cards / tokens)]
  BankAPI --> Audit[(audit logs)]
  FuturePOS[Future fake-shop POS] -. amount/session sync later .-> Terminal
  FuturePOS -. merchant/order context later .-> BankAPI

Phase-1 payment flow

sequenceDiagram
  participant M as Merchant
  participant T as Terminal firmware
  participant N as NFC reader
  participant A as Fake-bank API
  participant DB as Transactions/cards

  M->>T: Enter amount / choose preset
  T->>T: Create local checkout session
  T-->>M: Show amount + Tap prompt
  N-->>T: Read demo token/card id
  T->>A: POST payment authorization
  A->>DB: validate token/card + funds/rules
  DB-->>A: decision context
  A-->>T: approved / declined + reference
  T-->>M: Show result
  T->>A: optional completion/telemetry event

API / spec implications

The current fake-bank API already hints at the right ledger shape because it includes card_payment as a transaction type. For the terminal slice, I would add a terminal-oriented authorization surface rather than cram this into customer GraphQL immediately.

Recommended phase-1 contract shape:

See Terminal API specs.

Permissions / access model

Device identity

Recommended minimum model:

Backend permissions

Phase 1 can stay narrow:

Infra / IAM implications

No AWS permission broadening is required at doc stage, but future runtime should assume:

Dependencies and component strategy

See:

Roadmap

Phase 0 — docs and decisions

Phase 1 — breadboard prototype

Phase 2 — realistic checkout flow

Phase 3 — POS integration

Phase 4 — hardware refinement

Current recommendation

Do not start with custom hardware. Build the fake-bank terminal as a thin, Wi-Fi-connected Pico prototype with:

That gets the fastest believable result with the least regret.