Dokumentasi API — PayGate

Getting Started

Authentication

Setiap request ke API perlu 2 header: X-Api-Key (public key) dan Authorization: Bearer (secret key). Dapatkan sepasang key ini dari menu API Keys di dashboard merchant kamu.

X-Api-Key: pk_sandbox_1a2b3c4d5e6f
Authorization: Bearer sk_sandbox_9f8e7d6c5b4a3f2e1d0c...

Secret key hanya ditampilkan sekali saat dibuat. Simpan di environment variable server kamu, jangan hardcode di source code.

POST/api/v1/transactions.php

Membuat transaksi baru. Pelanggan akan diarahkan ke payment_url yang dikembalikan untuk menyelesaikan pembayaran.

Request Body

Field	Tipe	Wajib	Keterangan
order_id	string	Ya	ID unik dari sisi kamu
amount	number	Ya	Nominal, minimal 1000
method	string	Ya	qris, gopay, ovo, dana, shopeepay, va_bca, va_mandiri, va_bni
customer_name	string	Tidak	Nama pelanggan
customer_email	string	Tidak	Email pelanggan
callback_url	string	Tidak	URL webhook saat status berubah
success_redirect_url	string	Tidak	Redirect setelah bayar sukses
failed_redirect_url	string	Tidak	Redirect kalau gagal

Contoh (cURL)

curl -X POST https://nzpay.site/api/v1/transactions.php \
  -H "X-Api-Key: pk_sandbox_xxxxx" \
  -H "Authorization: Bearer sk_sandbox_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "INV-2026-0091",
    "amount": 150000,
    "method": "qris",
    "customer_name": "Budi Santoso",
    "callback_url": "https://tokoanda.com/webhook"
  }'

Contoh (PHP)

$ch = curl_init("https://nzpay.site/api/v1/transactions.php");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-Api-Key: pk_sandbox_xxxxx",
    "Authorization: Bearer sk_sandbox_xxxxx",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "order_id" => "INV-2026-0091",
    "amount" => 150000,
    "method" => "qris",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
echo $response['data']['payment_url'];

Contoh (Node.js)

const res = await fetch("https://nzpay.site/api/v1/transactions.php", {
  method: "POST",
  headers: {
    "X-Api-Key": "pk_sandbox_xxxxx",
    "Authorization": "Bearer sk_sandbox_xxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ order_id: "INV-2026-0091", amount: 150000, method: "qris" }),
});
const data = await res.json();
console.log(data.data.payment_url);

Response 201

{
  "success": true,
  "data": {
    "transaction_ref": "TRX-2026-000123",
    "order_id": "INV-2026-0091",
    "status": "pending",
    "payment_url": "https://nzpay.site/checkout.php?ref=TRX-2026-000123",
    "expired_at": "2026-08-28 15:30:00"
  }
}

GET/api/v1/transactions.php?order_id=xxx

Cek status transaksi berdasarkan order_id milikmu, atau transaction_ref dari PayGate.

curl https://nzpay.site/api/v1/transactions.php?order_id=INV-2026-0091 \
  -H "X-Api-Key: pk_sandbox_xxxxx" \
  -H "Authorization: Bearer sk_sandbox_xxxxx"

Response 200

{
  "success": true,
  "data": {
    "transaction_ref": "TRX-2026-000123",
    "order_id": "INV-2026-0091",
    "status": "success",
    "method": "qris",
    "gross_amount": 150000,
    "fee_amount": 1050,
    "net_amount": 148950,
    "paid_at": "2026-08-28 14:05:11",
    "expired_at": "2026-08-28 15:05:11",
    "created_at": "2026-08-28 13:50:00"
  }
}

Payment Methods

Kode method yang bisa dipakai saat membuat transaksi (bisa berubah sesuai yang diaktifkan admin):

Kode	Nama	Kategori
qris	QRIS	QRIS
va_bca	Virtual Account BCA	Virtual Account
va_mandiri	Virtual Account Mandiri	Virtual Account
va_bni	Virtual Account BNI	Virtual Account
gopay	GoPay	E-Wallet
ovo	OVO	E-Wallet
dana	DANA	E-Wallet
shopeepay	ShopeePay	E-Wallet

Error Codes

HTTP	Code	Keterangan
401	unauthorized	API key tidak ada / salah / sudah direvoke
403	merchant_not_verified	Akun merchant belum diverifikasi admin
403	blocked_by_risk_engine	Transaksi ditolak sistem deteksi fraud otomatis
400	missing_parameter	Parameter wajib untuk GET (order_id/transaction_ref) tidak ada
400	invalid_json	Body request bukan JSON valid
400	validation_error	Field wajib tidak lengkap / tidak valid
400	invalid_method	Kode metode pembayaran salah / nonaktif
409	duplicate_order_id	order_id sudah pernah dipakai merchant ini
404	not_found	Transaksi tidak ditemukan saat dicek
405	method_not_allowed	HTTP method selain GET/POST

Bagaimana Pembayaran Diproses

Sistem otomatis memilih cara pemrosesan berdasarkan konfigurasi platform, dengan urutan prioritas berikut untuk tiap metode:

Prioritas	Kondisi	Yang Terjadi
1	Metode QRIS dengan otomatisasi aktif	QR dinamis di-generate otomatis, status berubah otomatis lewat webhook begitu terverifikasi
2	Channel Platform aktif untuk metode itu	Tampilkan QR statis/nomor rekening admin, customer klik "Saya Sudah Transfer", verifikasi manual oleh admin
3	Provider pembayaran otomatis dikonfigurasi	Redirect ke halaman pembayaran ter-hosting provider
4	Tidak ada satupun di atas	Mode sandbox: tombol "Simulasi: Saya Sudah Bayar" untuk uji alur callback

Sebagai developer, kamu tidak perlu tahu jalur mana yang aktif — cukup redirect customer ke payment_url yang dikembalikan API, dan tunggu notifikasi ke callback_url kamu (atau polling lewat endpoint Check Transaction) untuk tahu kapan status berubah.

Catatan: selama sistem berjalan di jalur 2 (Channel Platform manual), ada jeda waktu verifikasi karena dilakukan manual oleh admin — jangan asumsikan status langsung berubah dalam hitungan detik seperti jalur 1 dan 3.