README

Laravel Package berskala Enterprise yang dirancang khusus untuk memproses, memvalidasi, dan melakukan manipulasi (generate) standar QRIS EMVCo Indonesia.

Library ini sangat berguna untuk mengubah QRIS Statis (yang mengharuskan pelanggan mengetik nominal manual) menjadi QRIS Dinamis (nominal sudah otomatis terisi saat di-scan) hanya melalui satu baris kode, sehingga mempermudah integrasi sistem kasir (POS), billing, dan e-commerce di ekosistem Laravel Anda.

🌟 Penjelasan Fitur Lengkap

1. QRIS EMVCo Parser (Pemecah String QRIS)

String QRIS mentah terdiri dari ratusan karakter acak berdasarkan format EMVCo internasional (contoh: 000201010211...).

Fungsi: Library ini membaca karakter rumit tersebut dan memecahnya menggunakan standar Tag, Length, Value (TLV).
Hasil: String mentah secara instan diterjemahkan menjadi Array Object PHP. Anda bisa dengan sangat mudah mengambil informasi rahasia di baliknya seperti Nama Toko (Merchant Name), Kota, maupun ID Merchant dari QRIS apa pun tanpa perlu melakukan pemotongan string secara manual.

2. QRIS Dynamic Generator (Injeksi Nominal Otomatis)

Ini adalah fungsi sentral (Core) dari package ini.

Fungsi: Menyuntikkan nominal tagihan ke dalam QRIS toko Anda. Anda cukup memberikan string QRIS toko biasa (Statis), dan package ini akan:
1. Menyisipkan Transaction Amount (Tag 54).
2. Mengubah indikator metode inisiasi (Tag 01) dari 11 (Statis) menjadi 12 (Dinamis).
Hasil: Sebuah string QRIS baru yang siap dibentuk menjadi gambar Barcode/QR Code. Saat pelanggan memindainya lewat M-Banking/E-Wallet, nominal tagihan akan langsung terisi.

3. Mesin Kriptografi CRC16 CCITT-False (Keamanan)

Keamanan adalah nyawa dari transaksi finansial. Di ujung setiap kode QRIS terdapat 4 karakter checksum keamanan.

Fungsi: Package ini dibekali kalkulator keamanan bawaan yang diwajibkan oleh Bank Indonesia (Algoritma CRC16 CCITT-False).
Hasil: Saat library ini mengubah nominal, ia akan otomatis menghitung dan menyematkan 4 digit keamanan baru. Hal ini memastikan QRIS yang dihasilkan dianggap Legal dan valid oleh sistem perbankan. Library ini juga otomatis menolak (throw Exception) apabila mencoba memproses QRIS palsu/rusak.

4. Integrasi Mulus di Ekosistem Laravel

Dirancang 100% dengan gaya programming Laravel yang modern.

Fungsi: Mendukung Laravel 10, 11, 12, dan 13. Dilengkapi Service Provider dan Facade bawaan.
Hasil: Anda tidak perlu memanggil class yang panjang. Cukup panggil Qris::generateDynamic() di dalam controller manapun, dan library ini bekerja otomatis di latar belakang (Plug and Play).

📦 Kebutuhan Sistem (Requirements)

PHP >= 8.2
Laravel >= 10.0 (Support Laravel 13)

🚀 Instalasi

Anda dapat menginstal package ini melalui Composer. Buka terminal proyek Laravel Anda dan jalankan:

composer require ardhikaxx/qris-dynamic-gateway

(Catatan Pengembang: Jika Anda menghubungkannya ke repositori lokal, pastikan mendaftarkan symlink/path repository di composer.json).

📖 Cara Penggunaan (Usage)

Setelah terinstal, Facade Qris dapat langsung digunakan di mana saja.

1. Mengekstrak Data dari QRIS Statis (Parsing)

Berguna untuk memeriksa validitas QRIS dan mendapatkan data spesifik dari string QRIS hasil scan.

use Qris\DynamicGateway\QrisFacade as Qris;
use Qris\DynamicGateway\Exceptions\InvalidQrisException;

try {
    // Contoh string payload QRIS mentah
    $payload = "0002010102115405100005802ID5913MOCK MERCHANT6007JAKARTA6304...";
    
    // Parser akan mereturn DTO `QrisData` yang kaya fitur
    $qris = Qris::parse($payload);
    
    echo "Nama Merchant: " . $qris->getMerchantName(); // Output: MOCK MERCHANT
    echo "Kode Negara: " . $qris->getCountryCode();    // Output: ID
    echo "Nominal Tagihan: " . $qris->getTransactionAmount(); 
    echo "Apakah Dinamis?: " . ($qris->isDynamic() ? 'Ya' : 'Tidak');

} catch (InvalidQrisException $e) {
    // Exception akan terpanggil bila CRC16 salah, atau struktur TLV rusak
    echo "Error: " . $e->getMessage(); 
}

2. Mengubah QRIS Statis menjadi Dinamis (Generation)

Sangat ideal digunakan pada aplikasi Kasir/POS atau saat Checkout E-commerce, di mana pelanggan harus membayar nilai spesifik yang sudah ditentukan sistem.

use Qris\DynamicGateway\QrisFacade as Qris;

// 1. QRIS Statis sumber dari toko Anda
$staticQris = "0002010102115802ID5913MOCK MERCHANT6007JAKARTA6304ABCD";

// 2. Buat QRIS Dinamis dengan nominal tagihan Rp 75.500
$dynamicQris = Qris::generateDynamic($staticQris, 75500);

// 3. (Opsional) Tambahkan biaya Tip/Pajak sebesar Rp 2.000 (Tag 55 & 56)
$dynamicWithTip = Qris::generateDynamic($staticQris, 75500, [
    'tip_indicator' => '02',
    'tip_fixed' => '2000'
]);

echo $dynamicWithTip;

Tip: Gabungkan hasil dari $dynamicQris dengan library seperti simplesoftwareio/simple-qrcode untuk merendernya menjadi gambar .png atau .svg di dalam view Blade Anda.

3. Debugging via Terminal (Artisan Command)

Anda bisa membedah (analyze) string QRIS langsung dari terminal untuk keperluan debugging dengan perintah bawaan:

php artisan qris:analyze "0002010102115405100005802ID5913MOCK MERCHANT..."

Ini akan mencetak tabel rapi yang berisi Merchant Name, Transaction Amount, dan semua tag yang terekstrak beserta validitas CRC16-nya.

🧪 Pengujian (Testing)

Package ini dirancang untuk level Enterprise dan telah teruji ketat (Unit Testing) mematuhi kalkulasi perbankan. Untuk menjalankan seluruh test suite secara mandiri:

composer install
vendor/bin/phpunit

💖 Dukungan & Donasi

Jika library ini bermanfaat bagi Anda dan telah menghemat banyak jam kerja Anda, Anda dapat menunjukkan apresiasi dengan memberikan traktiran kopi (donasi) melalui pemindaian kode QRIS di bawah ini:

📝 Lisensi

Proyek ini bersifat open-source dan didistribusikan di bawah Lisensi MIT.

ardhikaxx / qris-dynamic-gateway

Maintainers

Package info

Statistics

Security