Tạo webhook

Bước 1: Truy cập menu Webhooks.

Bước 2: Chọn + Thêm webhook ở góc trên bên phải.

Bước 3: Điền form 4 bước:

• Bước 1: Thông tin cơ bản. Đặt tên, chọn sự kiện Có tiền vào, Có tiền ra hoặc Cả hai, nhập URL nhận webhook.
• Bước 2: Tài khoản và bộ lọc. Chọn tài khoản ngân hàng được áp dụng. Có thể lọc theo tài khoản ảo (VA) hoặc theo tiền tố mã thanh toán.
• Bước 3: Bảo mật. Chọn phương thức xác thực: HMAC-SHA256, API Key, OAuth 2.0, hoặc không xác thực.
• Bước 4: Cảnh báo. Cấu hình kênh nhận thông báo khi webhook lỗi.

Bước 4: Nhấn Thêm để hoàn tất.

Dữ liệu gửi qua webhook

SePay gửi HTTP POST với body JSON như sau:

{
    "id": 92704,
    "gateway": "Vietcombank",
    "transactionDate": "2024-07-02 11:08:33",
    "accountNumber": "1017588888",
    "subAccount": "",
    "code": "SEVN63DC8E5C",
    "content": "SEVN63DC8E5C chuyen tien",
    "transferType": "in",
    "description": "NGUYEN VAN A chuyen tien",
    "transferAmount": 5000000,
    "accumulated": 105000000,
    "referenceCode": "FT24012345678"
}

Mô tả các trường, phân biệt null và chuỗi rỗng, ví dụ payload đầy đủ: xem Tích hợp webhook.

Phản hồi hợp lệ

SePay tính là thành công khi endpoint của bạn trả về:

• HTTP status 200 hoặc 201
• Body JSON có {"success": true}
• Hoàn tất trong 30 giây

Sai một trong ba điều kiện trên là tính thất bại và sẽ vào hàng đợi retry.

Xác thực

SePay hỗ trợ 4 phương thức xác thực: HMAC-SHA256, API Key, OAuth 2.0, không xác thực. So sánh và code mẫu PHP / Node.js / Python: xem Xác thực webhook.

Danh sách IP

Chống trùng lặp giao dịch

Cùng một giao dịch có thể nhận được webhook nhiều lần do retry tự động, gửi lại thủ công, hoặc nhiều webhook trỏ về cùng endpoint. Cần kiểm tra trùng dựa trên trường id trước khi xử lý.

Cách an toàn là đặt cột transaction_id là UNIQUE trong DB rồi dùng INSERT IGNORE. Code mẫu PHP và Node.js: xem Tích hợp webhook.

Retry tự động

Khi endpoint trả lỗi, SePay tự gọi lại theo lịch riêng. Thời gian giữa các lần gọi tăng theo dãy Fibonacci.

• Tối đa 7 lần
• Tối đa 5 giờ kể từ lần đầu thất bại
• Connect timeout: 5 giây
• Response timeout: 30 giây

Lịch retry chi tiết và cách chẩn đoán khi webhook không gửi: xem Xử lý lỗi.

Kiểm tra hoạt động

Cách 1: Trên trang chi tiết webhook, dùng tính năng Gửi thử để bắn payload mẫu sang URL của bạn mà không cần phát sinh giao dịch thật.

Cách 2: Chuyển một khoản nhỏ vào tài khoản đã cấu hình để tạo giao dịch thật, sau đó vào Nhật ký webhooks để xem các lần đã gửi.

Code mẫu

• PHP 8 + PDO + MySQL
• Node.js (Express) + mysql2
• Laravel: package sepayvn/laravel-sepay