PRD: Payment lifecycle over providers

Module	Payment	PRD ID	PRD-PAY-001
Status	Ready to dev	FEAT	PAY
Epic	—	Plane	BANA-1511
Date	2026-07-15	Version	v1.1
Packages	@nx/payment	URD	PAY
Surface	BackendSale · POS
Owner	Phát Nguyễn

What the payment service does

When a cashier collects a payment for an order by QR code or card reader, the money does not go straight from the POS into the books. It travels through an external payment provider - VNPAY - which then reports the result back.

The Payment Service is where that result lands. It takes the provider's notification, changes the payment's status, pushes the new status to the cashier's screen at once, and notifies the Sale so the order can settle. From there finance, inventory and invoicing react on their own.

The four states of a payment

Every payment runs a short lifecycle, described in business terms:

State	Meaning
pending	The request is created, the QR code is waiting to be scanned or the reader is waiting for a card
paid	The provider confirms the money has arrived
failed	The provider reports the transaction did not go through
expired	The QR code lapsed before anyone paid

Two ways VNPAY takes money

• VNPAY QR MMS: generates a QR code the customer scans with a banking app to pay.
• PhonePOS: turns the cashier's phone into a card-acceptance device the customer taps a card against.

Both report their result to the payment service along the same path, so the rest of the system behaves the same regardless of how the customer paid.

One QR payment, from scan to books

A cashier collects 200,000d for order #123 via VNPAY QR MMS:

What happens	Payment state	The cashier sees
Cashier taps collect, the QR code appears	pending	A screen waiting for the scan
Customer scans and pays, VNPAY reports back	paid	The screen flips to paid on its own, no manual refresh
Sale receives the notice, settles order #123	paid	Order #123 closes, receipt prints

• The cashier does not refresh or wait on a polling loop. The status pushes itself the moment VNPAY confirms.
• Right after the order settles, finance posts a receipt voucher, inventory decrements stock, invoicing issues the invoice - all on their own, never holding up the cashier.

The thing most often gotten wrong

Configuration and credentials do NOT belong to the payment service

Which provider to use, the merchant code and credentials, which wallet it binds to - all of that lives in the merchant's Finance Account, owned by the finance module. Both the shop owner and the operations team configure it there.

The payment service only reads the active configuration from the Finance Account when collecting. It has no configuration screen of its own and stores no credentials of its own.

A redelivered result is applied only once

A flaky network can make the provider send the same success notification twice. The payment service recognises the second one and skips it, so there is never a double charge or a double posting for the same payment.

1. Goals & Exclusions

Goals

• Ingest provider results and update the payment's status through the lifecycle pending → paid / failed / expired.
• Push status to the cashier's screen in real time, so the cashier knows whether it is paid without a manual refresh.
• Notify the sale the instant a payment succeeds, so the order settles and downstream parties (finance, inventory, invoicing) react on their own.
• Apply a redelivered result exactly once, so a duplicate notification has no duplicate effect.
• Route the CASH path through the same notification mechanism, so downstream status converges regardless of how the customer paid.
• Read the active provider configuration from the merchant's Finance Account at the moment of collection.

Exclusions

• The provider configuration screen, entering credentials, choosing a wallet - owned by the Finance Account in the finance module. This PRD only reads that configuration, it does not create or edit it.
• Posting receipt, payment and cost-of-goods vouchers from a paid amount - owned by Event-driven finance posting.
• Structured refund back through the original provider - Planned, see URD §7.
• SoftPOS / NFC tap-to-pay and other e-wallets (Momo, ZaloPay) - URD Non-Goals.
• Checkout and split-payment UX on the order - owned by the Orders module.
• Accounts/wallets, vouchers/ledger, categories - owned by separate finance PRDs.

2. Success Metrics

Metric	Target / signal
Status latency	The cashier sees pending → paid / failed / expired in near-real-time, with none of the polling delay
Deduplication	A redelivered provider result produces zero duplicate effects
Decoupling	The sale receives the result via a notification and re-emits it downstream; no party calls into the payment service directly
CASH convergence	The CASH path and the provider path yield the same downstream status

3. Personas & Scenarios

Persona	Goal in this feature
Cashier	Take a payment and see it flip to paid on the screen at once, without a manual refresh
Sale / Order	Be notified the instant a payment succeeds so the order can settle
Shop owner	Trust that every amount a customer pays posts fully downstream
System (payment service)	Ingest the provider result, update status exactly once, push it live and notify the sale

Core scenario: the cashier taps collect on an order → the payment service reads the provider configuration from the merchant's Finance Account and creates the request, status is pending → the customer scans the QR code and pays → the provider reports the result back → the payment service applies the result once and flips status to paid → the cashier sees the screen change to paid on its own → the sale is notified, settles the order and emits the notice to finance, inventory and invoicing.

4. User Stories

#	As a	I want	So that
01	cashier	payment status to update on the screen on its own	I do not refresh to know whether a QR payment has been paid
02	sale	to be notified the instant a payment succeeds	I settle the order without going to ask the provider myself
03	shop owner	a redelivered result to be applied only once	a flaky network never charges or posts twice
04	shop owner	a cash collection to run through the same notification path	downstream books are uniform whether the customer paid cash or QR

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	The payment service ingests provider results and updates the payment's status. • A success result moves status to paid; a failure result moves it to failed; a QR code that lapses before anyone pays moves it to expired. • The same ingestion path serves both VNPAY QR MMS and PhonePOS. • A result whose amount differs from the request amount is rejected and does not move status to paid.	✅	URD-PAY-001
FR-002	Status is pushed to the cashier's screen in real time, replacing the polling loop. • Each time status changes, the cashier's screen updates on its own, with no manual refresh. • Only the cashier of the correct merchant and the correct payment receives that update.	✅	URD-PAY-003
FR-003	On success, the payment service notifies the sale; the sale settles the order and emits downstream. • The sale receives the success notice and settles the corresponding order. • It then emits a payment-success event over the shared event stream for finance, inventory and invoicing to consume. • No downstream party calls into the payment service directly; all react via the notification and the event stream.	✅	URD-PAY-002 · URD-PAY-005
FR-004	A provider result is applied only once, even if redelivered. • A result for a payment already in the paid or expired state is skipped, with no status change and no duplicate notice. • A duplicate notification creates no second receipt voucher and does not settle the order twice.	✅	URD-PAY-004
FR-005	The payment service emits payment events; outbound webhook delivery uses the platform's shared webhook mechanism. • The payment service emits events by type (success, failure, expiry); the receiver (the sale) subscribes by event type at the platform level, not per merchant. • The platform's shared webhook mechanism handles outbound delivery: a failed delivery is retried with a widening gap, default 3 attempts. • A notification may be signed so the receiver can verify its origin; signing is optional.	✅	URD-PAY-005
FR-006	The CASH path also runs through the same notification mechanism. • When the cashier confirms cash received, the payment moves to paid and emits the notice exactly like the provider path. • This keeps downstream status convergent, regardless of whether the customer paid cash or QR.	✅	URD-PAY-002

5.1 Acceptance Criteria

• A pending payment → the provider reports success → status moves to paid, the cashier sees the screen flip to paid, the sale is notified and settles the order.
• A pending payment → the provider reports failure → status moves to failed, the order stays open.
• A QR code that lapses before the customer pays → status moves to expired, the order stays open.
• The provider reports back with an amount that differs from the request amount → the result is rejected, status does not move to paid.
• The same success result is delivered twice → the second one is skipped, there is no second receipt voucher and the order is not settled again.
• A pending payment moves to paid → the cashier screen of the correct merchant and the correct payment updates on its own, with no manual refresh; a cashier of another merchant receives no such update.
• A successful payment → the sale settles the order and emits payment-success → finance, inventory and invoicing receive it and react, none of them calling into the payment service directly.
• The cashier confirms cash received in full for an order → the payment moves to paid and emits the notice like the QR path; downstream status matches an order paid by QR.
• The notification path fails to deliver once → the platform's shared webhook mechanism retries with a widening gap up to the configured maximum, default 3.
• Collecting for a merchant that has configured no provider in its Finance Account → the payment service cannot read credentials and cannot create a request through that provider.

6. Non-Functional Requirements

Area	Requirement
Deduplication	A redelivered result is a no-op: no status change, no voucher, no second settlement of the order
Decoupling	No downstream party calls into the payment service directly; all react via the notification and the shared event stream
Real-time	Status reaches the cashier over a real-time push channel, not a polling loop
Merchant tenancy	All operations confined to the user's own merchant; a real-time update reaches only the correct merchant and the correct payment
Delivery durability	A failed notification is retried with a widening gap; a receiver auth failure (access denied) is not retried, because retrying would not help
i18n	User-facing labels and statuses are bilingual (English and Vietnamese)

7. UX & Flows

The payment service runs behind the collect action on the POS. The cashier sees only one thing: the status changing from pending to paid or failed on its own, with no manual refresh.

8. Data & Domain

Concept	Role
Payment	The record whose status the provider result drives through pending → paid / failed / expired
Notification subscription	Platform-level receiver config, by event type, with retry on delivery failure and optional signing
Provider configuration	Per-merchant provider and credentials, read from the Finance Account; owned and managed by the finance module
payment-success event	Emitted by the sale when a successful payment has settled; fanned out on the shared event stream for finance, inventory, invoicing

Conceptual only - full schema and invariants live in the payment domain model. The configuration and wallet model lives in the finance docs.

9. Dependencies & Assumptions

Depends on

#	Feature	What it depends on
01	Finance Account	the active provider and credentials live in the merchant's financial wallet, owned by the finance module; the payment service only reads them, never creates or edits them.
02	Sale	an order triggers the payment; the sale receives the result notice and emits the payment-success event.
03	Event-driven finance posting	consumes payment-success to post the receipt voucher downstream.
04	Platform core	the shared event stream and the notification plumbing.
05	A payment provider (VNPAY QR MMS, PhonePOS)	the external source of payment results.

Assumptions

#	Assumption	What if it is wrong
01	The merchant has configured at least one provider in its Finance Account before collecting through that provider.	Without it the payment service cannot read credentials and cannot create the payment request; the cashier cannot open the QR code.
02	The provider reports its result reliably, including redelivery over a flaky network.	If the result never arrives the payment sits at pending until it expires; deduplication ensures a redelivery does no harm.
03	The cashier's screen holds a live connection to receive real-time status.	On a lost connection the cashier does not see the status change on its own and must reopen the screen for the latest status.
04	The shared event stream is available for the payment-success fan-out.	If the stream is interrupted the receipt voucher, stock decrement and invoice catch up once it recovers, with nothing lost but a delay.

10. Release Plan & Criteria

Aspect	Plan
Phase	P1 - PAY per the URD feature catalog
Rollout	All merchants; collecting through a provider is gated on the merchant having configured that provider in its Finance Account
Migration	The payment-success seam moves from an in-process job queue to the shared event stream
Release criteria	Provider result → status update → live push to the cashier → sale notified, verified end to end; redelivery proven to have no duplicate effect
Monitoring	Notification delivery and retry rate, payment-success consumer lag, deduplication-rejection count, real-time connection health

References

• URD: Payment & Transaction - Payment Lifecycle
• Depends on: Finance Account · Event-driven finance posting
• Module: Payment & Transaction - URD
• Developer: @nx/payment · @nx/finance

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A redelivered provider notification is applied twice	The result is applied once by the payment's state; the redelivery is skipped (FR-004)
02	Sale and payment re-couple over time	The boundary is the notification and the shared event stream only; no in-process call back (FR-003)
03	Cash status and provider status diverge	The cash path also runs through the same notification mechanism so downstream status converges (FR-006)
04	Structured refund through the provider	Deferred - Planned, see URD §7

FAQ

#	Question	Answer
01	Where are the provider configuration and credentials entered?	In the merchant's Finance Account, owned by the finance module. Both the shop owner and the operations team configure it there. The payment service only reads the active configuration when collecting; it has no configuration screen of its own.
02	How does the cashier see status without a manual refresh?	A real-time push channel sends each status change straight to the cashier's screen, replacing the old polling loop.
03	What if the provider sends the same result twice?	The second one has no effect. The result is applied once, so a redelivered notification does not charge or post twice.
04	Does a cash payment skip the notification path?	No. The cash path also runs through the same notification mechanism so downstream status converges with provider payments.
05	Can I refund through the provider here?	Not in this increment. Structured refund through the provider is Planned, see URD §7.