Skip to main content
Version: 1.2.1 (Latest)

Webhook thông báo trạng thái liên kết tài khoản

Khi thực hiện tạo hoặc liên kết tài khoản ảo (VA) thông qua API Tạo tài khoản ảo (VA), một số ngân hàng áp dụng quy trình xử lý bất đồng bộ (Asynchronous Callback):

  • Vietcombank (VCB): Áp dụng cho tài khoản Cá nhân và Hộ kinh doanh (chỉ cần truyền webhookUrl, không cần requestId).
  • TPBank (TPB): Áp dụng cho tất cả các loại tài khoản (cần truyền cả webhookUrl và requestId).

Khi gọi API create-va, đối tác truyền địa chỉ webhookUrl để nhận kết quả. Khi hệ thống ngân hàng hoàn tất việc kích hoạt tài khoản hoặc người dùng xác thực thành công, ngân hàng sẽ gửi kết quả về Tingee. Ngay sau đó, Tingee tự động gửi thông báo Webhook tới địa chỉ webhookUrl mà đối tác đã cung cấp.

Sơ đồ luồng xử lý​

Luồng xử lý Webhook trạng thái liên kết tài khoản
← Vuốt ngang để xem thêm →

Chi tiết Webhook​

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

Webhook thông báo trạng thái liên kết hoặc hủy liên kết tài khoản ảo từ VCB và TPBank về hệ thống đối tác.

Header gửi kèm​

Các header này giúp bạn định danh, kiểm tra thời gian gửi và xác thực tính toàn vẹn của dữ liệu:

HeaderMô tả
Content-TypeLuôn là application/json.
x-request-idMã định danh duy nhất cho mỗi lượt gửi webhook từ Tingee (dạng UUID).
x-request-timestampThời gian Tingee gửi thông báo (format: yyyyMMddHHmmssSSS, múi giờ UTC+7).
x-signatureChữ ký điện tử HMAC-SHA512 dùng để kiểm tra tính toàn vẹn dữ liệu.

Body Parameter​

Dữ liệu chi tiết về trạng thái tài khoản ngân hàng được gửi trong phần body:

TrườngKiểuBắt buộcMô tả
requestIdstring~Mã định danh yêu cầu ban đầu (chỉ áp dụng đối với TPBank; ngân hàng Vietcombank không áp dụng).
merchantIdnumber✓ID của Merchant trên hệ thống Tingee.
merchantAccountNumberIdnumber~ID bản ghi tài khoản ngân hàng trên hệ thống Tingee (có ở TPBank).
shopIdnumber~ID của cửa hàng được gán tài khoản ảo này.
bankNamestring✓Tên ngân hàng ("VCB" hoặc "TPB").
bankBinstring✓Mã BIN ngân hàng: "970436" (Vietcombank) hoặc "970423" (TPBank).
accountNumberstring✓Số tài khoản ngân hàng gốc của khách hàng.
accountNamestring~Tên chủ tài khoản ngân hàng (viết hoa không dấu).
vaAccountNumberstring✓Số tài khoản ảo (VA) đã được cấp/liên kết thành công.
isNotifyAccountNumberboolean✓false: Tài khoản ảo (VA); true: Tài khoản gốc nhận biến động.
statusstring✓Trạng thái xử lý từ ngân hàng (xem chi tiết bảng bên dưới).

Danh sách các trạng thái (status):​

Giá trị statusÝ nghĩaHành động đề xuất
confirm-va-successLiên kết / Tạo VA thành côngCập nhật số tài khoản ảo (vaAccountNumber) vào hệ thống để bắt đầu nhận thanh toán.
delete-va-successHủy liên kết VA thành côngĐánh dấu tài khoản ảo đã ngừng nhận biến động hoặc hủy liên kết.
confirm-va-failedLiên kết / Tạo VA thất bạiThông báo cho khách hàng kiểm tra lại thông tin hoặc thử lại.
delete-va-failedHủy liên kết VA thất bạiGhi nhận lỗi hủy liên kết để tra soát.

Ví dụ Payload Body​

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

Phản hồi từ Server Đối tác​

Sau khi nhận và xử lý webhook, máy chủ đối tác cần phản hồi mã HTTP 200 OK kèm theo JSON xác nhận:

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

Copyright © 2026 TINGEE - Giải pháp thanh toán bởi HENO.