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

Parser Methods

BankList Methods

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 sonldn@lmsq.vn