Terima pembayaran QRIS dalam tiga panggilan.
Buat QRIS dengan nominal tepat dari Rp1 sampai Rp10.000.000, tampilkan ke pelanggan, lalu ketahui kapan lunas — lewat polling atau callback bertanda tangan ke servermu.
https://zeetasi.qzz.io01Mulai cepat
Alur paling sederhana untuk toko, bot, atau website:
- Buat invoice dengan
POST /create-qris. Simpanorder_idmilikmu. - Tampilkan
pay_url(halaman bayar siap pakai) atau gambar dariqris_urlke pelanggan. - Konfirmasi lewat
POST /check-paymentberkala, atau terima callback saat lunas.
curl -X POST https://zeetasi.qzz.io/create-qris \
-H "X-API-Key: API_KEY_KAMU" \
-H "Content-Type: application/json" \
-d '{"amount": 25000, "order_id": "INV-0001"}'const res = await fetch('https://zeetasi.qzz.io/create-qris', {
method: 'POST',
headers: {
'X-API-Key': process.env.GATEWAY_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount: 25000, order_id: 'INV-0001' }),
});
const { data } = await res.json();
console.log(data.pay_url, data.payable_amount);<?php
$ch = curl_init('https://zeetasi.qzz.io/create-qris');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('GATEWAY_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['amount' => 25000, 'order_id' => 'INV-0001']),
]);
$data = json_decode(curl_exec($ch), true)['data'];
echo $data['pay_url'];import os, requests
res = requests.post(
"https://zeetasi.qzz.io/create-qris",
headers={"X-API-Key": os.environ["GATEWAY_API_KEY"]},
json={"amount": 25000, "order_id": "INV-0001"},
timeout=15,
)
data = res.json()["data"]
print(data["pay_url"], data["payable_amount"])02Autentikasi
Semua endpoint bertanda KUNCI memerlukan header X-API-Key berisi API key gateway (env API_KEY di Vercel). Kunci tidak diterima lewat query string agar tidak bocor ke log.
X-API-Key: API_KEY_KAMU
Content-Type: application/json03Buat QRIS
/create-qrisbutuh API keyMenerbitkan invoice QRIS bernominal. Invoice berlaku 15 menit.
| Nama | Tipe | Keterangan |
|---|---|---|
amountWAJIB | integer | Rupiah, bilangan bulat, antara 1 dan 10.000.000. |
order_idWAJIB | string | ID unik pesananmu, 3–64 karakter (huruf, angka, . _ -). |
curl -X POST https://zeetasi.qzz.io/create-qris \
-H "X-API-Key: API_KEY_KAMU" \
-H "Content-Type: application/json" \
-d '{"amount": 25000, "order_id": "INV-0001"}'const res = await fetch('https://zeetasi.qzz.io/create-qris', {
method: 'POST',
headers: {
'X-API-Key': process.env.GATEWAY_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount: 25000, order_id: 'INV-0001' }),
});
const { data } = await res.json();
console.log(data.pay_url, data.payable_amount);<?php
$ch = curl_init('https://zeetasi.qzz.io/create-qris');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('GATEWAY_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['amount' => 25000, 'order_id' => 'INV-0001']),
]);
$data = json_decode(curl_exec($ch), true)['data'];
echo $data['pay_url'];import os, requests
res = requests.post(
"https://zeetasi.qzz.io/create-qris",
headers={"X-API-Key": os.environ["GATEWAY_API_KEY"]},
json={"amount": 25000, "order_id": "INV-0001"},
timeout=15,
)
data = res.json()["data"]
print(data["pay_url"], data["payable_amount"])Respons 201 Created
{
"success": true,
"data": {
"invoice_id": "3f9c2a1e-5b7d-4c80-9a42-0d1e6f7b8c21",
"order_id": "INV-0001",
"amount": 25000,
"unique_code": 0,
"payable_amount": 25000,
"currency": "IDR",
"status": "PENDING",
"qris_kind": "static_injected",
"expires_at": "2026-10-31T09:15:00.000Z",
"paid_at": null,
"created_at": "2026-10-31T09:00:00.000Z",
"qris_url": "https://zeetasi.qzz.io/qr/3f9c2a1e-5b7d-4c80-9a42-0d1e6f7b8c21",
"pay_url": "https://zeetasi.qzz.io/pay/3f9c2a1e-5b7d-4c80-9a42-0d1e6f7b8c21",
"qris_payload": "000201010212...6304ABCD"
}
}| Nama | Tipe | Keterangan |
|---|---|---|
payable_amount | integer | Nominal yang harus dibayar pelanggan (amount + kode unik bila aktif). |
unique_code | integer | Tambahan 1–N rupiah agar dua invoice tak bentrok. 0 bila fitur nonaktif atau nominal kecil. |
pay_url | string | Halaman bayar publik: QR, hitung mundur, dan status otomatis. |
qris_url | string | Gambar PNG QR untuk disematkan di aplikasimu. |
qris_payload | string | Isi QRIS mentah bila ingin membuat gambar QR sendiri. |
expires_at | ISO 8601 | Batas waktu bayar (UTC). |
04Cek pembayaran
/check-paymentbutuh API keyMengembalikan status terbaru. Aman dipanggil tiap 5–10 detik; panggilan lebih rapat dibatasi otomatis (throttled: true) untuk melindungi sesi ShopeePay.
| Nama | Tipe | Keterangan |
|---|---|---|
order_idWAJIB | string | ID pesanan yang sama saat membuat QRIS. |
curl -X POST https://zeetasi.qzz.io/check-payment \
-H "X-API-Key: API_KEY_KAMU" \
-H "Content-Type: application/json" \
-d '{"order_id": "INV-0001"}'const res = await fetch('https://zeetasi.qzz.io/check-payment', {
method: 'POST',
headers: { 'X-API-Key': process.env.GATEWAY_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ order_id: 'INV-0001' }),
});
const r = await res.json();
if (r.paid) console.log('Lunas!', r.transaction.paid_at);<?php
$ch = curl_init('https://zeetasi.qzz.io/check-payment');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('GATEWAY_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['order_id' => 'INV-0001']),
]);
$r = json_decode(curl_exec($ch), true);
if ($r['paid']) { /* kirim produk */ }r = requests.post(
"https://zeetasi.qzz.io/check-payment",
headers={"X-API-Key": os.environ["GATEWAY_API_KEY"]},
json={"order_id": "INV-0001"},
timeout=15,
).json()
if r["paid"]:
print("Lunas!", r["transaction"]["paid_at"])Respons saat lunas
{
"success": true,
"paid": true,
"status": "PAID",
"order_id": "INV-0001",
"transaction": {
"transaction_id": "TX-889120",
"amount": 25000,
"paid_at": "2026-10-31T09:04:12.000Z"
},
"data": {
"…": "sama seperti objek invoice"
}
}Nilai status: PENDING (menunggu), PAID (lunas), EXPIRED (kedaluwarsa/dibatalkan), FAILED. Anggap pesanan lunas hanya bila paid === true.
05Halaman bayar
/pay/{invoice_id}publikHalaman checkout siap pakai berbentuk struk: QR, nominal, hitung mundur, dan stempel LUNAS otomatis saat pembayaran masuk. Cukup kirim pay_url ke pelanggan (chat, email, tombol bayar).
/qr/{invoice_id}publikGambar PNG 512×512 untuk invoice yang masih aktif. Mengembalikan 410 bila sudah lunas atau kedaluwarsa.
06Callback (webhook)
Bila CALLBACK_URL dan CALLBACK_SECRET diisi, gateway mengirim POST ke servermu begitu invoice lunas, dengan percobaan ulang bertahap sampai servermu membalas 2xx. Pengiriman bersifat at-least-once, jadi buat handler yang idempotent.
{
"event": "payment.paid",
"event_id": "evt_3f9c2a1e-…",
"order_id": "INV-0001",
"invoice_id": "3f9c2a1e-…",
"amount": 25000,
"payable_amount": 25000,
"currency": "IDR",
"status": "PAID",
"transaction_id": "TX-889120",
"paid_at": "2026-10-31T09:04:12.000Z",
"source": "watcher"
}| Nama | Tipe | Keterangan |
|---|---|---|
X-Gateway-Signature | header | t=<unix>,v1=<hex>. v1 = HMAC-SHA256(CALLBACK_SECRET, t + "." + bodyMentah). |
X-Gateway-Event | header | Selalu payment.paid. |
X-Gateway-Event-Id | header | ID unik peristiwa untuk deduplikasi. |
Verifikasi tanda tangan
const crypto = require('crypto');
// WAJIB pakai body mentah (string persis yang diterima), bukan hasil JSON.parse.
app.post('/payment-callback', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
const h = Object.fromEntries(req.get('x-gateway-signature').split(',').map(p => p.trim().split('=')));
const expected = crypto.createHmac('sha256', process.env.CALLBACK_SECRET)
.update(h.t + '.' + raw).digest('hex');
const ok = h.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(h.v1), Buffer.from(expected)) &&
Math.abs(Date.now() / 1000 - Number(h.t)) < 300;
if (!ok) return res.sendStatus(401);
const evt = JSON.parse(raw);
// idempotent: abaikan bila evt.order_id sudah diproses
res.json({ ok: true });
});<?php
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_GATEWAY_SIGNATURE']), $h);
$expected = hash_hmac('sha256', $h['t'] . '.' . $raw, getenv('CALLBACK_SECRET'));
if (!hash_equals($expected, $h['v1']) || abs(time() - (int)$h['t']) > 300) {
http_response_code(401); exit;
}
$evt = json_decode($raw, true);
// idempotent: abaikan bila $evt['order_id'] sudah diproses
http_response_code(200); echo json_encode(['ok' => true]);import hmac, hashlib, time, os
from flask import Flask, request
@app.post("/payment-callback")
def callback():
raw = request.get_data(as_text=True) # body mentah
h = dict(p.strip().split("=", 1) for p in request.headers["X-Gateway-Signature"].split(","))
expected = hmac.new(os.environ["CALLBACK_SECRET"].encode(), f'{h["t"]}.{raw}'.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, h["v1"]) or abs(time.time() - int(h["t"])) > 300:
return "", 401
evt = request.get_json()
# idempotent: abaikan bila evt["order_id"] sudah diproses
return {"ok": True}07Riwayat transaksi
/transactionsbutuh API keyDaftar invoice terbaru. Parameter: page, limit (1–100), status, order_id.
/transactions/allbutuh API keySeperti di atas dengan filter tanggal start_date / end_date (YYYY-MM-DD, zona WIB), limit sampai 500, serta total_paid_amount.
/transactions/providerbutuh API keyMembaca mutasi langsung dari Partner Portal ShopeePay (butuh sesi aktif).
curl "https://zeetasi.qzz.io/transactions/all?status=PAID&start_date=2026-10-01&end_date=2026-10-31&limit=100" \
-H "X-API-Key: API_KEY_KAMU"08Operasional
/api/healthpublikCek hidup. Mengembalikan {"status":"online"} tanpa data sensitif.
/token-statusbutuh API keyMenguji sesi ShopeePay: VALID, INVALID, UNVERIFIED, atau NOT_CONFIGURED.
/update-sessionbutuh API keyMengganti sesi portal di memori. Body: {"curl": "…hasil Copy as cURL…"}. Bisa juga lewat dashboard → Sistem.
/cron/tickAPI key / CRON_SECRETSatu putaran pemantauan: menutup invoice kedaluwarsa, mencocokkan mutasi, dan mengirim callback tertunda. Jadwalkan tiap menit dari cron eksternal bila berjalan di Vercel.
/callbacksbutuh API keyAntrean callback. Pantau status=FAILED; kirim ulang dengan POST /callbacks/retry dan body {"order_id": "…"}.
09Kode error
Semua error berbentuk {"success": false, "error": {"code": "…", "message": "…"}}.
| Kode | HTTP | Arti |
|---|---|---|
UNAUTHORIZED | 401 | Header X-API-Key tidak ada atau salah. |
INVALID_JSON | 400 | Body bukan JSON yang valid. |
INVALID_AMOUNT | 400 | amount harus bilangan bulat positif (bukan string, bukan desimal). |
AMOUNT_OUT_OF_RANGE | 400 | Nominal di luar rentang Rp1 – Rp10.000.000. |
INVALID_ORDER_ID | 400 | order_id 3–64 karakter: huruf, angka, titik, garis bawah, atau strip. |
DUPLICATE_ORDER_ID | 409 | order_id sudah pernah dipakai. |
AMOUNT_IN_USE | 409 | Masih ada invoice PENDING dengan total bayar yang sama. Gunakan kode unik atau nominal lain. |
INVOICE_NOT_FOUND | 404 | Tidak ada invoice untuk order_id tersebut. |
INVOICE_INACTIVE | 410 | QR diminta untuk invoice yang sudah lunas/kedaluwarsa. |
NOT_CONFIGURED | 501 | Fitur belum dikonfigurasi (mis. QRIS_STATIC atau sesi portal). |
RATE_LIMITED | 429 | Terlalu banyak request. Tunggu lalu coba lagi. |
PROVIDER_TOKEN_INVALID | 502 | Sesi ShopeePay kedaluwarsa; perbarui sesi di dashboard → Sistem. |
PROVIDER_* | 502 | Gangguan saat membaca mutasi (tidak terjangkau, dibatasi, atau respons tak dikenali). |
Batas
- Nominal: Rp1 – Rp10.000.000 per invoice.
- Rate limit: 120 request per menit per IP.
- Masa berlaku invoice: 15 menit, ditambah tenggang 10 menit untuk mutasi yang terlambat.