🏦 Cổng thanh toán VietQR
Cổng thanh toán VietQR là một nhà cung cấp thanh toán trực tuyến trong phân hệ Payment của Xbook: khách hàng thanh toán bằng cách quét mã QR VietQR (mã động) hiển thị ngay trong trang thanh toán, hệ thống tạo giao dịch thanh toán (payment.transaction) và đối soát với hóa đơn (account.move) tương ứng. Cổng chỉ hỗ trợ giao dịch bằng đồng Việt Nam (VND).
💡 Trang này nói về cổng thanh toán online qua phân hệ Payment (khách quét mã QR động khi thanh toán). Nếu bạn chỉ cần sinh mã QR tĩnh ngay trên đơn bán hàng để khách chuyển khoản, hãy xem Thanh toán VietQR trên đơn bán.
🔁 Cách hoạt động
- Khi khách hàng chọn thanh toán bằng VietQR, hệ thống tạo một giao dịch thanh toán (payment.transaction) và sinh mã QR động theo đúng số tiền cần thanh toán.
- Mã QR được hiển thị ngay trong trang thanh toán (biểu mẫu nội tuyến, không chuyển hướng sang trang ngoài).
- Khách dùng ứng dụng ngân hàng hỗ trợ VietQR để quét mã và chuyển khoản đúng số tiền, đúng nội dung chuyển khoản đã được điền sẵn.
- Trong lúc khách chuyển khoản thủ công, giao dịch chuyển sang trạng thái Đang chờ (pending); giao dịch được xác nhận khi ngân hàng báo thành công.
- Giao dịch gắn với hóa đơn (account.move) qua mã tham chiếu (reference), phục vụ đối soát công nợ.
💡 Mỗi giao dịch sinh một mã QR riêng, đã chứa sẵn số tiền và nội dung chuyển khoản duy nhất để hệ thống khớp đúng khoản tiền khách đã chuyển.
✅ Bước 1 – Bật cổng thanh toán VietQR
- Mở trang cấu hình nhà cung cấp thanh toán trong phân hệ Payment và chọn nhà cung cấp VietQR.
- Đặt trạng thái của nhà cung cấp sang Đã bật (enabled) (hoặc giữ Thử nghiệm — test khi đang kiểm thử).
- Lưu lại.
⚠️ Cổng VietQR chỉ áp dụng cho giao dịch bằng VND. Với loại tiền tệ khác, hệ thống sẽ không hiển thị VietQR trong danh sách phương thức thanh toán.
📷 Cần chèn ảnh:
/img/integrations/payment-vietqr/01.png— Biểu mẫu nhà cung cấp thanh toán VietQR với trạng thái Đã bật.
⚙️ Bước 2 – Cấu hình ngân hàng & tài khoản nhận tiền
Trên biểu mẫu nhà cung cấp VietQR, mở thẻ VietQR Configuration và khai báo theo các nhóm bên dưới rồi lưu lại.
Thông tin xác thực API (API Credentials)
| Trường | Ý nghĩa |
|---|---|
| VietQR Client ID | Client ID do VietQR / ngân hàng đối tác cấp. |
| VietQR API Key | Khóa API để xác thực khi gọi dịch vụ VietQR. |
⚠️ VietQR Client ID và VietQR API Key chỉ hiển thị với người dùng có quyền quản trị hệ thống. Không chia sẻ các giá trị này ra ngoài.
Tài khoản ngân hàng (Bank Account)
- Lần đầu cấu hình, nhấn nút Sync cạnh ô Bank để hệ thống tải về danh sách ngân hàng hỗ trợ VietQR (lưu vào danh mục ngân hàng VietQR –
vietqr.bank). - Chọn Bank từ danh sách; hệ thống tự điền Bank BIN tương ứng.
- Nhập Account Number và Account Holder Name.
| Trường | Ý nghĩa |
|---|---|
| Bank | Chọn ngân hàng từ danh sách VietQR. Nhấn Sync để tải danh sách ngân hàng mới nhất. |
| Bank BIN | Mã BIN của ngân hàng (tự lấy theo ngân hàng đã chọn, chỉ đọc). |
| Account Number | Số tài khoản ngân hàng nhận tiền. |
| Account Holder Name | Tên chủ tài khoản. Hệ thống tự chuyển sang chữ in hoa, bỏ dấu. |
📷 Cần chèn ảnh:
/img/integrations/payment-vietqr/02.png— Thẻ VietQR Configuration với nhóm Bank Account và nút Sync.
Thiết lập mã QR (QR Settings)
| Trường | Ý nghĩa |
|---|---|
| QR Template | Mẫu hiển thị của ảnh QR do dịch vụ trả về (Compact, Compact 2, QR Only, Print). |
| QR Expiry (minutes) | Số phút trước khi mã QR hết hạn. Đặt 0 nếu muốn mã không hết hạn. |
| Transfer Content Source | Cách tạo nội dung chuyển khoản: theo Tên khách hàng + nội dung thêm hoặc nội dung cố định. |
| Extra Transfer Content | Nội dung thêm vào sau tên khách hàng (khi chọn Tên khách hàng + nội dung thêm). |
| Fixed Transfer Content | Nội dung chuyển khoản cố định (khi chọn nội dung cố định). |
| Debug Mode | Ghi log chi tiết khi gọi dịch vụ VietQR. Không bật trên môi trường vận hành. |
⚠️ Giá trị QR Expiry (minutes) phải là 0 hoặc lớn hơn; nếu nhập số âm hệ thống sẽ báo lỗi.
💳 Bước 3 – Khách hàng thanh toán & đối soát
- Tại trang thanh toán, khách hàng chọn phương thức VietQR và quét mã QR động hiển thị nội tuyến.
- Khung thanh toán hiển thị ngân hàng, số tài khoản, tên chủ tài khoản, số tiền và nội dung chuyển khoản để khách đối chiếu.
- Sau khi khách chuyển khoản, giao dịch ở trạng thái Đang chờ (pending) cho tới khi được xác nhận.
- Giao dịch được liên kết với hóa đơn (account.move) theo mã tham chiếu, giúp kế toán đối soát khoản đã thu.
💡 Để theo dõi và xác nhận khoản đã thu, xem thêm Thanh toán (khách hàng).
📷 Cần chèn ảnh:
/img/integrations/payment-vietqr/03.png— Trang thanh toán hiển thị mã QR VietQR cùng thông tin ngân hàng và nội dung chuyển khoản.
Liên quan
- Cổng thanh toán trực tuyến — khung cấu hình chung
- Cổng thanh toán VNPay
- Thanh toán VietQR trên đơn bán
- Thanh toán (khách hàng)