Webhook

Bảo mật & Chữ ký

Khi Baokim gọi webhook về phía Merchant, Baokim cũng ký dữ liệu request body bằng SHA256withRSA và gửi chữ ký trong header Signature. Merchant nên verify chữ ký này bằng public key của Baokim trước khi xử lý dữ liệu, tương tự như cách Baokim verify request từ Merchant.

Điều kiện thành công

Baokim coi webhook đã được gửi thành công khi nhận được response từ Merchant với:

• HTTP status code: 200
• Thời gian phản hồi trong giới hạn timeout cho phép

Merchant cần trả về body xác nhận đã nhận thông báo. Giá trị code khác nhau theo từng nhóm API:

Nhóm API	Body xác nhận	Ghi chú
VA (Direct), Master Merchant Basic/Pro	{ "code": 0, "message": "Success" }	code = 0 — đã xác nhận trong tài liệu gốc
BNPL, Installment, Thẻ quốc tế (Direct & Master), Master VA, Master Thẻ tín dụng	{ "code": 0, "message": "Success" }	⚠️ Tài liệu gốc không nêu rõ giá trị ACK — tạm suy luận theo nhóm VA, cần dev xác nhận trước khi đưa vào production
QRPay/QRGlobal	{ "code": 100, "message": "Success" }	code = 100 — đã xác nhận trong tài liệu gốc

⚠️ Lưu ý: Nếu Merchant tích hợp QRPay/QRGlobal mà trả về code = 0, Baokim sẽ không ghi nhận thành công và sẽ tiếp tục retry.

⚠️ Deeplink chưa có cơ chế Webhook được tài liệu hóa. Tài liệu gốc chỉ mô tả "Baokim thông báo kết quả cho Đối tác" mà không có URL, method, header hay cấu trúc field cụ thể, và không nêu giá trị ACK code. Không áp dụng quy ước code = 0 của nhóm B2B cho tới khi dev xác nhận và bổ sung tài liệu.

Thử lại & Hết thời gian chờ

Nếu webhook gọi thất bại (timeout hoặc HTTP status != 200), Baokim sẽ retry theo cơ chế backoff. Merchant cần đảm bảo webhook endpoint:

• Có thể xử lý và phản hồi nhanh (tránh xử lý nặng đồng bộ trong webhook handler).
• Xử lý được trường hợp nhận trùng webhook (idempotent) — dùng request_id để dedup.

Cơ chế retry theo từng nhóm API:

Nhóm API	Cơ chế retry	Số lần tối đa	Timeout
VA (Direct), Master Merchant Basic/Pro	Backoff	10 lần	30 giây
QRPay/QRGlobal	Fibonacci: 1 - 2 - 3 - 5 - 8 phút	5 lần	30 giây

⚠️ Cơ chế retry của BNPL, Installment, Thẻ quốc tế, Master VA, Master Thẻ tín dụng, Deeplink chưa được xác nhận trong tài liệu gốc — bảng trên chỉ áp dụng tạm cho VA/Master Basic-Pro (backoff 10 lần) và QRPay (Fibonacci), cần dev confirm trước khi đưa vào production cho các nhóm còn lại.

Các Header chung

Mỗi webhook request từ Baokim đến Merchant đều có các header sau:

Header	Mô tả
Content-Type	application/json
Signature	Chữ ký số SHA256withRSA của Baokim trên request body

Trong body webhook thường có các trường dùng để định danh sự kiện:

Trường	Mô tả
request_id	ID duy nhất của webhook request
request_time	Thời gian Baokim gửi webhook
merchant_code / master_merchant_code	Định danh Merchant
operation	Loại sự kiện: PAYMENT, REFUND, AUTHENTICATION, QR_PAYMENT_TRANS, QR_REFUND_TRANS, v.v.