rl-docs-hub

Home · Apps · rl-bank-mvp

---

Fake shop / merchant ecosystem functional requirements

Status: Draft, planning-level requirements.

Purpose

Define the functional behavior expected from the first believable fake merchant ecosystem that works with fake-bank, the payment terminal, and an iPad POS concept.

Actors

Merchant owner

Responsible for:

• creating or managing the shop identity
• configuring products, prices, and simple settings
• viewing orders and payments

Cashier / shop staff

Responsible for:

• creating baskets in the POS
• initiating checkout
• handling customer-ready payment states

Customer

Responsible for:

• reviewing the amount on terminal/POS
• presenting a fake-bank card/token/wallet credential
• completing or abandoning payment

Terminal device

Responsible for:

• showing payment-ready state
• collecting fake payment token/card identifier
• sending authorization request
• returning result to merchant flow

Bank backend

Responsible for:

• validating fake payment token/card/account rules
• creating payment transactions/events
• returning approve/decline/error outcomes

Shop backend / merchant layer

Responsible for:

• storing shop, products, basket, order, and checkout context
• coordinating POS and terminal session state
• presenting merchant-facing history and status

Functional requirements

Shop identity and setup

1. Merchant can create or manage at least one fake shop profile.
2. Shop profile should support at minimum:
   • shop name
   • merchant display label
   • currency
   • optional location/store label
3. Merchant can maintain a basic product catalogue.
4. Product records should support at minimum:
   • name
   • price
   • image or placeholder image reference
   • availability status
   • optional SKU/internal code
5. Product and asset realism should prefer our own stored/generated catalogue over live third-party fake APIs.

POS basket and checkout

1. Staff can browse/search products in the POS.
2. Staff can add one or more products to a basket.
3. POS calculates subtotal and checkout total.
4. POS can initiate a checkout session for a basket.
5. Checkout session should produce a clear merchant reference/order reference.
6. POS should hand off payment intent/context to the terminal without requiring the customer to type amount on the terminal in the target experience.
7. POS should reflect current payment state in near real time or fast manual refresh.

Terminal-assisted payment

1. Terminal can receive a checkout/payment request associated with a shop order or checkout session.
2. Terminal shows amount and merchant label clearly.
3. Customer can tap or present a supported fake-bank payment token/card identifier.
4. Terminal submits authorization request to backend.
5. Terminal returns one of the merchant-meaningful outcomes:
   • approved
   • declined
   • cancelled
   • timeout
   • error
6. Terminal requests must be idempotent by device/request key.
7. Terminal should fail closed if required network/backend state is unavailable.

Order and payment state

1. A checkout should create an order or pending sale record before payment finalization.
2. Approved payment should transition the order into a paid/completed state.
3. Declined/cancelled/timeout payment should keep the order in a recoverable non-paid state.
4. Merchant should be able to retry payment on the same order when appropriate.
5. Merchant should be able to abandon/void an unpaid checkout locally.
6. Merchant history should link orders and payment attempts clearly.

Merchant history and operations

1. Merchant can view recent orders.
2. Merchant can view recent payment attempts and outcomes.
3. Merchant can inspect enough detail to answer basic demo questions:
   • what was purchased
   • total amount
   • when it happened
   • whether payment succeeded
   • reference ids
4. Merchant-facing labels should be readable and not overly technical.

Customer-side effects

1. Approved merchant payments should appear as believable customer-side fake-bank activity.
2. Customer activity should include merchant/shop display naming where available.
3. The ecosystem should preserve traceable references between merchant-side order/payment history and customer-side payment history.

Roles and permissions

1. Merchant/staff users must not gain customer-bank privileges.
2. Customer users must not access merchant operational data.
3. Terminal/device identity must remain separate from customer/staff identity.
4. A merchant user should see only the shops/stores they are authorized for.

Audit and supportability

1. Key events should be auditable across shop, terminal, and bank layers.
2. Payment attempts should carry correlation/debug identifiers where feasible.
3. Merchant-visible states should remain simple even if internal event trails are richer.

Non-goals for MVP requirements

• real payment rails
• real EMV behavior
• inventory forecasting
• refunds/disputes/chargebacks
• tax and accounting correctness
• multi-branch fleet management
• deep staff scheduling/shift systems