Bank Hub Webhook Events

Bank Hub sử dụng webhook để thông báo các sự kiện quan trọng trong quá trình liên kết hoặc huỷ liên kết tài khoản ngân hàng đến hệ thống của bạn theo thời gian thực.

Cấu hình Webhook

Để nhận webhook events, bạn cần cung cấp webhook URL cho SePay Bank Hub. API thêm webhook

Lưu ý

Đây không phải webhook để nhận biến động số dư. Để nhận thông báo biến động số dư dùng IPN Xem chi tiết IPN

Cấu trúc chung Webhook Event

Mỗi webhook event có cấu trúc chuẩn như sau:

Webhook Event

{
  "timestamp": 1768312100,
  "xid": "e61cdae9-505e-4349-9713-a3e5b8b80b5e",
  "version": "1.0",
  "event": "EVENT_NAME",
  "metadata": {

  }
}

Các trường chung:

timestampintegerrequired

Unix timestamp (giây) khi event được tạo

xidstringrequired

UUID duy nhất của event

versionstringrequired

Phiên bản API webhook (hiện tại: "1.0")

eventstringrequired

Tên event (ví dụ: LINK_TOKEN_CREATED, BANK_ACCOUNT_LINKED)

metadataobjectrequired

Dữ liệu chi tiết của event, khác nhau tùy loại event

Luồng liên kết ngân hàng

Khi vừa tạo link token cho luồng liên kết ngân hàng

LINK_TOKEN_CREATED

{
  "timestamp": 1768312100,
  "xid": "e61cdae9-505e-4349-9713-a3e5b8b80b5e",
  "version": "1.0",
  "event": "LINK_TOKEN_CREATED",
  "metadata": {
    "purpose": "LINK_BANK_ACCOUNT",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": null
  }
}

Khi người dùng bắt đầu phiên liên kết và chuẩn bị chọn ngân hàng.

LINK_SESSION_INITIALIZED

{
  "timestamp": 1768311902,
  "xid": "d5df6e97-689e-49ae-b380-08126c6da950",
  "version": "1.0",
  "event": "LINK_SESSION_INITIALIZED",
  "metadata": {
    "link_session_xid": "0e296f70-cf41-4e8f-a89f-00cee248b887",
    "link_token_xid": "ef4cb765-c297-4a51-a9eb-6f7a751978ae"
  }
}

Khi người dùng đã chọn ngân hàng và chuyển đến màn hình nhập thông tin.

LINK_SESSION_STATE_CHANGED - REQUEST_BANK_ACCOUNT_LINK

{
  "timestamp": 1768312140,
  "xid": "e117249c-a827-4f89-951d-433c3a384785",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "REQUEST_BANK_ACCOUNT_LINK",
    "brand_name": "MBBank",
    "account_type": "personal",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": "a9e6d327-5888-449a-b82a-356fa80d6211"
  }
}

Khi người dùng đã nhập thông tin tài khoản và chuyển đến màn hình nhập OTP.

LINK_SESSION_STATE_CHANGED

{
  "timestamp": 1768311997,
  "xid": "a67f03a1-1bdf-46a5-8c6e-4af6aec28aca",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "CONFIRM_BANK_ACCOUNT_LINK",
    "brand_name": "MBBank",
    "account_type": "personal",
    "account_number": "0000000000011111",
    "account_holder_name": "NGUYEN VAN A",
    "link_token_xid": "ef4cb765-c297-4a51-a9eb-6f7a751978ae",
    "link_session_xid": "0e296f70-cf41-4e8f-a89f-00cee248b887"
  }
}

Khi quá trình liên kết hoàn tất thành công sẽ gửi 3 webhook events:

LINK_SESSION_STATE_CHANGED - FINISHED_BANK_ACCOUNT_LINK

{
  "timestamp": 1768312172,
  "xid": "21e2445d-9696-4edd-816c-746b2e6ec110",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "FINISHED_BANK_ACCOUNT_LINK",
    "brand_name": "MBBank",
    "account_type": "personal",
    "account_number": "0000000000011111",
    "account_holder_name": "NGUYEN VAN A",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": "a9e6d327-5888-449a-b82a-356fa80d6211"
  }
}

BANK_ACCOUNT_LINKED

{
  "timestamp": 1768312023,
  "xid": "e343bdec-97dc-4c60-b953-f81b183e0096",
  "version": "1.0",
  "event": "BANK_ACCOUNT_LINKED",
  "metadata": {
    "bank_account_xid": "587eabfb-f086-11f0-b16e-52c7e9b4f41b",
    "brand_name": "MBBank",
    "account_type": "personal",
    "account_number": "0000000000011111",
    "link_token_xid": "ef4cb765-c297-4a51-a9eb-6f7a751978ae",
    "link_session_xid": "0e296f70-cf41-4e8f-a89f-00cee248b887"
  }
}

LINK_SESSION_COMPLETED

{
  "timestamp": 1768312173,
  "xid": "19b3bbb2-41a3-4b27-a301-db91a036fb18",
  "version": "1.0",
  "event": "LINK_SESSION_COMPLETED",
  "metadata": {
    "bank_account_xid": "b1293181-f086-11f0-b16e-52c7e9b4f41b",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": "a9e6d327-5888-449a-b82a-356fa80d6211"
  }
}

Luồng huỷ liên kết

Khi vừa tạo thành công link token cho luồng huỷ liên kết ngân hàng:

LINK_TOKEN_CREATED

{
  "timestamp": 1768443727,
  "xid": "3406b960-71e4-4fdd-9bb3-41bba8fe6107",
  "version": "1.0",
  "event": "LINK_TOKEN_CREATED",
  "metadata": {
    "purpose": "UNLINK_BANK_ACCOUNT",
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": null
  }
}

Khi người dùng bắt đầu huỷ liên kết và chuyển đến màn hình xác nhận (OTP).

LINK_SESSION_STATE_CHANGED

{
  "timestamp": 1768443767,
  "xid": "a3d04fca-226c-4376-ac31-189283801f1b",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "REQUEST_BANK_ACCOUNT_UNLINK",
    "brand_name": "ACB",
    "account_type": "individual",
    "account_number": "7777777777",
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": "53f42c84-ada6-442a-8732-6d8ec686cdc0"
  }
}

Khi tài khoản ngân hàng được huỷ liên kết thành công (huỷ liên kết đến ngân hàng)

LINK_SESSION_COMPLETED

{
  "timestamp": 1768443806,
  "xid": "76e32fa6-5ed2-42b6-9f57-7cb8acbd12dc",
  "version": "1.0",
  "event": "LINK_SESSION_COMPLETED",
  "metadata": {
    "bank_account_xid": "54a488a6-f1b8-11f0-b21a-a6006ab65aca",
    "unlinked": true,
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": "53f42c84-ada6-442a-8732-6d8ec686cdc0"
  }
}

BANK_ACCOUNT_UNLINKED | BANK_ACCOUNT_INACTIVED

{
  "timestamp": 1768443805,
  "xid": "3c02781a-e061-44a0-b035-0cab9d00f73c",
  "version": "1.0",
  "event": "BANK_ACCOUNT_UNLINKED | BANK_ACCOUNT_INACTIVED",
  "metadata": {
    "bank_account_xid": "54a488a6-f1b8-11f0-b21a-a6006ab65aca",
    "brand_name": "ACB",
    "account_type": "individual",
    "account_number": "7777777777",
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": "53f42c84-ada6-442a-8732-6d8ec686cdc0"
  }
}

Lưu ý

BANK_ACCOUNT_UNLINKED: Huỷ liên kết trực tiếp với phía ngân hàng
BANK_ACCOUNT_INACTIVED: Chỉ vô hiệu hoá mà không huỷ trực tiếp với ngân hàng

Gọi lại Webhook

SePay sẽ gọi lại webhooks nếu trạng thái kết nối mạng đến webhook url thất bại. Ngoài ra, bạn có thể tùy chọn các điều kiện SePay hỗ trợ sẵn để có thể gọi lại webhooks. Thời gian gọi cách nhau bằng phút, tăng dần theo dãy số Fibonacci

Số lần gọi lại tối đa là 7 lần
Tối đa là 5 giờ kể từ khi gọi lần đầu thất bại
Network connect timeout của SePay là 5 giây
Thời gian chờ phản hồi tối đa của SePay là 8 giây

Lưu ý

SePay sẽ KHÔNG gọi lại webhooks nếu trạng thái là thất bại nhưng kết nối mạng là thành công, trừ khi webhook đó được thiết lập điều kiện gọi lại và chỉ gọi lại khi thỏa mãn một trong số các điều kiện được thiết lập.

Bước tiếp theo

Sau khi cấu hình webhook events, bạn có thể:

Thông báo biến động số dư (IPN) - Nhận thông báo giao dịch realtime
API Cập nhật Webhook - Cập nhật URL webhook qua API
API Danh sách tài khoản - Xem danh sách tài khoản đã liên kết
API Danh sách giao dịch - Truy vấn lịch sử giao dịch