PRD: Vòng đời thanh toán qua nhà cung cấp

Module	Thanh toán	PRD ID	PRD-PAY-001
Trạng thái	Sẵn sàng dev	FEAT	PAY
Epic	—	Plane	BANA-1511
Ngày	2026-07-15	Phiên bản	v1.1
Gói	@nx/payment	URD	PAY
Surface	BackendSale · POS
Phụ trách	Phát Nguyễn

Dịch vụ thanh toán làm gì

Khi thu ngân (cashier) thu tiền một đơn bằng mã QR hoặc máy quẹt, tiền không đi thẳng từ POS vào sổ. Nó đi qua một nhà cung cấp thanh toán (payment provider) bên ngoài - VNPAY - rồi nhà cung cấp báo kết quả về.

Dịch vụ thanh toán (Payment Service) là nơi nhận kết quả đó. Nó lấy thông báo từ nhà cung cấp, đổi trạng thái của khoản thanh toán, đẩy trạng thái mới về màn hình thu ngân ngay lập tức, và báo cho bán hàng (Sale) biết để tất toán đơn. Từ đó tài chính, kho và hóa đơn tự phản ứng theo.

Bốn trạng thái của một khoản thanh toán

Mỗi khoản thanh toán đi qua một vòng đời ngắn, mô tả bằng ngôn ngữ nghiệp vụ:

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ả

Hai kiểu nhận tiền của VNPAY

• VNPAY QR MMS: sinh một mã QR, khách quét bằng app ngân hàng để trả.
• PhonePOS: biến điện thoại của thu ngân thành thiết bị nhận thẻ, khách chạm thẻ vào điện thoại.

Cả hai đều báo kết quả về dịch vụ thanh toán theo cùng một đường, nên phần sau của hệ thống xử lý giống nhau bất kể khách trả bằng cách nào.

Một khoản thanh toán QR, từ lúc quét tới lúc lên sổ

Thu ngân thu 200.000đ cho đơn #123 bằng VNPAY QR MMS:

Việc xảy ra	Trạng thái khoản thanh toán	Thu ngân thấy
Thu ngân bấm thu tiền, mã QR hiện ra	đang chờ	Màn chờ khách quét
Khách quét và trả, VNPAY báo về	đã thanh toán	Màn tự chuyển sang đã trả, không cần bấm làm mới
Bán hàng nhận tin, tất toán đơn #123	đã thanh toán	Đơn #123 đóng, in hóa đơn

• Thu ngân không phải bấm làm mới hay chờ vòng hỏi trạng thái. Trạng thái tự đẩy về ngay khi VNPAY xác nhận.
• Ngay sau khi đơn tất toán, tài chính ghi phiếu thu, kho trừ hàng, hóa đơn phát hành - tất cả tự chạy, không giữ chân thu ngân.

Chỗ dễ sai nhất

Cấu hình và thông tin xác thực KHÔNG thuộc dịch vụ thanh toán

Việc chọn nhà cung cấp nào, nhập mã merchant và thông tin xác thực, gắn với ví nào - tất cả nằm trong ví tài chính (Finance Account) của merchant, do module tài chính quản lý. Cả chủ merchant và đội vận hành (operations team) cấu hình tại đó.

Dịch vụ thanh toán chỉ đọc cấu hình đang hoạt động từ ví tài chính khi thu tiền. Nó không có màn cấu hình riêng và không lưu thông tin xác thực của riêng nó.

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. Dịch vụ thanh toán nhận ra lần thứ hai và bỏ qua, nên không có chuyện tính tiền hai lần hay lên sổ hai lần cho cùng một khoản.

1. Mục tiêu & Loại trừ

Mục tiêu

• Nhận kết quả từ nhà cung cấp và cập nhật trạng thái khoản thanh toán qua vòng đời đang chờ → đã thanh toán / thất bại / hết hạn.
• Đẩy trạng thái về màn hình thu ngân theo thời gian thực, để thu ngân biết đã trả hay chưa mà không phải bấm làm mới.
• Báo cho bán hàng ngay khi thanh toán thành công, để đơn được tất toán và các bên phía sau (tài chính, kho, hóa đơn) tự phản ứng.
• Áp dụng một kết quả gửi lại đúng một lần, để một thông báo lặp không gây hiệu ứng trùng.
• Cho đường tiền mặt (CASH) cũng đi qua cùng cơ chế báo tin, để trạng thái phía sau hội tụ bất kể khách trả bằng gì.
• Đọc cấu hình nhà cung cấp đang hoạt động từ ví tài chính của merchant tại thời điểm thu tiền.

Loại trừ

• Màn cấu hình nhà cung cấp, nhập thông tin xác thực, chọn ví - thuộc ví tài chính của module tài chính. PRD này chỉ đọc cấu hình đó, không tạo hay sửa.
• Ghi sổ phiếu thu, phiếu chi, giá vốn từ một khoản đã trả - thuộc Hạch toán theo sự kiện.
• Hoàn tiền có cấu trúc qua nhà cung cấp gốc - Dự kiến, xem URD §7.
• SoftPOS / NFC chạm-để-trả và các ví điện tử khác (Momo, ZaloPay) - Phi mục tiêu của URD.
• Giao diện thanh toán và chia nhỏ thanh toán trên đơn - thuộc module Bán hàng.
• Tài khoản/ví, voucher/sổ cái, nhóm - thuộc các PRD tài chính riêng.

2. Thước đo thành công

Thước đo	Mục tiêu / tín hiệu
Độ trễ trạng thái	Thu ngân thấy đang chờ → đã thanh toán / thất bại / hết hạn gần như tức thì, không có độ trễ của vòng hỏi trạng thái
Chống trùng	Một kết quả gửi lại từ nhà cung cấp tạo ra 0 hiệu ứng trùng
Tách rời	Bán hàng nhận kết quả qua báo tin và phát tiếp cho các bên phía sau; không bên nào phải gọi thẳng vào dịch vụ thanh toán
Hội tụ CASH	Đường tiền mặt và đường nhà cung cấp cho ra trạng thái phía sau giống nhau

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Thu ngân	Thu một khoản và thấy nó chuyển sang đã trả ngay trên màn, không phải bấm làm mới
Bán hàng / Đơn	Được báo ngay khi thanh toán thành công để tất toán đơn
Chủ merchant	Tin rằng mỗi khoản khách trả đều lên sổ đầy đủ ở phía sau
Hệ thống (dịch vụ thanh toán)	Nhận kết quả nhà cung cấp, cập nhật trạng thái đúng một lần, đẩy real-time và báo bán hàng

Kịch bản cốt lõi: thu ngân bấm thu tiền cho đơn → dịch vụ thanh toán đọc cấu hình nhà cung cấp từ ví tài chính của merchant và tạo yêu cầu, trạng thái là đang chờ → khách quét mã QR và trả → nhà cung cấp báo kết quả về → dịch vụ thanh toán áp dụng kết quả một lần, đổi trạng thái sang đã thanh toán → thu ngân thấy màn tự chuyển sang đã trả → bán hàng được báo, tất toán đơn và phát tin cho tài chính, kho, hóa đơn.

4. User Stories

#	Là một	Tôi muốn	Để
01	thu ngân	trạng thái thanh toán tự cập nhật trên màn	tôi không phải bấm làm mới để biết một khoản QR đã trả hay chưa
02	bán hàng	được báo ngay khi thanh toán thành công	tôi tất toán đơn mà không phải tự đi hỏi nhà cung cấp
03	chủ merchant	một kết quả gửi lại chỉ được áp dụng một lần	một lần mạng chập chờn không bao giờ tính tiền hay lên sổ hai lần
04	chủ merchant	khoản thu tiền mặt cũng đi qua cùng đường báo tin	sổ sách phía sau đồng nhất dù khách trả tiền mặt hay QR

5. Yêu cầu chức năng

#	Yêu cầu	Trạng thái	URD ref
FR-001	Dịch vụ thanh toán nhận kết quả từ nhà cung cấp và cập nhật trạng thái khoản thanh toán. • Kết quả thành công đưa trạng thái sang đã thanh toán; kết quả thất bại đưa sang thất bại; mã QR hết hạn trước khi có ai trả đưa sang hết hạn. • Cùng một đường nhận áp dụng cho cả VNPAY QR MMS và PhonePOS. • Kết quả có số tiền lệch với số tiền của yêu cầu thì bị từ chối, không đổi trạng thái sang đã thanh toán.	✅	URD-PAY-001
FR-002	Trạng thái được đẩy về màn hình thu ngân theo thời gian thực, thay cho vòng hỏi trạng thái. • Mỗi lần trạng thái đổi, màn của thu ngân tự cập nhật, không cần bấm làm mới. • Chỉ thu ngân của đúng merchant và đúng khoản thanh toán nhận được cập nhật đó.	✅	URD-PAY-003
FR-003	Khi thành công, dịch vụ thanh toán báo cho bán hàng; bán hàng tất toán đơn và phát tin cho các bên phía sau. • Bán hàng nhận tin thành công rồi tất toán đơn tương ứng. • Sau đó bán hàng phát một sự kiện payment-success trên luồng sự kiện dùng chung (shared event stream) để tài chính, kho và hóa đơn tiêu thụ. • Không bên phía sau nào gọi thẳng vào dịch vụ thanh toán; tất cả phản ứng qua tin báo và luồng sự kiện.	✅	URD-PAY-002 · URD-PAY-005
FR-004	Một kết quả từ nhà cung cấp chỉ được áp dụng một lần, dù bị gửi lại. • Kết quả cho một khoản đã ở trạng thái đã thanh toán hoặc hết hạn bị bỏ qua, không đổi trạng thái và không báo trùng. • Một thông báo lặp không tạo phiếu thu thứ hai và không tất toán đơn lần hai.	✅	URD-PAY-004
FR-005	Dịch vụ thanh toán phát sự kiện thanh toán; việc gửi webhook ra ngoài dùng cơ chế webhook chung của platform. • Dịch vụ thanh toán phát sự kiện theo loại (thành công, thất bại, hết hạn); bên nhận (bán hàng) đăng ký nhận theo loại sự kiện ở mức nền tảng, không theo từng merchant. • Cơ chế webhook chung của platform lo việc gửi tin ra ngoài: gửi thất bại thì thử lại với khoảng cách giãn dần, số lần thử lại mặc định 3 lần. • Tin báo có thể được ký để bên nhận xác minh nguồn; việc ký là tùy chọn.	✅	URD-PAY-005
FR-006	Đường tiền mặt (CASH) cũng đi qua cùng cơ chế báo tin. • Thu ngân xác nhận đã nhận tiền mặt thì khoản thanh toán chuyển sang đã thanh toán và phát tin giống hệt đường nhà cung cấp. • Nhờ vậy trạng thái phía sau hội tụ, bất kể khách trả tiền mặt hay QR.	✅	URD-PAY-002

5.1 Tiêu chí nghiệm thu

• Một khoản thanh toán đang chờ → nhà cung cấp báo thành công → trạng thái sang đã thanh toán, thu ngân thấy màn tự chuyển sang đã trả, bán hàng được báo và tất toán đơn.
• Một khoản thanh toán đang chờ → nhà cung cấp báo thất bại → trạng thái sang thất bại, đơn vẫn để mở.
• Một mã QR hết hạn trước khi khách trả → trạng thái sang hết hạn, đơn vẫn để mở.
• Nhà cung cấp báo về với số tiền lệch so với số tiền của yêu cầu → kết quả bị từ chối, trạng thái không chuyển sang đã thanh toán.
• Cùng một kết quả thành công được gửi về hai lần → lần thứ hai bị bỏ qua, không có phiếu thu thứ hai và đơn không bị tất toán lần nữa.
• Một khoản đang chờ chuyển sang đã thanh toán → màn thu ngân của đúng merchant và đúng khoản đó tự cập nhật, không cần bấm làm mới; thu ngân của merchant khác không nhận được cập nhật này.
• Một khoản thanh toán thành công → bán hàng tất toán đơn và phát payment-success → tài chính, kho, hóa đơn nhận được và phản ứng, không bên nào phải gọi thẳng vào dịch vụ thanh toán.
• Thu ngân xác nhận đã nhận đủ tiền mặt cho một đơn → khoản chuyển sang đã thanh toán và phát tin giống đường QR; trạng thái phía sau giống với một đơn trả bằng QR.
• Đường báo tin gửi thất bại một lần → cơ chế webhook chung của platform thử lại với khoảng cách giãn dần cho tới số lần tối đa đã cấu hình, mặc định 3 lần.
• Thu tiền cho một merchant chưa cấu hình nhà cung cấp nào trong ví tài chính → dịch vụ thanh toán không đọc được thông tin xác thực và không tạo được yêu cầu qua nhà cung cấp đó.

6. Yêu cầu phi chức năng

Khía cạnh	Yêu cầu
Chống trùng	Một kết quả gửi lại là thao tác không tác dụng: không đổi trạng thái, không tạo phiếu, không tất toán đơn lần hai
Tách rời	Không bên phía sau nào gọi thẳng vào dịch vụ thanh toán; tất cả phản ứng qua tin báo và luồng sự kiện dùng chung
Real-time	Trạng thái tới thu ngân qua một kênh đẩy thời gian thực, không qua vòng hỏi trạng thái
Phân quyền theo merchant	Mọi thao tác giới hạn trong merchant của chính người dùng; cập nhật real-time chỉ tới đúng merchant và đúng khoản thanh toán
Độ bền báo tin	Gửi tin thất bại được thử lại với khoảng cách giãn dần; một lỗi xác thực của bên nhận (từ chối truy cập) không thử lại vì thử lại cũng vô ích
i18n	Nhãn và trạng thái hiển thị cho người dùng là song ngữ (tiếng Anh và tiếng Việt)

7. UX & Luồng

Dịch vụ thanh toán chạy ngầm phía sau thao tác thu tiền trên POS. Thu ngân chỉ thấy một điều: trạng thái tự chuyển từ đang chờ sang đã trả hoặc thất bại, không phải bấm làm mới.

8. Dữ liệu & Miền nghiệp vụ

Khái niệm	Vai trò
Khoản thanh toán	Bản ghi mà kết quả từ nhà cung cấp điều khiển trạng thái qua đang chờ → đã thanh toán / thất bại / hết hạn
Đăng ký báo tin	Cấu hình điểm nhận tin ở mức nền tảng, theo loại sự kiện, có thử lại khi gửi thất bại và ký tùy chọn
Cấu hình nhà cung cấp	Nhà cung cấp và thông tin xác thực theo từng merchant, đọc từ ví tài chính; do module tài chính sở hữu và quản lý
Sự kiện payment-success	Do bán hàng phát khi một khoản thành công đã tất toán; fan-out trên luồng sự kiện dùng chung cho tài chính, kho, hóa đơn

Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong payment domain model. Mô hình cấu hình và ví nằm trong tài liệu finance.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	Ví tài chính (Finance Account)	nhà cung cấp đang hoạt động và thông tin xác thực nằm trong ví tài chính của merchant, do module tài chính sở hữu; dịch vụ thanh toán chỉ đọc, không tạo hay sửa.
02	Bán hàng	một đơn kích hoạt thanh toán; bán hàng nhận tin kết quả và phát sự kiện payment-success.
03	Hạch toán theo sự kiện	tiêu thụ payment-success để tự ghi phiếu thu phía sau.
04	Nền tảng lõi	luồng sự kiện dùng chung và hạ tầng đường báo tin.
05	Nhà cung cấp thanh toán (VNPAY QR MMS, PhonePOS)	nguồn bên ngoài của kết quả thanh toán.

Giả định

#	Giả định	Sai thì sao
01	Merchant đã cấu hình ít nhất một nhà cung cấp trong ví tài chính trước khi thu qua nhà cung cấp đó.	Chưa cấu hình thì dịch vụ thanh toán không đọc được thông tin xác thực và không tạo được yêu cầu thanh toán; thu ngân không mở được mã QR.
02	Nhà cung cấp gửi kết quả về một cách tin cậy, kể cả gửi lại khi mạng chập chờn.	Kết quả không về thì khoản treo ở đang chờ cho tới khi hết hạn; việc chống trùng bảo đảm một lần gửi lại không gây hại.
03	Màn hình thu ngân duy trì một kết nối trực tiếp để nhận trạng thái real-time.	Mất kết nối thì thu ngân không thấy trạng thái tự đổi và phải mở lại màn để lấy trạng thái mới nhất.
04	Luồng sự kiện dùng chung sẵn sàng cho fan-out payment-success.	Luồng gián đoạn thì phiếu thu, trừ kho và hóa đơn bắt kịp về sau khi luồng hồi phục, không mất, nhưng có độ trễ.

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P1 - PAY theo danh mục feature URD
Rollout	Mọi merchant; việc thu qua nhà cung cấp gắn với việc merchant đã cấu hình nhà cung cấp trong ví tài chính
Migration	Seam payment-success chuyển từ một hàng đợi công việc trong tiến trình sang luồng sự kiện dùng chung
Tiêu chí phát hành	Kết quả nhà cung cấp → cập nhật trạng thái → đẩy real-time cho thu ngân → bán hàng được báo, kiểm chứng đầu-cuối; gửi lại chứng minh không tác dụng trùng
Theo dõi	Tỷ lệ gửi và thử lại tin báo, độ trễ tiêu thụ payment-success, số lần chống trùng từ chối, sức khỏe kết nối real-time

Tham chiếu

• URD: Thanh toán & Giao dịch - Vòng đời Thanh toán
• Phụ thuộc: Ví tài chính · Hạch toán theo sự kiện
• Module: Thanh toán & Giao dịch - URD
• Developer: @nx/payment · @nx/finance

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Một thông báo gửi lại từ nhà cung cấp áp dụng hai lần	Kết quả áp dụng một lần theo trạng thái của khoản; lần gửi lại bị bỏ qua (FR-004)
02	Bán hàng và thanh toán gắn chặt lại theo thời gian	Ranh giới chỉ là tin báo và luồng sự kiện dùng chung; không có đường gọi thẳng trong tiến trình (FR-003)
03	Trạng thái tiền mặt và trạng thái nhà cung cấp lệch nhau	Đường tiền mặt cũng đi qua cùng cơ chế báo tin nên trạng thái phía sau hội tụ (FR-006)
04	Hoàn tiền có cấu trúc qua nhà cung cấp	Hoãn lại - Dự kiến, xem URD §7

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Cấu hình nhà cung cấp và thông tin xác thực nhập ở đâu?	Trong ví tài chính của merchant, do module tài chính quản lý. Cả chủ merchant và đội vận hành cấu hình tại đó. Dịch vụ thanh toán chỉ đọc cấu hình đang hoạt động khi thu tiền, không có màn cấu hình riêng.
02	Thu ngân thấy trạng thái mà không bấm làm mới bằng cách nào?	Một kênh đẩy thời gian thực gửi mỗi thay đổi trạng thái thẳng về màn của thu ngân, thay cho vòng hỏi trạng thái cũ.
03	Nhà cung cấp gửi cùng một kết quả hai lần thì sao?	Lần thứ hai không có tác dụng. Kết quả được áp dụng một lần, nên một thông báo gửi lại không tính tiền hay lên sổ hai lần.
04	Thanh toán tiền mặt có bỏ qua đường báo tin không?	Không. Đường tiền mặt cũng đi qua cùng cơ chế báo tin để trạng thái phía sau hội tụ với thanh toán qua nhà cung cấp.
05	Tôi hoàn tiền qua nhà cung cấp ở đây được không?	Không trong bước tăng này. Hoàn tiền có cấu trúc qua nhà cung cấp là Dự kiến, xem URD §7.