Balance Hook

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

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.

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

2. 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

3. Nhận publicToken sau khi người dùng hoàn tất liên kết, và dùng nó để lấy accessToken.

4. 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.

5. 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.

Gọi API

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

CURL

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",
}'

Javascript (Axios)

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "qrpay", // or virtual_account
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
 });

 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

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

Javascript (Axios)

  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

  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>'

Javascript (Axios)

  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.