VISORA AI V5.3 — SePay Bank Webhook + VietQR Mục tiêu Bản V5.3 chuyển SePay từ luồng Payment Gateway IPN cũ sang đúng SePay Webhook giao dịch ngân hàng có trong my.sepay.vn, dùng HMAC-SHA256 như giao diện cấu hình của SePay.
Luồng thanh toán gói: 1.
Khách hàng chọn gói tại /billing. 2.
VISORA tạo mã thanh toán duy nhất và hiển thị VietQR với đúng tài khoản, số tiền, nội dung. 3.
Khách quét QR và chuyển khoản. 4.
SePay gửi giao dịch tiền vào đến endpoint VISORA. 5.
VISORA xác minh HMAC trên raw body, kiểm tra timestamp, tài khoản nhận, mã thanh toán và số tiền. 6.
Giao dịch hợp lệ được xử lý idempotent, tự kích hoạt/gia hạn gói đúng một lần. 7.
Trang thanh toán tự cập nhật trạng thái và email xác nhận được gửi cho Owner/Admin/contact email của doanh nghiệp nếu SMTP hệ thống đã bật.
URL cấu hình trên SePay Khuyến nghị dùng: https://YOUR-DOMAIN/api/sepay-webhook.html Alias tương thích: https://YOUR-DOMAIN/webhooks/sepay Mở URL bằng trình duyệt (GET) sẽ trả JSON chẩn đoán để kiểm tra route/config.
SePay phải gửi POST đến cùng URL để nhận giao dịch.
Cấu hình trên my.sepay.vn Tạo Webhook: Tên: VISORA URL nhận webhook: https://YOUR-DOMAIN/api/sepay-webhook.html Loại giao dịch: Tiền vào Định dạng dữ liệu: JSON / application/json Tài khoản: chọn đúng tài khoản nhận tiền đã cấu hình trong VISORA Phương thức xác thực: HMAC-SHA256 Secret Key: copy ngay khi SePay tạo và dán vào VISORA → Super Admin → Thanh toán & Gói Nên bật gửi lại khi server trả lỗi Cấu hình trong VISORA Vào /admin/billing: Bật SePay Chọn Test/Production Nhập HMAC-SHA256 Secret Key Nhập mã ngân hàng VietQR Nhập tên ngân hàng, chủ tài khoản, số tài khoản nhận tiền Chọn tiền tố mã thanh toán, mặc định VSR Lưu cấu hình Nếu SePay có cấu hình cấu trúc mã thanh toán, nên dùng cùng tiền tố VSR để trường code được nhận diện; VISORA vẫn có cơ chế dự phòng tìm mã trong content giao dịch.
Database Migration mới: 008_sepay_bank_webhook_qr.php.
Bảng sepay_bank_transactions lưu giao dịch nhận từ webhook gồm SePay ID, ngân hàng, tài khoản, mã thanh toán, số tiền, trạng thái đối soát, raw body và hash để debug/audit. event_id có UNIQUE index để chống xử lý trùng khi SePay retry/replay.
Auto Schema Repair V5.3 cũng biết bảng/index mới nên database cũ thiếu thành phần sẽ được tự bổ sung.
Bảo mật HMAC ký trên chuỗi {timestamp}.{raw_body}.
Kiểm tra X-SePay-Signature và X-SePay-Timestamp.
Từ chối request lệch thời gian quá 5 phút.
Không parse rồi stringify lại trước khi kiểm tra chữ ký.
Chỉ xử lý transferType=in.
Đối chiếu chính xác tài khoản nhận + mã đơn + số tiền.
Chống trùng ở cả transaction SePay ID và payment state.
HMAC Secret được lưu mã hóa trong platform_settings.
Kiểm tra nhanh 1.
Mở /api/sepay-webhook.html và xác nhận ok=true, configured=true. 2.
Trong SePay, dùng chức năng Gửi thử webhook.
VISORA phải trả HTTP 200 + {"success": true}. 3.
Tạo một thanh toán gói từ /billing. 4.
Quét QR và chuyển đúng số tiền/nội dung. 5.
Trang QR sẽ tự chuyển trạng thái thành Đã thanh toán; gói trong organization_subscriptions và organizations được cập nhật tự động. 6.
Xem log tại Super Admin → Thanh toán & Gói → Log SePay Webhook gần đây.