Payment & Transaction Phase A In-progress
Connects the merchant's payment providers to BANA and turns completed payments into money the merchant can track. It spans two backend services: Payment (provider credentials + webhook/event dispatch) and Finance (double-entry wallets, accounts, and the auto-posted transaction ledger). Used by cashiers (who collect payment) and owners (who reconcile the books).
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-08 |
| Tier | Core |
| Status | In-progress |
| Phase | P1 (payment events) · P2 (finance ledger) |
| Priority | HIGH |
| Primary users | Cashier (collects), Owner / Manager (reconciles) |
Two packages, one business module. Collecting a payment and recording its money are two halves of the same story. The Payment service handles the live payment lifecycle (provider, webhook, real-time status); the Finance service books the resulting income/expense into a double-entry ledger. See §5 Backend Packages.
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Per-merchant payment provider credentials (VNPAY QR MMS, VNPAY PhonePOS) | Direct provider/gateway integration code (lives in the payment engine) |
| Real-time payment status (webhook + WebSocket broadcast) | Checkout / split-payment UX (owned by the Orders module) |
| Outbound webhook subscriptions per merchant | Card-data / token storage |
| Finance accounts / wallets (CASH, BANK, QR code, mobile POS) + internal control accounts | Multi-currency conversion (single currency per voucher) |
| Double-entry vouchers (RECEIPT / PAYMENT / TRANSFER / ADJUSTMENT) | Tax invoice issuance (owned by Tax & Invoice) |
| Auto-posted income/expense from sale, purchase, and inventory events | Cross-merchant settlement / reconciliation |
| Income/expense category hierarchy (14 seeded categories + custom) | Refund / reversal of external provider charges |
3. Capabilities
| Capability | What the user can do | Status |
|---|---|---|
| Payment provider credentials | Owner connects VNPAY QR MMS / PhonePOS with encrypted per-merchant credentials | Built |
| Live payment status | Cashier sees a payment go from pending to paid/failed/expired in real time | Built |
| Webhook subscriptions | Configure which endpoints receive payment events, with event types and retries | Built |
| Finance accounts / wallets | Owner creates wallets (cash, bank, QR, mobile POS) and tracks running balances | Built |
| Auto income on payment | A completed sale payment automatically posts a balanced RECEIPT voucher | Built |
| Auto expense on purchase / inventory | Receiving a purchase order or adjusting stock posts the matching voucher | Built |
| Transaction ledger | Owner views the double-entry ledger, account balances, and voucher history | Built |
| Manual vouchers | Owner records a manual receipt/payment/transfer/adjustment and voids by reversal | Built |
| Categories | 14 seeded income/expense categories plus merchant-specific custom ones | Built |
| Refund / reversal of external charges | Structured refund back through the original provider | Planned |
| Cash reconciliation per shift | Expected vs. actual cash with variance | Planned |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Orders | A sale order is what triggers a payment; payment completion settles the order |
| Inventory | Stock issue/adjustment events drive expense postings into the ledger |
| Tax & Invoice | A successful payment can trigger invoice issuance downstream |
5. Backend Packages
This module is powered by two services. Implementation detail lives in the developer docs — this section only maps the module to them.
| Package | Role | Developer docs |
|---|---|---|
@nx/payment | Payment lifecycle: provider credentials, webhook dispatch, real-time status broadcast | payment |
@nx/finance | Double-entry bookkeeping: accounts/wallets, vouchers, transaction ledger, categories | finance |
6. Key User Flows
Collect a payment (Payment service)
Record the money (Finance service)
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner | Connect providers, manage wallets/accounts, create manual vouchers, view ledger | — |
| Manager | View ledger, manage accounts, create manual vouchers | Change provider credentials (owner-gated) |
| Cashier | Collect payments, see live payment status | Manage accounts or post manual vouchers |
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P1 | Payment provider credentials, webhook + WebSocket payment status, webhook subscriptions |
| P2 | Finance accounts/wallets, double-entry vouchers, auto-posting from sale/purchase/inventory events, categories, manual vouchers + void |
| P3 | Structured provider refunds, per-shift cash reconciliation with variance |
9. Related Pages
- URD
- Test Cases
- PRDs
- Orders · Inventory · Tax & Invoice
- Developer: payment · finance