GETTING STARTED

DOKUMENTASI INTEGRASI MITRA

HizzPay menyediakan REST API berkinerja tinggi untuk mengotomasi penerimaan pembayaran QRIS langsung ke rekening merchant. Setiap transaksi dialokasikan kode identifikasi transaksi instan sehingga sistem dapat mendeteksi mutasi masuk secara real-time dan menembakkan notifikasi webhook bertanda tangan kriptografis ke server Anda.

2. AUTENTIKASI API

Semua request dari server backend Anda ke endpoint HizzPay wajib menyertakan header X-Api-Key:

X-Api-Key: pk_live_your_api_key_here

Kunci API dapat diperoleh di menu API & Webhook pada portal mitra Anda setelah akun disetujui oleh superadmin.

3. MEMBUAT INVOICE PEMBAYARAN

Endpoint: POST /api/v1/invoices

Request Headers:

Header	Wajib	Keterangan
`Content-Type`	Ya	`application/json`
`X-Api-Key`	Ya	API Key partner Anda (`pk_live_...`)

Request Body (JSON):

Field	Tipe	Wajib	Keterangan
`order_id`	String	Ya	ID unik pesanan dari sistem toko Anda (misal: `ORDER-1234`)
`amount`	Number	Ya	Nominal pokok yang harus dibayar pelanggan (misal: `50000`)
`customer_name`	String	Opsional	Nama lengkap pelanggan
`return_url`	String	Opsional	URL tujuan redirect otomatis setelah pelanggan membayar sukses
`callback_url`	String	Opsional	Override endpoint webhook khusus untuk invoice ini
`expired_in_minutes`	Number	Opsional	Durasi berlaku invoice (default: `15` menit)

curl -X POST https://api.yourdomain.com/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_live_sample123" \
  -d '{
    "order_id": "ORD-9912",
    "amount": 50000,
    "customer_name": "Budi Santoso",
    "return_url": "https://tokomu.com/finish"
  }'

Response Success (HTTP 201 Created):

{
  "invoice_no": "INV-20261004-a9f1",
  "order_id": "ORD-9912",
  "partner_name": "Meong Topup",
  "customer_name": "Budi Santoso",
  "base_amount": 50000,
  "unique_code": 123,
  "total_amount": 50123,
  "status": "PENDING",
  "payment_method": "QRIS",
  "payment_url": "https://pay.yourdomain.com/checkout.html?inv=INV-20261004-a9f1",
  "token": "INV-20261004-a9f1",
  "redirect_url": "https://pay.yourdomain.com/checkout.html?inv=INV-20261004-a9f1",
  "return_url": "https://tokomu.com/finish",
  "expired_at": "2026-10-04T18:45:00Z",
  "created_at": "2026-10-04T18:30:00Z"
}

SEPERTI MIDTRANS SNAP

4. INTEGRASI HIZZPAY SNAP (POPUP & EMBED)

HizzPay Snap memungkinkan website mitra Anda menampilkan modal popup checkout QRIS interaktif tanpa memindahkan pelanggan keluar dari halaman toko Anda.

Metode A: Popup Modal di Halaman Checkout

1. Pasang tag script Snap JS SDK di halaman frontend website Anda:

<script src="https://pay.hizzpay.com/snap/snap.js"></script>

2. Panggil fungsi hizzpaySnap.pay() dengan token invoice dan callback event:

// Panggil ketika pelanggan klik tombol 'Bayar Sekarang' di web Anda:
hizzpaySnap.pay(response.token, {
  onSuccess: function(result) {
    console.log("Pembayaran Sukses!", result);
    // result = { invoice_no, order_id, total_amount, status: 'PAID' }
    window.location.href = "/checkout/sukses?order_id=" + result.order_id;
  },
  onPending: function(result) {
    console.log("Menunggu transfer pelanggan...", result);
  },
  onError: function(err) {
    alert("Terjadi kesalahan pembayaran: " + err.message);
  },
  onClose: function() {
    console.log("Pelanggan menutup popup tanpa menyelesaikan pembayaran.");
  }
});

Metode B: Direct Redirect URL

Jika Anda lebih memilih mengarahkan pelanggan ke halaman pembayaran mandiri, cukup redirect ke response.redirect_url:

window.location.href = response.redirect_url;

6. SPESIFIKASI WEBHOOK NOTIFIKASI

Saat transaksi berhasil diverifikasi oleh sistem, server kami akan mengirimkan HTTP POST JSON secara instan ke URL webhook Anda:

Header Webhook yang Dikirimkan:

Header	Keterangan
`Content-Type`	`application/json`
`X-Gateway-Signature`	Signature HMAC-SHA256 yang dibuat menggunakan `SecretKey` Anda
`X-Gateway-Timestamp`	Epoch timestamp milidetik saat notifikasi dikirimkan

Payload JSON Webhook:

{
  "event": "payment.success",
  "invoice_no": "INV-20261004-a9f1",
  "order_id": "ORD-9912",
  "base_amount": 50000,
  "unique_code": 123,
  "total_amount": 50123,
  "status": "PAID",
  "paid_at": "2026-10-04T18:32:15Z",
  "timestamp": 1791113535000
}

Wajib: Server Anda harus merespons webhook dengan status HTTP 200 OK dalam kurun waktu 5 detik. Jika server Anda mengembalikan error (4xx/5xx) atau timeout, sistem gateway akan mencoba mengirim ulang otomatis (retry) sebanyak 5 kali secara berkala.

7. CARA VERIFIKASI SIGNATURE HMAC-SHA256

Untuk memastikan payload benar-benar berasal dari gateway HizzPay dan tidak diubah di tengah jalan, validasi header X-Gateway-Signature:

Contoh Verifikasi di PHP:

$secretKey = 'sk_live_secret_partner_anda';
$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GATEWAY_SIGNATURE'] ?? '';

$expectedSignature = hash_hmac('sha256', $rawBody, $secretKey);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['status'] === 'PAID') {
    // Proses pengiriman pesanan ke pelanggan Anda di sini
}

http_response_code(200);
echo json_encode(['received' => true]);

Contoh Verifikasi di Node.js (Express / Fastify / Hono):

import crypto from 'crypto';

app.post('/api/callback/payment', (req, res) => {
  const secretKey = 'sk_live_secret_partner_anda';
  const signature = req.headers['x-gateway-signature'];
  const rawBody = JSON.stringify(req.body);

  const expected = crypto.createHmac('sha256', secretKey).update(rawBody).digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { order_id, status } = req.body;
  if (status === 'PAID') {
    // Update status pesanan di database Anda
  }

  return res.status(200).json({ received: true });
});

8. PENGUJIAN SANDBOX

Anda dapat menguji seluruh siklus integrasi (buat invoice -> pembayaran -> webhook) tanpa menggunakan uang asli menggunakan fitur Simulator Sandbox:

Buka Sandbox Simulator Daftar Akun Partner