Referensi lengkap
Kamus tag EMVCo/QRIS, struktur basis data, daftar endpoint, dan catatan implementasi algoritma konversi static → dynamic.
1. Format payload
QRIS mengikuti spesifikasi QR Code EMVCo dengan pengkodean TLV (Tag-Length-Value):
[Tag: 2 digit][Panjang: 2 digit][Nilai: variabel]
Contoh tag 59 (Merchant Name) dengan nilai VALETTASHOP menjadi
5910VALETTASHOP.
2. Kamus tag
| Tag | Nama | Contoh |
|---|---|---|
00 |
Payload Format Indicator | 01 |
01 |
Point of Initiation Method | 11 (static) / 12 (dynamic) |
02 |
Visa | |
03 |
Mastercard | |
04 |
Mastercard | |
15 |
Visa | |
26 |
Merchant Account Information | ID.CO.QRIS.WWW + merchant id |
27 |
Merchant Account Information | Merchant Account Information |
28 |
Merchant Account Information | Merchant Account Information |
29 |
Merchant Account Information | Merchant Account Information |
30 |
Merchant Account Information | Merchant Account Information |
31 |
Merchant Account Information | Merchant Account Information |
32 |
Merchant Account Information | Merchant Account Information |
33 |
Merchant Account Information | Merchant Account Information |
34 |
Merchant Account Information | Merchant Account Information |
35 |
Merchant Account Information | Merchant Account Information |
36 |
Merchant Account Information | Merchant Account Information |
37 |
Merchant Account Information | Merchant Account Information |
38 |
Merchant Account Information | Merchant Account Information |
39 |
Merchant Account Information | Merchant Account Information |
40 |
Merchant Account Information | Merchant Account Information |
41 |
Merchant Account Information | Merchant Account Information |
42 |
Merchant Account Information | Merchant Account Information |
43 |
Merchant Account Information | Merchant Account Information |
44 |
Merchant Account Information | Merchant Account Information |
45 |
Merchant Account Information | Merchant Account Information |
46 |
Merchant Account Information | Merchant Account Information |
47 |
Merchant Account Information | Merchant Account Information |
48 |
Merchant Account Information | Merchant Account Information |
49 |
Merchant Account Information | Merchant Account Information |
50 |
Merchant Account Information | Merchant Account Information |
51 |
Merchant Account Information | Merchant Account Information |
52 |
Merchant Category Code | 5812 |
53 |
Transaction Currency | 360 |
54 |
Transaction Amount | 25000 |
55 |
Tip or Convenience Indicator | 02 (fixed) / 03 (persentase) |
56 |
Value of Convenience Fee (Fixed) | 1000 |
57 |
Value of Convenience Fee (%) | 2.5 |
58 |
Country Code | ID |
59 |
Merchant Name | VALETTASHOP |
60 |
Merchant City | JAKARTA |
61 |
Postal Code | 11750 |
62 |
Additional Data Field | data tambahan |
63 |
CRC | 58C7 |
3. CRC16
Checksum memakai CRC16-CCITT: polinomial 0x1021, inisialisasi 0xFFFF,
tanpa refleksi, 4 digit heksadesimal huruf besar. Input checksum adalah seluruh string
termasuk akhiran 6304.
4. Algoritma konversi
- Parse seluruh elemen TLV.
- Buang tag
54,55,56,57,63yang lama. - Ganti tag
01dari11menjadi12. - Sisipkan tag
54(nominal) sebelum tag58; bila ada biaya, sisipkan55bersama56atau57. - Bangun ulang string, hitung CRC16 baru, tempelkan pada tag
63.
Implementasi PHP berada di app/qris_core.php dan merupakan port dari
github.com/verssache/qris-dinamis
(MIT License) — paragraf di atas mengikuti alur yang sama persis.
5. Basis data
| Tabel | Isi |
|---|---|
settings | Konfigurasi: QRIS static merchant, nama/kota, masa berlaku, kode unik, webhook secret. |
admin_users | Akun admin (bcrypt, role admin/viewer). |
api_keys | Kunci API (hash SHA-256) dan secret webhook. |
invoices | Tagihan: nominal, kode unik, total, status, isi QRIS, callback, kedaluwarsa. |
webhook_events | Log setiap webhook masuk beserta hasil verifikasi signature. |
callback_log | Riwayat pengiriman callback keluar (HTTP code, status). |
qriscache | Path PNG QR per invoice. |
6. Daftar endpoint
| Method | Path | Auth | Keterangan |
|---|---|---|---|
| POST | /api/v1/invoices | API key | Buat tagihan |
| GET | /api/v1/invoices/{id} | API key | Status tagihan |
| POST | /api/v1/invoices/{id}/cancel | API key | Batalkan tagihan |
| GET | /api/v1/me | API key | Profil merchant |
| POST | /api/v1/webhook | HMAC | Notifikasi pembayaran masuk |
| GET | /api/public/invoices/{id}/qr.png | publik | Gambar QR |
| GET | /api/public/invoices/{id}/status | publik | Status ringkas |
| GET | /pay/{id} | publik | Halaman bayar pelanggan |
7. Kode unik
Setiap tagihan mendapat kode unik acak antara 1 dan batas yang diatur (default 99). Nominal akhir
yang dibayar pelanggan adalah amount + unique_code. Dengan begitu satu mutasi rekening
hanya cocok dengan satu tagihan, dan nominal yang tampil di aplikasi pembayaran berbeda per tagihan.
Batas 0 menonaktifkan kode unik.
8. Status
pending— menunggu pembayaran, belum lewat masa berlaku.paid— bukti pembayaran sudah diterima (webhook terverifikasi atau ditandai admin).expired— lewat masa berlaku, ditandai worker cron.cancelled— dibatalkan manual.
9. Worker cron
bin/qris-worker.php dijalankan tiap 5 menit. Tugasnya menandai tagihan pending yang
kedaluwarsa sebagai expired dan mengirim ulang callback yang sebelumnya gagal.
Secret database dibaca dari /root/.qris-db.env (mode 0600) karena PHP-CLI tidak mewarisi
environment PHP-FPM.
10. Batasan hukum dan operasional
- Alat ini mengubah QRIS milik merchant Anda sendiri; bukan alat untuk mengarang QRIS pihak lain.
- Pastikan Anda terdaftar sebagai merchant pada provider QRIS yang Anda pakai dan obey aturan main merchant terkait penagihan dinamis.
- Gateway tidak memproses atau memegang dana; seluruh transaksi tetap terjadi di aplikasi pembayaran pelanggan dan masuk ke rekening provider Anda.
- Jangan pernah menandai tagihan lunas hanya karena pelanggan mengklaim sudah membayar.