Tài liệu VietQR: cấu trúc chuỗi mã, CRC, link tạo nhanh

Cấu trúc chuỗi mã

Mã VietQR là một chuỗi ký tự theo định dạng EMV® QR Code — Merchant-Presented Mode do EMVCo công bố, được NAPAS và các ngân hàng áp dụng cho dịch vụ chuyển nhanh NAPAS 247. Chuỗi gồm nhiều trường nối tiếp, mỗi trường có dạng ID (2 số) + độ dài (2 số) + giá trị.

ID	Tên trường	Giá trị dùng ở đây
`00`	Phiên bản định dạng	`01`
`01`	Kiểu khởi tạo	`11` mã tĩnh (không số tiền) · `12` mã động (có số tiền)
`38`	Thông tin người nhận (NAPAS)	Trường con `00` = `A000000727` (định danh NAPAS); `01` = [`00` BIN ngân hàng, `01` số tài khoản]; `02` = `QRIBFTTA` (chuyển nhanh đến tài khoản)
`53`	Mã tiền tệ	`704` (VND)
`54`	Số tiền	Số nguyên, có khi khách điền số tiền
`58`	Mã quốc gia	`VN`
`62`	Dữ liệu bổ sung	Trường con `03` mã cửa hàng, `07` mã điểm bán, `08` nội dung chuyển khoản (tổng tối đa 99 ký tự)
`63`	Mã kiểm tra	CRC-16 (4 ký tự hex in hoa)

Tên chủ tài khoản không nằm trong chuỗi — ứng dụng ngân hàng tự tra tên khi quét.

Ví dụ

Techcombank (BIN 970407), tài khoản 19036688889999, số tiền 2.500.000 đ, nội dung HD0012:

00 02 01
01 02 12
38 58 00 10 A000000727
      01 28 00 06 970407
            01 14 19036688889999
      02 08 QRIBFTTA
53 03 704
54 07 2500000
58 02 VN
62 10 08 06 HD0012
63 04 A938

Viết liền: 00020101021238580010A000000727012800069704070114190366888899990208QRIBFTTA5303704540725000005802VN62100806HD00126304A938

Mã kiểm tra CRC

CRC tính theo CRC-16/CCITT-FALSE (đa thức 0x1021, giá trị đầu 0xFFFF) trên toàn bộ chuỗi từ đầu đến hết 6304, rồi viết 4 ký tự hex in hoa vào cuối.

function crc16(s) {
  let c = 0xffff;
  for (const b of new TextEncoder().encode(s)) {
    c ^= b << 8;
    for (let i = 0; i < 8; i++) c = c & 0x8000 ? ((c << 1) ^ 0x1021) & 0xffff : (c << 1) & 0xffff;
  }
  return c.toString(16).toUpperCase().padStart(4, '0');
}

Link điền sẵn

Mở trang tạo mã với thông tin điền sẵn — tiện để đặt nút trên web, gửi cho nhân viên:

https://vietqr.hvsc.vn/?bank=VCB&acc=0123456789&name=NGUYEN%20VAN%20AN&amount=150000&msg=Hoc%20phi%20T10

Tham số	Ý nghĩa
`bank`	Mã / tên viết tắt / BIN ngân hàng (xem danh sách)
`acc`	Số tài khoản
`name`	Tên chủ tài khoản (in trên thẻ)
`amount`	Số tiền (VND)
`msg`	Nội dung chuyển khoản
`loai`	Loại mã khác: `vcard`, `wifi`, `link`, `text`, `sms`, `email`

Link nhận tiền

Đường link gọn, dễ đọc — người trả mở ra thấy mã và sao chép thông tin 1 chạm:

https://vietqr.hvsc.vn/ck/vcb/0123456789?tien=150000&nd=Hoc+phi+T10&ten=NGUYEN+VAN+AN

Phần	Ý nghĩa
`/ck/vcb/0123456789`	Mã ngân hàng (viết thường) và số tài khoản
`tien`	Số tiền (VND)
`nd`	Nội dung chuyển khoản
`ten`	Tên chủ tài khoản (hiển thị)
`ch` / `db`	Mã cửa hàng / mã điểm bán
`mau`	Màu chủ đạo (hex, không có #)

Thông tin nằm trong link, không lưu trên máy chủ. Link dạng cũ /thanh-toan?b=…&a=… vẫn mở được.

Mã QR động

Mã dạng https://vietqr.hvsc.vn/q/abc1234 trỏ về link bạn chọn và có thể đổi link sau khi in, xem thống kê lượt quét — cần đăng nhập, quản lý tại Mã QR động.

File hàng loạt

Xem cấu trúc cột và tải file mẫu ở trang Tạo hàng loạt. Nút Xuất CSV kèm chuỗi mã trả về chuỗi VietQR của từng dòng để đưa vào phần mềm khác (in hoá đơn, gửi email…).

Nguồn tham khảo

NAPAS — Hệ thống tạo mã VietQR: vietqr.net
EMVCo — EMV® QR Code Specification for Payment Systems: Merchant-Presented Mode: emvco.com