- payment domain: payments/memberships/attempts/receipts/refunds/commands/events, legacy-demo provenance (0024), checkout header-hash idempotency (0025) - wallet collection all-or-none across shop orders; group-wide cancellation; checkout cutover, status-only payOrder removed - Stripe crypto-only Checkout adapter, raw-body HMAC webhooks, durable command worker with leases - original-method refunds with receipt/allocation budgets; refund_pending/refund_failed aftersale states - admin channel CRUD/revisions/audit/verify + operations list/detail/reconcile; secret-ref allowlist (VMALL_PAYMENT_*), env-fixed demo/sandbox/live - mall/mobile checkout pay surfaces, admin console pages; shared contract updated - pre-launch leftovers recorded in docs/TBD-payments.md cargo test -p vmall-api green twice; four frontend builds green; browser smoke: mall wallet checkout paid, admin channels/operations verified
4.6 KiB
wallet Specification
Purpose
The wallet gives the existing customer-account ledger its entry points: a simulated demo recharge, a withdrawal application that freezes funds until a platform admin reviews it exactly once (approve consumes the frozen amount, reject returns it to available), and a paginated view of the caller's own fund entries. Balances only move through the account module's credit/debit/freeze/release primitives in the same transaction as the business record, and every movement pairs with an append-only ledger entry.
Requirements
Requirement: Demo wallet recharge
In a demo deployment an authenticated user SHALL recharge their wallet through the simulated flow that records a recharge row and credits the available monetary account with one signed ledger entry in one transaction, without invoking an external channel. The payload and UI SHALL clearly label the flow simulated/demo. Amounts SHALL be positive integer minor units in account currency without floating-point arithmetic. Sandbox and live deployments SHALL refuse this operation server-side and SHALL not advertise it as available. Turning off a UI control SHALL NOT be the security boundary; historical demo credits SHALL prevent live financial activation in that database.
Scenario: demo recharge credits balance
- WHEN a signed-in buyer in a demo deployment recharges 5000 minor units
- THEN available balance increases by exactly 5000 and one wallet_recharge entry records the resulting balance
Scenario: flow is labeled as demo
- WHEN a buyer opens the enabled recharge flow
- THEN it is visibly labeled simulated and contacts no external provider
Scenario: live recharge cannot mint funds
- WHEN a signed-in buyer directly calls the demo-recharge endpoint in sandbox or live mode
- THEN the operation is refused without a recharge record, balance change or ledger entry
Requirement: Guarded withdrawal freeze
An authenticated user SHALL apply to withdraw a positive amount in their account currency. The application SHALL atomically move the amount from available to frozen balance through guarded conditional updates that succeed only when available balance covers the amount, and each balance change SHALL be paired with a ledger entry in the same transaction. When available balance is insufficient the request SHALL fail without changing any balance, and concurrent applications SHALL never overdraw or produce a negative balance.
Scenario: withdrawal freezes funds
- WHEN a buyer applies to withdraw 1000 minor units
- THEN available balance decreases and frozen balance increases by exactly 1000 minor units and two ledger entries record the move
Scenario: concurrent applications cannot overdraw
- WHEN two withdrawal applications together exceed the available balance
- THEN at most one application succeeds and all balances remain non-negative
Requirement: One-time withdrawal review
Platform admins SHALL list pending withdrawal applications and approve or reject each exactly once through a guarded status transition that requires the pending status and returns 409 on a repeated review. Approve SHALL deduct the frozen amount with a ledger entry recording that the funds left the platform. Reject SHALL return the frozen amount to available balance with a ledger entry. Every review SHALL record the reviewing admin, timestamp, and optional note.
Scenario: reject returns funds
- WHEN an admin rejects a pending withdrawal application
- THEN the frozen amount returns to available balance and the application status becomes rejected
Scenario: approve consumes frozen funds
- WHEN an admin approves a pending withdrawal application
- THEN frozen balance decreases by the requested amount and the application status becomes approved
Scenario: repeated review conflicts
- WHEN an admin reviews an application that was already reviewed
- THEN the API returns 409 and no balance or ledger row changes
Requirement: Paginated fund entries
An authenticated user SHALL page through their own monetary account entries newest first. Each entry SHALL carry the signed delta minor, resulting balance minor, reason, optional business reference, and timestamp, mapped from the existing append-only ledger rows. Entries SHALL never expose or mutate another user's ledger.
Scenario: entries page maps the ledger
- WHEN the buyer requests a page of fund entries
- THEN only their own available/frozen ledger rows appear with signed deltas and resulting balances
Scenario: entries are user-isolated
- WHEN one user requests fund entries
- THEN no entry belonging to another user is ever returned