Webhook kết quả thanh toán thẻ
✧ Mở bằng AI
ePay gửi IPN về Pay2S. Pay2S kiểm tra chữ ký và truy vấn kết quả phía ePay trước khi ghi nhận thành công. Worker webhook Pay2S gửi kết quả về webhookUrl đã ký khi tạo phiên.
Webhook giữ chuẩn hiện tại: resultCode=0 là thành công; resultCode=2 là hủy đã xác minh. Các trạng thái pending, failed, review tra cứu qua API; bộ này không thêm loại webhook thất bại riêng.
Kiểm tra chữ ký
Dùng secret tương ứng với accessKey tài khoản/cửa hàng đã tạo đơn. Chuỗi HMAC SHA256 nối theo đúng thứ tự dưới đây, dạng key=value, ngăn cách bằng &, không URL-encode:
accessKey,amount,extraData,message,orderId,orderInfo,orderType,partnerCode,payType,requestId,responseTime,resultCode,transId
So sánh kết quả hex với m2signature bằng phép so sánh chống timing attack. Giữ nguyên giá trị nhận được, kể cả chuỗi rỗng extraData. requestId trong webhook là ID nội bộ của đơn; requestTrace là mã tham chiếu, không thuộc chuỗi ký này.
import crypto from 'node:crypto';
const fields = ['accessKey','amount','extraData','message','orderId','orderInfo',
'orderType','partnerCode','payType','requestId','responseTime','resultCode','transId'];
const canonical = fields.map(k => k + '=' + payload[k]).join('&');
const expected = crypto.createHmac('sha256', secretKey).update(canonical).digest('hex');
const valid = /^[a-f0-9]{64}$/.test(payload.m2signature || '') &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(payload.m2signature));
Kiểm tra các trường bắt buộc, partnerCode, accessKey, mã đơn, số tiền và môi trường giao dịch trước khi hoàn tất đơn. Ví dụ đầy đủ có trong backend mẫu.
Tiếp nhận và gửi lại
Lưu bền vững trước khi trả HTTP 200. Webhook có thể được gửi nhiều lần. Dùng giao dịch database và khóa đơn để việc giao hàng chỉ chạy một lần. Không coi chữ ký hợp lệ là đủ nếu số tiền hoặc chủ sở hữu đơn không khớp.
Sandbox không dùng để giao hàng thật. Webhook chuẩn hiện tại không có trường môi trường trong chuỗi ký; xác định môi trường theo kết nối/đơn đã lưu và API trạng thái.
Trong Playground, bảng webhook chỉ hiển thị các thông báo đã xác minh chữ ký và khớp số tiền/mã đơn của phiên trình duyệt. Không nhận được webhook ngay vẫn có thể tra cứu API trạng thái; không tự tạo giao dịch mới.