Tài liệu API VietQR

Hướng dẫn tích hợp mã QR thanh toán VietQR vào website

1. Cấu trúc URL

Base URL

https://qr.tingee.vn/vietqr

Cú pháp đầy đủ

https://qr.tingee.vn/vietqr?bankBin={BIN}&accountNumber={STK}&accountName={TEN}&amount={SOTIEN}&description={NOIDUNG}&theme={THEME}&size={SIZE}

2. Tham số API

Tham số	Bắt buộc	Kiểu	Mô tả
`bankBin`	✓	string	Mã BIN ngân hàng (6 số). VD: `970436`
`accountNumber`	✓	string	Số tài khoản ngân hàng
`accountName`	-	string	Tên chủ tài khoản (hiển thị với theme `frame-account`)
`amount`	-	number	Số tiền (VNĐ). VD: `50000`
`description`	-	string	Nội dung chuyển khoản
`theme`	-	string	`qr` - Chỉ mã QR cơ bản `qr-logo` - Mã QR có logo VietQR ở giữa `frame` - Hiển thị đầy đủ với khung, logo ngân hàng, NAPAS, VietQR `frame-account` - Giống frame + hiển thị số TK và tên chủ TK Mặc định: `qr`
`size`	-	number	Kích thước (px). Min: 200, Max: 2000. Mặc định: `720`

Danh sách mã BIN ngân hàng

970416ACB

970405Agribank

970409BacABank

970418BIDV

970446COOPBANK

970431Eximbank

970437HDBank

970452KienLongBank

970449LPBank

970422MBBank

970426MSB

970428NamABank

970419NCB

970448OCB

970403Sacombank

970429SCB

970440SeABank

970443SHB

970407Techcombank

970423TPBank

970441VIB

970454VietCapitalBank

970436Vietcombank

970415VietinBank

970432VPBank

3. Cách sử dụng

3.1. Nhúng trực tiếp vào HTML

Sử dụng thẻ <img> để hiển thị QR code:

<img 
  src="https://qr.tingee.vn/vietqr?bankBin=970436&accountNumber=190367899999&amount=50000&description=Thanh toan don hang&theme=frame"
  alt="VietQR Payment"
  style="max-width: 360px; width: 100%;"
/>

3.2. Tải ảnh về (Download)

Sử dụng fetch API để tải ảnh QR code:

async function downloadQR(orderId, amount) {
  const url = `https://qr.tingee.vn/vietqr?bankBin=970436&accountNumber=190367899999&amount=${amount}&description=DH${orderId}&theme=frame`;
  
  const response = await fetch(url);
  const blob = await response.blob();
  const downloadUrl = URL.createObjectURL(blob);
  
  const a = document.createElement('a');
  a.href = downloadUrl;
  a.download = `qr-${orderId}.png`;
  a.click();
  
  URL.revokeObjectURL(downloadUrl);
}

4. Ví dụ thực tế

React/Next.js

export function PaymentQR({ orderId, amount }) {
  const qrUrl = `https://qr.tingee.vn/vietqr?bankBin=970436&accountNumber=190367899999&amount=${amount}&description=DH${orderId}&theme=frame-account`;
  
  return (
    <div>
      <h3>Quét mã để thanh toán</h3>
      <img src={qrUrl} alt="QR" style={{ maxWidth: '360px', width: '100%' }} />
      <p>Số tiền: {amount.toLocaleString('vi-VN')} đ</p>
    </div>
  );
}

PHP

<?php
function generateVietQR($bankBin, $accountNumber, $amount, $description) {
    $params = http_build_query([
        'bankBin' => $bankBin,
        'accountNumber' => $accountNumber,
        'amount' => $amount,
        'description' => $description,
        'theme' => 'frame',
        'size' => 720
    ]);
    
    return "https://qr.tingee.vn/vietqr?" . $params;
}

$qrUrl = generateVietQR('970436', '190367899999', 500000, 'Thanh toan don hang');
echo "<img src='$qrUrl' alt='QR' style='max-width: 360px;' />";
?>

Python

from urllib.parse import urlencode

def generate_vietqr_url(bank_bin, account_number, amount, description):
    params = {
        'bankBin': bank_bin,
        'accountNumber': account_number,
        'amount': amount,
        'description': description,
        'theme': 'frame',
        'size': 720
    }
    return f"https://qr.tingee.vn/vietqr?{urlencode(params)}"

qr_url = generate_vietqr_url('970436', '190367899999', 500000, 'Don hang 123')
print(f'<img src="{qr_url}" alt="QR" style="max-width: 360px;" />')