sonjeremy/vietqr

VietQR Code Generator Library for NAPAS247 Fast Transfer Service

dev-main 2025-12-17 12:35 UTC

Requires

• php: >=8.3
• ext-ctype: *
• ext-json: *
• ext-mbstring: *

Requires (Dev)

• endroid/qr-code: ^5.0

proprietary

• Lê Minh Sơn

README

A PHP 8.3+ library for generating VietQR codes for NAPAS247 Fast Transfer Service.

Installation

Via Composer (Recommended)

composer require sonjeremy/vietqr

Manual Installation

require_once 'QLoader.php';

Requirements

• PHP 8.3 or higher
• ext-mbstring
• ext-ctype
• ext-json

Quick Start

<?php

require 'vendor/autoload.php'; // or require 'QLoader.php';

use SonJeremy\VietQR\Generator;

// Static QR - can be used for multiple transactions
$qr = Generator::StaticToAccount('970403', '0011012345678')
    -> Build();

// Dynamic QR - single transaction with specific amount
$qr = Generator::DynamicToAccount('970436', '1234567890')
    -> Amount(180000)
    -> Purpose('Payment for order')
    -> Build();

Features

• ✅ Generate Static and Dynamic QR codes
• ✅ Support for Bank Account (QRIBFTTA) and Card (QRIBFTTC) transfers
• ✅ CRC-16-CCITT calculation (ISO/IEC 13239)
• ✅ Full VietQR specification support (ID 00-99)
• ✅ Bank BIN lookup with online API and local fallback
• ✅ Bank logo URLs
• ✅ QR code parsing and validation

Usage Examples

Generate QR with Amount and Purpose

use SonJeremy\VietQR\Generator;

$qr = Generator::DynamicToAccount('970436', '1234567890')
    -> Amount(500000)
    -> Purpose('Thanh toan don hang')
    -> Reference('INV-2024-001')
    -> BillNumber('HD-12345')
    -> Build();

Parse and Validate QR Code

use SonJeremy\VietQR\Parser;

$parser = Parser::Parse($qrData);

if ($parser -> VerifyCRC()) {
    echo "Bank: " . $parser -> GetBankBIN();
    echo "Account: " . $parser -> GetAccountNumber();
    echo "Amount: " . $parser -> GetAmount();
    echo "Purpose: " . $parser -> GetPurpose();
}

Bank List with Logo

use SonJeremy\VietQR\BankList;

// Get bank with logo
$bank = BankList::GetByBIN('970436', true);
echo $bank['name'];      // Ngân hàng TMCP Ngoại Thương Việt Nam
echo $bank['shortName']; // Vietcombank
echo $bank['logo'];      // https://cdn.vietqr.io/img/VCB.png

// Get all banks supporting transfer
$banks = BankList::GetTransferSupported(true);

// Search banks
$results = BankList::Search('Vietcom');

API Reference

Generator Methods

Method	Description
StaticToAccount($bin, $account)	Create static QR to bank account
DynamicToAccount($bin, $account)	Create dynamic QR to bank account
StaticToCard($bin, $card)	Create static QR to card
DynamicToCard($bin, $card)	Create dynamic QR to card
Amount($amount)	Set transaction amount
Purpose($purpose)	Set transaction purpose
Reference($reference)	Set reference label
BillNumber($bill)	Set bill/invoice number
MobileNumber($mobile)	Set mobile number
Build()	Generate QR data string

Parser Methods

Method	Description
Parse($qrData)	Create parser from QR string
VerifyCRC()	Verify CRC checksum
GetBankBIN()	Get bank BIN code
GetAccountNumber()	Get account number
GetAmount()	Get transaction amount
GetPurpose()	Get purpose
IsStatic() / IsDynamic()	Check QR type

BankList Methods

Method	Description
GetByBIN($bin, $logo)	Get bank by BIN
GetBINByCode($code)	Get BIN by bank code
GetLogo($bin)	Get bank logo URL
GetAll($logo)	Get all banks
Search($query, $logo)	Search banks
GetTransferSupported($logo)	Get banks supporting transfer
IsTransferSupported($bin)	Check if bank supports transfer

Running Tests

php tests/VietQRTest.php

Project Structure

├── src/
│   ├── Config.php
│   ├── CRC16.php
│   ├── DataField.php
│   ├── Generator.php
│   ├── Parser.php
│   ├── BankList.php
│   ├── Enum/
│   │   ├── InitiationMethod.php
│   │   ├── ServiceType.php
│   │   └── ...
│   └── Builder/
│       ├── AdditionalData.php
│       └── MerchantInfo.php
├── tests/
│   └── VietQRTest.php
├── composer.json
└── README.md

License

Proprietary - All rights reserved.

Author

Lê Minh Sơn [e-mail]