Appearance
Cổng thanh toán OnePay / VNPay
Trang này dành cho người quản trị và kế toán (finance): nối tài khoản merchant của tổ chức với hệ thống để khách trả tiền online cho khoá học, gói thuê bao, vé sự kiện và các sản phẩm khác.
Hệ thống hỗ trợ hai cổng của Việt Nam:
| Cổng | Khách trả bằng | Module cần bật |
|---|---|---|
| OnePay | Thẻ nội địa ATM, thẻ quốc tế | PaymentOnePay |
| VNPAY | QR code, thẻ nội địa ATM, thẻ quốc tế | PaymentVnPay |
Cả hai chỉ thu VND. Module do nhà cung cấp bật cho tổ chức, kèm module Thương mại điện tử; chưa bật thì cổng đó không có trong danh sách chọn.
Chuẩn bị
Trước khi vào hệ thống, lấy từ OnePay / VNPAY (email cấp tài khoản hoặc trang quản trị merchant):
- Bộ thông tin xác thực (bảng bên dưới).
- URL cổng thanh toán của môi trường bạn đang dùng — môi trường thử (sandbox) và môi trường thật có URL khác nhau.
Tạo cấu hình cổng
- Vào Thương mại điện tử → Cổng thanh toán → Tạo.
- Khối Thông tin chung:
| Ô | Ghi chú |
|---|---|
| Cổng | onepay hoặc vnpay. Không đổi được sau khi tạo — chọn sai thì xoá bản ghi và tạo lại |
| Tên hiển thị | Tên khách thấy ở mục Phương thức thanh toán trên trang thanh toán, ví dụ Thẻ ATM / Visa (OnePay). Để trống thì khách thấy mã cổng |
| Kích hoạt | Tắt sẵn. Chỉ bật khi đã điền đủ và đã có URL webhook trong merchant portal |
| Thứ tự | Số nhỏ đứng trước; cổng đứng đầu được chọn sẵn cho khách |
- Khối Thông tin xác thực và khối Cấu hình: mỗi dòng là một cặp Tên / Giá trị, bấm Thêm trường để thêm dòng. Tên phải gõ đúng y hệt bảng bên dưới (chữ thường, có gạch dưới) — gõ sai một ký tự là hệ thống không đọc được.
- Bấm Tạo. Trang chuyển sang màn sửa, lúc này mới có khối Webhook (xem bước sau).
Thông tin xác thực được mã hoá khi lưu.
OnePay
Thông tin xác thực
| Tên | Giá trị |
|---|---|
access_code | Access Code do OnePay cấp |
merchant_id | Merchant ID |
secure_secret | Secure Secret, dạng chuỗi hex — dán nguyên văn |
Cấu hình
| Tên | Bắt buộc | Giá trị |
|---|---|---|
vpc_url | Có | URL trang thanh toán của OnePay (sandbox hoặc thật). Thiếu dòng này khách không thanh toán được |
locale | Không | vn (mặc định) hoặc en — ngôn ngữ trang OnePay |
currency | Không | Mặc định VND |
ip_whitelist | Không | Xem Chỉ nhận thông báo từ IP của cổng |
description | Không | Một dòng mô tả hiện dưới Tên hiển thị trên trang thanh toán |
VNPAY
Thông tin xác thực
| Tên | Giá trị |
|---|---|
tmn_code | Mã terminal (TmnCode) |
hash_secret | Chuỗi bí mật (HashSecret) — dán nguyên văn |
Cấu hình
| Tên | Bắt buộc | Giá trị |
|---|---|---|
vnp_url | Có | URL trang thanh toán của VNPAY (sandbox hoặc thật). Thiếu dòng này khách không thanh toán được |
vnp_version | Không | Mặc định 2.1.0 |
locale | Không | vn (mặc định) hoặc en |
currency | Không | Mặc định VND |
order_type | Không | Mặc định other |
bank_code | Không | Để không khai thì khách tự chọn ngân hàng trên trang VNPAY (nên dùng). Khai mã ngân hàng thì khách bị đưa thẳng tới ngân hàng đó |
ip_whitelist | Không | Xem dưới |
description | Không | Dòng mô tả trên trang thanh toán |
Phiên thanh toán VNPAY hết hạn sau 15 phút kể từ khi khách được chuyển sang cổng.
Dòng không dùng thì xoá hẳn
Đừng để dòng có Tên mà Giá trị trống. Không khai dòng thì hệ thống dùng giá trị mặc định; khai dòng trống thì nó được hiểu là "giá trị rỗng".
Dán URL webhook vào merchant portal
Sau khi tạo, mở lại bản ghi: khối Webhook hiện URL webhook dạng
https://<tên-miền-của-bạn>/webhooks/payment/onepay
https://<tên-miền-của-bạn>/webhooks/payment/vnpaySao chép và dán vào ô URL nhận thông báo kết quả (IPN) trong trang quản trị merchant của cổng. Đây là đường chắc chắn nhất để đơn được ghi nhận: cổng gọi thẳng về đây, hệ thống kiểm chữ ký rồi mới ghi nhận. Khi khách quay về website sau khi trả, hệ thống cũng kiểm chữ ký và ghi nhận theo đường đó; nhưng khách có thể đóng trình duyệt trước khi quay về, nên đừng bỏ qua webhook.
Đường đưa khách quay lại sau khi trả (return URL) thì hệ thống tự gửi kèm mỗi giao dịch, bạn không cần khai. Với OnePay, form gợi ý dán cùng URL webhook vào cả ô return lẫn ô IPN nếu merchant portal đòi cả hai.
Dùng đúng tên miền khách thấy
URL webhook lấy theo tên miền bạn đang mở trang quản trị. Mở bằng tên miền chính của tổ chức trước khi sao chép.
Chỉ nhận thông báo từ IP của cổng
Tuỳ chọn, cho cả hai cổng. Thêm dòng ip_whitelist vào khối Cấu hình, giá trị là danh sách địa chỉ IP do cổng công bố, ngăn bằng dấu phẩy, chấm phẩy hoặc khoảng trắng. Từ đó, thông báo gọi về webhook từ IP ngoài danh sách bị từ chối.
Chỉ áp cho đường webhook — trình duyệt của khách quay về không bị chặn. Không khai dòng này = không lọc. Khai sai IP thì mọi thông báo thật bị từ chối và đơn không bao giờ lên Đã thanh toán — kiểm bằng một giao dịch thử ngay sau khi thêm.
Chuyển từ thử sang thật
- Làm toàn bộ với bộ khoá và URL sandbox của cổng. Bật Kích hoạt.
- Mua thử một sản phẩm giá nhỏ bằng thẻ thử của cổng. Kiểm:
- Thương mại điện tử → Giao dịch có dòng Thành công;
- đơn ở Đơn hàng lên Đã giao;
- tài khoản mua đã có thứ vừa mua (ví dụ khoá trong Khoá học của tôi).
- Thay thông tin xác thực và URL (
vpc_url/vnp_url) bằng bộ của môi trường thật. URL webhook giữ nguyên — nhưng phải dán lại vào merchant portal của môi trường thật. - Mua thật một đơn nhỏ để xác nhận lần cuối.
Kiểm luồng ghi danh mà không cần cổng: tạo một voucher giảm 100% — đơn 0đ đi thẳng tới bàn giao, không qua cổng nào. Cách này không kiểm được cổng.
Tắt hoặc thay cổng
Tắt "Kích hoạt" là ngừng nhận cả thông báo của giao dịch đang dở
Cổng bị tắt Kích hoạt thì biến khỏi trang thanh toán, và hệ thống từ chối thông báo cổng gửi về cho cổng đó — kể cả của khách đã bị trừ tiền vài phút trước. Tắt vào lúc vắng khách, rồi mở Giao dịch kiểm không còn dòng nào đang chờ của cổng đó.
Đổi sang tài khoản merchant khác: sửa thông tin xác thực trên chính bản ghi cũ, đừng tạo bản ghi thứ hai cho cùng một cổng.
Lỗi thường gặp
| Hiện tượng | Nguyên nhân thường gặp |
|---|---|
| Trang thanh toán báo "Tenant này chưa kích hoạt cổng thanh toán nào." | Chưa bản ghi cổng nào bật Kích hoạt |
| Khách bấm thanh toán thì lỗi, không sang được trang cổng | Thiếu vpc_url / vnp_url, thiếu secure_secret, hoặc tên dòng gõ sai |
| Khách trả xong, quay về thấy "Cổng thanh toán hiện không khả dụng…" | Cổng vừa bị tắt Kích hoạt, hoặc thông tin xác thực hỏng (dòng dưới) |
| Khách bị trừ tiền nhưng đơn vẫn Chờ thanh toán | Xảy ra khi khách không quay về website và webhook không tới: URL webhook chưa dán (hoặc dán ở môi trường khác) trong merchant portal; ip_whitelist sai; hoặc khoá bí mật không khớp nên chữ ký bị từ chối. Kiểm Các lần thanh toán trên trang chi tiết đơn |
| Mở bản ghi cổng thấy thông báo "Không đọc được thông tin xác thực đã lưu", các ô trống | Thông tin xác thực được mã hoá bằng một khoá khác của hệ thống (thường sau khi chuyển máy chủ hoặc khôi phục dữ liệu). Nhập lại toàn bộ từ merchant portal rồi lưu. Trước khi làm, cổng này không xử lý được giao dịch |
Hệ thống có cảnh báo vận hành cho các tình huống thanh toán: giao dịch treo, thanh toán thất bại, thông báo gọi về bị từ chối liên tục, tỉ lệ lỗi của một cổng tăng đột biến. Nên đặt luật gửi chúng tới người trực — xem Cảnh báo vận hành. Báo cáo Cổng thanh toán: thành công / thất bại ở Trung tâm báo cáo cho thấy tỉ lệ lỗi theo từng cổng (Đơn hàng → Doanh thu).
Đừng dùng cổng "fake"
Danh sách Cổng còn có một mục fake — cổng giả lập dành cho môi trường phát triển. Không bao giờ tạo hoặc bật cổng này trên hệ thống thật: khi nó đang bật, bất kỳ ai cũng tự "duyệt" được đơn của mình mà không trả đồng nào.
Ai làm được gì
Quyền *_payment_gateway_config: mặc định chỉ Kế toán (finance) và Quản trị (admin). Vai trò khác cần quyền này mới thấy menu Cổng thanh toán. Xem Vai trò và phân quyền.