URD: Thanh toán & Giao dịch
| Module | CORE-08 | Phiên bản | v0.4 |
|---|---|---|---|
| Trạng thái | In-progress | Ngày | 2026-05-30 |
1. Mục đích
Định nghĩa yêu cầu hướng người dùng cho việc thu thanh toán và ghi nhận tiền kết quả. Module kết nối nhà cung cấp thanh toán của một merchant tới BANA, bộc lộ trạng thái thanh toán live, và ghi sổ mọi thanh toán, mua hàng, và biến động tồn hoàn tất vào một sổ cái tài chính ghi sổ kép để chủ có thể xem số dư và đối chiếu sổ sách.
2. Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Credential nhà cung cấp thanh toán theo từng merchant (VNPAY QR MMS, PhonePOS) | Code tích hợp gateway trực tiếp (mối quan tâm lập trình viên) |
| Trạng thái thanh toán real-time (webhook + WebSocket) | UX checkout / tách-thanh-toán (module Đơn hàng) |
| Subscription webhook outbound theo từng merchant | Lưu trữ dữ liệu thẻ / token |
| Tài khoản / ví Tài chính + tài khoản control | Quy đổi đa tiền tệ |
| Voucher ghi sổ kép (RECEIPT / PAYMENT / TRANSFER / ADJUSTMENT) | Phát hành hóa đơn thuế (module Thuế & Hóa đơn) |
| Tự-post từ event bán, mua, và kho | Hoàn tiền nhà cung cấp có cấu trúc (Dự kiến) |
| Phân cấp nhóm (seed + tùy chỉnh) | Đối chiếu tiền mặt theo từng ca (Dự kiến) |
3. Định nghĩa
| Thuật ngữ | Định nghĩa |
|---|---|
| Nhà cung cấp thanh toán (Payment provider) | Một service ngoài (ví dụ VNPAY) xử lý thanh toán của một khách hàng |
| Webhook | Một thông báo outbound BANA gửi tới subscriber khi một thanh toán đổi trạng thái |
| Tài khoản / Ví (Account / Wallet) | Một nơi tiền nằm: cash, bank, thu QR, POS di động, hoặc một tài khoản control nội bộ |
| Voucher | Một mục ghi sổ cân bằng của một loại (RECEIPT, PAYMENT, TRANSFER, ADJUSTMENT) |
| Giao dịch (dòng sổ cái) | Một dòng DEBIT hoặc CREDIT trong một voucher, ảnh hưởng số dư của một tài khoản |
| Nhóm (Category) | Một nhãn thu hoặc chi phân loại tiền đến từ đâu hoặc đi đâu |
| Tự-post (Auto-posting) | Một voucher được tạo tự động bởi hệ thống phản ứng với một event nghiệp vụ |
4. Mô hình Khái niệm
Chỉ là khái niệm — schema đầy đủ nằm trong mô hình miền lập trình viên payment và finance.
5. Yêu cầu Chức năng
Mỗi bảng cho một lĩnh vực chức năng. Mã
<AREA>khớp với ID test-case. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).
5.1 Vòng đời Thanh toán (PAY)
| ID | P | Yêu cầu |
|---|---|---|
| URD-PAY-001 | M | Hệ thống nhận kết quả thanh toán từ nhà cung cấp và cập nhật trạng thái của thanh toán |
| URD-PAY-002 | M | Khi thanh toán thành công, hệ thống thông báo cho subscriber (ví dụ sale settle đơn) |
| URD-PAY-003 | M | Trạng thái thanh toán được broadcast live tới thu ngân (pending → paid / failed / expired) |
| URD-PAY-004 | M | Cùng kết quả thanh toán chỉ được áp một lần, dù gửi nhiều lần (idempotent) |
| URD-PAY-005 | S | Chủ có thể subscribe endpoint webhook theo loại event, với retry khi gửi thất bại |
| URD-PAY-006 | W | Hoàn tiền có cấu trúc qua nhà cung cấp gốc (Dự kiến — xem §7) |
5.2 Credential Nhà cung cấp (PRV)
| ID | P | Yêu cầu |
|---|---|---|
| URD-PRV-001 | M | Chủ có thể kết nối một nhà cung cấp thanh toán (VNPAY QR MMS, PhonePOS) theo từng merchant |
| URD-PRV-002 | M | Credential nhà cung cấp được lưu mã hóa và không bao giờ hiện đầy đủ |
| URD-PRV-003 | S | Credential được giới hạn theo từng merchant nên một merchant không thể dùng của merchant khác |
5.3 Tài khoản & Ví (WAL)
| ID | P | Yêu cầu |
|---|---|---|
| URD-WAL-001 | M | Chủ có thể tạo tài khoản loại CASH, BANK, mã QR, hoặc POS di động |
| URD-WAL-002 | M | Hệ thống duy trì tài khoản control nội bộ (ví dụ inventory, COGS) tự động |
| URD-WAL-003 | M | Mỗi tài khoản theo dõi một số dư mở và một số dư hiện tại chạy |
| URD-WAL-004 | M | Một tài khoản mặc định mỗi merchant nhận thu bán tự-post |
| URD-WAL-005 | S | Vai trò phi-chủ chỉ thấy tài khoản của merchant họ được cấp truy cập |
5.4 Voucher & Sổ cái (VCH)
| ID | P | Yêu cầu |
|---|---|---|
| URD-VCH-001 | M | Mọi voucher cân bằng: tổng DEBIT bằng tổng CREDIT |
| URD-VCH-002 | M | Loại voucher là RECEIPT, PAYMENT, TRANSFER, ADJUSTMENT |
| URD-VCH-003 | M | Một thanh toán bán hoàn tất tự-post một voucher RECEIPT vào tài khoản mặc định |
| URD-VCH-004 | M | Nhận một đơn mua hàng tự-post một voucher PAYMENT |
| URD-VCH-005 | M | Một lần xuất/điều chỉnh tồn tự-post voucher sổ cái khớp |
| URD-VCH-006 | M | Mỗi voucher ghi source event của nó nên cùng event chỉ post một lần (idempotent) |
| URD-VCH-007 | M | Voucher được đánh số theo từng merchant và loại (ví dụ PT / PC / PCK / PKT) |
| URD-VCH-008 | S | Chủ có thể tạo một voucher thủ công (draft → issue) |
| URD-VCH-009 | S | Chủ có thể void một voucher qua một đảo ngược cân bằng (không xóa cứng) |
| URD-VCH-010 | C | Chuyển giữa hai tài khoản được ghi như một voucher tổng-không |
5.5 Nhóm (CAT)
| ID | P | Yêu cầu |
|---|---|---|
| URD-CAT-001 | M | 14 nhóm hệ thống được seed và không thể gỡ |
| URD-CAT-002 | M | Nhóm có kiểu INCOME hoặc EXPENSE |
| URD-CAT-003 | S | Chủ có thể thêm nhóm tùy chỉnh theo từng merchant, gồm một phân cấp cha |
6. Tiêu chí Chấp nhận
AC-PAY-01: Cập nhật trạng thái thanh toán
| Cho trước | Khi | Thì |
|---|---|---|
| Một thanh toán pending | Nhà cung cấp báo thành công | Trạng thái thành paid, subscriber được thông báo, thu ngân thấy cập nhật live |
| Một thanh toán pending | Nhà cung cấp báo thất bại / hết hạn | Trạng thái thành failed / expired; đơn vẫn mở |
| Một kết quả đã áp | Cùng kết quả gửi lại | Bị bỏ qua; không hiệu ứng trùng |
AC-VCH-01: Tự-post từ event
| Cho trước | Khi | Thì |
|---|---|---|
| Một thanh toán bán thành công | Event được xử lý | Một voucher RECEIPT cân bằng post vào tài khoản mặc định |
| Một đơn mua hàng đã nhận | Event được xử lý | Một voucher PAYMENT cân bằng post |
| Cùng source event | Nó được gửi lại | Không voucher thứ hai được tạo (idempotent) |
AC-VCH-02: Voucher thủ công và void
| Cho trước | Khi | Thì |
|---|---|---|
| Một chủ | Tạo và issue một voucher thủ công | Một voucher cân bằng xuất hiện trong sổ cái với một số thứ tự |
| Một voucher đã issue | Chủ void nó | Một voucher đảo ngược cân bằng được post; bản gốc được giữ |
AC-WAL-01: Tài khoản và số dư
| Cho trước | Khi | Thì |
|---|---|---|
| Một chủ | Tạo một tài khoản với một số dư mở | Tài khoản hiện số dư mở đó là hiện tại |
| Một voucher đã post | Nó debit/credit một tài khoản | Số dư chạy của tài khoản cập nhật tương ứng |
7. Ràng buộc & Không-mục-tiêu
Ràng buộc
| ID | Ràng buộc |
|---|---|
| C-01 | Mọi voucher phải cân bằng (tổng DEBIT = tổng CREDIT) |
| C-02 | 14 nhóm seed không thể gỡ |
| C-03 | Credential nhà cung cấp mã hóa at-rest và masked trong response |
| C-04 | Mỗi event nghiệp vụ post tối đa một voucher (idempotent qua source event id) |
| C-05 | Bản ghi dùng soft-delete / đảo ngược — không xóa cứng lịch sử tài chính |
| C-06 | Một tài khoản mặc định mỗi merchant cho thu bán tự-post |
Không-mục-tiêu
- Flow SoftPOS / NFC tap-to-pay
- Nhà cung cấp e-wallet bổ sung (Momo, ZaloPay)
- Hoàn / đảo charge nhà cung cấp ngoài có cấu trúc
- Quy đổi đa tiền tệ và đối chiếu cross-currency
- Dashboard đối chiếu tiền mặt theo từng ca
8. Lịch sử Phiên bản
| Ngày | Tác giả | Mô tả | Ver |
|---|---|---|---|
| 2026-02-26 | P. Do — Product Owner | User story ban đầu | v0.1 |
| 2026-04-16 | P. Do — Product Owner | Ví tài chính, giao dịch, nhóm | v0.3 |
| 2026-05-30 | Di chuyển | Tái cấu trúc theo quy ước module; căn các lĩnh vực (PAY/PRV/WAL/VCH/CAT) theo thực tế hai-package; hoàn tiền + đối chiếu đánh dấu Dự kiến | v0.4 |