README

Generate VietQR codes for Vietnamese bank transfers. Follows NAPAS VietQR v1.5.2 specification (EMVCo standard).

Features

Static & Dynamic QR - Reusable or one-time payment codes
Account & Card Transfers - IBFT to bank accounts or cards
50+ Vietnamese Banks - Type-safe bank enum with BIN codes
Multiple Formats - SVG, PNG, PDF, Base64 image generation
Laravel Integration - Service provider, facade, Laravel 10/11/12
NAPAS Compliant - Verified against official specification

Requirements

PHP 8.2+
Laravel 10, 11, or 12

Installation

composer require takashato/laravel-vietqr

The package auto-registers via service provider.

Quick Start

Simple Bank Account QR (Static)

use Takashato\VietQr\VietQrCode;
use Takashato\VietQr\Enums\Bank;

// Static QR - customer enters amount
$qr = VietQrCode::bankAccount(Bank::VIETCOMBANK, '0011012345678');

// Get QR string (for your own rendering)
$qrString = $qr->build();

// Generate SVG
$svg = $qr->generateQr('svg', 300);

// Generate Base64 PNG
$base64 = $qr->generateQrBase64('png', 300);

Dynamic QR with Amount

use Takashato\VietQr\VietQrCode;
use Takashato\VietQr\Enums\Bank;

// Dynamic QR - fixed amount of 180,000 VND
$qr = VietQrCode::bankAccount(
    bank: Bank::TECHCOMBANK,
    accountNumber: '19033123456789',
    amount: 180000,
    purpose: 'Thanh toan don hang #12345'
);

echo $qr->build();

Card Transfer QR

use Takashato\VietQr\VietQrCode;
use Takashato\VietQr\Enums\Bank;

$qr = VietQrCode::bankCard(
    bank: Bank::MB_BANK,
    cardNumber: '9704229012345678',
    amount: 50000
);

Advanced Usage

Fluent Builder API

use Takashato\VietQr\VietQrCode;
use Takashato\VietQr\Data\MerchantInfo;
use Takashato\VietQr\Data\AdditionalInfo;
use Takashato\VietQr\Enums\Service;

$qr = (new VietQrCode())
    ->dynamicMethod()
    ->withMerchant(function (MerchantInfo $merchant) {
        $merchant
            ->setService(Service::NAPAS_BY_ACCOUNT)
            ->setAcquirerId('970436')  // Vietcombank BIN
            ->setMerchantId('0011012345678');
    })
    ->amount(180000)
    ->withAdditionalInfo(function (AdditionalInfo $info) {
        $info
            ->terminalLabel('POS001')
            ->purpose('Thanh toan don hang');
    })
    ->build();

Using Bank Enum

use Takashato\VietQr\Enums\Bank;

// Get bank BIN code
$bin = Bank::VIETCOMBANK->value; // '970436'

// Get bank names
$shortName = Bank::VIETCOMBANK->shortName(); // 'Vietcombank'
$fullName = Bank::VIETCOMBANK->nameVi(); // 'Ngân hàng TMCP Ngoại thương Việt Nam'

// Find bank by BIN
$bank = Bank::fromBin('970436'); // Bank::VIETCOMBANK

// Search banks
$results = Bank::search('viet'); // Returns matching Bank enums

Using Facade

use Takashato\VietQr\Facades\VietQr;

$qr = VietQr::create()
    ->staticMethod()
    ->withMerchant(...)
    ->build();

Available Banks

The Bank enum includes 50+ Vietnamese banks:

State-owned: Vietcombank, VietinBank, BIDV, Agribank

Joint-stock: Techcombank, MB Bank, ACB, VPBank, Sacombank, TPBank, HDBank, VIB, SHB, SCB, OCB, MSB, Eximbank, SeABank, LienVietPostBank, ABBank, and more...

Foreign branches: HSBC, Standard Chartered, Shinhan Bank, UOB, Woori Bank, CIMB, and more...

E-wallets: VNPT Money, CAKE, Ubank, Timo, TNEX

QR Code Types

Type	Method	Amount	Use Case
Static	`staticMethod()`	Customer enters	Store display, reusable
Dynamic	`dynamicMethod()`	Fixed in QR	Invoice, one-time payment

Services

Service	Enum	Description
NAPAS_BY_ACCOUNT	`Service::NAPAS_BY_ACCOUNT`	Transfer to bank account
NAPAS_BY_CARD	`Service::NAPAS_BY_CARD`	Transfer to bank card
QR_CASH	`Service::QR_CASH`	ATM cash withdrawal
QR_PUSH	`Service::QR_PUSH`	Product payment

Blade Usage

{{-- SVG directly in HTML --}}
{!! VietQrCode::bankAccount(Bank::BIDV, '12345678901')->generateQr('svg', 250) !!}

{{-- Base64 image --}}
<img src="data:image/png;base64,{{ VietQrCode::bankAccount(Bank::BIDV, '12345678901')->generateQrBase64('png', 250) }}" alt="VietQR">

Documentation

Comprehensive documentation is available in the /docs directory:

Project Overview & PDR - Feature list, requirements, roadmap
System Architecture - Component design, data flow, EMVCo structure
Codebase Summary - File structure, design patterns, code organization
Code Standards - Development guidelines, naming conventions, quality checks

Testing

composer test

Code Quality

# Format code with Pint
composer format

# Run static analysis
composer analyse

Security

For security vulnerabilities, please email takashato@gmail.com.

Credits

License

MIT License. See LICENSE.md.

takashato / laravel-vietqr

Maintainers

Details