Account linking status webhook

When you create or link a virtual account (VA) via the Create virtual account (VA) API, some banks process the request asynchronously (Asynchronous Callback):

• Vietcombank (VCB): Applies to Personal and Household business accounts (pass webhookUrl only; requestId is not needed).
• TPBank (TPB): Applies to all account types (pass both webhookUrl and requestId).

When calling the create-va API, pass a webhookUrl to receive the result. When the bank finishes activating the account or the user completes verification, the bank sends the result to Tingee. Tingee then immediately sends a webhook notification to the webhookUrl you provided.

---

Flow diagram

Account linking status webhook flow

← Swipe to see more →

---

Webhook details

POST

URLhttps://your-server.com/api/webhook/va-status

Webhook that notifies the partner system of the virtual account linking or unlinking status from VCB and TPBank.

Headers sent

These headers help you identify the request, check when it was sent and verify the integrity of the data:

Header	Description
Content-Type	Always application/json.
x-request-id	Unique identifier of each webhook delivery from Tingee (UUID).
x-request-timestamp	Time Tingee sends the notification (format: yyyyMMddHHmmssSSS, UTC+7).
x-signature	HMAC-SHA512 digital signature used to verify data integrity.

---

Body Parameter

The details of the bank account status are sent in the body:

Field	Type	Required	Description
requestId	string	~	Original request identifier (applies to TPBank only; not used for Vietcombank).
merchantId	number	✓	Merchant ID on the Tingee system.
merchantAccountNumberId	number	~	ID of the bank account record on the Tingee system (present for TPBank).
shopId	number	~	ID of the shop this virtual account is assigned to.
bankName	string	✓	Bank name ("VCB" or "TPB").
bankBin	string	✓	Bank BIN: "970436" (Vietcombank) or "970423" (TPBank).
accountNumber	string	✓	The customer's original bank account number.
accountName	string	~	Account holder name (uppercase, without diacritics).
vaAccountNumber	string	✓	The virtual account (VA) number that was issued/linked successfully.
isNotifyAccountNumber	boolean	✓	false: virtual account (VA); true: original account receiving balance notifications.
status	string	✓	Processing status from the bank (see the table below).

Status values (status):

status value	Meaning	Recommended action
confirm-va-success	VA linked / created successfully	Save the virtual account number (vaAccountNumber) in your system to start receiving payments.
delete-va-success	VA unlinked successfully	Mark the virtual account as no longer receiving balance notifications, or as unlinked.
confirm-va-failed	VA linking / creation failed	Ask the customer to check their information or try again.
delete-va-failed	VA unlinking failed	Log the unlinking error for investigation.

---

Sample Payload Body

Vietcombank (VCB)

{
  "merchantId": 1001,
  "shopId": 24,
  "bankName": "VCB",
  "bankBin": "970436",
  "accountNumber": "0123456789",
  "accountName": "NGUYEN VAN A",
  "vaAccountNumber": "99990123456789",
  "isNotifyAccountNumber": false,
  "status": "confirm-va-success"
}

TPBank (Success)

{
  "requestId": "REQ_20261008_001",
  "merchantId": 1001,
  "merchantAccountNumberId": 5678,
  "shopId": 24,
  "bankName": "TPB",
  "bankBin": "970423",
  "accountNumber": "0123456789",
  "accountName": "NGUYEN VAN A",
  "vaAccountNumber": "0123456789",
  "isNotifyAccountNumber": false,
  "status": "confirm-va-success"
}

TPBank (Unlinked)

{
  "requestId": "REQ_20261008_002",
  "merchantId": 1001,
  "merchantAccountNumberId": 5678,
  "shopId": 24,
  "bankName": "TPB",
  "bankBin": "970423",
  "accountNumber": "0123456789",
  "accountName": "NGUYEN VAN A",
  "vaAccountNumber": "0123456789",
  "isNotifyAccountNumber": false,
  "status": "delete-va-success"
}

Partner server response

After receiving and processing the webhook, your server must respond with HTTP 200 OK and the following acknowledgement JSON:

{
  "code": "00",
  "message": "Success"
}