vietqr-core-sdk

EMVCo QR Code & NAPAS 247 Specification Guide

This document provides a comprehensive technical breakdown of the EMVCo Merchant-Presented QR Code Specification as adapted by the National Payment Corporation of Vietnam (NAPAS) for the NAPAS 247 Quick Transfer ecosystem (VietQR).


1. Overview & Format Fundamentals

VietQR utilizes the EMVCo QR Code Specification for Payment Systems (Merchant-Presented Mode). The payload is encoded as a continuous string of Tag-Length-Value (TLV) data objects:

[Tag: 2 digits][Length: 2 digits][Value: variable string]

2. Top-Level EMVCo TLV Tags

Tag Name Type Mandatory/Optional Description
00 Payload Format Indicator String (2) Mandatory Always 01 (indicates EMVCo QR Code version 1.0).
01 Point of Initiation Method String (2) Mandatory 11 = Static QR (can be used for multiple transactions), 12 = Dynamic QR (specific to a single transaction with predefined amount).
38 Merchant Account Information Sub-TLV Mandatory Contains NAPAS 247 banking routing information.
53 Transaction Currency Code String (3) Mandatory ISO 4217 numeric currency code: 704 for Vietnamese Dong (VND).
54 Transaction Amount Numeric String Optional Transaction amount (e.g., 50000, 100000). Omitted in static open-amount QRs.
58 Country Code String (2) Mandatory ISO 3166-1 alpha-2 country code: VN for Vietnam.
59 Merchant / Beneficiary Name String Optional Unaccented Latin name of beneficiary (e.g., NGUYEN VAN A).
60 Merchant City String Optional City or location (e.g., HANOI, HCM).
62 Additional Data Field Template Sub-TLV Optional Contains transaction memo, bill number, reference label, etc.
63 CRC16 Checksum Hex (4) Mandatory 4-character uppercase hexadecimal CRC16-CCITT checksum.

3. Tag 38: Merchant Account Information (NAPAS 247)

Tag 38 is a composite TLV containing sub-tags that identify the receiving bank, account/card number, and transfer service code:

38 [Len]
   00 10 A000000727                 (NAPAS Globally Unique Identifier / GUID)
   01 [Len]
      00 06 [Bank BIN]              (6-digit NAPAS Bank Identifier)
      01 [Len] [Account/Card Number](Bank Account or Card Number)
   02 08 [Service Code]             (QRIBFTTA or QRIBFTTC)

Sub-Tags Breakdown:

Sub-Tag Name Content / Format Description
00 Globally Unique Identifier (GUID) A000000727 (Length 10) NAPAS Registered Application Identifier (AID).
01 Payment Network Specific (Beneficiary) Composite Sub-TLV:  
 ↳ 00 Bank BIN Code 6 digits (e.g., 970422 MB, 970436 VCB) NAPAS Acquiring Bank BIN code.
 ↳ 01 Account or Card Number Alphanumeric (up to 19 characters) Recipient’s bank account or card number.
02 Service Code 8 characters: QRIBFTTA or QRIBFTTC • QRIBFTTA: Quick Transfer to Bank Account
• QRIBFTTC: Quick Transfer to Card Number

4. Tag 62: Additional Data Field Template

Tag 62 encodes contextual metadata about the payment:

Sub-Tag Name Description Example
01 Bill Number Invoice or invoice identifier INV-2025-001
02 Mobile Number Customer phone number 0901234567
03 Store Label Branch or physical store ID STORE01
05 Reference Label Reference code for automated reconciliation REF889911
07 Terminal Label POS or counter terminal identifier POS-01
08 Purpose / Memo Transaction description displayed in banking apps Thanh toan don hang #1042

5. CRC16-CCITT Checksum Calculation

EMVCo mandates the CRC16-CCITT-FALSE algorithm:

Calculation Steps:

  1. Construct the entire TLV string omitting the CRC:
    0002010102123854...62180814DON HANG 1042
    
  2. Append 6304 to the payload string:
    0002010102123854...62180814DON HANG 10426304
    
  3. Compute CRC16-CCITT over all bytes of this combined string.
  4. Format the resulting 16-bit integer as a 4-character uppercase hexadecimal string (padded with leading zeros if necessary, e.g., 7B9F).
  5. Append the 4 hex characters to form the final QR payload:
    0002010102123854...62180814DON HANG 104263047B9F
    

Reference Implementation (Rust):

pub fn crc16_ccitt(data: &str) -> String {
    let mut crc: u16 = 0xFFFF;
    for byte in data.bytes() {
        crc ^= (byte as u16) << 8;
        for _ in 0..8 {
            if (crc & 0x8000) != 0 {
                crc = (crc << 1) ^ 0x1021;
            } else {
                crc <<= 1;
            }
        }
    }
    format!("{:04X}", crc)
}

6. Parsing & Decoding Algorithm (TLV Parser)

To parse and validate an arbitrary VietQR payload:

  1. Verify Minimum Length: The payload must have at least 8 characters (000201 + 6304xxxx).
  2. Verify CRC16:
    • Extract the last 4 characters as expected_crc.
    • Take the substring up to the last 4 characters.
    • Recompute CRC16-CCITT and compare with expected_crc (case-insensitive).
  3. Parse TLV Sequence:
    • Read Tag (2 chars) and Length L (2 chars).
    • Read Value (next L chars).
    • If Tag is 38, recursively parse Sub-Tags 00, 01 (and its sub-tags 00 and 01), and 02.
    • If Tag is 62, recursively parse Sub-Tags 01 through 08.
    • If Tag is 54, parse numeric amount.
    • If Tag is 59, extract beneficiary name.