Cổng Thanh Toán (Payment Gateways)¶
Trang Cổng Thanh Toán (/dashboard/financial/payment-gateways) quản lý tất cả cổng thanh toán tích hợp trong hệ thống. Từ đây có thể kích hoạt/tắt gateway, cấu hình thông tin API, xem webhook URL và kiểm tra kết nối thực tế.
Tổng Quan Trang¶
Header & Mô Tả¶
| # | Phần tử | Mô tả |
|---|---|---|
| ① | Tiêu đề | "Payment Gateway Management" |
| ② | Mô tả | Giải thích phạm vi quản lý và gợi ý chuyển đổi cấp độ (nếu có quyền) |
| ③ | Tab Payment Gateways | Tab duy nhất — danh sách tất cả cổng thanh toán |
Bộ Điều Khiển Cấp Độ (Chain/Platform Admin)¶
Chỉ hiển thị với người dùng có vai trò Chain Manager hoặc Platform Admin:
| # | Phần tử | Mô tả |
|---|---|---|
| ④ | Chọn cấp độ | Dropdown chọn cấp độ cấu hình: Hotel / Chain / Platform |
| ⑤ | Bulk Update | Cập nhật hàng loạt nhiều gateway cùng lúc |
| ⑥ | Alert thông tin | Mô tả phạm vi áp dụng của cấp độ đang chọn |
Card Cổng Thanh Toán¶
| # | Phần tử | Mô tả |
|---|---|---|
| ⑦ | Card gateway | Mỗi cổng thanh toán hiển thị dạng card riêng biệt |
| ⑧ | Tags trạng thái | Enabled/Disabled · Configured/Not Configured · Inherited (nếu kế thừa) |
| ⑨ | Tỷ lệ thành công | % giao dịch thành công (xanh nếu >95%, vàng nếu thấp hơn) |
| ⑩ | Doanh số tháng | Tổng giá trị giao dịch trong tháng (VND) |
| ⑪ | Cài đặt | Mở modal cấu hình API gateway |
| ⑫ | Webhook | Xem URL webhook được tự động tạo |
| ⑬ | Kiểm tra | Gửi giao dịch thử để kiểm tra kết nối (chỉ khi gateway Active + Configured) |
Cấp Độ Cấu Hình¶
Hệ thống hỗ trợ cấu hình gateway theo 3 cấp độ, theo thứ tự ưu tiên từ cao xuống thấp:
| Cấp độ | Icon | Màu | Ý nghĩa |
|---|---|---|---|
| PLATFORM | ⚡ | Tím | Cấu hình toàn nền tảng (chỉ Platform Admin) |
| CHAIN | 🌐 | Xanh dương | Cấu hình cho toàn chuỗi khách sạn |
| HOTEL | 🏠 | Xanh lá | Cấu hình riêng cho từng khách sạn |
| INHERITED | 🔀 | Cam | Kế thừa từ cấp cao hơn (không có cấu hình riêng) |
Kế thừa cấu hình
Gateway ở cấp HOTEL có thể kế thừa cấu hình từ CHAIN hoặc PLATFORM. Tag "Inherited from CHAIN" xuất hiện khi gateway không có cấu hình riêng ở cấp hiện tại.
Các Cổng Thanh Toán Được Hỗ Trợ¶
| Gateway | Màu đặc trưng |
|---|---|
| VNPAY | Xanh dương |
| MOMO | Hồng đậm |
| ONEPAY | Xanh lá |
| STRIPE | Tím |
| PAYPAL | Xanh đậm |
Cấu Hình Gateway¶
Nhấn icon Cài đặt (⚙) trên card để mở modal cấu hình. Modal rộng 800px.
| # | Phần tử | Mô tả |
|---|---|---|
| ① | Tiêu đề | "Configure {TÊN GATEWAY} Gateway - {CẤP ĐỘ} Level" |
| ② | Alert thông tin | Nhắc nhở về phạm vi áp dụng cấu hình (chỉ hiện nếu không phải HOTEL level) |
| ③ | Card Basic Configuration | Phần cấu hình cơ bản |
| ④ | Enable Gateway | Switch bật/tắt gateway |
| ⑤ | Environment | Môi trường: Sandbox (Testing) hoặc Production (Live) |
| ⑥ | Card API Configuration | Phần thông tin kết nối API |
| ⑦ | Merchant ID | Mã định danh merchant từ nhà cung cấp |
| ⑧ | API Key / Access Code | Khóa API hoặc Access Code (OnePay) |
| ⑨ | Secret Key | Khóa bí mật (ô nhập ẩn, có toggle hiện/ẩn) |
| ⑩ | Webhook URL | URL tự động tạo — read-only nếu đã có, có nút Copy |
| ⑪ | Hủy | Đóng modal, không lưu thay đổi |
| ⑫ | Lưu cấu hình | Lưu và áp dụng cấu hình gateway |
Tham Chiếu Các Trường Cấu Hình¶
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| Enable Gateway | — | Bật: gateway hoạt động và nhận thanh toán; Tắt: tạm dừng |
| Environment | — | Sandbox = môi trường thử nghiệm; Production = thực tế |
| Merchant ID | — | Mã merchant do nhà cung cấp cấp khi đăng ký |
| API Key | — | Khóa API để xác thực request (OnePay gọi là Access Code) |
| Secret Key | — | Khóa bí mật để ký/xác minh request — không chia sẻ |
| Webhook URL | — | URL hệ thống tự tạo để nhận callback từ gateway |
Webhook URL¶
Nhấn icon Webhook (🔗) trên card để xem URL webhook đã được hệ thống tự động tạo.
| # | Phần tử | Mô tả |
|---|---|---|
| ① | Tiêu đề | "{TÊN GATEWAY} Webhook Configuration" |
| ② | Card Webhook URL | Khung hiển thị URL |
| ③ | URL | Địa chỉ webhook (read-only) — dán vào cổng thanh toán |
| ④ | Copy | Sao chép URL vào clipboard |
| ⑤ | Đóng | Đóng modal |
Cách sử dụng Webhook URL
Sau khi copy, dán URL này vào phần cấu hình webhook trong trang quản trị của nhà cung cấp (VD: trang admin VNPAY, MoMo Business, Stripe Dashboard). Hệ thống sẽ tự động nhận thông báo kết quả thanh toán qua URL này.
Cập Nhật Hàng Loạt (Bulk Update)¶
Chỉ dành cho Chain Manager / Platform Admin
Nút Bulk Update chỉ hiển thị khi người dùng có quyền quản lý cấp Chain hoặc Platform.
Modal Bulk Update cho phép áp dụng cùng một cấu hình cho nhiều gateway cùng lúc:
| Trường | Mô tả |
|---|---|
| Chọn Gateways | Multi-select — chọn các gateway cần cập nhật |
| Environment | Đặt môi trường chung cho tất cả gateway đã chọn |
| Enable All Selected | Bật hoặc tắt đồng loạt tất cả gateway đã chọn |
Kiểm Tra Kết Nối (Test Gateway)¶
Nhấn icon Kiểm tra (🧪) trên card để gửi giao dịch thử tới cổng thanh toán.
Điều kiện để Test
Nút Test chỉ hoạt động khi gateway đồng thời thỏa mãn:
- isActive = true (đang bật)
- Đã cấu hình đầy đủ (có merchantId + apiKey + secretKey)
Nếu một trong hai điều kiện không đạt, nút bị disabled.
Mẹo & Thực Hành Tốt Nhất¶
Không dùng Production khi đang thử nghiệm
Luôn chọn Sandbox khi kiểm tra tích hợp. Chỉ chuyển sang Production sau khi đã xác nhận gateway hoạt động đúng trong môi trường Sandbox.
Bảo mật Secret Key
Secret Key không bao giờ được hiển thị lại sau khi lưu. Lưu trữ Secret Key ở nơi an toàn (password manager) trước khi nhập vào hệ thống. Nếu quên, phải tạo lại từ trang quản trị của nhà cung cấp.
Webhook tự động — không cần nhập thủ công
Webhook URL được hệ thống sinh tự động theo chuẩn bảo mật. Không thay đổi URL này — chỉ cần copy và cấu hình ở phía nhà cung cấp.
Kế thừa cấu hình giúp giảm lặp lại
Nếu tất cả khách sạn trong chuỗi dùng cùng một cổng thanh toán với cùng thông tin API, cấu hình ở cấp Chain một lần — tất cả khách sạn sẽ kế thừa tự động mà không cần cấu hình riêng.
Kiểm tra tỷ lệ thành công thường xuyên
Tỷ lệ thành công < 95% (màu vàng) là dấu hiệu cần điều tra: gateway đang ở Sandbox chưa chuyển Production, thông tin API sai, hoặc kết nối mạng không ổn định.
Câu Hỏi Thường Gặp¶
Hotel Manager có thể cấu hình cổng thanh toán không?
Có. Hotel Manager thấy tab Payment Gateways và có thể cấu hình các gateway ở cấp HOTEL. Tuy nhiên, Hotel Manager không thấy bộ chọn cấp độ (CHAIN/PLATFORM) và không có nút Bulk Update.
Gateway 'Not Configured' nhưng vẫn Active — có ảnh hưởng gì không?
Gateway Active nhưng Not Configured (thiếu merchantId/apiKey/secretKey) sẽ không xử lý được giao dịch thực tế. Nút Test cũng bị disabled. Cần cấu hình đầy đủ trước khi đưa vào sử dụng.
Tại sao nút Test bị disabled?
Nút Test bị disabled khi gateway ở trạng thái Disabled hoặc Not Configured. Phải bật gateway và điền đủ merchantId + apiKey + secretKey thì mới test được.
Bulk Update có ảnh hưởng đến cấu hình API riêng của từng gateway không?
Bulk Update chỉ cập nhật các trường được chọn trong form (Environment và Enable/Disable). Thông tin API riêng (merchantId, apiKey, secretKey) của từng gateway không bị thay đổi.
Webhook URL có thay đổi khi cập nhật cấu hình không?
Không. Webhook URL được tạo một lần và cố định theo gateway ID. Việc cập nhật merchantId/apiKey/secretKey không ảnh hưởng đến Webhook URL.
Liên Kết Liên Quan¶
- Thanh Toán — Giao dịch thanh toán sử dụng các gateway này
- Hóa Đơn — Hóa đơn liên kết với thanh toán
- Báo Cáo Tài Chính — Phân tích doanh thu theo kênh thanh toán