API Documentation

Panduan lengkap integrasi REST API & Webhook Signature PanzzPay Payment Gateway.

panzz-pay-api.vercel.app

v1.0.0 Production

Ringkasan Integrasi

PanzzPay-API menyediakan endpoint RESTful untuk membuat tagihan QRIS Dinamis secara otomatis dengan suntikan 3-digit kode unik. Setiap pembayaran yang masuk akan dideteksi secara otomatis via GoBiz merchant dan notifikasi callback dikirim ke server Anda via Webhook HTTP POST.

Base URL Server

https://panzz-pay-api.vercel.app

Autentikasi Header

x-api-key: YOUR_API_KEY

Format Response

JSON (application/json)

POST

https://panzz-pay-api.vercel.app/api/payment

Membuat Tagihan QRIS Baru

Endpoint ini digunakan oleh backend/bot e-commerce Anda untuk men-generate kode QRIS dinamis baru dengan nominal unik.

Request Body (JSON)

Field	Tipe	Wajib	Keterangan
amount	Integer	YA	Nominal transaksi dasar dalam Rupiah (contoh: `15000`).
customer_order_id	String	Opsional	ID pesanan unik dari sistem Anda (contoh: `INV-1002`).
bot_name / app_name	String	Opsional	Nama bot atau aplikasi client (contoh: `KuyStore Bot`). Jika tidak diisi, otomatis menggunakan deskripsi API Key.
webhook_url	String (URL)	YA	URL HTTP(S) callback tempat server Anda menerima notifikasi mutasi.
expiry_minutes	Integer	Opsional	Masa berlaku tagihan dalam menit (default: `15` menit).
use_unique_code	Boolean	Opsional	`true` (default) atau `false` untuk mengaktifkan/menonaktifkan penambahan kode unik 3 digit.
unique_code	Integer	Opsional	Angka `1-999` untuk menentukan kode unik 3 digit secara manual.

Contoh Kode Integrasi

curl -X POST "https://panzz-pay-api.vercel.app/api/payment" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "amount": 15000,
    "customer_order_id": "INV-1002",
    "webhook_url": "https://yoursite.com/api/webhook"
  }'

Response JSON (200 OK)

{
  "id": "PAY-8F3E1A2B",
  "transaction_id": "PAY-8F3E1A2B",
  "amount": 15000,
  "unique_amount": 15482,
  "total": 15482,
  "status": "pending",
  "qris_payload": "00020101021226670016ID.CO.GOPAY.WWW011893600...63048B2F",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qr_png_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "created_at": 1784908800000,
  "expires_at": 1784909700000,
  "customer_order_id": "INV-1002",
  "order_id": "INV-1002",
  "webhook_url": "https://yoursite.com/api/webhook"
}

POST

https://panzz-pay-api.vercel.app/api/payment/cancel

Pembatalan Pesanan Client (Stop Poller)

Membatalkan pesanan secara langsung ketika pembeli membatalkan pesanan dari bot/webstore, sehingga Poller di VPS langsung berhenti memantau nominal tersebut.

Parameter Body (JSON)	Tipe	Status	Keterangan
customer_order_id / order_id	String	Opsional	ID pesanan invoice milik client (e.g. `INV-1002` / `KUY-1234`).
id / transaction_id	String	Opsional	ID transaksi payment milik gateway (e.g. `PAY-8F3E1A2B`).

{
  "success": true,
  "ok": true,
  "id": "PAY-8F3E1A2B",
  "status": "expired"
}

GET

https://panzz-pay-api.vercel.app/events

Server-Sent Events (Real-time SSE Stream)

Menghubungkan aplikasi/bot client secara langsung ke stream notifikasi real-time via EventSource tanpa polling manual.

Event Stream Types:

payment.created: Pemicu saat invoice tagihan baru berhasil di-generate.
payment.success: Pemicu saat pembayaran mutasi QRIS berhasil terverifikasi lunas.
payment.expired: Pemicu saat tagihan dibatalkan/kedaluwarsa.
payment.timeout: Pemicu saat tagihan mencapai batas waktu poller.

const eventSource = new EventSource('https://panzz-pay-api.vercel.app/events');

eventSource.addEventListener('payment.success', (e) => {
  const payment = JSON.parse(e.data);
  console.log('Pembayaran Lunas:', payment.id, payment.unique_amount);
});

GET

https://panzz-pay-api.vercel.app/api/health

Server Health & Session Check

Memeriksa status operasional server gateway dan status koneksi sesi GoPay Merchant.

{
  "status": "healthy",
  "timestamp": 1784908800000,
  "gopay_integrated": true,
  "static_qris_loaded": true
}

Webhook Callback & Verifikasi Signature

Ketika pembayaran QRIS berhasil terdeteksi (payment.success) atau waktu invoice habis (payment.expired), server PanzzPay-API akan secara otomatis mengirimkan notifikasi HTTP POST ke webhook_url yang Anda daftarkan.

Header Webhook Request

Content-Type: application/json

User-Agent: PanzzPay-API Webhook Dispatcher v1.0

X-Event: payment.success

X-Signature: HMAC-SHA256-HEX-STRING

Policy Retry Manual

Maksimal 3x percobaan ulang otomatis.
Interval backoff: 4 detik & 8 detik.
Anda dapat mengirim ulang manual via menu Webhook Logs.

Contoh Payload Body (JSON)

{
  "event": "payment.success",
  "id": "PAY-8F3E1A2B",
  "transaction_id": "PAY-8F3E1A2B",
  "amount": 15000,
  "unique_amount": 15482,
  "total": 15482,
  "status": "paid",
  "customer_order_id": "INV-1002",
  "order_id": "INV-1002",
  "created_at": 1784908800000,
  "expires_at": 1784909700000,
  "paid_at": 1784909120000
}

Verifikasi Signature (HMAC-SHA256)

const crypto = require('crypto');

function verifyWebhook(rawBodyString, signatureHeader, webhookSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBodyString)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

HTTP Status & Error Codes Reference

Kode	Status Error	Keterangan / Solusi
200 OK	Success	Permintaan berhasil diproses dan invoice tagihan QRIS berhasil di-generate.
400 Bad Request	Invalid Parameter	Parameter wajib missing/salah (misal `amount` bukan angka positif).
401 Unauthorized	Invalid API Key	Header `x-api-key` missing atau tidak cocok dengan key aktif di server.
429 Too Many Requests	Rate Limit Exceeded	Terlalu banyak percoban login admin berturut-turut. Terkunci selama 15 menit.
503 Service Unavailable	Server Busy / Collision	Gagal mengalokasikan 3-digit kode unik karena lalu lintas transaksi tinggi. Ulangi kembali dalam beberapa detik.