REST API · JSON · HTTPS · EMVCO QRIS
Dokumentasi Teknis & API ZPay
Panduan lengkap integrasi pembayaran QRIS Dinamis, arsitektur pembacaan mutasi otomatis, pembuatan link bayar, rekonsiliasi saldo, hingga verifikasi kriptografi webhook HMAC-SHA256.
Base URL
Untuk AI agent
Alur setup merchant & cara kerja pembaca mutasi
Bagaimana seseorang mendaftar, menghubungkan QRIS tokonya, hingga sistem ZPay otomatis mendeteksi uang masuk dan mengirimkan webhook lunas ke website toko.
Tahap Setup
Penjelasan Teknis & Operasional
1. Aktivasi AkunRp25.000
Calon merchant membuat akun di ZPay dan membayar biaya aktivasi satu kali Rp25.000. Sistem membuat ruang kerja terisolasi beserta pasangan kunci zp_live_, zp_test_, dan whsec_.
2. Koneksi QRIS & Rekening
Merchant menempelkan payload QRIS Statis usaha mereka di Dashboard (atau memakai rekening merchant agregator ZPay) serta mendaftarkan rekening bank/DANA tujuan pencairan.
3. Konversi EMVCo Dinamis
Saat tagihan dibuat (misal Rp50.000), mesin ZPay mencari angka kode unik 3 digit yang sedang tidak terpakai di jendela 15 menit (misal +Rp137 = Rp50.137), menyuntikkan Tag 54 EMVCo, dan menghitung ulang checksum CRC-16/CCITT-FALSE.
4. Pembacaan Mutasi & Webhook
Begitu pembeli membayar Rp50.137, jembatan pembaca mutasi ZPay mendeteksi kredit masuk, mencocokkan nominal Rp50.137 dengan tagihan pending, menandai status paid, dan menembakkan HTTP POST JSON bertanda tangan HMAC-SHA256 ke callback_url toko.
Kredensial
API key untuk memanggil API, dan secret untuk memverifikasi webhook yang kami kirim ke tokomu.
API key live (zp_live_), API key uji (zp_test_), dan secret webhook dibuat di dashboard setelah akunmu aktif.
Mulai cepat
Empat langkah dari nol sampai pembayaran pertama tercatat otomatis di sistem tokomu.
1. Buat API key
Buat API key di bagian Kredensial di atas. Simpan di environment variable server, misalnya ZPAY_API_KEY. Jangan pernah menaruhnya di kode frontend atau aplikasi mobile.
Autentikasi
Setiap request API wajib membawa API key di header Authorization. Key zp_test_ untuk mode uji (lihat Sandbox).
Header
Authorization: Bearer zp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
API key disimpan terenkripsi dan tersembunyi di dashboard. Hanya kamu yang bisa menampilkannya lagi, dengan password akun. Curiga bocor? Buat ulang: key lama langsung mati.
Membuat ulang API key langsung mematikan key lama. Lakukan ini kalau key pernah bocor.
API key hanya untuk server-ke-server. Request dari browser tanpa key memakai sesi dashboard, bukan API key.
API key salah atau akun nonaktif dijawab 401 invalid_api_key.
Buat tagihan
Membuat tagihan QRIS dinamis dengan nominal unik. Balasan 201 berisi tagihan baru.
amountintegerwajib
Nominal dalam rupiah, Rp1.000 sampai Rp10.000.000. Kode unik ditambahkan otomatis.
referencestring
Nomor pesanan di sistemmu (maks 100 karakter). Ikut dikirim di webhook. Tidak unik: cocokkan pembayaran lewat id, bukan reference.
descriptionstring
Keterangan yang tampil di halaman bayar (maks 200 karakter).
callback_urlurl
Penerima webhook tagihan ini. Kosong = pakai URL webhook default akunmu (tagihan uji: kosong = tanpa webhook).
redirect_urlurl
Pembeli diarahkan ke sini 5 detik setelah pembayaran diterima.
expires_ininteger
Masa berlaku dalam menit, 5 sampai 60. Default 15.
Idempotency-Keyheader
Opsional. Kirim ulang request dengan key yang sama = tagihan yang sama (200), bukan tagihan baru. Pakai nomor pesanan.
import os, requests
r = requests.post(
"https://zpay.zeropoint.id/api/payments",
headers={
"Authorization": f"Bearer {os.environ['ZPAY_API_KEY']}",
"Idempotency-Key": "INV-2041",
},
json={"amount": 50000, "reference": "INV-2041", "description": "Paket Premium 1 bulan"},
timeout=15,
)
r.raise_for_status()
tagihan = r.json()
# simpan tagihan["id"] di pesananmu (dipakai mencocokkan webhook, bukan reference)
print(tagihan["pay_url"])
Respons 201
{
"id": "ZPY-7K3M9QX4R81P2",
"reference": "INV-2041",
"description": "Paket Premium 1 bulan",
"status": "pending",
"base_amount": 50000,
"unique_code": 137,
"amount": 50137,
"qris": "0002010102122661...6304A1B2",
"pay_url": "https://zpay.zeropoint.id/pay/ZPY-7K3M9QX4R81P2",
"callback_url": "https://tokoku.id/webhook/zpay",
"redirect_url": "https://tokoku.id/pesanan/INV-2041",
"created_at": "2026-08-24T03:00:00.000Z",
"expires_at": "2026-08-24T03:15:00.000Z",
"paid_at": null,
"late": false,
"livemode": true,
"link_id": null,
"payment": null
}
Tampilkan amount (sudah termasuk kode unik) ke pembeli. Pembayaran dengan nominal berbeda tidak bisa dicocokkan otomatis.
Ambil tagihan
Status terbaru satu tagihan, termasuk detail pembayaran dan riwayat webhook-nya.
r = requests.get(
"https://zpay.zeropoint.id/api/payments/ZPY-7K3M9QX4R81P2",
headers={"Authorization": f"Bearer {os.environ['ZPAY_API_KEY']}"},
timeout=15,
)
print(r.json()["status"])
Setelah lunas, objek payment berisi issuer (bank atau e-wallet pembayar), payer (nama yang sudah disamarkan bank), bca_ref (nomor referensi transaksi), dan transaction_at. Field webhooks berisi 20 pengiriman terakhir.
Struk gambar (PNG) untuk dikirim ke pembeli: GET /api/payments/:id/receipt.png. Hanya tagihan lunas, selain itu 404 not_paid.
Daftar tagihan
Tagihan milikmu, terbaru lebih dulu, dengan paginasi berbasis waktu.
statusstring
Saring: pending, paid, expired, atau cancelled.
from, toISO 8601
Rentang waktu, from ikut, to tidak ikut.
bystring
paid = rentang dan urutan memakai waktu bayar. Default waktu dibuat.
qstring
Cari di referensi, keterangan, ID, ref bank, nama pembayar, atau nominal persis.
issuerstring
Bank atau e-wallet pembayar, mis. DANA.
summary1
Tambahkan ringkasan: jumlah dan total seluruh hasil filter, per status, dan per sumber.
limitinteger
Jumlah per halaman, 1 sampai 200. Default 50.
before, before_idISO 8601, string
Halaman berikutnya: isi dengan next_before dan next_before_id dari respons sebelumnya.
page = None
while True:
params = {"status": "paid", "limit": 100}
if page:
params |= {"before": page["next_before"], "before_id": page["next_before_id"]}
page = requests.get("https://zpay.zeropoint.id/api/payments", params=params,
headers={"Authorization": f"Bearer {os.environ['ZPAY_API_KEY']}"}).json()
for t in page["data"]:
print(t["reference"], t["amount"])
if not page["has_more"]:
break
Respons
{
"data": [ { "id": "ZPY-7K3M9QX4R81P2", "status": "paid", "amount": 50137 } ],
"has_more": true,
"next_before": "2026-08-24T02:00:00.000Z",
"next_before_id": "ZPY-7K3M9QX4R81P2"
}
Batalkan tagihan
Menutup tagihan yang masih menunggu. Pembayaran yang masuk setelah dibatalkan tidak akan dicocokkan.
requests.post("https://zpay.zeropoint.id/api/payments/ZPY-7K3M9QX4R81P2/cancel",
headers={"Authorization": f"Bearer {os.environ['ZPAY_API_KEY']}"})
Tagihan yang sudah lunas, kedaluwarsa, atau batal dijawab 409 not_pending. Kalau tagihan punya callback_url, event payment.cancelled ikut dikirim.
Link pembayaran & penarikan dana
Membuat tautan pembayaran berulang (/l/:slug) yang bisa dibagikan di chat WhatsApp, Instagram, atau tombol beli cepat.
titlestringwajib
Judul produk atau layanan yang tampil di halaman checkout pembeli.
amountinteger | null
Nominal tetap dalam Rupiah. Kosongkan (null) jika pembeli bebas mengisi nominal sendiri (misal donasi).
slugstring
Akhiran URL khusus, misal kelas-fullstack menjadi https://zpay.zeropoint.id/l/kelas-fullstack.
Menarik saldo tersedia (available) ke rekening bank atau DANA terdaftar. Gratis (Rp0) ke DANA & bank mitra, atau Rp2.500 via jalur BI-FAST ke bank lain.
Saldo
Ringkasan saldo akunmu: bisa ditarik, dana tertahan beserta jadwal cairnya, dan penarikan yang sedang berjalan.
r = requests.get(
"https://zpay.zeropoint.id/api/balance",
headers={"Authorization": f"Bearer {os.environ['ZPAY_API_KEY']}"},
timeout=15,
)
print(r.json()["available"])
Respons
{
"currency": "IDR",
"available": 1250000, // bisa ditarik sekarang
"held": 340000, // tertahan, menunggu jadwal pencairan
"in_process": 0, // penarikan sedang diproses
"withdrawn": 5000000, // total sudah ditarik (lunas)
"next_release_at": "2026-10-13T12:10:00.000Z",
"upcoming": [
{ "at": "2026-10-13T12:10:00.000Z", "amount": 340000, "count": 12 }
],
"total_received": 1590000, // settled + held
"settled": 1250000,
"gross": 1620000, // total bruto tagihan lunas
"fee": 30000, // total biaya layanan
"platform_fee": 0,
"adjustments": 0, // penyesuaian saldo oleh admin
"min_withdraw": 50000,
"pending_withdrawals": { "count": 0, "amount": 0 },
"server_time": "2026-10-12T10:00:00.000Z"
}
Field respons
availableinteger
Saldo yang bisa ditarik sekarang (rupiah).
heldinteger
Dana sudah lunas tapi belum cair, menunggu jadwal settlement bank.
next_release_atISO 8601
Kapan sebagian dana tertahan cair berikutnya (null kalau tidak ada).
upcomingarray
Jadwal pencairan dana tertahan: { at, amount, count } per batch.
in_processinteger
Total nominal penarikan yang sedang diproses.
pending_withdrawalsobject
Penarikan yang belum selesai: { count, amount }.
withdrawninteger
Total yang sudah berhasil ditarik (lunas).
total_receivedinteger
Total bersih diterima (settled + held).
gross, feeinteger
Total bruto tagihan lunas dan total biaya layanan.
adjustmentsinteger
Penyesuaian saldo manual oleh admin (bisa minus).
min_withdrawinteger
Nominal minimal satu penarikan.
Saldo selalu live. Tagihan mode uji tidak pernah jadi uang, jadi key zp_test_ pun membaca saldo live akun yang sama.
Siklus status
Setiap tagihan dimulai dari pending dan berakhir di salah satu dari tiga status final.
pending → dana masuk, nominal cocok → paid
pending → lewat batas waktu + 5 menit → expired
pending → dibatalkan lewat dashboard/API → cancelled
Menunggu pending
QR aktif dan bisa dibayar. Mutasi rekening dicek tiap 8 detik.
Lunas paid
Kredit dengan nominal persis ditemukan di mutasi rekening dalam jendela waktu tagihan.
Kedaluwarsa expired
Lewat batas waktu + 5 menit masa tenggang tanpa pembayaran yang cocok.
Batal cancelled
Dibatalkan lewat dashboard atau API sebelum dibayar.
Webhook
Kami mengirim POST JSON ke callback_url setiap kali status tagihan berubah jadi final.
Event
Dikirim saat
payment.paid
Pembayaran cocok ditemukan, tagihan lunas. Bisa datang setelah payment.expired / payment.cancelled bila admin mencocokkan pembayaran telat (data.late = true).
payment.expired
Tagihan lewat batas waktu tanpa pembayaran.
payment.cancelled
Tagihan dibatalkan.
ping
Tombol “Kirim tes” di bagian Kredensial.
Contoh kiriman
// Header
X-ZPay-Event: payment.paid
X-ZPay-Delivery: 1842
X-ZPay-Timestamp: 1790218892
X-Signature: 5f2b9c...a91e // hex HMAC-SHA256(secret, "<timestamp>.<body>")
// Body
{
"id": "evt_Qm9vK8nPz1Lx4wR7",
"event": "payment.paid",
"created_at": "2026-08-24T03:03:12.000Z",
"livemode": true, // false = event tagihan mode uji (sandbox)
"data": {
"id": "ZPY-7K3M9QX4R81P2",
"reference": "INV-2041",
"status": "paid",
"base_amount": 50000,
"amount": 50137,
"pay_url": "https://zpay.zeropoint.id/pay/ZPY-7K3M9QX4R81P2",
"paid_at": "2026-08-24T03:03:12.000Z",
"late": false,
"livemode": true,
"link_id": null,
"payment": {
"issuer": "DANA",
"payer": "BU**I SAN**SO",
"bca_ref": "238412255",
"transaction_at": "2026-08-24T03:03:08.000Z"
}
}
}
Verifikasi tanda tangan
Hitung HMAC-SHA256(secret, timestamp + "." + body) dari body mentah, bandingkan dengan header X-Signature memakai perbandingan waktu-konstan, dan tolak timestamp yang lebih tua dari 5 menit supaya kiriman lama tidak bisa diputar ulang.
import hashlib, hmac, os, time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["ZPAY_WEBHOOK_SECRET"].encode()
@app.post("/webhook/zpay")
def zpay():
ts = request.headers.get("X-ZPay-Timestamp", "")
sig = request.headers.get("X-Signature", "")
expected = hmac.new(SECRET, f"{ts}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig) or abs(time.time() - int(ts or 0)) > 300:
abort(401)
event = request.get_json()
if event.get("livemode") is False:
return "", 200 # event mode uji: jangan pernah menandai pesanan asli
if event["event"] == "payment.paid":
# cari pesanan lewat id tagihan, BUKAN reference; nominal harus sama dengan total pesanan
order = find_order_by_zpay_id(event["data"]["id"])
if order and event["data"]["base_amount"] == order.total:
mark_paid(order, event["id"]) # lewati kalau event.id sudah pernah diproses
return "", 200
Gagal atau bukan 2xx? Dicoba ulang 6 kali: langsung, lalu +30 detik, +2 menit, +10 menit, +30 menit, +2 jam.
Balas 2xx secepatnya (batas 10 detik). Proses berat jalankan di belakang.
Event bisa terkirim lebih dari sekali. Simpan id event yang sudah diproses dan lewati duplikatnya.
Tanda tangan valid belum berarti pesanannya benar. Simpan id tagihan saat membuatnya, cari pesanan lewat data.id (bukan reference), pastikan data.base_amount sama dengan total pesanan, dan abaikan livemode: false.
URL ke jaringan privat (localhost, 10.x, 192.168.x, metadata cloud) ditolak. Redirect tidak diikuti.
Halaman bayar
Setiap tagihan punya halaman bayar siap pakai di pay_url.
Halaman bayar menampilkan QR, nominal persis, hitung mundur, tombol cek transaksi, dan berubah sendiri saat lunas. Setelah lunas, pembeli bisa mengunduh atau mencetak bukti bayar.
Kalau ada redirect_url, pembeli diarahkan ke sana 5 detik setelah lunas. Tagihan mode uji tidak dialihkan otomatis: alamatnya ditampilkan dan harus diklik.
Mau tampil di aplikasimu sendiri? Buat gambar QR dari string qris dengan library QR apa pun.
Jangan anggap pesanan lunas hanya karena pembeli kembali ke redirect_url. Selalu pegang webhook atau cek status lewat API.
Kepala halaman bayar menampilkan logo, nama toko, dan centang verifikasi dari Akun → Profil toko.
Tagihan dari link pembayaran (/l/:slug) punya link_id, reference kosong, dan webhook-nya dikirim ke URL webhook default akunmu.
Error & batasan
Semua error berbentuk { "error": "pesan untuk manusia", "code": "kode_mesin" }.
HTTP
code
Artinya
400
invalid_amount, invalid_url, invalid_expires_in, invalid_json, invalid_action
Input tidak valid. Baca pesan error-nya.
401
unauthorized, invalid_api_key
API key tidak ada, salah, atau sudah dibuat ulang.
403
account_not_active, forbidden, live_invoice
Akun belum disetujui/nonaktif, tidak punya akses, atau simulasi pada tagihan live.
404
not_found
Tagihan tidak ada atau bukan milikmu.
409
not_pending, not_final
Aksi tidak cocok dengan status tagihan saat ini.
413
payload_too_large
Body lebih dari 20 KB.
429
rate_limited, too_many_pending
Terlalu banyak request. Lihat header Retry-After.
503
amount_busy
Kode unik untuk nominal itu habis sementara. Coba lagi sebentar.
Nominal
Rp1.000 sampai Rp10.000.000, ditambah kode unik kecil (default Rp100 sampai Rp250; baca unique_code di respons).
Masa berlaku
5 sampai 60 menit (default 15), plus 5 menit masa tenggang.
Tagihan menunggu
Maksimal 50 per akun dalam satu waktu.
Pembuatan
Maksimal 30 tagihan per menit per akun.
Request
Maksimal 300 request per menit per alamat IP.
Body
JSON maksimal 20 KB per request.
Coba langsung (Live API Playground)
Uji pengiriman request POST /api/payments langsung dari halaman dokumentasi ini dan lihat respons JSON mentahnya.
// Klik tombol "Kirim Request POST /api/payments" di sebelah kiri
// untuk mengeksekusi simulasi pembuatan tagihan QRIS Dinamis.
Sandbox (mode uji)
Uji integrasi dari buat tagihan sampai webhook tanpa uang sungguhan. Data uji terpisah total dari data live.
Pakai API key zp_test_ dari bagian Kredensial. Endpoint-nya sama persis; tagihan uji punya livemode: false.
QR tagihan uji sengaja tidak bisa dibayar. Lunasi atau kedaluwarsakan lewat endpoint ini, atau tombol di halaman bayarnya.
Webhook uji hanya dikirim ke callback_url yang diisi saat membuat tagihan uji (bukan URL default), ditandatangani secret mode uji. Server produksi yang memakai secret live otomatis menolaknya; tetap abaikan livemode: false.
Key live tidak bisa membaca tagihan uji, dan sebaliknya. Tagihan uji tidak masuk saldo, statistik, atau notifikasi.
actionstring
pay = lunas (issuer SANDBOX, bca_ref palsu), expire = kedaluwarsa. Default pay. Hanya untuk tagihan uji yang masih pending.
r = requests.post(
"https://zpay.zeropoint.id/api/payments/ZPY-7K3M9QX4R81P2/simulate",
headers={"Authorization": f"Bearer {os.environ['ZPAY_TEST_KEY']}"},
json={"action": "pay"}, # atau "expire"
timeout=15,
)
print(r.json()["status"])
Tagihan live dijawab 403 live_invoice, tagihan uji yang sudah final 409 not_pending. Tagihan uji yang tidak disimulasikan kedaluwarsa sendiri seperti tagihan live.
