Download the PHP package dhank77/qris-dinamis without Composer
On this page you can find all versions of the php package dhank77/qris-dinamis. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download dhank77/qris-dinamis
More information about dhank77/qris-dinamis
Files in dhank77/qris-dinamis
Package qris-dinamis
Short Description Convert static QRIS to dynamic QRIS in PHP: parse, validate, inject amount & service fee, recalculate CRC16. Zero dependencies.
License MIT
Homepage https://github.com/dhank77/qris-dinamis
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package qris-dinamis
QRIS Dinamis for PHP
Ubah QRIS statis menjadi QRIS dinamis (dengan nominal) langsung dari PHP.
Parse, validasi, tambah biaya layanan, dan hitung ulang CRC16 — tanpa dependensi.
Instalasi • Mulai Cepat • Panduan • Referensi API • Contoh • Cara Kerja • FAQ
Daftar Isi
- Apa itu QRIS dinamis?
- Fitur
- Persyaratan
- Instalasi
- Mulai Cepat
- Mendapatkan string QRIS statis
- Panduan Pemakaian
- 1. Konversi ke dinamis
- 2. Menambahkan biaya layanan
- 3. Validasi
- 4. Membaca isi QRIS
- 5. Menangani error
- 6. Membuat gambar QR
- 7. Command line (CLI)
- 8. Web demo
- Integrasi Framework
- Laravel
- CodeIgniter 4
- PHP native
- Referensi API
- Contoh
- Cara Kerja
- FAQ
- Testing
- Kontribusi
- Kredit & Lisensi
Apa itu QRIS dinamis?
QRIS (Quick Response Code Indonesian Standard) adalah standar QR pembayaran dari Bank Indonesia. Satu kode QR bisa dibayar lewat semua aplikasi bank dan e-wallet (GoPay, OVO, DANA, ShopeePay, m-banking, dll).
| Jenis | Keterangan |
|---|---|
| Statis | QR tanpa nominal. Pembeli mengetik sendiri jumlah yang dibayar. Biasanya dicetak dan ditempel di kasir. |
| Dinamis | QR dengan nominal yang sudah terisi. Pembeli cukup scan lalu konfirmasi. |
Library ini mengambil QRIS statis milik toko Anda, menyisipkan nominal (dan opsional biaya layanan), lalu menghitung ulang checksum sehingga menjadi QRIS dinamis yang valid. Uang tetap masuk ke rekening/merchant yang sama.
Fitur
- ✅ Konversi statis → dinamis dengan nominal tertentu
- ✅ Biaya layanan tetap (Rupiah) atau persentase
- ✅ Validasi struktur TLV, tag wajib, dan checksum CRC16
- ✅ Parser — nama merchant, kota, kode pos, NMID, issuer, MCC, mata uang, dll
- ✅ Konversi ulang QRIS yang sudah dinamis (nominal lama diganti)
- ✅ Exception yang jelas dengan daftar error rinci
- ✅ CLI untuk konversi cepat dari terminal
- ✅ Web demo lengkap: upload gambar, scan kamera, paste screenshot, unduh QR
- ✅ Nol dependensi, PHP 8.1+
- ✅ Output identik byte-per-byte dengan versi TypeScript asli
Persyaratan
- PHP 8.1 atau lebih baru
- Tidak ada ekstensi khusus yang wajib
- Opsional:
chillerlan/php-qrcodejika ingin membuat gambar QR di server
Instalasi
Untuk membuat gambar QR di server (opsional):
Tanpa Composer
Unduh repositori ini, lalu:Mulai Cepat
String $dynamic tinggal diubah menjadi gambar QR (lihat Membuat gambar QR) dan ditampilkan ke pembeli.
Mendapatkan string QRIS statis
Library ini bekerja dengan string QRIS, bukan gambar. Cara mendapatkan string dari QRIS statis toko Anda:
- Unduh / foto gambar QRIS statis dari aplikasi merchant (DANA Bisnis, GoBiz, OVO Merchant, QRIS bank, dll).
- Baca isinya dengan salah satu cara:
- Jalankan web demo, klik Upload Image, lalu salin string yang muncul.
- Pakai aplikasi pemindai QR apa pun di HP, lalu salin teks hasil scan.
- String yang benar selalu diawali
000201dan diakhiri6304+ 4 karakter checksum. - Simpan di konfigurasi (mis.
.env), bukan diterima dari input pengguna.
Cek apakah string sudah benar:
Panduan Pemakaian
Semua fungsi utama tersedia sebagai method statis di class QrisDinamis\Qris.
1. Konversi ke dinamis
$amountadalah nominal dalam Rupiah, harus lebih dari 0.- Input boleh mengandung spasi / baris baru di awal dan akhir — otomatis di-trim.
- Input yang sudah dinamis juga boleh: nominal dan biaya lama akan diganti.
2. Menambahkan biaya layanan
Biaya layanan (convenience fee) ditampilkan terpisah oleh aplikasi pembayaran dan ditambahkan ke total yang dibayar pembeli.
| Konstanta | Nilai | Arti $feeValue |
Tag yang ditulis |
|---|---|---|---|
Qris::FEE_FIXED |
'fixed' |
Rupiah | 55 = 02, 56 = nilai |
Qris::FEE_PERCENTAGE |
'percentage' |
Persen (boleh desimal) | 55 = 03, 57 = nilai |
Jika $feeValue bernilai 0 atau null, biaya diabaikan.
Catatan: dukungan tampilan biaya layanan bergantung pada aplikasi pembayaran pembeli. Uji dulu dengan beberapa aplikasi sebelum dipakai di produksi.
3. Validasi
Yang diperiksa:
| Pemeriksaan | Contoh pesan error |
|---|---|
| String kosong | QRIS string is empty |
Diawali 000201 |
QRIS must start with Payload Format Indicator "000201" |
| Panjang minimum | QRIS string is too short |
| Checksum CRC16 | CRC mismatch: expected 2982, got ABCD |
Tag wajib 00 01 52 53 58 59 60 63 |
Missing required tag 59 (Merchant Name) |
Nilai tag 01 harus 11/12 |
Invalid Point of Initiation Method: "13" ... |
| Ada Merchant Account Info (tag 26–51) | No Merchant Account Information found (tags 26-51) |
4. Membaca isi QRIS
Data per penyelenggara (tag 26–51):
Struktur TLV mentah dan ekspor:
5. Menangani error
Qris::parse() dan Qris::convert() melempar QrisDinamis\Exception\InvalidQrisException jika QRIS atau parameter tidak valid. Class ini turunan \InvalidArgumentException.
Exception juga dilempar jika:
$amount≤ 0 →Amount must be greater than 0$feeValuenegatif →Fee value must not be negative$feeTypebukanfixed/percentage→Invalid fee type: ...
6. Membuat gambar QR
Library ini hanya menghasilkan string. Untuk gambar, pakai library QR mana pun. Contoh dengan chillerlan/php-qrcode:
Bisa juga dirender di browser dengan library JavaScript (lihat examples/web).
7. Command line (CLI)
Setelah composer require, CLI tersedia di vendor/bin/qris.
Mode interaktif
Mode langsung (cocok untuk script)
8. Web demo
Repositori ini menyertakan aplikasi web lengkap di examples/web:
- tempel string QRIS, upload / drag & drop gambar, scan kamera, paste screenshot (Ctrl+V)
- tampilkan informasi QRIS
- konversi dengan nominal + biaya layanan
- tampilkan & unduh QR hasil, salin string
- mode gelap / terang
- JSON API di
examples/web/api.php
Buka http://localhost:8000. Scan kamera memerlukan HTTPS atau localhost.
JSON API:
action |
Parameter | Respons sukses |
|---|---|---|
validate |
qris |
{ "ok": true, "valid": bool, "errors": [] } |
parse |
qris |
{ "ok": true, "data": {...} } |
convert |
qris, amount, opsional fee_type, fee_value |
{ "ok": true, "result": "000201...", "data": {...} } |
Error dikembalikan dengan status 422 dan { "ok": false, "errors": [...] }.
Integrasi Framework
Laravel
.env
config/services.php
Controller
resources/views/pay.blade.php
Contoh lengkap dengan endpoint API dan validasi request ada di examples/laravel.
CodeIgniter 4
PHP native
Referensi API
QrisDinamis\Qris
| Method | Return | Keterangan |
|---|---|---|
convert(string $qris, int\|float $amount, ?string $feeType = null, int\|float\|null $feeValue = null) |
string |
Validasi lalu konversi ke QRIS dinamis. Melempar InvalidQrisException. |
parse(string $qris) |
QrisData |
Validasi lalu parse. Melempar InvalidQrisException. |
validate(string $qris) |
array{valid: bool, errors: string[]} |
Validasi tanpa exception. |
isValid(string $qris) |
bool |
Singkatan dari validate()['valid']. |
assertValid(string $qris) |
void |
Melempar InvalidQrisException jika tidak valid. |
parseTlv(string $data) |
Tlv[] |
Parse TLV mentah tanpa validasi (untuk debugging). |
crc16(string $str) |
string |
CRC16-CCITT, 4 digit hex huruf besar. |
| Konstanta | Nilai |
|---|---|
Qris::FEE_FIXED |
'fixed' |
Qris::FEE_PERCENTAGE |
'percentage' |
QrisDinamis\QrisData
Objek hasil Qris::parse(). Semua properti readonly.
| Properti | Tipe | Tag | Keterangan |
|---|---|---|---|
version |
string |
00 | Payload Format Indicator ("01") |
method |
string |
01 | "static" atau "dynamic" |
merchantAccountInfo |
array |
26–51 | Lihat Membaca isi QRIS |
merchantCategoryCode |
string |
52 | MCC, mis. "5812" |
currency |
string |
53 | Kode ISO 4217, "360" = IDR |
amount |
?string |
54 | Nominal, null jika statis |
tipIndicator |
?string |
55 | "prompt", "fixed", "percentage", atau null |
tipFixed |
?string |
56 | Biaya tetap |
tipPercentage |
?string |
57 | Biaya persen |
countryCode |
string |
58 | "ID" |
merchantName |
string |
59 | Nama merchant |
merchantCity |
string |
60 | Kota |
postalCode |
string |
61 | Kode pos |
additionalData |
?Tlv[] |
62 | Data tambahan |
crc |
string |
63 | Checksum |
raw |
Tlv[] |
— | Semua elemen TLV |
| Method | Return |
|---|---|
isStatic() / isDynamic() |
bool |
issuer() |
?string — penyelenggara utama, mis. "ID.DANA.WWW" |
nmid() |
?string — National Merchant ID |
amountValue() |
?float |
currencyLabel() |
string — "IDR" untuk 360 |
toArray() |
array |
QrisData mengimplementasikan JsonSerializable.
QrisDinamis\Tlv
| Properti | Tipe |
|---|---|
tag |
string — 2 digit |
name |
string — nama tag yang mudah dibaca |
length |
int |
value |
string |
children |
?Tlv[] — sub-elemen untuk tag 26–51 dan 62 |
QrisDinamis\Exception\InvalidQrisException
Turunan \InvalidArgumentException.
| Method | Return |
|---|---|
getMessage() |
string — ringkasan |
getErrors() |
string[] — daftar error rinci |
Class tingkat rendah
Tersedia jika butuh kontrol lebih; tidak melakukan validasi otomatis.
| Class | Method |
|---|---|
QrisDinamis\Converter |
convert(), buildTlvString(Tlv[]), formatNumber() |
QrisDinamis\Parser |
parse(), parseTlv(), tagName(), isMerchantTag() |
QrisDinamis\Validator |
validate() |
QrisDinamis\Crc16 |
calculate() |
Contoh
Folder examples/ berisi contoh yang bisa langsung dijalankan dari root repositori:
| File | Isi |
|---|---|
01-basic-convert.php |
Konversi paling sederhana |
02-service-fee.php |
Biaya layanan tetap & persen |
03-validate.php |
Validasi dan penanganan error |
04-parse.php |
Membaca semua informasi QRIS |
05-generate-qr-image.php |
Membuat PNG / SVG di server |
06-api-endpoint.php |
Endpoint JSON minimal |
07-checkout-page.php |
Halaman checkout dengan kode unik |
laravel/ |
Controller + view Laravel |
web/ |
Aplikasi web lengkap + JSON API |
Folder examples/ dan tests/ tidak ikut terpasang saat composer require, sehingga paket di vendor/ tetap kecil.
Cara Kerja
QRIS mengikuti format EMVCo Merchant-Presented QR, berupa rangkaian elemen TLV (Tag–Length–Value):
Tag penting:
| Tag | Nama | Contoh |
|---|---|---|
00 |
Payload Format Indicator | 01 |
01 |
Point of Initiation Method | 11 statis, 12 dinamis |
26–51 |
Merchant Account Information | issuer, merchant ID, NMID |
52 |
Merchant Category Code | 5812 |
53 |
Transaction Currency | 360 (IDR) |
54 |
Transaction Amount | 25000 |
55 |
Tip / Convenience Indicator | 02 tetap, 03 persen |
56 |
Convenience Fee (tetap) | 1000 |
57 |
Convenience Fee (persen) | 2.5 |
58 |
Country Code | ID |
59 |
Merchant Name | Warung Sayur |
60 |
Merchant City | Kab. Demak |
61 |
Postal Code | 59567 |
62 |
Additional Data | |
63 |
CRC | 4 digit hex |
Langkah konversi:
- Parse string menjadi daftar elemen TLV.
- Ubah tag
01dari11(statis) menjadi12(dinamis). - Buang tag
54–57dan63yang lama (jika ada). - Sisipkan tag
54(nominal) — serta55+56/57jika ada biaya — tepat sebelum tag58. - Susun ulang string, tambahkan
6304, lalu hitung CRC16-CCITT (polinomial0x1021, nilai awal0xFFFF) dan tempelkan 4 digit hex hasilnya.
Contoh perubahan (disingkat):
FAQ
Apakah ini payment gateway? Bukan. Library ini hanya membuat kode QR. Uang langsung masuk ke merchant pemilik QRIS statis. Library ini tidak tahu apakah pembayaran sudah dilakukan — tidak ada callback/webhook.
Lalu bagaimana memastikan pembeli sudah membayar?
Cek mutasi / riwayat transaksi di aplikasi merchant atau bank. Agar mudah dicocokkan, tambahkan kode unik kecil ke nominal (mis. Rp 150.000 → Rp 150.127) dan simpan bersama pesanan. Lihat examples/07-checkout-page.php. Untuk konfirmasi otomatis, gunakan payment gateway resmi.
Apakah QRIS dinamis hasil konversi aman dipakai? Formatnya mengikuti standar EMVCo dan checksum dihitung ulang dengan benar, sehingga bisa dibaca aplikasi pembayaran. Namun QRIS dinamis "resmi" biasanya diterbitkan per transaksi oleh penyelenggara. Uji dengan beberapa aplikasi sebelum dipakai di produksi dan patuhi ketentuan penyelenggara QRIS Anda.
Kenapa muncul "CRC mismatch"? String rusak atau terpotong saat disalin (mis. spasi di tengah, karakter hilang). Salin ulang dari hasil scan asli.
Bisa dipakai untuk QRIS dari penyelenggara mana saja? Ya, selama QRIS mengikuti standar (DANA, GoPay, OVO, ShopeePay, LinkAja, QRIS bank, dll).
Apakah nominal boleh desimal?
Rupiah tidak memakai desimal, jadi gunakan bilangan bulat untuk $amount. Biaya persentase boleh desimal (mis. 0.7).
Keamanan?
Simpan QRIS statis di server (konfigurasi / .env). Jangan menerima string QRIS dari klien untuk dikonversi, karena pengguna bisa menggantinya dengan QRIS milik orang lain.
Testing
Nilai yang diharapkan di tes diambil dari output versi TypeScript asli, sehingga hasil library ini dijamin identik.
Kontribusi
Pull request dan laporan bug sangat diterima.
- Fork repositori
- Buat branch:
git checkout -b fitur-baru - Pastikan
composer testlulus - Kirim pull request
Riwayat perubahan ada di CHANGELOG.md.
Kredit & Lisensi
- Port PHP dari verssache/qris-dinamis karya Gidhan (TypeScript).
- Web demo memakai jsQR dan qrcode-generator (MIT).
Dirilis di bawah lisensi MIT. Lihat LICENSE.
QRIS adalah standar kode QR pembayaran milik Bank Indonesia. Proyek ini tidak berafiliasi dengan Bank Indonesia maupun penyelenggara jasa pembayaran mana pun.
