Dokumentasi API YNA PAY

Autentikasi

Setiap request ke endpoint /api/v1/* wajib menyertakan 1 API Key lewat header X-Api-Key. API Key otomatis dibuat saat Anda daftar (1 API Key per akun) dan bisa dilihat kapan saja lewat Dashboard → tab API & Webhook. Kalau bocor atau hilang, klik "Generate Ulang" di dashboard - key lama langsung berhenti berfungsi dan digantikan yang baru saat itu juga.

X-Api-Key: yna-••••••••••••••••••nj

Contoh di atas cuma ilustrasi format (bukan API Key akun manapun) - tapi tetap ditampilkan tersamar & pakai tombol mata, konsisten dengan tampilan API Key asli Anda di Dashboard.

Setiap API Key juga dibatasi kuota request (rate limit) per jendela waktu tertentu untuk menjaga kestabilan layanan - kalau terlampaui, Anda akan menerima response 429 sampai jendela waktunya reset.

POST /api/v1/qris/create

Membuat invoice/QRIS baru. Nominal amount adalah nominal ASLI yang ingin Anda terima utuh - margin/fee YNA PAY dihitung otomatis DI ATAS nominal ini, jadi jumlah yang benar-benar ditagihkan ke pembayar (total_charged) bisa lebih besar dari amount. Fee yang berlaku mengikuti tier akun Anda (fee reseller otomatis lebih murah kalau akun Anda berstatus reseller).

curl -X POST https://api.ynapay.my.id/api/v1/qris/create \
  -H "X-Api-Key: yna-kut64e32wsd5t76yhbnj" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "product_name": "Contoh Produk"}'

{
  "status": "success",
  "data": {
    "ref_no": "QR1776670534209",
    "status": "pending",
    "product_name": "Pembayaran",
    "customer_name": "Pelanggan",
    "original_amount": 10000,
    "fee_total": 500,
    "total_charged": 10500,
    "qr_url": "https://api.ynapay.my.id/qr/QR1776670534209",
    "payment_link": "https://api.ynapay.my.id/pay/QR1776670534209",
    "receipt_url": null,
    "payor_name": null,
    "issuer": null,
    "created_at": "2026-07-24T08:00:00.000Z",
    "expired_at": "2026-07-24T08:30:00.000Z",
    "paid_at": null
  }
}

GET /api/v1/qris/status/:refNo

Cek status transaksi. Endpoint ini selalu re-check status resmi ke sistem pembayaran dulu (bukan sekadar baca cache lokal), jadi bisa dipakai untuk polling.

{ "status": "success", "data": { "ref_no": "QR1776670534209", "status": "success", "...": "..." } }

GET /api/v1/transactions

List riwayat transaksi milik Anda, terbaru lebih dulu.

{
  "status": "success",
  "data": [ { "ref_no": "QR...", "status": "success", "...": "..." } ],
  "meta": { "page": 1, "limit": 20, "total": 42, "total_pages": 3 }
}

GET /api/v1/balance

Cek breakdown saldo akun Anda saat ini.

{
  "status": "success",
  "data": {
    "available_balance": 250000,
    "pending_balance": 50000,
    "blocked_balance": 0,
    "total_withdrawn": 1200000
  }
}

POST /api/v1/deposit

Membuat QRIS untuk top-up/deposit saldo akun Anda sendiri. Nominal deposit TIDAK PERNAH kena potongan fee/margin apapun (100% masuk ke saldo Anda begitu dibayar).

{
  "status": "success",
  "data": {
    "ref_no": "QR1776670600123",
    "amount": 50000,
    "note": "Top up saldo",
    "qr_url": "https://api.ynapay.my.id/qr/QR1776670600123",
    "status": "pending",
    "created_at": "2026-07-24T08:10:00.000Z",
    "expired_at": "2026-07-24T08:40:00.000Z",
    "paid_at": null
  }
}

GET /api/v1/deposits

List riwayat deposit milik Anda, terbaru lebih dulu.

GET /api/v1/payment-channels

Daftar bank & e-wallet yang sedang AKTIF untuk withdraw (sama dengan daftar yang muncul di form withdraw Dashboard User), berguna kalau Anda ingin menampilkan pilihan channel withdraw ini juga di sistem Anda sendiri.

{
  "status": "success",
  "data": {
    "banks": [ { "code": "bca", "name": "BCA" }, { "code": "seabank", "name": "SeaBank" } ],
    "ewallets": [ { "code": "dana", "name": "DANA" }, { "code": "gopay", "name": "GoPay" } ]
  }
}

PUT /api/v1/settings/callback-url

Atur URL server Anda sendiri yang akan menerima notifikasi otomatis setiap transaksi mencapai status final (success/failed/expired). Kirim callback_url: null atau string kosong untuk menonaktifkan.

{ "callback_url": "https://toko-anda.com/webhook/yna-pay" }

GET /api/v1/webhook-logs

Lihat histori pengiriman webhook ke callback URL Anda, termasuk status (pending/success/failed), jumlah percobaan, dan pesan error terakhir.

POST /api/v1/webhook-logs/:id/retry

Kirim ulang 1 notifikasi webhook secara manual, berapa pun status/jumlah percobaan sebelumnya. Berguna kalau server Anda sempat down saat notifikasi asli dikirim.

Format Webhook yang Anda Terima

Kalau callback_url sudah diatur, server Anda akan menerima POST dengan body berikut setiap transaksi final. Verifikasi keasliannya lewat header X-YNA-Signature (HMAC-SHA256 dari body JSON, secret diberikan terpisah oleh admin YNA PAY).

{
  "ref_no": "QR1776670534209",
  "status": "success",
  "original_amount": 10000,
  "total_charged": 10500,
  "product_name": "Pembayaran",
  "customer_name": "Pelanggan",
  "payor_name": "Budi Santoso",
  "issuer": "GOPAY",
  "paid_at": "2026-07-24T08:05:00.000Z",
  "timestamp": "2026-07-24T08:05:01.000Z"
}

Server Anda harus membalas dengan status HTTP 2xx. Kalau tidak, YNA PAY akan mencoba kirim ulang beberapa kali secara otomatis dengan jeda yang makin lama.

Endpoint Khusus Dashboard (Bukan Bagian API Publik)

Fitur QRIS Manual & Deposit di Dashboard User/Admin (tombol Batal QRIS dan Download QR) punya endpoint tersendiri yang TIDAK termasuk API publik /api/v1/* di atas. Endpoint di bawah ini pakai autentikasi sesi login (cookie), bukan X-Api-Key - jadi tidak bisa dan tidak dimaksudkan untuk dipanggil dari sistem/aplikasi luar. Endpoint ini hanya berfungsi saat dipanggil dari halaman Dashboard yang sedang login, dan dicantumkan di sini murni sebagai referensi/transparansi.

Tidak boleh/tidak bisa dipakai:

• Lewat header X-Api-Key - endpoint ini tidak mengenali kredensial API sama sekali, hanya sesi login dashboard.
• Dari server/aplikasi pihak ketiga di luar dashboard YNA PAY - kalau butuh integrasi otomatis untuk cek status/riwayat, pakai endpoint publik /api/v1/* di atas.
• Endpoint /api/admin/* oleh akun user biasa - otomatis ditolak (403), khusus akun dengan role admin.
• Membatalkan QRIS yang statusnya sudah final (success/failed/ expired/cancelled) - hanya QRIS yang masih pending yang bisa dibatalkan.

Format Error

Semua error mengikuti format yang sama:

{ "status": "error", "message": "Penjelasan error di sini." }