Secure QRIS

1. Generate QRIS Dinamis

Panggil endpoint POST /generate dengan payload terenkripsi menggunakan kredensial client.

Flow:

1. Dapatkan clientId dan clientSecret dari halaman Register
2. Client Secret tidak pernah dikirim ke server — hanya untuk enkripsi/dekripsi di client
3. Enkripsi payload { amount, ref_id? } dengan AES-256-GCM + PBKDF2
4. Kirim { salt, iv, content } + header X-Client-ID ke POST /generate
5. Server merespon terenkripsi — decrypt di client

// Enkripsi di client-side
const salt = crypto.getRandomValues(new Uint8Array(16));
const iv = crypto.getRandomValues(new Uint8Array(12));
const key = await crypto.subtle.importKey('raw',
  new TextEncoder().encode(clientSecret),
  { name: 'PBKDF2' }, false, ['deriveKey']);
const aesKey = await crypto.subtle.deriveKey(
  { name: 'PBKDF2', salt, iterations: 100000, hash: 'SHA-256' },
  key, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
const payload = { amount: 15000, ref_id: "INV-001" };
const encrypted = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv }, aesKey,
  new TextEncoder().encode(JSON.stringify(payload)));

const res = await fetch('/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Client-ID': clientId },
  body: JSON.stringify({ salt: buf2hex(salt), iv: buf2hex(iv), content: buf2hex(encrypted) })
});
const encryptedRes = await res.json();
// Decrypt response dengan ClientSecret yang sama

Contoh Response (setelah decrypt):

{
  "qris": "000201010212...6304ABCD",
  "qr_image_svg": "<svg>...</svg>",
  "merchant_name": "Toko Makmur",
  "merchant_city": "Denpasar",
  "nmid": "ID123456",
  "unique_code": "ABC123",
  "amount_suffix": 42,
  "mdr_amount": 3500,
  "qr_amount": 15042,
  "expires_at": "2025-01-02T12:00:00.000Z"
}
// Keterangan:
// amount_suffix  → jitter 1-99 untuk matching transaksi
// mdr_amount     → fee MDR 0.7% (jika nominal > Rp500rb), 0 jika ≤ Rp500rb
// qr_amount      → nominal QRIS: amount + suffix (+ MDR jika client-managed)

Error Response:

// [401] Missing X-Client-ID — header tidak dikirim
Missing X-Client-ID

// [401] Decryption Failed (Invalid Key) — clientSecret salah
Decryption Failed (Invalid Key)

// [400] Client missing qr_string — client belum register QR statis
Client missing qr_string

// [400] Limit transaksi — melebihi batas maksimal (atur di MDR Config)
Transaksi melebihi batas maksimal Rp 1.000.000

// [500] Cannot generate unique suffix — semua kombinasi jitter habis (jarang)
{"error": "Cannot generate unique suffix"}

// [403] GoBiz belum disetup di dashboard
{"error": "GoBiz not configured. Admin must complete GoBiz setup first."}

2. Plugin API (Tanpa Enkripsi)

Endpoint POST /plugin/generate dan POST /plugin/status menggunakan X-API-Key (sama dengan clientId) tanpa enkripsi. Cocok untuk integrasi WordPress/WooCommerce.

// Generate QRIS tanpa enkripsi
POST /plugin/generate
X-API-Key: <clientId>
{ "amount": 15000, "order_id": "INV-001" }

// Cek status
POST /plugin/status
X-API-Key: <clientId>
{ "unique_code": "ABC123" }

3. Webhook Notifikasi

Sistem akan mengirim notifikasi POST ke URL yang dikonfigurasi setiap kali ada kecocokan transaksi.

{
  "event": "qris.match",
  "unique_code": "ABC123",
  "transaction_id": "TXN-001",
  "amount": 500001,
  "mdr_amount": 3500,
  "amount_suffix": 42,
  "qr_amount": 500043,
  "status": "SETTLEMENT",
  "matched_at": "2025-01-01T12:00:00.000Z",
  "merchant_name": "Toko Makmur",
  "timestamp": "2025-01-01T12:00:00.000Z"
}