PHPackages                             liopay/vietqr - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. liopay/vietqr

ActiveLibrary[Payment Processing](/categories/payments)

liopay/vietqr
=============

Production-ready PHP library for building and parsing VietQR (NAPAS FastFund 24/7 IBFT) QR codes compliant with EMVCo 1.5.2 specification.

v1.0.0(5mo ago)3131MITPHPPHP >=7.4CI passing

Since Nov 13Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/liopayvn/vietqr-php)[ Packagist](https://packagist.org/packages/liopay/vietqr)[ Docs](https://liopay.vn)[ RSS](/packages/liopay-vietqr/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

VietQR
======

[](#vietqr)

[![Latest Version](https://camo.githubusercontent.com/9b469ce7b3311388ad49bc4ed78c8bc6ea150a676471e826acbc598e2b9cf90f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c696f7061792f7669657471722e737667)](https://packagist.org/packages/liopay/vietqr)[![PHP Version](https://camo.githubusercontent.com/204b1791e3a57f86a93de1422b2a6e584f5045431629c5b9abd4e28dbc8b5357/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d626c75652e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Total Downloads](https://camo.githubusercontent.com/deeefa9cbf0542dcafff967bca704e275b889892601a9040e10f0a81c49d1eaa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c696f7061792f7669657471722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/liopay/vietqr)

**English** | **[Tiếng Việt](README.vi.md)**

Production-ready PHP library for building and parsing VietQR (NAPAS FastFund 24/7 IBFT) QR codes compliant with EMVCo 1.5.2 specification.

Features
--------

[](#features)

- **EMVCo 1.5.2 Compliant** - Follows NAPAS QR Switching specification v1.5.2
- **Build QR Codes** - Generate QR codes for all service types (PUSH/CASH/IBFT)
- **Parse QR Strings** - Parse any VietQR string into structured data
- **Full Validation** - Comprehensive validation per NAPAS specification
- **CRC16-CCITT** - Automatic checksum calculation and verification
- **Zero Dependencies** - No external runtime dependencies
- **PHP 7.4+** - Strict typing throughout
- **PSR-4 Autoloading** - Modern PHP package structure

Installation
------------

[](#installation)

```
composer require liopay/vietqr
```

Quick Start
-----------

[](#quick-start)

### Build an Inter-Bank Fund Transfer QR Code

[](#build-an-inter-bank-fund-transfer-qr-code)

```
use Liopay\VietQR\Builder\QRIBFTBuilder;

$builder = new QRIBFTBuilder();

$qrString = $builder
    ->setPointOfInitiation('12') // Dynamic QR
    ->setBeneficiaryBankBin('970436')
    ->setConsumerId('1017595600')
    ->setIBFTToAccount()
    ->setAmount('180000')
    ->setPurposeOfTransaction('thanh toan don hang')
    ->build();

// Result: 00020101021238540010A00000072701240006970436011010175956000208QRIBFTTA530370454061800005802VN62230819thanh toan don hang630470FA
```

### Parse a QR Code

[](#parse-a-qr-code)

```
use Liopay\VietQR\Parser\QRParser;

$parser = new QRParser();

$qrData = $parser->parse($qrString);

echo $qrData->getConsumerId(); // "1017595600"
echo $qrData->getAmount(); // "180000"
echo $qrData->getServiceCode(); // "QRIBFTTA"
echo $qrData->getPurposeOfTransaction(); // "thanh toan don hang"
```

Service Types
-------------

[](#service-types)

VietQR supports four service types:

### 1. **QRIBFTTA** - Inter-Bank Fund Transfer to Account

[](#1-qribftta---inter-bank-fund-transfer-to-account)

Peer-to-peer transfer to bank account.

```
$builder = new QRIBFTBuilder();
$qr = $builder
    ->setPointOfInitiation('12') // Dynamic
    ->setBeneficiaryBankBin('970436')
    ->setConsumerId('1017595600')
    ->setIBFTToAccount()
    ->setAmount('180000')
    ->setPurposeOfTransaction('thanh toan don hang')
    ->build();
```

### 2. **QRIBFTTC** - Inter-Bank Fund Transfer to Card

[](#2-qribfttc---inter-bank-fund-transfer-to-card)

Peer-to-peer transfer to card number.

```
$builder = new QRIBFTBuilder();
$qr = $builder
    ->setPointOfInitiation('12') // Dynamic
    ->setBeneficiaryBankBin('970436')
    ->setConsumerId('9704361017595600')
    ->setIBFTToCard()
    ->setAmount('180000')
    ->build();
```

### 3. **QRPUSH** - Payment Service

[](#3-qrpush---payment-service)

Standard merchant payment QR codes.

```
$builder = new QRPushBuilder();
$qr = $builder
    ->setPointOfInitiation('12') // Dynamic
    ->setAcquirerBankBin('970436')
    ->setMerchantId('1017595600')
    ->setMerchantCategoryCode('5812')
    ->setAmount('180000')
    ->setMerchantName('NGO QUOC DAT')
    ->setMerchantCity('HANOI')
    ->build();
```

### 4. **QRCASH** - ATM Cash Withdrawal

[](#4-qrcash---atm-cash-withdrawal)

QR codes for ATM cash withdrawal. **Note**: Reference Label and Terminal Label are mandatory.

```
$builder = new QRCashBuilder();
$qr = $builder
    ->setPointOfInitiation('12') // Must be dynamic
    ->setAcquirerBankBin('970436')
    ->setATMId('12345678')
    ->setCashService() // Sets service code to QRCASH
    ->setMerchantCategoryCode('6011')
    ->setMerchantName('NGO QUOC DAT')
    ->setMerchantCity('HANOI')
    ->setReferenceLabel('20190109155714228384') // Required
    ->setTerminalLabel('0000111') // Required
    ->build();
```

Specification Constants
-----------------------

[](#specification-constants)

### Required Values

[](#required-values)

- **AID**: `A000000727` (NAPAS Application Identifier)
- **Currency**: `704` (VND - Vietnamese Dong)
- **Country**: `VN` (Vietnam)

### Data Object IDs (Root Level)

[](#data-object-ids-root-level)

IDNameRequired00Payload Format Indicator✓01Point of InitiationOptional38Merchant Account Information✓52Merchant Category Code✓53Transaction Currency✓54Transaction AmountConditional58Country Code✓59Merchant Name✓60Merchant City✓62Additional Data FieldOptional63CRC Checksum✓### Point of Initiation Values

[](#point-of-initiation-values)

- `11` - Static QR (reusable for multiple transactions)
- `12` - Dynamic QR (single-use transaction)

TLV Encoding
------------

[](#tlv-encoding)

VietQR uses TLV (Tag-Length-Value) encoding:

```
Format: ID (2 digits) + Length (2 digits) + Value (variable)
Example: "59" + "12" + "NGO QUOC DAT"

```

```
$tlvHelper = new TLVHelper();

// Encode
$encoded = $tlvHelper->encode('59', 'NGO QUOC DAT');
// Result: "5912NGO QUOC DAT"

// Decode
$decoded = $tlvHelper->decode($encoded);
// Result: ['59' => 'NGO QUOC DAT']
```

CRC Checksum
------------

[](#crc-checksum)

VietQR uses **CRC16-CCITT False**:

- Polynomial: `0x1021`
- Init Value: `0xFFFF`
- Applied to all data including `"6304"` but excluding CRC value

```
$crcHelper = new CRCHelper();

// Calculate
$crc = $crcHelper->calculate($data);

// Verify
$isValid = $crcHelper->verify($qrString);

// Append to QR data
$completeQR = $crcHelper->append($qrData);
```

Validation
----------

[](#validation)

All builders perform automatic validation:

- ✓ Field length constraints
- ✓ Required field presence
- ✓ Format validation (numeric, alphanumeric)
- ✓ MCC code validation
- ✓ Service code validation
- ✓ CRC checksum calculation
- ✓ Additional Data Field mandatory fields per QR type

Exception Handling
------------------

[](#exception-handling)

```
use Liopay\VietQR\Exception\{
    VietQRException,
    InvalidFormatException,
    InvalidCRCException,
    ValidationException,
    MissingRequiredFieldException
};

try {
    $qr = $builder->build();
} catch (MissingRequiredFieldException $e) {
    // Handle missing required field
} catch (ValidationException $e) {
    // Handle validation error
} catch (VietQRException $e) {
    // Handle general VietQR error
}
```

Value Objects
-------------

[](#value-objects)

Immutable, validated value objects for type safety:

```
use Liopay\VietQR\ValueObject\{
    ServiceCode,
    PointOfInitiation
};

// Service Code
$serviceCode = new ServiceCode('QRPUSH');
$serviceCode->isPayment(); // true
$serviceCode->isIBFT(); // false

// Point of Initiation
$poi = PointOfInitiation::static();
$poi->isStatic(); // true
$poi->getValue(); // "11"
```

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Run PHPStan static analysis:

```
composer phpstan
```

Check code style:

```
composer cs-check
```

Fix code style:

```
composer cs-fix
```

Requirements
------------

[](#requirements)

- PHP >= 7.4

Specification Compliance
------------------------

[](#specification-compliance)

This library implements:

- **NAPAS QR Switching Technical Specifications v1.5.2**
- **EMVCo QR Code Specification for Payment Systems: Merchant-Presented Mode**

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

Credits
-------

[](#credits)

Developed by [Liopay](https://liopay.vn)

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

Support
-------

[](#support)

For issues and questions, please use the [GitHub issue tracker](https://github.com/liopayvn/vietqr-php/issues).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance70

Regular maintenance activity

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

179d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b5dca3124d040fb5f1e59100485f3a23e42e4e4b1c6d89c5d4cd3e79d95f574e?d=identicon)[Ngô Quốc Đạt](/maintainers/Ng%C3%B4%20Qu%E1%BB%91c%20%C4%90%E1%BA%A1t)

---

Top Contributors

[![datlechin](https://avatars.githubusercontent.com/u/56961917?v=4)](https://github.com/datlechin "datlechin (18 commits)")

---

Tags

qr codepaymentqr-generatorbank transfervietqrEMVCoQR-Paymentvietnamnapasfastfundibftvietnamese-paymentqr-parser

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/liopay-vietqr/health.svg)

```
[![Health](https://phpackages.com/badges/liopay-vietqr/health.svg)](https://phpackages.com/packages/liopay-vietqr)
```

###  Alternatives

[henryejemuta/laravel-monnify

A laravel package to seamlessly integrate monnify api within your laravel application

132.1k](/packages/henryejemuta-laravel-monnify)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)