Gateway QRIS

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

TagNamaContoh
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

  1. Parse seluruh elemen TLV.
  2. Buang tag 54, 55, 56, 57, 63 yang lama.
  3. Ganti tag 01 dari 11 menjadi 12.
  4. Sisipkan tag 54 (nominal) sebelum tag 58; bila ada biaya, sisipkan 55 bersama 56 atau 57.
  5. 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

TabelIsi
settingsKonfigurasi: QRIS static merchant, nama/kota, masa berlaku, kode unik, webhook secret.
admin_usersAkun admin (bcrypt, role admin/viewer).
api_keysKunci API (hash SHA-256) dan secret webhook.
invoicesTagihan: nominal, kode unik, total, status, isi QRIS, callback, kedaluwarsa.
webhook_eventsLog setiap webhook masuk beserta hasil verifikasi signature.
callback_logRiwayat pengiriman callback keluar (HTTP code, status).
qriscachePath PNG QR per invoice.

6. Daftar endpoint

MethodPathAuthKeterangan
POST/api/v1/invoicesAPI keyBuat tagihan
GET/api/v1/invoices/{id}API keyStatus tagihan
POST/api/v1/invoices/{id}/cancelAPI keyBatalkan tagihan
GET/api/v1/meAPI keyProfil merchant
POST/api/v1/webhookHMACNotifikasi pembayaran masuk
GET/api/public/invoices/{id}/qr.pngpublikGambar QR
GET/api/public/invoices/{id}/statuspublikStatus ringkas
GET/pay/{id}publikHalaman 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

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