Webhook

Tingee sẽ gửi webhook về endpoint của đối tác khi xảy ra các sự kiện quan trọng trong quá trình sử dụng dịch vụ Direct Debit.

Webhook giúp Đối tác:

• Đồng bộ trạng thái: Cập nhật kết quả thanh toán, liên kết tài khoản theo thời gian thực.
• Tự động hóa: Chủ động xử lý nghiệp vụ ngay khi có thông báo từ hệ thống.

Đối tác cần cung cấp URL nhận webhook cho đội ngũ kỹ thuật Tingee để cấu hình trước khi bắt đầu tích hợp.

---

Luồng xử lý Webhook

1. Sự kiện: Xảy ra các hành động như Liên kết tài khoản, Thanh toán, Hủy liên kết, hoặc Cập nhật PTXN.
2. Gửi thông báo: Tingee gửi request POST chứa payload dữ liệu đến URL đã cấu hình.
3. Xác thực: Đối tác kiểm tra chữ ký x-signature trong Header để đảm bảo dữ liệu đến từ Tingee.
4. Xử lý & Phản hồi: Đối tác xử lý dữ liệu và phản hồi lại Tingee (Status code 200).
5. Retry: Nếu gửi thất bại, hệ thống Tingee sẽ tự động thử lại theo cơ chế Retry.

---

Cấu trúc Payload

1. Kết quả đăng ký tài khoản (type: "register")

Gửi sau khi khách hàng hoàn tất luồng liên kết tài khoản trên giao diện Tingee.

{
  "type": "register",
  "partnerCode": "one-pay",
  "payload": {
    "requestId": "3086f1f9-e2f5-4549-83a6-b80b2b89138a",
    "clientId": "YOUR_CLIENT_ID",
    "subscriptionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f",
    "tokenRef": "TKN-12345678",
    "bankBin": "970415",
    "customer": {
      "name": "Nguyen Van A",
      "phone": "0912345678",
      "email": "customer@example.com"
    },
    "accountNumber": "123456789012",
    "confirmPaymentByEmail": true,
    "confirmPaymentByZalo": false,
    "confirmPhoneNumber": "0909123456",
    "confirmEmail": "nguyenvana@example.com",
    "status": "success"
  }
}

2. Kết quả thanh toán (type: "transaction")

Gửi sau khi hệ thống xử lý xong yêu cầu khấu trừ tiền từ tài khoản khách hàng.

{
  "type": "transaction",
  "partnerCode": "one-pay",
  "payload": {
    "clientId": "YOUR_CLIENT_ID",
    "requestId": "00000198-1f93-4338-94bb-ffc0829d5e9d",
    "customer": {
      "name": "Nguyen Van A",
      "phone": "0912345678",
      "email": "customer@example.com"
    },
    "code": "DD-20260115001",
    "amount": 150000,
    "currency": "VND",
    "content": "Thanh toan don hang #12345",
    "transactionDate": "2026-01-15T12:20:49Z",
    "status": "SUCCESS",
    "additionalData": {
      "billId": "HD12345677"
    }
  }
}

3. Kết quả cập nhật PTXN (type: "edit")

Gửi sau khi khách hàng hoàn tất việc thay đổi phương thức xác nhận thanh toán.

{
  "type": "edit",
  "partnerCode": "one-pay",
  "payload": {
    "requestId": "00000198-1f93-4338-94bb-ffc0829d5e9d",
    "clientId": "63b7eefd1bd3f003a2c3950857d2fd90",
    "subscriptionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f",
    "tokenRef": "TKN-12345678",
    "confirmPaymentByEmail": true,
    "confirmPaymentByZalo": false,
    "confirmPhoneNumber": "0909123456",
    "confirmEmail": "nguyenvana@example.com",
    "status": "success"
  }
}

4. Kết quả hủy đăng ký tài khoản (type: "delete")

Gửi sau khi yêu cầu hủy liên kết tài khoản được xử lý hoàn tất.

{
  "type": "delete",
  "partnerCode": "one-pay",
  "payload": {
    "requestId": "00000198-1f93-4338-94bb-ffc0829d5e9d",
    "clientId": "63b7eefd1bd3f003a2c3950857d2fd90",
    "subscriptionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f",
    "tokenRef": "TKN-12345678",
    "status": "success"
  }
}

---

Bảo mật & Xác thực

Nội dung	Tài liệu hướng dẫn
Header Webhook	Xem chi tiết
Sinh chữ ký SHA512	Xem chi tiết
Xác thực Webhook	Xem chi tiết
Cơ chế Retry	Xem chi tiết