Tài Liệu API

BankAPI cung cấp giao diện RESTful để tích hợp với hệ thống ngân hàng Việt Nam. Mọi request cần gửi kèm API key trong header.

Xác Thực

Tất cả API đều yêu cầu xác thực bằng Bearer token trong header Authorization.

Header

Authorization: Bearer YOUR_API_KEY

Mã Lỗi

Mã	Ý nghĩa
200	...
400	...
401	...
404	...
429	...
500	...

GET /bank/info

Thông tin ngân hàng

Lấy thông tin tổng quan của một ngân hàng theo mã BIN. Endpoint này trả về tên, logo, trạng thái kết nối và các thông tin cơ bản khác.

Tham Số

Tên	Kiểu	Bắt buộc	Mô Tả
bankCode	string	Có	Mã BIN 6 chữ số của ngân hàng (VD: 970436 cho Vietcombank)

Ví Dụ Request

curl -X GET "https://api.bankapi.vn/v1/bank/info?bankCode=970436" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.bankapi.vn/v1/bank/info?bankCode=970436",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data.bankName); // "Vietcombank"

Phản Hồi Mẫu

JSON

{
  "success": true,
  "data": {
    "bankCode": "970436",
    "bankName": "Vietcombank",
    "shortName": "VCB",
    "logo": "https://cdn.bankapi.vn/logo/vcb.png",
    "status": "active",
    "supportedFeatures": ["transfer", "qr", "lookup"]
  }
}

GET /bank/account/lookup

Tra cứu tên tài khoản

Tra cứu tên chủ tài khoản theo mã ngân hàng và số tài khoản. Dùng để xác minh người nhận trước khi chuyển khoản, tránh nhầm lẫn.

Tham Số

Tên	Kiểu	Bắt buộc	Mô Tả
bankCode	string	Có	Mã BIN ngân hàng (VD: 970436)
accountNumber	string	Có	Số tài khoản cần tra cứu (VD: 1903000123456)

Ví Dụ Request

curl -X GET "https://api.bankapi.vn/v1/bank/account/lookup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "bankCode=970436" \
  -d "accountNumber=1903000123456"

JavaScript

const params = new URLSearchParams({
  bankCode: "970436",
  accountNumber: "1903000123456"
});
const res = await fetch(
  `https://api.bankapi.vn/v1/bank/account/lookup?${params}`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data.accountName); // "NGUYEN VAN AN"

Phản Hồi Mẫu

JSON

{
  "success": true,
  "data": {
    "accountNumber": "1903000123456",
    "accountName": "NGUYEN VAN AN",
    "bankCode": "970436",
    "bankName": "Vietcombank"
  }
}

POST /bank/transfer

Chuyển khoản liên ngân hàng

Khởi tạo lệnh chuyển khoản liên ngân hàng. Giao dịch sẽ ở trạng thái PENDING trước khi được xử lý. Dùng transactionId để theo dõi trạng thái.

Tham Số

Tên	Kiểu	Bắt buộc	Mô Tả
bankCode	string	Có	Mã BIN ngân hàng đích (người nhận)
accountNumber	string	Có	Số tài khoản người nhận
amount	number	Có	Số tiền (VND), tối thiểu 1.000đ
description	string	Không	Nội dung chuyển khoản, tối đa 50 ký tự
idempotencyKey	string	Không	Khoá duy nhất để tránh giao dịch trùng lặp

Ví Dụ Request

curl -X POST "https://api.bankapi.vn/v1/bank/transfer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bankCode": "970436",
    "accountNumber": "1903000123456",
    "amount": 500000,
    "description": "Thanh toan don hang 1234"
  }'

JavaScript

const res = await fetch("https://api.bankapi.vn/v1/bank/transfer", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    bankCode: "970436",
    accountNumber: "1903000123456",
    amount: 500000,
    description: "Thanh toan don hang 1234"
  })
});
const data = await res.json();
console.log(data.data.transactionId); // "TXN8F3K2A9B"

Phản Hồi Mẫu

JSON

{
  "success": true,
  "data": {
    "transactionId": "TXN8F3K2A9B",
    "amount": 500000,
    "bankCode": "970436",
    "accountNumber": "1903000123456",
    "accountName": "NGUYEN VAN AN",
    "description": "Thanh toan don hang #1234",
    "status": "PENDING",
    "createdAt": "2025-05-09T10:30:00.000Z",
    "estimatedAt": "2025-05-09T10:30:30.000Z"
  }
}

GET /bank/qr

Tạo mã QR VietQR

Tạo mã QR chuẩn VietQR để nhận thanh toán. Mã QR trả về bao gồm ảnh base64 và URL ảnh để nhúng trực tiếp vào trang web hoặc app.

Tham Số

Tên	Kiểu	Bắt buộc	Mô Tả
bankCode	string	Có	Mã BIN ngân hàng thụ hưởng
accountNumber	string	Có	Số tài khoản thụ hưởng
accountName	string	Không	Tên chủ tài khoản (hiển thị trên QR)
amount	number	Không	Số tiền cố định (VND). Bỏ trống để người dùng tự nhập
description	string	Không	Nội dung thanh toán

Ví Dụ Request

curl -X GET "https://api.bankapi.vn/v1/bank/qr" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "bankCode=970436" \
  -d "accountNumber=1903000123456" \
  -d "accountName=NGUYEN VAN AN" \
  -d "amount=500000" \
  -d "description=Thanh toan don hang"

JavaScript

const params = new URLSearchParams({
  bankCode: "970436",
  accountNumber: "1903000123456",
  accountName: "NGUYEN VAN AN",
  amount: "500000",
  description: "Thanh toan don hang"
});
const res = await fetch(
  `https://api.bankapi.vn/v1/bank/qr?${params}`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
// Nhúng ảnh vào trang web:
document.getElementById("qr").src = data.data.qrUrl;

Phản Hồi Mẫu

JSON

{
  "success": true,
  "data": {
    "qrUrl": "https://img.vietqr.io/image/970436-1903000123456-compact2.png?amount=500000&addInfo=Thanh%20toan&accountName=NGUYEN%20VAN%20AN",
    "qrBase64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "expiresAt": "2025-05-09T10:45:00.000Z",
    "bankName": "Vietcombank",
    "accountNumber": "1903000123456",
    "accountName": "NGUYEN VAN AN"
  }
}