Nhảy tới nội dung

Webhook​

Webhook là một HTTTP request được sử dụng trong việc triển khai các phản ứng sự kiện. bankHub sẽ gửi webhook để thông tin về những thay đổi với những bankHub grant hoặc thông tin giao dịch tài chính. Ví dụ, bankHub sẽ gửi một webhook khi một grant đang gặp lỗi hoặc giao dịch phát sinh từ đơn hàng được tạo.

Để nhận các bankHub webhook, cần thiết lập một endpoint trên máy chủ của bạn phương thức là POST. Sau đó cung cấp URL endpoint này cho bankHub như mô tả ở sau.

Cấu hình webhook​

Webhook được cấu hình thông qua bankHub Console. Khi thiết lập webhook, webhook URL phải theo định dạng http(s)://your-domain.com/webhook-endpoint.

bankHub sẽ gửi dữ liệu với phương thức là POST và định dạng là raw JSON từ một trong những địa chỉ IP sau:

  • 20.2.69.168 (sandbox)

Gửi lại Webhook(17 lần)​

Với những trường hợp phản hồi http status là 4XX, 5XX, hoặc không phản hồi trong vòng 30 giây, thì bankHub sẽ gửi lại webhook tới hệ thống của bạn với 17 lần trong vòng 24 giờ và thời gian giãn cách sau mỗi lần gọi dựa theo fibbonanci và một vài trọng số khác.

Ví dụ:

Lần gọiThời gian tới lần gọi sau
130 giây
21 phút
43 phút
68 phút
16453 phút
Request Body
  • environment string

    Môi trường gửi

  • webhookType string required

    Possible values: [GRANT, TRANSACTIONS]

    Loại webhook:

    • GRANT - Webhook cho grant
    • TRANSACTIONS - Webhook cho giao dịch ngân hàng
  • webhookCode string required

    Possible values: [ERROR, USER_PERMISSION_REVOKED, DEFAULT_UPDATE, GRANT_DELETED, GRANT_PAUSED, TRANSACTION_UPDATE]

    Mã webhook

    • Loại webhook là GRANT gồm:

      • ERROR - Lỗi từ tài khoản tài chính gắn với grant
      • USER_PERMISSION_REVOKED - Người dùng cuối xoá grant trên bankHub ID đã cấp cho ứng dụng của bạn
      • GRANT_DELETED - Người dùng cuối xoá grant đã cấp trên giao diện ứng dụng của bạn
      • GRANT_PAUSED - Người dùng cuối tạm dừng grant đã cấp trên giao diện ứng dụng của bạn

    • Loại webhook là TRANSACTIONS gồm:

      • DEFAULT_UPDATE - Một giao dịch ngân hàng mới phát sinh đến tài khoản được cấp quyền
      • TRANSACTION_UPDATE - (beta) Cập nhật thông tin đối ứng cho một giao dịch
  • grantId string nullable

    Mã định danh grant, giá trị tồn tại khi loại webhook là GRANT

  • error object nullable

    Thông tin lỗi của grant tương ứng, giá trị tồn tại khi loại webhook là GRANT và mã webhook là ERROR

  • errorType string

    Loại lỗi

  • errorCode string

    Possible values: [GRANT_LOGIN_REQUIRED, OTP_REQUIRED, PREVENTION_WEB]

    Mã lỗi từ tài khoản tài chính

    • GRANT_LOGIN_REQUIRED - Thông tin đăng nhập thay đổi như: mật khẩu,...
    • OTP_REQUIRED - Yêu cầu xác thực OTP
    • PREVENTION_WEB - Chặn đăng nhập từ website dịch vụ tài chính
  • errorMessage string

    Mô tả lỗi

  • transaction object nullable

    Thông tin chuyển khoản, giá trị của transactionCode hoặc reference có thể dùng để định danh một giao dịch tài chính, nhưng tuỳ vào dịch vụ tài chính sẽ hỗ trợ trường nào, nên tuỳ dịch vụ tài chính 1 trong 2 sẽ có giá trị hoặc sẽ có cả 2.

    Dịch vụ tài chínhtransactionCodereference
    MBBanktruetrue
    OCBfalsetrue
  • id string required

    Mã định danh giao dịch trên hệ thống của bankHub

  • transactionCode string nullable

    Mã giao dịch của dịch vụ tài chính, không thể dùng để tra soát với ngân hàng

  • reference string nullable

    Mã tham chiếu giao dịch của dịch vụ tài chính, dùng để tra soát với ngân hàng, mã này là mã chính thức hiển thị trên Internet banking. Mã này có thể bị trùng trong 1 số trường hợp. Một số ngân hàng như Agribank và Eximbank không có sẵn mã này

  • transactionDate string required

    Ngày giao dịch thực hiện thành công. Còn được gọi là valueDate

  • transactionDateTime string nullable

    Ngày giờ giao dịch thực hiện thành công. Còn được gọi là valueDateTime

  • bookingDate string nullable

    Ngày nhập sổ nhật kí kế toán. Một số ngân hàng nó sẽ là ngày làm việc kế tiếp. Ở Casso, đây sẽ là ngày được hiển thị trên Internet Banking.

  • amount number required

    Số tiền

  • description string required

    Nội dung giao dịch

  • runningBalance number nullable

    Số dư sau giao dịch

  • accountNumber string required

    Số tài khoản dịch vụ tài chính

  • virtualAccountNumber string nullable

    Số tài khoản ảo

  • virtualAccountName string nullable

    Tên tài khoản ảo

  • paymentChannel string nullable

    Kênh thanh toán. Có 4 kênh chính gồm: Napas247 | Nội bộ | Citad | Swift

  • counterAccountNumber string nullable

    Số tài khoản đối ứng

  • counterAccountName string nullable

    Tên tài khoản đối ứng

  • counterAccountBankId string nullable

    Mã BIN của ngân hàng của tài khoản đối ứng

  • counterAccountBankName string nullable

    Tên ngân hàng tài khoản đối ứng

  • paymentMeta object
  • referenceNumber string

    Mã đơn hàng của đối tác

  • fiId string required

    Mã định danh tổ chức tài chính

  • fiName string required

    Tên tổ chức tài chính

  • fiServiceId string required

    Mã định danh dịch vụ tài chính

  • fiServiceName string required

    Tên dịch vụ tài chính

  • currency string required

    Loại tiền

Responses

Success

Loading...