vietnam-qr-pay

To decode a QR string, instantiate the QRPay class with the raw content. You can then access provider, merchant, consumer, and amount information.

import { QRPay } from 'vietnam-qr-pay';

// Decoding VietQR
const vietQR = new QRPay('00020101021238530010A0000007270123000697041601092576788590208QRIBFTTA5303704540410005802VN62150811Chuyen tien6304BBB8');
console.log(vietQR.isValid); // true
console.log(vietQR.provider.name); // VIETQR
console.log(vietQR.consumer.bankBin); // 970416

// Decoding VNPay
const vnPay = new QRPay('00020101021126280010A0000007750110010531314453037045408210900005802VN5910CELLPHONES62600312CPSHN ONLINE0517021908061613127850705ONLHN0810CellphoneS63047685');
console.log(vnPay.isValid); // true
console.log(vnPay.provider.name); // VNPAY
console.log(vnPay.merchant.merchantId); // 0105313144

Install the library via npm to encode and decode VietQR and VNPayQR codes.

npm install vietnam-qr-pay

The vietnam-qr-pay library provides tools to encode and decode various Vietnamese payment QR formats, including VietQR (Static and Dynamic), MoMo, ZaloPay, and VNPay. The main entry point exports the QRPay class, various Provider implementations, and constants used for configuration and identification.

import { QRPay } from 'vietnam-qr-pay';

// Usage depends on the specific provider (VietQR, MoMo, etc.)
// See specific provider documentation for detailed implementation.

The Bank interface defines the structure for bank information used within the library. It includes identifiers like key (BankKey), code (BankCode), and bin (Bank Identification Number), as well as metadata like name, shortName, and swiftCode.

A critical field is vietQRStatus, which determines the capabilities of the bank regarding VietQR transactions. The VietQRStatus enum provides the following states:

• NOT_SUPPORTED (-1): The bank does not support VietQR.
• RECEIVE_ONLY (0): The bank can only receive payments via QR.
• TRANSFER_SUPPORTED (1): The bank supports both receiving and initiating transfers via QR.

export enum VietQRStatus {
  NOT_SUPPORTED = -1,
  RECEIVE_ONLY = 0,
  TRANSFER_SUPPORTED = 1
}

Use QRPay.initVNPayQR to generate VNPay merchant QR codes.

import { QRPay } from 'vietnam-qr-pay';

const qrPay = QRPay.initVNPayQR({
  merchantId: '0102154778',
  merchantName: 'TUGIACOMPANY',
  store: 'TU GIA COMPUTER',
  terminal: 'TUGIACO1',
})
const content = qrPay.build()
console.log(content)

You can take an existing QR content string, decode it into a QRPay instance, modify its properties (like amount or purpose), and then call .build() to generate a new valid QR string.

import { QRPay } from 'vietnam-qr-pay';

const qrContent = '00020101021238530010A0000007270123000697041601092576788590208QRIBFTTA5303704540410005802VN62150811Chuyen tien6304BBB8';
const qrPay = new QRPay(qrContent);

// Modify properties
qrPay.amount = '999999';
qrPay.additionalData.purpose = 'Cam on nhe';

// Rebuild
const newQRContent = qrPay.build();

ZaloPay QR codes also use BVBank as an intermediary. Note that ZaloPay QR codes may contain additional information in field ID 26 which this library currently ignores.

import { QRPay, BanksObject } from 'vietnam-qr-pay';

const accountNumber = '99ZP24009M07248267'
  
const zaloPayQR = QRPay.initVietQR({
  bankBin: BanksObject.banviet.bin,
  bankNumber: accountNumber,
})

const content = zaloPayQR.build()

Use QRPay.initVietQR to create a static VietQR (QR Tĩnh). A static QR does not include an amount or purpose, making it suitable for general receiving.

import { QRPay, BanksObject } from 'vietnam-qr-pay';

const qrPay = QRPay.initVietQR({
  bankBin: BanksObject.acb.bin,
  bankNumber: '257678859', // Account number
})
const content = qrPay.build()

console.log(content)
// 00020101021138530010A0000007270123000697041601092576788590208QRIBFTTA53037045802VN6304AE9F

Use QRPay.initVietQR with amount and purpose to create a dynamic VietQR (QR Động). This is used for specific transactions where the amount and description are pre-filled.

import { QRPay, BanksObject } from 'vietnam-qr-pay';

const qrPay = QRPay.initVietQR({
  bankBin: BanksObject.acb.bin,
  bankNumber: '257678859', // Account number
  amount: '10000', // Amount
  purpose: 'Chuyen tien', // Transaction purpose
})
const content = qrPay.build()

console.log(content)
// 00020101021238530010A0000007270132000697041601092576788590208QRIBFTTA53037045405100005802VN62150811Chuyen tien630453E6

The QRPay class is the primary interface for interacting with QR pay data. Use it to check validity, access parsed data, or rebuild QR content.

| Name | Type | Description |
| --- | --- | --- |
| `isValid` | `boolean` | Check if the QR code is valid |
| `initMethod` | `string` | Initialization method (`11` - Static, `12` - Dynamic) |
| `provider` | `Provider` | Provider information |
| `merchant` | `Merchant` | Merchant information |
| `consumer` | `Consumer` | Payer information |
| `amount` | `string` | Transaction amount |
| `currency` | `string` | Currency code (VNĐ: 704) |
| `nation` | `string` | Country code |
| `additionalData` | `AdditionalData` | Additional information |
| `crc` | `string` | Checksum |
| `build()` | `method` | Generates a new QR content string |

The AdditionalData object contains various metadata fields extracted from or used to build the QR code.

| Name | Description |
| --- | --- |
| `billNumber` | Bill number |
| `mobileNumber` | Mobile number |
| `store` | Store name |
| `loyaltyNumber` | Loyalty card number |
| `reference` | Reference code |
| `customerLabel` | Customer label |
| `terminal` | Terminal name |
| `purpose` | Transaction purpose/content |