Dokumentasi REST API

v1.0.0
Panduan integrasi DazePay QRIS Gateway ke aplikasi, website, dan bot Telegram/Discord Anda. API Key aktif Anda dapat dilihat dan dikelola di halaman Kredensial API Key.

1. Konfigurasi Dasar & Skema Biaya

Parameter endpoint global dan autentikasi yang digunakan di seluruh request.

https://.../api/v1
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Semua request API privat wajib menyertakan header Authorization di atas.

Struktur Biaya Transaksi

MDR (Merchant Discount Rate) 0% (Gratis)
Biaya Layanan Gateway Rp 0 - Rp 100 / transaksi
Fee Mode (Pengaturan Penanggung Biaya)
seller (Default)

Fee dipotong dari saldo Merchant. Customer membayar sesuai nominal asli tagihan. Merchant menerima: amount - fee.

buyer

Fee ditambahkan ke tagihan customer. Customer membayar lebih. Merchant menerima: amount (full utuh).

Anda dapat mengubah mode ini di halaman Pengaturan Akun.

POST /payment/create
Buat Tagihan QRIS Baru

Membuat transaksi pembayaran QRIS baru secara dinamis. Gateway akan menghasilkan QR code unik serta halaman hosted checkout.

Request Body (JSON)

Field Tipe Wajib Keterangan
amount Integer Ya Nominal dasar tagihan dalam Rupiah (min Rp 100, max Rp 10.000.000)
description String Opsional Deskripsi singkat pesanan (contoh: "Top Up Game #123")
customer_name String Opsional Nama lengkap pelanggan
customer_email String Opsional Email pelanggan
callback_url String (URL) Opsional URL redirect pembeli setelah transaksi berhasil dibayar
metadata Object (JSON) Opsional Data tambahan khusus sistem Anda (contoh: {"user_id": 99})

Contoh Request Body

{
  "amount": 50000,
  "description": "Order Token Listrik #891",
  "customer_name": "Ahmad Budi",
  "customer_email": "[email protected]",
  "callback_url": "https://tokoanda.com/order/success",
  "metadata": { "order_id": 891 }
}

Contoh Response Sukses (200 OK)

{
  "success": true,
  "message": "Pembayaran berhasil dibuat.",
  "data": {
    "invoice_id": "DZP-20261108-DAA9DFB3",
    "amount": 50000,
    "fee": 0,
    "unique_code": 409,
    "amount_charged": 50409,
    "fee_mode": "buyer",
    "status": "pending",
    "payment_method": "QRIS",
    "qr_url": "https://.../api/v1/qr/DZP-20261108-DAA9DFB3.png",
    "qr_string": "00020101021126650013ID.CO.BCA.WWW...",
    "checkout_url": "https://.../pay/DZP-20261108-DAA9DFB3",
    "expired_at": "2026-11-08T15:45:00.000Z",
    "created_at": "2026-11-08T15:30:00.000Z"
  }
}

Kamus Field Response

  • invoice_id: ID tagihan unik yang diawali prefix DZP-.
  • amount_charged: Nominal pasti yang wajib ditransfer/di-scan pelanggan (termasuk kode unik pencegah bentrok).
  • qr_url: Alamat URL langsung gambar QRIS PNG. Bisa disematkan ke tag <img src="..."> atau dikirim ke bot chat.
  • qr_string: Raw string EMVCo QRIS. Cocok jika frontend Anda menggunakan library client-side seperti qrcode.react.
  • checkout_url: URL halaman checkout siap pakai DazePay (sudah dilengkapi countdown timer & auto-polling).
  • expired_at: Batas kadaluwarsa tagihan (otomatis expired jika belum dibayar hingga waktu ini).
GET /payment/status/{invoice_id}
Cek Status Pembayaran (Polling)

Endpoint untuk memeriksa status transaksi. Rekomendasi interval polling: 3 detik sekali.

Contoh Response Lunas (Success - 200 OK)

{
  "success": true,
  "data": {
    "invoice_id": "DZP-20261108-DAA9DFB3",
    "amount": 50000,
    "fee": 0,
    "amount_charged": 50409,
    "net_amount": 50409,
    "status": "success",
    "paid_at": "2026-11-08T15:32:14.227Z",
    "expired_at": "2026-11-08T15:45:00.000Z"
  }
}

Lifecycle Status Transaksi

pending

Menunggu pembayaran. QRIS masih aktif dapat di-scan pembeli.

success

Pembayaran terverifikasi lunas. Saldo masuk ke akun Merchant.

expired

Waktu batas bayar habis. Tagihan dibatalkan secara otomatis.

failed

Terjadi kegagalan atau invoice ditolak.

GET /qr/{invoice_id}.png
QR Code Image Langsung (Public)

Endpoint publik (tanpa Authorization) yang mengembalikan file biner gambar PNG QRIS. Sangat cocok di-embed langsung pada website toko online atau bot messaging.

// 1. Sematkan langsung di tag HTML: <img src="https://.../api/v1/qr/DZP-20261108-DAA9DFB3.png" alt="QRIS" />
// 2. Unduh via cURL / terminal: curl -o qris.png "https://.../api/v1/qr/DZP-20261108-DAA9DFB3.png"
WEBHOOK Notifikasi Real-Time (HTTP POST)
Otomatisasi Push Callback

Setiap kali pembayaran sukses, server DazePay secara otomatis mengirimkan callback POST ke Webhook URL merchant tanpa perlu melakukan polling terus-menerus.

HTTP Headers yang Dikirimkan ke Merchant

Content-Type: application/json
User-Agent: DazePay-Webhook/1.0
X-Event: payment.success
X-Signature: <HMAC_SHA256_HEX_SIGNATURE>

Payload JSON Webhook Callback

{
  "event": "payment.success",
  "data": {
    "invoice_id": "DZP-20261108-DAA9DFB3",
    "amount": 50000,
    "fee": 0,
    "amount_charged": 50409,
    "net_amount": 50409,
    "status": "success",
    "payment_method": "QRIS",
    "customer_name": "Ahmad Budi",
    "metadata": { "order_id": 891 },
    "paid_at": "2026-11-08T15:32:14.227Z"
  }
}

Contoh Kode Integrasi

Alur lengkap: Buat invoice -> tampilkan QR -> polling sampai lunas.

// Alur Integrasi Node.js (Fetch API)
const API_KEY = 'YOUR_DAZEPAY_API_KEY';
const BASE_URL = 'https://.../api/v1';

// 1. Buat Tagihan QRIS
async function createPayment(amount, description) {
  const res = await fetch(`${BASE_URL}/payment/create`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ amount, description })
  });
  return res.json();
}

// 2. Cek Status Tagihan
async function checkPaymentStatus(invoiceId) {
  const res = await fetch(`${BASE_URL}/payment/status/${invoiceId}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  return res.json();
}

// 3. Eksekusi Order Otomatis
async function processCheckout() {
  const payment = await createPayment(50000, 'Order #891');
  console.log('Kirim QR ke Pembeli:', payment.data.qr_url);
  console.log('Atau buka Checkout Page:', payment.data.checkout_url);

  // Polling interval 3 detik (max 15 menit)
  for (let i = 0; i < 300; i++) {
    await new Promise(r => setTimeout(r, 3000));
    const check = await checkPaymentStatus(payment.data.invoice_id);
    if (check.data.status === 'success') {
      console.log('PEMBAYARAN SUKSES DITERIMA!', check.data);
      return check.data;
    }
  }
}
processCheckout();

Verifikasi Signature Webhook (HMAC SHA-256)

Selalu validasi header X-Signature untuk mencegah pemalsuan notifikasi webhook.

const crypto = require('crypto');

app.post('/webhook/dazepay', (req, res) => {
  const signature = req.headers['x-signature'];
  const webhookSecret = 'YOUR_WEBHOOK_SECRET'; // Ambil di menu Webhook

  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('hex');

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

  const { invoice_id, amount, status } = req.body.data;
  console.log(`Pembayaran ${invoice_id} sebesar Rp ${amount} terverifikasi [${status}]`);

  res.json({ received: true });
});