QR Pay

Tạo mã thanh toán

Tài liệu về API

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

Bắt đầu

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

QR PAY (Mã QR thanh toán) là mã QR động được tạo theo đơn hàng và kèm xác nhận thanh toán.

Với mỗi mã thanh toán được tạo thì sẽ có một số tài khoản ảo được sinh ra và số tài khoản ảo này sẽ gắn với một đơn hàng tương ứng, khi KH thanh toán vào số tài khoản ảo thì đơn hàng đó cũng được xác nhận thanh toán thành công.

Khi khách hàng thực hiện thanh toán vào số tài khoản ảo với đúng số tiền hoặc đúng số tiền và nội dung thì phía bankHub sẽ xác nhận đơn hàng của bạn thanh toán, hệ thống của bạn sẽ nhận được một webhook loại TRANSACTIONS và paymentMeta sẽ kèm giá trị referenceNumber lúc tạo QR Pay.

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": "19c4a4ab-3ea8-4254-8436-bffe01d3352f",
    "reference": "FT23339WL0MW\\BNK",
    "transactionDate": "2023-12-05",
    "transactionDateTime": "2023-12-05T16:25:00+07:00",
    "bookingDate": "2023-12-05",
    "amount": 10000,
    "description": "CSP5BXM10C5 test",
    "runningBalance": null,
    "accountNumber": 867623232,
    "virtualAccountNumber": "CASD0867623232",
    "virtualAccountName": null,
    "paymentChannel": null,
    "counterAccountNumber": null,
    "counterAccountName": null,
    "counterAccountBankId": null,
    "counterAccountBankName": null,
    "paymentMeta": {
      "referenceNumber": "m9nTyCFrVZubG"
    },
    "fiId": "3c2e880d-efb5-11ed-8620-0ae7e48c82d8",
    "fiName": "OCB",
    "fiServiceId": "fbad1579-7224-11ee-b6d2-42010a40001e",
    "fiServiceName": "OCB VietQR Pay",
    "currency": "VND"
  }
}

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

Dưới đây là các bước để tích hợp QR Pay 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.
Mở giao diện bankHub Link bằng grantToken được trả về ở bước trên. Xem chi tiết
Sau khi người dùng hoàn tất xác thực, phía giao diện của bạn sẽ nhận được một publicToken, dùng publicToken này để lấy accessToken cho phân quyền.
Sau khi có accessToken, gọi API lấy thông tin định danh của TK tạo QR Pay để kiểm tra thông tin TK có hợp lệ hay không. Trường hợp TK không hợp lệ bạn sẽ gọi API /grant/remove để xoá phân quyền này.
Bây giờ bạn đã có thể gọi API Tạo QR Pay.
Tạo mã QR từ kết quả ở trường qrCode và hiển thị mã QR này trên giao diện của bạn. Để đơn giản việc tạo mã VietQR bạn có thể dùng Quicklink của vietqr.io để tạo QR và nhúng link vào hệ thống của bạn.
Xử lý trạng thái đơn hàng trên hệ thống của bạn khi nhận webhook giao dịch, và trường referenceNumber trong paymentMeta từ webhook là mã đơn hàng trên hệ thống của bạn.

Gọi API

Tạo phân quyền cho QR Pay

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

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "qrpay",
   "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
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 của TK tạo QR Pay

CURL
Javascript (Axios)

  curl --location 'https://sandbox.bankhub.dev/qr-pay/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');

  const config = {
    method: 'get',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/qr-pay/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);
  });

thông tin

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

Tạo QR Pay

CURL
Javascript (Axios)

  curl --location 'https://sandbox.bankhub.dev/qr-pay' \
  --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>'
  --data '{
    "amount": 2000,
    "description": "cassotest",
    "referenceNumber": "1234455811acbc"
  }'

  const axios = require('axios');
  const data = JSON.stringify({
    "amount": 2000,
    "description": "cassotest",
    "referenceNumber": "1234455811acbc"
  });
  const config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/qr-pay',
    headers: { 
      'X-BankHub-Api-Version': '2023-01-01', 
      'Authorization': '<ACCESS_TOKEN_HERE>', 
      'x-client-id': '<CLIENT_ID_HERE>', 
      'x-secret-key': '<SECRET_KEY_HERE>'
    },
    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

Tài liệu về API

Bắt đầu

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

Gọi API​

Tạo phân quyền cho QR Pay​

Lấy accessToken từ publicToken​

Lấy thông tin định danh của TK tạo QR Pay​

Tạo QR Pay​

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

Gọi API

Tạo phân quyền cho QR Pay

Lấy accessToken từ publicToken

Lấy thông tin định danh của TK tạo QR Pay

Tạo QR Pay