Dokumentasi API KuyzPay

Base URL

Salinhttps://api.kuyzpay.xyz/api/v1

Ganti domain contoh dengan domain instalasi KuyzPay Anda. Produksi wajib memakai HTTPS.

Authentication

Setiap akun KuyzPay memiliki satu merchant/nama toko. Merchant ID dipakai bersama, sedangkan Sandbox dan Live mempunyai secret, webhook, whitelist IP, serta riwayat transaksi yang terpisah. Simpan secret hanya di server.

Sandbox dan Live

Pilih environment melalui switcher Dashboard. Endpoint API tetap sama, tetapi gunakan Secret Key dari environment yang dipilih. Jika memakai signature, kirim environment bernilai sandbox atau live; jika memakai secret, KuyzPay mengenali environment dari secret tersebut.

Masa sesi akun pembayaran

Koneksi akun pembayaran menggunakan access token yang disimpan terenkripsi di server, bukan cookie browser pengguna. Admin dan member Premium dapat mengisi email/password GoBiz/GoPay secara opsional pada pengaturan akun pembayaran; password tidak ditampilkan kembali di dashboard. Jika login password didukung provider, KuyzPay dapat mencobanya saat token tidak valid. OTP tetap tersedia bila login password gagal atau tidak didukung. Masa berlaku token ditentukan provider dan tidak selalu menyertakan tanggal expiry. KuyzPay memvalidasi token berkala, menyimpannya agar tetap tersedia setelah restart, mencoba refresh otomatis jika refresh token tersedia, dan menandai akun Belum login jika provider menolak sesi.

Kompatibilitas dan alias parameter

KuyzPay menyediakan nama parameter utama dan beberapa alias alternatif untuk mempermudah migrasi integrasi. Endpoint utama tersedia pada /api/v1/*; integrasi lama dapat memakai alias terbatas /v1/order, /v1/check-order, /v1/merchant, dan /v1/merchant/balance. Alias order mengembalikan status: "Success", sedangkan endpoint asli mempertahankan envelope KuyzPay status: 1.

Simple Order dapat memakai secret. Advanced Order dapat menggantinya dengan signature = md5(merchant_id:secret:ref_id), sehingga secret tidak dikirim di body. ref_id bersifat idempotent: pengulangan request mengembalikan order lama.

Metode Pembayaran

Channel pada response

Biaya transaksi

Alur pemrosesan KuyzPay

1. Pembuatan tagihan: QRIS sumber divalidasi, diubah menjadi QRIS dinamis, diberi nominal final, lalu CRC dihitung ulang.
2. Rekonsiliasi: transaksi masuk pada akun pembayaran yang terhubung dicocokkan menggunakan nominal final dan rentang waktu order.
3. Konfirmasi: satu transaksi provider hanya dapat diklaim oleh satu order. Status diperbarui secara atomik sebelum webhook dikirim.

GET Membuat Order Sederhana

ref_id wajib unik per merchant dan environment. Nilai yang sama boleh dipakai sekali di Sandbox dan sekali di Live. Pengulangan pada environment yang sama mengembalikan order lama. Untuk produksi, gunakan signature pada GET agar Secret Key tidak tersimpan di URL/access log; alternatif yang direkomendasikan adalah POST JSON.

Salincurl -G "https://api.kuyzpay.xyz/api/v1/order" \
  --data-urlencode "merchant=KPXXXXXXXX" \
  --data-urlencode "environment=live" \
  --data-urlencode "signature=MD5_MERCHANT_SECRET_REF" \
  --data-urlencode "ref_id=ORDER-001" \
  --data-urlencode "nominal=25000" \
  --data-urlencode "metode=QRIS"

POST Membuat Order Advanced

Salincurl -X POST "https://api.kuyzpay.xyz/api/v1/order" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "KPXXXXXXXX",
    "reff_id": "ORDER-001",
    "amount": 25000,
    "kode_channel": "QRIS",
    "signature": "MD5_MERCHANT_ID_SECRET_REF_ID",
    "customer_name": "Budi",
    "redirect_url": "https://toko.example/sukses",
    "webhook_url": "https://toko.example/webhook"
  }'

Response sukses

{
  "status": 1,
  "rc": 200,
  "data": {
    "trx_id": "KP260828ABC123",
    "ref_id": "ORDER-001",
    "pay_url": "https://domain-kuyzpay.com/pay/KP260828ABC123",
    "qr_link": "https://domain-kuyzpay.com/pay/KP260828ABC123/qr",
    "qr_string": "000201010212...6304ABCD",
    "total_bayar": 25292,
    "total_diterima": 25250,
    "admin_fee": 250,
    "fee_percent": 1,
    "member_profit": 250,
    "platform_fee": 0,
    "unique_code": 42,
    "channel": "QRIS_ADMIN",
    "payment_source": "platform_qris",
    "environment": "live",
    "auto_paid_after_seconds": null,
    "status": "Unpaid",
    "expired_at": "2026-08-28 10:15:00",
    "expired_ts": 1787886900,
    "late_payment_monitor_until": "2026-08-29 10:15:00"
  }
}

POST Cek Status Order

Gunakan trx_id (direkomendasikan) atau ref_id. Hentikan polling setelah status terminal.

Salincurl -X POST "https://api.kuyzpay.xyz/api/v1/check-order" \
  -H "Content-Type: application/json" \
  -d '{"merchant_id":"KPXXXXXXXX","secret":"YOUR_SECRET","trx_id":"KP260828ABC123"}'

{
  "status": 1,
  "rc": 200,
  "message": "Data Found",
  "data": {
    "trx_id": "KP260828ABC123",
    "reff_id": "ORDER-001",
    "merchant_id": "KPXXXXXXXX",
    "nominal": 25000,
    "jumlah_bayar": 25042,
    "jumlah_diterima": 25000,
    "unique_code": 42,
    "environment": "live",
    "status": "Success",
    "payment_method": "QRIS",
    "payment_reference": "PROVIDER-TRANSACTION-ID",
    "created_at": "2026-08-28 10:00:00",
    "paid_at": "2026-08-28 10:03:27",
    "expired_at": "2026-08-28 10:15:00",
    "cancelled_at": "",
    "cancel_reason": "",
    "late_paid_at": "",
    "late_payment_monitor_until": "2026-08-29 10:15:00"
  }
}

POST Batalkan Order

Endpoint ini idempotent. Gunakan ketika timer order pada aplikasi Anda habis atau pelanggan membatalkan checkout. KuyzPay mengubah order Unpaid menjadi Cancelled, berhenti menampilkan QR, dan mengirim event payment.cancelled.

Salincurl -X POST "https://api.kuyzpay.xyz/api/v1/cancel-order" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "KPXXXXXXXX",
    "secret": "YOUR_SECRET",
    "trx_id": "KP260828ABC123",
    "reason": "Timer checkout pelanggan habis"
  }'

Anda boleh mengganti trx_id dengan ref_id/reff_id. Autentikasi juga dapat memakai signature = md5(merchant_id:secret:ref_id). Request ulang terhadap order yang sudah Cancelled tetap menghasilkan HTTP 200. Order yang sudah menerima pembayaran menghasilkan HTTP 409.

Pembayaran setelah cancel/expired

1. Jangan hapus relasi trx_id/ref_id dari database aplikasi Anda ketika timer habis.
2. Tandai order internal sebagai expired/cancelled dan panggil endpoint cancel.
3. Jika foto QR lama dibayar, KuyzPay mengubah status menjadi PaidLate dan mengirim payment.late.
4. Handler Anda harus mencatat dana tersebut lalu memilih kebijakan: aktifkan pesanan, masukkan saldo pelanggan, refund manual, atau minta pemeriksaan admin.

Pembatalan oleh pembayar

Hosted checkout menampilkan tombol Batalkan pembayaran jika link memiliki token pembatalan yang sah, pengguna merupakan pemilik invoice Premium yang sedang login, atau pengguna adalah Admin. Token disertakan otomatis pada pay_url baru dan tidak memerlukan Secret Key merchant di browser.

GET Informasi Akun

Salincurl -G "https://api.kuyzpay.xyz/api/v1/merchant/balance" \
  --data-urlencode "merchant_id=KPXXXXXXXX" \
  --data-urlencode "secret=YOUR_SECRET"

Sebagai alias alternatif, parameter merchant dapat menggantikan merchant_id dan signature=md5(merchant_id:secret) dapat menggantikan Secret Key mentah.

{
  "status": 1,
  "rc": 200,
  "message": "",
  "data": {
    "nama_toko": "Toko Saya",
    "merchant_id": "KPXXXXXXXX",
    "is_sandbox": false,
    "saldo_tersedia": 125000,
    "saldo_tertahan": 50000,
    "total_dicairkan": 300000,
    "balance_authoritative": true,
    "settlement_mode": "platform_wallet_manual_payout"
  }
}

POST Status Provider

Gunakan endpoint ini sebelum membuat invoice Live atau ketika menerima PROVIDER_AUTH_REQUIRED. Respons tidak membocorkan ID akun pembayaran, token, email provider, maupun detail internal. Autentikasi, pemisahan environment, dan whitelist IP sama dengan endpoint merchant.

Salincurl -X POST "https://api.kuyzpay.xyz/api/v1/provider/status" \
  -H "Content-Type: application/json" \
  -d '{"merchant_id":"KPXXXXXXXX","secret":"YOUR_LIVE_SECRET"}'

{
  "status": 1,
  "rc": 200,
  "data": {
    "environment": "live",
    "payment_source": "platform_qris",
    "live_available": false,
    "provider_status": "unavailable",
    "requires_reauthentication": true,
    "error_code": "PROVIDER_AUTH_REQUIRED",
    "checked_at": "2026-09-10T12:00:00.000Z",
    "recheck_after_seconds": 60
  }
}

Callback / Webhook

KuyzPay mengirim POST application/json untuk perubahan status penting. Signature terdapat di header X-KuyzPay-Signature dan menggunakan HMAC-SHA256 dengan secret merchant terhadap raw JSON body.

{
  "event": "payment.success",
  "data": {
    "merchant_id": "KPXXXXXXXX",
    "environment": "live",
    "payment_channel": "QRIS_ADMIN",
    "fee_percent": 1,
    "fee_amount": 250,
    "member_profit": 250,
    "platform_fee": 0,
    "total_dibayar": 25292,
    "total_diterima": 25250,
    "customer_name": "Budi"
  },
  "reference": "KP260828ABC123",
  "reff_id": "ORDER-001",
  "signature": "md5_merchant_id_secret_ref_id",
  "status": "Success"
}

Salinconst crypto = require('crypto');

function validWebhook(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex'));
}

Header webhook

Balas HTTP 2xx; body {"status":true} direkomendasikan sebagai format respons ringkas. Jika pengiriman gagal, KuyzPay mencoba hingga tiga kali dengan jeda dua menit, menyimpan setiap hasil, dan menyediakan resubmit pada detail transaksi.

Status dan Error