Balance Hook

Cá nhân

Doanh nghiệp

Balance Hook là một webhook sự kiện được Cas cung cấp để thông báo tức thời khi có bất kỳ biến động số dư nào trên tài khoản ngân hàng hoặc tài khoản ảo (VA) mà bạn đã tích hợp.

Khi người dùng nạp tiền, rút tiền, hoặc phát sinh giao dịch làm thay đổi số dư, hệ thống của bạn sẽ nhận được một cuộc gọi POST từ Cas, giúp bạn xử lý giao dịch một cách nhanh chóng và tự động, không cần liên tục truy vấn.

Tài liệu về API

Chi tiết Balance Hook yêu cầu, phản hồi và code mẫu

Xem chi tiết Balance Hook API

Bắt đầu

Tìm hiểu về các thông tin để triển khai và cách thức hoạt động.

Bắt đầu

AI Agent

Cài skill để AI coding agent tích hợp Cas chính xác theo codebase của bạn

Tích hợp với AI Agent

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

Dưới đây là các bước để tích hợp Balance Hook vào sản phẩm của bạn.

Tạo một phân quyền /grant/token với scopes có giá trị là qrpay hoặc virtual_account.

user (tuỳ chọn): thông tin khách hàng mà hệ thống của bạn đã lưu, dùng để điền sẵn biểu mẫu trên Cas Link và hỗ trợ kiểm tra thông tin tài khoản. Xem chi tiết

Mở giao diện Cas Link bằng grantToken để người dùng liên kết tài khoản ngân hàng. Xem chi tiết
Nhận publicToken sau khi người dùng hoàn tất liên kết, và dùng nó để lấy accessToken.
Sau khi có accessToken, gọi API Lấy thông tin định danh tài khoản để kiểm tra thông tin và bắt đầu thêm vào hệ thống của bạn.
Cấu hình endpoint nhận webhook, CAS.SO sẽ gửi dữ liệu thay đổi số dư khi có giao dịch mới phát sinh.

Thông tin khách hàng (`user`)

user là trường tuỳ chọn khi tạo phân quyền. Nếu hệ thống của bạn đã lưu sẵn thông tin của khách hàng, hãy truyền vào để:

Điền sẵn biểu mẫu liên kết: Cas Link tự động điền các ô tên chủ tài khoản, số định danh, số điện thoại và email, người dùng không cần nhập lại những thông tin bên bạn đã có.
Kiểm tra thông tin tài khoản: với scopes là qrpay, Cas Link đối chiếu thông tin bạn gửi với thông tin tài khoản mà ngân hàng trả về; nếu tên chủ tài khoản hoặc số định danh không khớp thì thao tác liên kết sẽ bị dừng lại và báo lỗi cho người dùng.

Trường	Kiểu	Mô tả
`legalName`	string	Tên chủ tài khoản cá nhân
`idNumber`	string	Số định danh cá nhân (CCCD/CMND) của chủ tài khoản
`companyName`	string	Tên doanh nghiệp
`companyLegalId`	string	Mã số thuế/mã số doanh nghiệp
`mobileNumber`	string	Số điện thoại khách hàng đăng ký với ngân hàng
`email`	string	Email của khách hàng

ghi chú

Tuỳ theo dịch vụ tài chính là loại cá nhân hay doanh nghiệp mà bạn truyền cặp legalName/idNumber hoặc companyName/companyLegalId. Trường nào không truyền thì bỏ qua việc đối chiếu trường đó.

Gọi API

Tạo phân quyền cho Balance Hook

CURL
Javascript (Axios)

curl --location 'https://sandbox.bankhub.dev/grant/token' \
--header 'X-BankHub-Api-Version: 2023-01-01' \
--header 'x-client-id: <CLIENT_ID_HERE>' \
--header 'x-secret-key: <SECRET_KEY_HERE>' \
--header 'Content-Type: application/json' \
--data '{
    "scopes": "qrpay",
    "language": "vi",
    "redirectUri": "https://your-domain.vn/link",
    "user": {
        "legalName": "NGUYEN VAN A",
        "idNumber": "079201000123",
        "mobileNumber": "0901234567",
        "email": "nguyenvana@gmail.com"
    }
}'

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "qrpay", // or virtual_account
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
   "user": {
     "legalName": "NGUYEN VAN A",
     "idNumber": "079201000123",
     "mobileNumber": "0901234567",
     "email": "nguyenvana@gmail.com"
   }
 });

 const config = {
   method: 'post',
   maxBodyLength: Infinity,
   url: 'https://sandbox.bankhub.dev/grant/token',
   headers: { 
     'X-BankHub-Api-Version': '2023-01-01', 
     'x-client-id': '<CLIENT_ID_HERE>', 
     'x-secret-key': '<SECRET_KEY_HERE>', 
     'Content-Type': 'application/json',
   },
   data: data
 };

 axios.request(config)
 .then((response) => {
   console.log(JSON.stringify(response.data));
 })
 .catch((error) => {
   console.log(error);
 });

thông tin

Xem chi tiết API, tại đây

Lấy accessToken từ publicToken

CURL
Javascript (Axios)

  curl --location 'https://sandbox.bankhub.dev/grant/exchange' \
  --header 'X-BankHub-Api-Version: 2023-01-01' \
  --header 'x-client-id: <CLIENT_ID_HERE>' \
  --header 'x-secret-key: <SECRET_KEY_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
      "publicToken": "bdbde2bad-7685-4f95-987c-71309a4a3"
  }'

  const axios = require('axios');
  const data = JSON.stringify({
    "publicToken": "bdbde2bad-7685-4f95-987c-71309a4a3"
  });

  const config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/grant/exchange',
    headers: { 
      'X-BankHub-Api-Version': '2023-01-01', 
      'x-client-id': '<CLIENT_ID_HERE>', 
      'x-secret-key': '<SECRET_KEY_HERE>', 
      'Content-Type': 'application/json'
    },
    data: data
  };

  axios.request(config)
    .then((response) => {
      console.log(JSON.stringify(response.data));
    })
    .catch((error) => {
      console.log(error);
    });

thông tin

Xem chi tiết API, tại đây

Lấy thông tin định danh tài khoản vừa được cấp quyền

CURL
Javascript (Axios)

  curl --location 'https://sandbox.bankhub.dev/identity' \
  --header 'X-BankHub-Api-Version: 2023-01-01' \
  --header 'Authorization: <ACCESS_TOKEN_HERE>' \
  --header 'x-client-id: <CLIENT_ID_HERE>' \
  --header 'x-secret-key: <SECRET_KEY_HERE>'

  const axios = require('axios');

  let config = {
    method: 'get',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/identity',
    headers: { 
      'X-BankHub-Api-Version': '2023-01-01', 
      'Authorization': '<ACCESS_TOKEN_HERE>', 
      'x-client-id': '<CLIENT_ID_HERE>', 
      'x-secret-key': '<SECRET_KEY_HERE>'
    }
  };

  axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Nhận thông báo biến động số dư

Bạn cần cấu hình một Webhook loại TRANSACTIONS trên Developer Console – đây là URL mà Cas sẽ gửi thông báo khi có biến động.
Khi phát sinh sự kiện thay đổi số dư, Cas sẽ gửi HTTP POST đến URL đó.
Hệ thống của bạn sẽ xử lý payload nhận được để thực hiện các nghiệp vụ như: ghi nhận giao dịch, gửi thông báo, v.v.

Xem dữ liệu webhook mẫu

{
  "environment": "dev",
  "webhookType": "TRANSACTIONS",
  "webhookCode": "DEFAULT_UPDATE",
  "error": null,
  "grantId": "4c657924-13f3-11ee-a4bb-42010a40001b",
  "transaction": {
    "id": "3cacecf6935011ee952542010a400022",
    "transactionCode": "993UNdEHhIgfy3I",
    "reference": null,
    "transactionDate": "2023-12-05",
    "transactionDateTime": "2023-12-05T16:25:00+07:00",
    "bookingDate": "2023-12-05",
    "amount": 10000,
    "description": "test",
    "runningBalance": 3330000,
    "accountNumber": 867623232,
    "virtualAccountNumber": null,
    "virtualAccountName": null,
    "paymentChannel": null,
    "counterAccountNumber": null,
    "counterAccountName": null,
    "counterAccountBankId": null,
    "counterAccountBankName": null,
    "paymentMeta": null,
    "fiId": "3c26a8ed-efb5-11ed-8620-0ae7e48c82d8",
    "fiName": "VietinBank",
    "fiServiceId": "433f71c4-efb5-11ed-8620-0ae7e48c82d8",
    "fiServiceName": "VietinBank iPay - Official API",
    "currency": "VND"
  }
}

THÔNG TIN

Xem chi tiết API, tại đây.

Tài liệu về API

Bắt đầu

AI Agent

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

Thông tin khách hàng (user)​

Gọi API​

Tạo phân quyền cho Balance Hook​

Lấy accessToken từ publicToken​

Lấy thông tin định danh tài khoản vừa được cấp quyền​

Nhận thông báo biến động số dư​

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

Thông tin khách hàng (`user`)

Gọi API

Tạo phân quyền cho Balance Hook

Lấy accessToken từ publicToken

Lấy thông tin định danh tài khoản vừa được cấp quyền

Nhận thông báo biến động số dư