zeetasi.pay
Referensi API · v1

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.

Base URLhttps://zeetasi.qzz.io

01Mulai cepat

Alur paling sederhana untuk toko, bot, atau website:

  • Buat invoice dengan POST /create-qris. Simpan order_id milikmu.
  • Tampilkan pay_url (halaman bayar siap pakai) atau gambar dari qris_url ke pelanggan.
  • Konfirmasi lewat POST /check-payment berkala, 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.

Simpan API key hanya di server/backend. Jangan pernah menaruhnya di JavaScript browser atau aplikasi mobile.
Header wajib
X-API-Key: API_KEY_KAMU
Content-Type: application/json

03Buat QRIS

POST/create-qrisbutuh API key

Menerbitkan invoice QRIS bernominal. Invoice berlaku 15 menit.

NamaTipeKeterangan
amountWAJIBintegerRupiah, bilangan bulat, antara 1 dan 10.000.000.
order_idWAJIBstringID 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

application/json
{
  "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"
  }
}
NamaTipeKeterangan
payable_amountintegerNominal yang harus dibayar pelanggan (amount + kode unik bila aktif).
unique_codeintegerTambahan 1–N rupiah agar dua invoice tak bentrok. 0 bila fitur nonaktif atau nominal kecil.
pay_urlstringHalaman bayar publik: QR, hitung mundur, dan status otomatis.
qris_urlstringGambar PNG QR untuk disematkan di aplikasimu.
qris_payloadstringIsi QRIS mentah bila ingin membuat gambar QR sendiri.
expires_atISO 8601Batas waktu bayar (UTC).
Nominal kecil: Rp1 diterima. Kode unik tidak dipakai untuk nominal di bawah Rp1.000, sehingga Rp1 tetap Rp1 — dua invoice PENDING dengan nominal sama tidak boleh berjalan bersamaan.

04Cek pembayaran

POST/check-paymentbutuh API key

Mengembalikan status terbaru. Aman dipanggil tiap 5–10 detik; panggilan lebih rapat dibatasi otomatis (throttled: true) untuk melindungi sesi ShopeePay.

NamaTipeKeterangan
order_idWAJIBstringID 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

application/json
{
  "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

GET/pay/{invoice_id}publik

Halaman 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).

GET/qr/{invoice_id}publik

Gambar 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.

Body callback
{
  "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"
}
NamaTipeKeterangan
X-Gateway-Signatureheadert=<unix>,v1=<hex>. v1 = HMAC-SHA256(CALLBACK_SECRET, t + "." + bodyMentah).
X-Gateway-EventheaderSelalu payment.paid.
X-Gateway-Event-IdheaderID 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

GET/transactionsbutuh API key

Daftar invoice terbaru. Parameter: page, limit (1–100), status, order_id.

GET/transactions/allbutuh API key

Seperti di atas dengan filter tanggal start_date / end_date (YYYY-MM-DD, zona WIB), limit sampai 500, serta total_paid_amount.

GET/transactions/providerbutuh API key

Membaca 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

GET/api/healthpublik

Cek hidup. Mengembalikan {"status":"online"} tanpa data sensitif.

GET/token-statusbutuh API key

Menguji sesi ShopeePay: VALID, INVALID, UNVERIFIED, atau NOT_CONFIGURED.

POST/update-sessionbutuh API key

Mengganti sesi portal di memori. Body: {"curl": "…hasil Copy as cURL…"}. Bisa juga lewat dashboard → Sistem.

GET/cron/tickAPI key / CRON_SECRET

Satu putaran pemantauan: menutup invoice kedaluwarsa, mencocokkan mutasi, dan mengirim callback tertunda. Jadwalkan tiap menit dari cron eksternal bila berjalan di Vercel.

GET/callbacksbutuh API key

Antrean callback. Pantau status=FAILED; kirim ulang dengan POST /callbacks/retry dan body {"order_id": "…"}.

09Kode error

Semua error berbentuk {"success": false, "error": {"code": "…", "message": "…"}}.

KodeHTTPArti
UNAUTHORIZED401Header X-API-Key tidak ada atau salah.
INVALID_JSON400Body bukan JSON yang valid.
INVALID_AMOUNT400amount harus bilangan bulat positif (bukan string, bukan desimal).
AMOUNT_OUT_OF_RANGE400Nominal di luar rentang Rp1 – Rp10.000.000.
INVALID_ORDER_ID400order_id 3–64 karakter: huruf, angka, titik, garis bawah, atau strip.
DUPLICATE_ORDER_ID409order_id sudah pernah dipakai.
AMOUNT_IN_USE409Masih ada invoice PENDING dengan total bayar yang sama. Gunakan kode unik atau nominal lain.
INVOICE_NOT_FOUND404Tidak ada invoice untuk order_id tersebut.
INVOICE_INACTIVE410QR diminta untuk invoice yang sudah lunas/kedaluwarsa.
NOT_CONFIGURED501Fitur belum dikonfigurasi (mis. QRIS_STATIC atau sesi portal).
RATE_LIMITED429Terlalu banyak request. Tunggu lalu coba lagi.
PROVIDER_TOKEN_INVALID502Sesi ShopeePay kedaluwarsa; perbarui sesi di dashboard → Sistem.
PROVIDER_*502Gangguan 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.