Tạo Webhooks

Các bước tích hợp WebHooks

• Bước 1: Truy cập vào menu WebHooks

• Bước 2: Chọn vào button + Thêm webhooks ở phía trên, bên phải

  

• Bước 3: Điền đầy đủ thông tin, bao gồm:

  • Đặt tên: Bạn đặt tên bất kỳ

  1. Chọn sự kiện: Bạn có thể chọn sự kiện Bắn WebHooks khi có tiền vào, có tiền ra hoặc cả hai

  2. Chọn điều kiện: Bao gồm:

     • Khi tài khoản ngân hàng là: Chọn tài khoản mà khi có giao dịch, webhooks sẽ bắn. Trong trường hợp bạn muốn chỉ định các tài khoản ảo (VA) cụ thể để nhận thông báo, tích vào hộp kiểm Lọc theo tài khoản ảo và chọn các tài khoản ảo cần theo dõi.
     • Bỏ qua nếu nội dung giao dịch không có Code thanh toán: Nếu bạn chọn Có, SePay sẽ KHÔNG bắn webhooks nếu không nhận diện được code thanh toán trong nội dung thanh toán. > TIP: Cấu hình nhận diện code thanh toán tại phần Công ty → Cấu hình chung → Cấu trúc mã thanh toán

  3. Thuộc tính WebHooks: Bao gồm:

     • Gọi đến URL: Đường link mà bạn muốn gọi WebHooks. Nếu muốn lập trình website nhận webhooks, xem hướng dẫn tại đây.
     • Là WebHooks xác thực thanh toán?: Chọn Đúng nếu webhooks này dùng để xác thực thanh toán cho website/ứng dụng bán hàng.
     • Gọi lại WebHooks khi: Hiện tại SePay hỗ trợ một số điều kiện để bạn có thể gọi lại WebHooks tự động:
       • HTTP Status Code không nằm trong phạm vi từ 200 đến 299.

  4. Cấu hình chứng thực WebHooks: Bao gồm:

     • Kiểu chứng thực: Hiện SePay hỗ trợ chứng thực với OAuth 2.0, API Key hoặc Không cần chứng thực.
       • Nếu chọn OAuth 2.0, bạn cần điền đầy đủ thông tin như OAuth 2.0 Access Token URL, OAuth 2.0 Client Id, OAuth 2.0 Client Secret.
       • Nếu chọn Không chứng thực hoặc Api Key, bạn cần chọn Request Content type là application/json, multipart/form-data hoặc application/x-www-form-urlencoded tùy theo ứng dụng nhận webhooks của mình.

• Bước 4: Chọn [Thêm] để hoàn tất tích hợp.

Dữ liệu gửi qua webhooks

• SePay sẽ gửi một request với phương thức là POST, với nội dung gửi như sau:

{
  "id": 92704,
  "gateway": "Vietcombank",
  "transactionDate": "2023-03-25 14:02:37",
  "accountNumber": "0123499999",
  "code": null,
  "content": "chuyen tien mua iphone",
  "transferType": "in",
  "transferAmount": 2277000,
  "accumulated": 19077000,
  "subAccount": null,
  "referenceCode": "MBVCB.3278907687",
  "description": ""
}

• Giải thích tham số

Kiểm tra hoạt động

• Nếu sử dụng tài khoản Demo, bạn vào menu Giao dịch → Giả lập giao dịch để thêm một giao dịch mới. Xem thông tin về Giả lập giao dịch tại đây.

• Nếu không sử dụng tài khoản demo, bạn có thể thử chuyển một khoản tiền nhỏ vào để có giao dịch thử nghiệm.

• Sau đó vào menu Nhật ký → Nhật ký webhooks để xem danh sách các webhooks đã bắn.

• Ngoài ra, bạn có thể xem tin nhắn webhooks đã gửi theo từng giao dịch tại menu ⇆ Giao dịch → cột Tự động → chọn vào Pay.

Nhận diện webhooks thành công

• Khi nhận webhooks gọi từ SePay, website của bạn cần phản hồi (response) theo quy ước sau để SePay biết được kết quả là thành công:

  • Với chứng thực OAuth 2.0 (Xem hướng dẫn cấu hình OAuth2 cho tích hợp Webhooks)

    • Nội dung trả về là json có success: true: {"success": true, ....}
    • HTTP Status Code phải là 201

  • Với chứng thực API Key

    • Nội dung trả về là json có success: true: {"success": true, ....}
    • HTTP Status Code phải là 201 hoặc 200

  • Với không chứng thực

    • Nội dung trả về là json có success: true: {"success": true, ....}
    • HTTP Status Code phải là 201 hoặc 200

• Nếu kết quả trả về không thỏa mãn các điều kiện trên, SePay sẽ xem là webhook thất bại.

Retry webhooks tự động

• 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.

Yêu cầu chống trùng lặp giao dịch

• Để tránh trùng lặp giao dịch khi phát sinh các sự cố với kết nối webhook của phía người dùng tại cơ chế retry. SePay khuyến nghị người dùng xử lý chống trùng lặp giao dịch khi nhận thông báo biến động giao dịch từ SePay thông qua webhook của mình.

• Người dùng cần kiểm tra tính duy nhất của trường id, hoặc kết hợp thêm các trường khác như referenceCode, transferType, transferAmount từ dữ liệu SePay gửi qua webhook để đảm bảo tính duy nhất của giao dịch.

Retry webhooks bằng tay

• Bạn có thể thao tác gọi lại webhooks bằng tay bằng cách vào Chi tiết một giao dịch → Chọn Xem tại Webhooks đã bắn → Gọi lại. Hoặc vào phần Nhật ký Webhooks, chọn vào Gọi lại