Cấu hình webhook và API key SePay để nhận thanh toán

Bài này hướng dẫn từng bước lấy các thông tin cấu hình từ SePay để tích hợp thanh toán chuyển khoản vào backend: sinh mã QR tĩnh (VietQR) và nhận webhook mỗi khi có tiền vào tài khoản. Kết quả cuối cùng là 4 biến môi trường trong file .env.

Trong toàn bài, thay <bank-account-number>, <account-holder>, <api-key> bằng giá trị thật của bạn; https://api.example.com/webhooks/sepay là URL webhook ví dụ của backend, <ngrok-url> là địa chỉ tunnel khi chạy local.

Tóm tắt nhanh

Ứng dụng cần 4 biến môi trường sau để hoạt động:

SEPAY_BANK_NAME="MBBank"                        # Hoặc tên viết tắt ngân hàng khác (VD: Vietcombank, ACB)
SEPAY_ACCOUNT_NUMBER="<bank-account-number>"    # Số tài khoản
SEPAY_ACCOUNT_NAME="<account-holder>"           # Tên tài khoản
SEPAY_WEBHOOK_API_KEY="<api-key>"               # Tạo trong phần Tích hợp Webhook => Kiểu chứng thực: API Key

1. Thêm tài khoản ngân hàng

Thông tin này dùng để sinh mã QR hoặc đối soát giao dịch ngân hàng.

1. Đăng nhập SePay.
2. Vào menu Tài khoản ngân hàng, bấm Thêm tài khoản ngân hàng.
3. Điền ngân hàng và số tài khoản. Hệ thống thường tự động kiểm tra tên tài khoản.
4. Lấy thông tin điền vào .env:
   • SEPAY_BANK_NAME: dùng tên viết tắt hoặc mã BIN của ngân hàng (VD: MBBank, Vietcombank, Techcombank).
   • SEPAY_ACCOUNT_NUMBER: số tài khoản của bạn.
   • SEPAY_ACCOUNT_NAME: tên hiển thị trên tài khoản.

2. Cấu hình webhook và lấy API key

Webhook giúp SePay "bắn" thông báo về server của bạn mỗi khi có người chuyển khoản thành công. Chuỗi chứng thực tạo ở bước này chính là biến SEPAY_WEBHOOK_API_KEY.

1. Vào menu Tích hợp Webhook, bấm Thêm Webhook.
2. Cấu hình các mục như sau:
   • Tên: đặt tùy ý (VD: MyApp Webhook).
   • (1) Chọn sự kiện: ở mục "Bắn WebHooks khi", chọn Có tiền vào.
   • (2) Chọn điều kiện:
     • Chọn tài khoản ngân hàng đã thêm ở bước 1.
     • Ở mục "Bỏ qua nếu nội dung giao dịch không có Code?", chọn Không (server sẽ tự bóc tách).
   • (3) Thuộc tính WebHooks:
     • Gọi đến URL: đường dẫn webhook của backend (VD: https://<ngrok-url>/webhooks/sepay khi chạy local, hoặc https://api.example.com/webhooks/sepay trên production).
     • Là WebHooks xác thực thanh toán?: chọn Không.
     • Gọi lại WebHooks khi?: tích chọn HTTP Status Code không nằm trong phạm vi từ 200 đến 299 (để SePay retry nếu server bị lỗi tạm thời).
   • (4) Cấu hình chứng thực WebHooks (BẮT BUỘC):
     • Kiểu chứng thực: chọn API Key (hoặc Bearer Token).
     • Giá trị: một chuỗi mật khẩu sinh ngẫu nhiên, hoặc bạn tự chọn. Bạn sẽ copy chuỗi này vào .env.
     • Request Content type: application/json.
   • Trạng thái: Kích hoạt.
3. Bấm Thêm / Lưu.
4. Copy chuỗi giá trị ở mục (4), dán vào biến SEPAY_WEBHOOK_API_KEY trong file .env.

Vì sao không cần SEPAY_API_TOKEN?

Với mô hình tạo QR tĩnh (VietQR) và nhận kết quả thanh toán từ SePay qua webhook, bạn không cần đến API key để gọi ngược lên hệ thống SePay (SEPAY_API_TOKEN). Mã QR tự sinh được từ các thông tin gốc (số tài khoản, ngân hàng, tên người nhận, số tiền), còn SEPAY_WEBHOOK_API_KEY dùng để kiểm tra auth khi SePay gửi webhook đến server của bạn - như vậy là đủ bảo mật.

Xử lý sự cố