URD: Payments
| Module | Version | Updated |
|---|---|---|
CORE-08 | v0.7 | 2026-07-15 |
What the Payments module does
Define the user-facing requirements for collecting one payment through an external provider. When a customer pays by QR code or card tap, the money does not land in the ledger right away - it goes through an external payment provider (Payment provider), for example VNPAY, and the provider reports the result back. The Payments module ingests that result, changes the payment status, pushes the new status to the cashier (cashier) instantly, and notifies sale (sale) to settle the order once the payment succeeds.
Choosing a provider and entering its credentials does not belong to this module. That lives in the merchant's financial wallet (Finance Account), part of the merchant (Merchant), owned and managed by the finance module. The Payments module only reads the active configuration to execute a payment; it never stores or configures credentials itself.
Four points to understand first
This is the most important part of the document. Understanding the four points below is understanding most of the module.
1. A payment moves through four states
| Status | Meaning |
|---|---|
| pending | Request created; a QR code is waiting to be scanned, or a card reader is waiting for a tap |
| paid | The provider confirms the money has landed |
| failed | The provider reports the transaction did not go through |
| expired | The QR code expired before anyone paid |
The order on the sale side does not settle until the payment reaches paid. Both failed and expired leave the order open, so the cashier can collect again.
2. A redelivered result is applied only once
A flaky network can make a provider send the same success notification twice. The Payments module recognizes the redelivery and skips it - idempotent means the same result, however many times it is delivered, changes status and fires notifications exactly once. There is never a double charge or a double settlement for the same payment.
3. Payments executes, the financial wallet holds the configuration
This is exactly where the boundary between the two modules sits: Payments owns execution of one specific amount; the financial wallet owns configuration - which provider is active, whose credentials are attached to which wallet. The Payments module has no configuration screen of its own; every time it needs to collect, it reads the active configuration from the merchant's financial wallet at that exact moment.
4. The cashier watches the whole lifecycle, sale only hears about the end
The two sides see a payment differently:
- The cashier tracks status in real time across the whole lifecycle - the screen flips from pending to paid or failed on its own, no refresh needed.
- Sale is notified exactly once, when the payment reaches paid, to settle the order. Sale never watches the intermediate states.
What is in the module
One feature area. Click the AREA code to jump to Details for its requirements.
AREA | Name | Status |
|---|---|---|
PAY | Payment Lifecycle | Built |