BeePay Docs

Chế độ tối

Webhook hoạt động như thế nào ​

Flow end-to-end ​

Khách chuyển khoản
      ↓
Ngân hàng gửi SMS / Push / Email
      ↓
BeePay nhận qua: Android app | IMAP | iOS Shortcut
      ↓
Parser trích xuất: amount, account, description, sender
      ↓
Match order_id từ description (dùng payment_prefix của bạn)
      ↓
POST webhook đến endpoint của bạn
      ↓
Bạn trả 200 OK → BeePay đánh dấu success
   Nếu ≠ 200 → Retry sau 1, 5, 30 phút

Parser ​

BeePay parse 50+ định dạng SMS/notification từ:

  • Banking push: MB, VCB, Techcombank, ACB, BIDV, VPBank, MSB, TPBank
  • SMS ngân hàng: tất cả ngân hàng VN có SMS biến động số dư
  • Email: ACB (lichsubank), VCB iBanking notification

Parser extract: amount, balance_after, account_number, transaction_date, ref, description, sender_name.

Match order_id ​

BeePay tìm order_id trong description theo payment_prefix của bạn.

Ví dụ: prefix = BEEPAY → parser sẽ tìm regex \bBEEPAY\d{3,10}\b trong nội dung chuyển khoản.

Nội dung khách ghi BEEPAY42 → order_id = BEEPAY42.

👉 Chi tiết về order_id

Payload webhook ​

Headers:

X-Webhook-Signature: sha256=<HMAC>
X-Webhook-Source: beepay

Body (payload_format: standard):

json
{
  "event": "bank_transaction",
  "bank_code": "MB",
  "bank_name": "MB Bank",
  "transaction_type": "credit",
  "amount": "500000.00",
  "currency": "VND",
  "account_number": "008000888",
  "transaction_ref": "FT26111330819043",
  "transaction_date": "2026-04-21T09:30:15.000Z",
  "description": "BEEPAY42 thanh toan don hang 42",
  "counterpart_name": "NGUYEN VAN A",
  "order_id": "BEEPAY42",
  "transaction_id": 12345,
  "timestamp": 1745227515
}

Các field có thể tuỳ biến trong Dashboard → Admin → Webhook Config (admin).

Trả về gì từ endpoint? ​

  • 200 OK — webhook thành công, BeePay đánh dấu success, không retry
  • 409 Conflict (tuỳ chọn) — đơn đã xử lý rồi, BeePay không retry
  • 5xx / timeout > 10s — BeePay retry theo lịch: 1 phút → 5 phút → 30 phút → 2h → 6h → 24h, tối đa 6 lần

Sau retry cuối cùng thất bại, webhook ở trạng thái failed — admin có thể retry thủ công trong Dashboard.

Bảo mật ​

  • Xác thực HMAC signature — bắt buộc production
  • IP whitelist: webhook gửi từ IP BeePay production
  • HTTPS only (http endpoint bị BeePay refuse)