URD: Thanh toán
| Module | Phiên bản | Cập nhật |
|---|---|---|
CORE-08 | v0.7 | 2026-07-15 |
Module Thanh toán làm gì
Xác định các yêu cầu hướng người dùng cho việc thu một khoản thanh toán qua nhà cung cấp bên ngoài. Khi khách trả tiền bằng mã QR hoặc quẹt thẻ, tiền không vào sổ ngay - nó đi qua một nhà cung cấp thanh toán (Payment provider) bên ngoài, ví dụ VNPAY, rồi nhà cung cấp báo kết quả về. Module Thanh toán nhận kết quả đó, đổi trạng thái của khoản thanh toán, đẩy trạng thái mới cho thu ngân (cashier) ngay lập tức, và báo cho bán hàng (sale) tất toán đơn khi thanh toán thành công.
Việc chọn nhà cung cấp nào và nhập thông tin xác thực không thuộc module này. Nó nằm trong ví tài chính (Finance Account) của chi nhánh (Merchant), do module tài chính sở hữu và quản lý. Module Thanh toán chỉ đọc cấu hình đang bật để thực thi, không tự lưu hay tự cấu hình thông tin xác thực.
Bốn ý cần hiểu trước
Đây là phần quan trọng nhất của tài liệu. Hiểu bốn ý dưới đây là hiểu phần lớn module.
1. Một khoản thanh toán đi qua bốn trạng thái
| Trạng thái | Nghĩa |
|---|---|
| đang chờ (pending) | Đã tạo yêu cầu; mã QR đang chờ khách quét, hoặc máy quẹt đang chờ thẻ |
| đã thanh toán (paid) | Nhà cung cấp xác nhận tiền đã vào |
| thất bại (failed) | Nhà cung cấp báo giao dịch không thành |
| hết hạn (expired) | Mã QR hết hạn trước khi có ai trả |
Đơn hàng phía bán hàng không tất toán cho tới khi khoản thanh toán chạm đã thanh toán. Thất bại và hết hạn đều để đơn ở trạng thái mở, thu ngân thu lại được.
2. Một kết quả gửi lại chỉ được áp dụng một lần
Mạng chập chờn có thể khiến nhà cung cấp gửi cùng một thông báo thành công hai lần. Module Thanh toán nhận ra lần gửi lại và bỏ qua - idempotent (chống trùng) nghĩa là cùng một kết quả, dù gửi bao nhiêu lần, cũng chỉ đổi trạng thái và báo tin đúng một lần. Không có chuyện tính tiền hai lần hay tất toán đơn hai lần cho cùng một khoản.
3. Thanh toán thực thi, ví tài chính giữ cấu hình
Ranh giới giữa hai module nằm đúng ở đây: thanh toán lo phần thực thi một khoản tiền cụ thể; ví tài chính lo phần cấu hình - nhà cung cấp nào đang bật, thông tin xác thực gắn với ví nào. Module Thanh toán không có màn cấu hình riêng; mỗi lần cần thu tiền, nó đọc cấu hình đang bật từ ví tài chính của merchant tại đúng thời điểm đó.
4. Thu ngân theo dõi cả vòng đời, bán hàng chỉ nhận khi xong
Hai bên nhìn khoản thanh toán khác nhau:
- Thu ngân theo dõi trạng thái theo thời gian thực suốt vòng đời - màn tự chuyển từ đang chờ sang đã trả hoặc thất bại, không cần bấm làm mới.
- Bán hàng chỉ nhận đúng một lần báo tin, khi khoản đã đã thanh toán, để tất toán đơn. Bán hàng không theo dõi các trạng thái trung gian.
Module có những gì
Một nhóm feature duy nhất. Bấm vào mã AREA để sang tab Chi tiết đọc yêu cầu.
AREA | Tên | Trạng thái |
|---|---|---|
PAY | Vòng đời Thanh toán | Đã dựng |