vietqr-core-sdk

Đặc Tả Kỹ Thuật Chuẩn EMVCo QR Code & NAPAS 247 (VietQR)

Tài liệu này cung cấp chi tiết kỹ thuật chuyên sâu về cấu trúc chuỗi Mã QR chuẩn EMVCo Merchant-Presented áp dụng cho mạng lưới Chuyển Nhanh NAPAS 247 (VietQR) của các ngân hàng Việt Nam.


1. Nguyên Lý & Định Dạng Cơ Bản

Chuỗi mã thanh toán VietQR tuân thủ nghiêm ngặt chuẩn quốc tế EMVCo QR Code Specification for Payment Systems (Merchant-Presented Mode). Dữ liệu được mã hóa liên tục dưới dạng các trường Tag-Length-Value (TLV):

[Tag: 2 chữ số][Length: 2 chữ số][Value: chuỗi nội dung]

2. Bảng Danh Mục Các Tag EMVCo Cấp Cao

Tag Tên Trường Kiểu Dữ Liệu Bắt Buộc / Tuỳ Chọn Ý Nghĩa Kỹ Thuật
00 Payload Format Indicator Chuỗi (2) Bắt buộc Luôn cố định là 01 (phiên bản EMVCo QR 1.0).
01 Point of Initiation Method Chuỗi (2) Bắt buộc 11 = QR Tĩnh (dùng nhiều lần, không gắn số tiền cố định), 12 = QR Động (giao dịch một lần, gắn số tiền).
38 Merchant Account Information Sub-TLV Bắt buộc Định danh ngân hàng thụ hưởng và số tài khoản/thẻ theo chuẩn NAPAS 247.
53 Transaction Currency Code Chuỗi (3) Bắt buộc Mã tiền tệ ISO 4217: 704 (Đồng Việt Nam - VND).
54 Transaction Amount Chuỗi số Tuỳ chọn Số tiền giao dịch (ví dụ: 50000, 1500000). Bỏ qua nếu là mã QR tĩnh mở.
58 Country Code Chuỗi (2) Bắt buộc Mã quốc gia ISO 3166-1 alpha-2: VN.
59 Merchant Name Chuỗi Tuỳ chọn Tên người thụ hưởng (viết hoa không dấu, ví dụ: NGUYEN VAN A).
60 Merchant City Chuỗi Tuỳ chọn Thành phố của điểm chấp nhận thanh toán (ví dụ: HANOI, HCM).
62 Additional Data Field Template Sub-TLV Tuỳ chọn Chứa nội dung chuyển tiền, số hóa đơn, số điện thoại, mã tham chiếu.
63 CRC16 Checksum Hex (4) Bắt buộc Mã kiểm tra toàn vẹn 4 ký tự thập lục phân viết hoa.

3. Chi Tiết Tag 38: Thông Tin Tài Khoản Thụ Hưởng (NAPAS 247)

Tag 38 là một cụm Sub-TLV lồng nhau chứa thông tin định tuyến liên ngân hàng NAPAS 247:

38 [Len]
   00 10 A000000727                 (NAPAS AID - Globally Unique Identifier)
   01 [Len]
      00 06 [Mã BIN Ngân Hàng]     (Mã BIN 6 số của ngân hàng thụ hưởng)
      01 [Len] [Số Tài Khoản/Thẻ]   (Số tài khoản hoặc số thẻ thụ hưởng)
   02 08 [Mã Dịch Vụ]              (QRIBFTTA hoặc QRIBFTTC)

Các Sub-Tag bên trong Tag 38:

Sub-Tag Tên Trường Định Dạng Mô Tả
00 GUID A000000727 (Độ dài 10) Mã định danh toàn cầu duy nhất của cổng NAPAS.
01 Payment Network Specific Sub-TLV lồng: Thông tin chi tiết điểm nhận tiền:
 ↳ 00 Mã BIN Ngân Hàng 6 chữ số (ví dụ: 970422 MB, 970436 VCB) Mã ngân hàng thụ hưởng định danh theo chuẩn NAPAS.
 ↳ 01 Số Tài Khoản / Thẻ Chuỗi ký tự số (tối đa 19 ký tự) Số tài khoản ngân hàng hoặc số thẻ thanh toán.
02 Mã Dịch Vụ (Service Code) 8 ký tự • QRIBFTTA: Chuyển nhanh đến Tài khoản ngân hàng.
• QRIBFTTC: Chuyển nhanh đến Số thẻ (Card Number).

4. Chi Tiết Tag 62: Dữ Liệu Bổ Sung Giao Dịch

Tag 62 chứa các thông tin phụ trợ phục vụ đối soát và gạch nợ tự động:

Sub-Tag Tên Trường Ý Nghĩa Ví Dụ
01 Bill Number Số hóa đơn / Mã phiếu thu INV-2025-001
02 Mobile Number Số điện thoại khách hàng 0901234567
03 Store Label Mã cửa hàng / Điểm bán STORE01
05 Reference Label Mã tham chiếu đối soát tự động REF889911
07 Terminal Label Mã máy POS / Thiết bị thanh toán POS-01
08 Purpose / Memo Nội dung chuyển khoản hiển thị trên app ngân hàng HB1042 thanh toan hosting

5. Thuật Toán Tính Toán CRC16-CCITT

Chuẩn EMVCo quy định bắt buộc sử dụng thuật toán CRC16-CCITT-FALSE:

Quy trình tính toán:

  1. Tạo toàn bộ chuỗi TLV ngoại trừ trường CRC:
    0002010102123854...62180814DON HANG 1042
    
  2. Nối thêm tiền tố 6304 vào cuối chuỗi:
    0002010102123854...62180814DON HANG 10426304
    
  3. Tính toán giá trị CRC16 theo thuật toán trên trên toàn bộ các byte của chuỗi này.
  4. Chuyển đổi số nguyên 16-bit nhận được thành chuỗi thập lục phân 4 ký tự viết hoa (có thêm 0 ở đầu nếu nhỏ hơn 4 chữ số, ví dụ: 7B9F).
  5. Ghép vào chuỗi để tạo mã QR hoàn chỉnh:
    0002010102123854...62180814DON HANG 104263047B9F
    

6. Thuật Toán Phân Tích & Giải Mã (TLV Parser)

Các bước kiểm tra và bóc tách dữ liệu từ một chuỗi VietQR bất kỳ:

  1. Kiểm tra độ dài tối thiểu: Chuỗi phải có độ dài tối thiểu 8 ký tự (000201 + 6304xxxx).
  2. Kiểm tra tính toàn vẹn CRC16:
    • Tách 4 ký tự cuối cùng làm expected_crc.
    • Lấy chuỗi đứng trước 4 ký tự cuối.
    • Tính toán lại CRC16 và so sánh với expected_crc. Nếu không khớp, trả về lỗi mã QR bị sai lệch.
  3. Phân tích tuần tự chuỗi TLV:
    • Đọc 2 ký tự Tag, 2 ký tự Length L.
    • Cắt chuỗi Value có độ dài L.
    • Đối với Tag 38, tiếp tục phân tích đệ quy Sub-Tag 00, 01 (và tiếp tục tách 00, 01 bên trong), 02.
    • Đối với Tag 62, tiếp tục phân tích các Sub-Tag từ 01 đến 08.
    • Trích xuất số tiền tại Tag 54, tên người thụ hưởng tại Tag 59.