Webhook

Tingee sends a webhook to your endpoint when important events occur while you use the Direct Debit service.

Webhooks help you:

• Sync status: Update payment and account linking results in real time.
• Automate: Handle your business logic as soon as the system notifies you.

You need to provide your webhook URL to the Tingee technical team for configuration before you start the integration.

---

Webhook flow

1. Event: An action occurs, such as account linking, payment, unlinking, or a confirmation method update.
2. Notification: Tingee sends a POST request with the data payload to the configured URL.
3. Verification: You check the x-signature signature in the header to make sure the data comes from Tingee.
4. Handling & response: You process the data and respond to Tingee (status code 200).
5. Retry: If delivery fails, the Tingee system retries automatically according to the retry mechanism.

---

Payload structure

1. Account registration result (type: "register")

Sent after the customer completes the account linking flow on the Tingee interface.

{
  "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. Payment result (type: "transaction")

Sent after the system finishes processing a request to debit the customer's account.

{
  "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. Confirmation method update result (type: "edit")

Sent after the customer finishes changing the payment confirmation method.

{
  "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. Account unlinking result (type: "delete")

Sent after the account unlinking request has been fully processed.

{
  "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"
  }
}

---

Security & verification

Topic	Guide
Webhook headers	See details
Generate the SHA512 signature	See details
Verify the webhook	See details
Retry mechanism	See details