Quickstart

Panduan tercepat untuk integrasi Dehuyz Gateway. Setelah baca ini lo sudah bisa generate QR dan terima notifikasi pembayaran.

1. Setup akun

1. Daftar di /signup — email + password (8+ karakter).
2. Setelah signup, lo dapat starter API key (sk_test_...) yang ditampilkan sekali di halaman dashboard. Salin segera.
3. Untuk production, generate key baru di /dashboard/api-keys dengan mode live.

2. Generate invoice + QR

curl -X POST https://gateway.dehuyz.example.com/api/v1/invoices \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "description": "Order #INV-001",
    "external_id": "order-001"
  }'

Response (200):

{
  "invoice_id": "a1b2c3d4e5f67890",
  "external_id": "order-001",
  "status": "pending",
  "amount": 50000,
  "qr_string": "00020101...",
  "qr_image": "iVBORw0KGgo...",
  "refnum_bri": "100000XYZ",
  "expires_at": "2026-05-22T12:05:00+00:00"
}

• qr_string: QRIS string yang bisa di-render jadi QR dengan library lo sendiri (qrcode, dll).
• qr_image: base64 PNG, bisa langsung di-set sebagai <img src="data:image/png;base64,...">.

3. Terima notifikasi pembayaran

Pilih salah satu (atau keduanya):

Cara A — Polling (paling sederhana)

import httpx, time

while True:
    r = httpx.get(
        f"https://gateway.dehuyz.example.com/api/v1/invoices/{inv['invoice_id']}",
        headers={"Authorization": f"Bearer {api_key}"},
    )
    status = r.json()["status"]
    if status == "paid":
        print("PAID!")
        break
    elif status in ("expired", "cancelled"):
        break
    time.sleep(3)  # poll tiap 3 detik

Cara B — Webhook (real-time, push)

1. Setup endpoint webhook di /dashboard/webhooks — paste URL HTTPS yang akan menerima notifikasi.
2. Sistem auto-generate secret HMAC. Simpan baik-baik.
3. Saat customer bayar, gateway POST ke URL lo dengan signed body.

Detail lengkap: lihat Webhooks dan Polling.

4. Customer bayar

Customer scan QR dari aplikasi mobile banking apa pun yang support QRIS Indonesia (BRImo, Livin Mandiri, BCA Mobile, OVO, Gopay, dll). Pembayaran otomatis terdeteksi sistem dalam 2 detik.

Status invoice

Limit & default

• QR expiry default: 300 detik (5 menit) — diatur BRI portal, gak bisa di-override
• Min amount: 1 (Rp 1)
• Max amount: 9,999,999,999 (BIGINT)
• Idempotency: pakai external_id unik per request — duplicate calls return invoice yang sama
• Rate limit per merchant: 60 req/min (configurable)

Selanjutnya

• Authentication — detail API key + best practice
• Webhooks — verifikasi HMAC, retry, idempotency receiver
• Polling — best practice polling tanpa hammer server
• Errors — handle response error
• Settlement — withdraw saldo ke rekening bank