Download the PHP package ahr-ahr/qris-dynamic without Composer

English | Bahasa Indonesia

QRIS Dynamic

PHP library for parsing, validating, decoding, and generating dynamic QRIS payloads.

Why This Library Exists

Most QRIS-related repositories only do one thing:

• Inject amount using regex
• Replace strings blindly
• Ignore TLV structure
• Ignore CRC validation
• Fail on nested QRIS tags

This library was built differently.

qris-dynamic understands the actual QRIS payload structure using a recursive TLV parser, CRC16 validation, payload abstraction, and dynamic QRIS generation.

What is QRIS Internally?

QRIS payload is basically:

Example:

Can be read as:

So mathematically:

Where:

QRIS Anatomy

Example QRIS payload:

Visual Breakdown

Important QRIS Tags

Static vs Dynamic QRIS

Static QRIS

Static QRIS usually does not include tag 54 (transaction amount).

The customer enters the amount manually during payment.

Dynamic QRIS

Dynamic QRIS contains transaction amount.

Example:

Can be interpreted as:

This library injects the amount automatically and recalculates CRC16 safely.

CRC16 Visualization

CRC is the integrity protection layer of QRIS.

If payload changes:

then CRC becomes invalid.

Simplified CRC Flow

Nested Merchant Information

Some QRIS tags contain nested TLV values.

Example:

This library recursively parses nested structures automatically.

TLV Structure Visualization

How Parsing Works

QRIS parsing is essentially a sequential string slicing process.

The parser reads:

repeatedly until the payload ends.

Example

Payload:

Parser reads it like this:

Mathematical Interpretation

If:

then:

and:

Example:

means:

which is valid.

Sequential Parsing Algorithm

The parser works using offsets.

Pseudo flow:

Offset Visualization

Parser Complexity

The TLV parser operates in linear time complexity.

because the payload is scanned sequentially using offsets.

Nested TLV Parsing

Some QRIS tags contain another TLV structure internally.

Example:

This means the parser must recursively parse child payloads.

Recursive Parsing Visualization

Internal Parsing Flow

Why Recursive Parsing Matters

Many QRIS implementations fail because merchant account information itself contains nested TLV payloads.

Naive parsers usually:

• split incorrectly
• fail on nested tags
• break CRC generation
• generate invalid QRIS payloads

This library recursively parses nested structures safely before rebuilding the payload and recalculating CRC16.

Features

• Decode QRIS image
• Parse TLV payloads
• Recursive nested TLV parser
• Generate dynamic QRIS
• CRC16 generation & validation
• Fluent API
• Payload abstraction
• QRIS validation
• Exception hierarchy
• PHPUnit tested

Installation

Basic Usage

Generate Dynamic QRIS

Decode QRIS Image

Parse TLV Payload

Example Output

Validation Logic

QRIS validation in this library consists of two layers:

1. Structural validation
2. CRC16 checksum validation

Structural Validation

The parser verifies:

• Required tags exist
• TLV lengths are valid
• Nested payloads are parsable

Example:

is valid because:

CRC16 Validation

CRC16 ensures payload integrity.

If even one character changes:

then checksum becomes invalid.

Validation Pipeline

Validate QRIS

Quick Validation

Validation With Exceptions

Fluent API

Exception Hierarchy

Example Parsed QRIS

Project Structure

Testing

Run all tests:

Current Test Status

Roadmap

• [ ] QRIS image exporting helper
• [ ] Better merchant abstraction
• [ ] Tag specification validation
• [ ] Multi-provider QRIS utilities
• [ ] Packagist release
• [ ] GitHub Actions CI

License

This project is licensed under the MIT License.

Disclaimer

This library is an independent open-source project and is not affiliated with Bank Indonesia or any payment provider.

Use responsibly and always validate generated QRIS payloads before production use.