💳 Cổng thanh toán trực tuyến
Cổng thanh toán trực tuyến (nhà cung cấp thanh toán — payment.provider) là khung chung trong phân hệ Payment của Xbook, cho phép khách hàng trả tiền online ngay trong trang thanh toán. Mỗi lần thanh toán, hệ thống tạo một giao dịch thanh toán (payment.transaction) và theo dõi trạng thái của khoản tiền đó. Đây cũng là nền tảng để bật và cấu hình các cổng dành riêng cho Việt Nam như VietQR và VNPay.
💡 Trang này mô tả khung Nhà cung cấp thanh toán dùng chung. Cách khai báo thông tin xác thực cho từng cổng cụ thể được trình bày ở trang riêng của cổng đó (xem mục Liên quan).
🧩 Nhà cung cấp thanh toán là gì
Mỗi nhà cung cấp thanh toán là một bản ghi đại diện cho một cổng (ví dụ VietQR, VNPay). Nhà cung cấp giữ các thông tin: tên (Name), phương thức thanh toán được hỗ trợ (Payment Methods), thông tin xác thực với cổng, các điều kiện khả dụng (quốc gia, loại tiền, số tiền tối đa) và các thông điệp hiển thị cho khách trong quá trình thanh toán.
Khi khách thực hiện thanh toán, hệ thống chỉ chọn ra những nhà cung cấp đang hoạt động (trạng thái Đã bật hoặc Thử nghiệm), phù hợp với quốc gia của khách, loại tiền và số tiền của giao dịch.
📂 Vào trang cấu hình nhà cung cấp
Mở Invoicing → Cấu hình (Configuration) → Online Payments → Payment Providers.
Tại đây bạn thấy danh sách các nhà cung cấp dưới dạng thẻ Kanban. Màu thẻ phản ánh trạng thái của nhà cung cấp:
- Vàng — đang Vô hiệu (Disabled).
- Cam — đang ở chế độ Thử nghiệm (Test Mode).
- Xanh lá — đã Bật (Enabled) để chạy thật.
📷 Cần chèn ảnh:
/img/integrations/payment-providers/01.png— Danh sách Kanban các nhà cung cấp thanh toán với màu thẻ theo trạng thái.
🔘 Trạng thái của một cổng thanh toán
Trường State của nhà cung cấp có ba trạng thái:
| Trường | Ý nghĩa |
|---|---|
| Vô hiệu (Disabled) | Cổng không hoạt động và không xuất hiện trong các phương thức thanh toán của khách. Đây là trạng thái mặc định. |
| Thử nghiệm (Test Mode) | Khoản thanh toán được xử lý qua giao diện thử nghiệm (giao dịch giả lập). Nên dùng trạng thái này khi đang thiết lập và kiểm thử cổng. |
| Đã bật (Enabled) | Cổng chạy ở môi trường thật và sẵn sàng nhận thanh toán của khách. |
⚠️ Khi chuyển một cổng từ Thử nghiệm/Đã bật sang Vô hiệu (hoặc đổi qua lại giữa Thử nghiệm và Đã bật), hệ thống sẽ lưu trữ (archive) các token thanh toán đã đăng ký với cổng đó. Hệ thống hiển thị cảnh báo số lượng token bị ảnh hưởng trước khi bạn lưu.
💡 Khi đặt trạng thái sang Đã bật, cổng tự động được xuất bản (Published) để hiển thị trên website; khi Vô hiệu, cổng được gỡ xuất bản. Bạn không thể xuất bản một cổng đang ở trạng thái Vô hiệu.
⚙️ Bật và cấu hình một cổng
- Vào Invoicing → Cấu hình → Online Payments → Payment Providers và mở thẻ của cổng cần dùng.
- Tại nhóm thông tin trạng thái, chọn State là Thử nghiệm (Test Mode) khi kiểm thử, hoặc Đã bật (Enabled) khi chạy thật.
- Mở thẻ Credentials để nhập thông tin xác thực do cổng cung cấp (mỗi cổng có các trường riêng — xem trang của cổng tương ứng).
- Mở thẻ Configuration để xem các phương thức thanh toán và đặt các điều kiện khả dụng (xem các phần bên dưới).
- Lưu lại bản ghi.
⚠️ Một số trường bắt buộc tùy theo cổng. Nếu để trống các trường bắt buộc khi đặt trạng thái Thử nghiệm hoặc Đã bật, hệ thống sẽ báo lỗi và liệt kê các trường cần điền.
📷 Cần chèn ảnh:
/img/integrations/payment-providers/02.png— Biểu mẫu nhà cung cấp thanh toán với trường State và các thẻ Credentials, Configuration.
Phương thức thanh toán
Trong thẻ Configuration, nhóm Payment Form, trường Payment Methods liệt kê các phương thức thanh toán mà cổng hỗ trợ. Trường này chỉ để xem — bạn không gõ trực tiếp vào đây. Để bật hoặc tắt từng phương thức, bấm liên kết Enable Payment Methods ngay bên dưới để mở danh sách phương thức thanh toán. Một phương thức thanh toán (ví dụ thẻ, ví, QR...) chỉ khả dụng với khách khi nó thuộc một cổng đang hoạt động. Khi mọi cổng chứa một phương thức đều bị Vô hiệu, phương thức đó cũng được ngừng kích hoạt.
Điều kiện khả dụng
Cũng trong thẻ Configuration, nhóm Availability giúp giới hạn phạm vi áp dụng của cổng:
| Trường | Ý nghĩa |
|---|---|
| Maximum Amount | Số tiền tối đa mà cổng được áp dụng. Để trống nếu không giới hạn. |
| Currencies | Các loại tiền mà cổng chấp nhận. Để trống nếu không giới hạn. |
| Countries | Các quốc gia mà cổng khả dụng. Để trống để áp dụng cho mọi quốc gia. |
Thông điệp hiển thị cho khách
Thẻ Messages cho phép tùy biến các thông điệp hiển thị cho khách trong từng tình huống thanh toán: Help Message (hướng dẫn), Pending Message (chờ duyệt), Authorize Message (đã ủy quyền), Done Message (đã hoàn tất) và Cancelled Message (đã hủy).
🔄 Giao dịch thanh toán
Mỗi lần khách thanh toán, hệ thống tạo một bản ghi giao dịch thanh toán (payment.transaction) lưu lại mã tham chiếu (Reference), số tiền (Amount), nhà cung cấp (Provider), phương thức thanh toán và trạng thái của khoản tiền.
Trường Status của giao dịch có các trạng thái sau:
| Trường | Ý nghĩa |
|---|---|
| Draft (Nháp) | Giao dịch vừa được khởi tạo, chưa gửi tới cổng. |
| Pending (Đang chờ) | Đã gửi tới cổng và đang chờ xác nhận thanh toán. |
| Authorized (Đã ủy quyền) | Khoản tiền đã được ủy quyền nhưng chưa thu (áp dụng khi cổng cho phép thu tiền thủ công). |
Confirmed (Đã xác nhận — done) | Giao dịch thành công, khoản tiền đã được thu. |
Canceled (Đã hủy — cancel) | Giao dịch bị hủy. |
| Error (Lỗi) | Giao dịch gặp lỗi trong quá trình xử lý. |
💡 Bạn xem danh sách giao dịch ở Invoicing → Cấu hình → Online Payments → Payment Transactions (menu này chỉ hiển thị ở chế độ nhà phát triển).
Thao tác trên một giao dịch
Trên biểu mẫu giao dịch, tùy trạng thái mà các nút sau xuất hiện:
- Capture Transaction — thu tiền cho giao dịch đang ở trạng thái Authorized (chỉ hiện khi
state = authorized). - Void Transaction — hủy bỏ một giao dịch Authorized (có xác nhận trước khi thực hiện vì không thể hoàn tác).
- Nút Refunds ở khung thống kê dẫn tới các giao dịch hoàn tiền liên quan (chỉ hoàn tiền được cho giao dịch ở trạng thái Confirmed).
⚠️ Chỉ giao dịch ở trạng thái Authorized mới có thể thu (Capture) hoặc hủy (Void); chỉ giao dịch ở trạng thái Confirmed mới có thể hoàn tiền (Refund).
📷 Cần chèn ảnh:
/img/integrations/payment-providers/03.png— Biểu mẫu giao dịch thanh toán với thanh trạng thái và các nút thao tác.