Tài liệu VietQR API.

BeePay QR sinh mã QR chuyển khoản theo chuẩn NAPAS / EMVCo hoàn toàn offline trên server riêng — không phụ thuộc bên thứ ba. Quét được trên mọi app ngân hàng Việt Nam.

Quick Link Example

https://qr.beepay.vn/img/VCB-1031234567.png?amount=50000&addInfo=BEEPAY+HD123

Quick Start

Cách nhanh nhất là dùng Quick Link — chỉ cần URL, không cần API key, không cần backend.

https://qr.beepay.vn/img/{BANK}-{ACCOUNT}.png

Trong đó:

• {BANK} — mã ngắn ngân hàng (vd VCB, TCB, MB) hoặc BIN 6 số (970436). Xem danh sách.
• {ACCOUNT} — số tài khoản hoặc số thẻ thụ hưởng.

Thêm số tiền & nội dung

https://qr.beepay.vn/img/VCB-1031234567.png?amount=50000&addInfo=BEEPAY+HD123

Khái niệm cơ bản

• EMV / EMVCo Payload — chuỗi TLV chứa thông tin chuyển khoản, kết thúc bằng CRC16-CCITT-FALSE.
• BIN — mã định danh NAPAS 6 chữ số của ngân hàng (vd Vietcombank = 970436).
• Service Code — QRIBFTTA (chuyển tới tài khoản) hoặc QRIBFTTC (tới thẻ).
• QR tĩnh vs động — không có amount = tĩnh (người chuyển nhập số tiền); có amount = động (cố định).

Quick Link · PNG

Trả về ảnh PNG mã QR. Phù hợp nhúng trực tiếp vào <img src>, email, sticker, in ấn.

Query parameters

GET /v1/qr/image

Phiên bản verbose của Quick Link — dùng query string thay vì path.

GET /v1/qr/string

Trả về chuỗi EMV thuần (text/plain). Dùng khi bạn muốn tự render QR ở client (vd với thư viện qrcode.js).

00020101021238540010A00000072701240006970436011010312345670208QRIBFTTA5204000053037045405500005802VN62150811BEEPAY HD12363046A8E

POST /v1/qr/generate

Trả về JSON đầy đủ gồm chuỗi EMV + ảnh PNG base64 + metadata. Dùng khi build app/dashboard.

Request body

{
  "bank": "VCB",
  "accountNo": "1031234567",
  "amount": "50000",
  "addInfo": "BEEPAY HD123",
  "serviceCode": "QRIBFTTA"
}

Response · 200 OK

{
  "bank": { "code": "VCB", "bin": "970436", "shortName": "Vietcombank" },
  "accountNo": "1031234567",
  "amount": "50000",
  "addInfo": "BEEPAY HD123",
  "serviceCode": "QRIBFTTA",
  "emv": "00020101021238540010A00...63046A8E",
  "qrBase64": "data:image/png;base64,iVBORw0KGgoA..."
}

GET /v1/banks

Trả về danh sách 47 ngân hàng VN kèm BIN NAPAS, mã ngắn, SWIFT.

{
  "count": 47,
  "banks": [
    { "code": "VCB", "bin": "970436", "name": "Ngân hàng TMCP Ngoại Thương Việt Nam", "shortName": "Vietcombank", "swift": "BFTVVNVX" },
    ...
  ]
}

Tham số đầy đủ

Service codes

Mã lỗi

Examples

# Tải PNG về
curl -o qr.png "https://qr.beepay.vn/img/VCB-1031234567.png?amount=50000&addInfo=BEEPAY+HD123"

# Lấy chuỗi EMV
curl "https://qr.beepay.vn/v1/qr/string?bank=VCB&accountNo=1031234567&amount=50000"

# POST → JSON đầy đủ
curl -X POST https://qr.beepay.vn/v1/qr/generate \
  -H "Content-Type: application/json" \
  -d '{"bank":"VCB","accountNo":"1031234567","amount":"50000"}'

const res = await fetch("https://qr.beepay.vn/v1/qr/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    bank: "VCB",
    accountNo: "1031234567",
    amount: "50000",
    addInfo: "BEEPAY HD123",
  }),
});
const { emv, qrBase64 } = await res.json();
console.log(emv);

import requests

r = requests.post(
    "https://qr.beepay.vn/v1/qr/generate",
    json={
        "bank": "VCB",
        "accountNo": "1031234567",
        "amount": "50000",
    },
)
data = r.json()
print(data["emv"])

<!-- Nhúng trực tiếp ảnh QR -->
<img src="https://qr.beepay.vn/img/VCB-1031234567.png?amount=50000&addInfo=BEEPAY+HD123"
     width="320" alt="VietQR" />

Deeplink · Universal /pay

Một URL duy nhất, mở trên mobile sẽ tự bật app ngân hàng và điền sẵn thông tin chuyển khoản. Trên desktop, hiển thị landing page có QR + tên người nhận.

Tương thích contract của dl.vietqr.io/pay — bạn có thể đổi domain trong link sẵn có và dùng ngay.

Query parameters

https://qr.beepay.vn/pay?app=acb&ba=5847@ACB&am=100000&tn=BEEPAY+HD123

POST /v1/deeplink

Build URL deeplink theo định dạng chuẩn từ thông tin chuyển khoản.

{
  "bank": "ACB",
  "accountNo": "5847",
  "amount": "100000",
  "addInfo": "BEEPAY HD123"
}

{
  "url": "https://qr.beepay.vn/pay?app=acb&ba=5847@ACB&am=100000&tn=BEEPAY+HD123",
  "status": "supported",
  "app": "acb"
}

Ngân hàng hỗ trợ deeplink

Endpoint GET /v1/deeplinks trả về registry đầy đủ.

Danh sách BIN ngân hàng

Endpoint GET /v1/banks trả về đầy đủ. Một số mã thông dụng: