OnixPayzDokumentasi API

OnixPayz API v1

Integrasi pembayaran yang jelas dan langsung.

Buat pembayaran QRIS, Virtual Account, dan retail melalui satu API. Dokumentasi ini hanya memuat fitur yang tersedia saat ini.

Pengantar

API OnixPayz menerima dan mengembalikan JSON melalui HTTPS. Base URL produksi:

https://onixpayz.com/api/v1

Gunakan endpoint ini hanya dari server Anda. Jangan meletakkan API key di browser, aplikasi mobile, repository publik, atau halaman checkout.

Autentikasi

Semua endpoint merchant menggunakan API key aktif dengan awalan npk_ pada header X-API-Key.

Header request

ParameterTipeWajibKeteranganContoh
X-API-KeystringYaAPI key aktif milik merchant.npk_xxxxxxxxxx
Content-TypestringYaFormat data yang dikirim ke API.application/json
AcceptstringTidakFormat response yang diharapkan.application/json

Catatan:Jangan mengirim API key melalui query parameter atau menyimpannya pada frontend.

API key tersedia di dashboard merchant. Segera buat ulang key apabila pernah terpapar.

Alur integrasi

Satu transaksi pembayaran berjalan melalui empat tahap. Merchant cukup membuat pembayaran dan menerima perubahan status; tampilan checkout serta instruksi pembayaran disediakan oleh OnixPayz.

01

Buat transaksi

Kirim nominal, channel, dan referensi unik dari sistem Anda.

02

Arahkan pelanggan

Tampilkan payment_url agar pelanggan memperoleh instruksi pembayaran.

03

Terima webhook

Validasi signature dan proses event secara idempotent.

04

Pantau settlement

Dana berhasil masuk ke saldo tersedia sesuai jadwal kliring.

Snap Checkout

Snap Checkout OnixPayz adalah halaman pembayaran siap pakai yang dapat langsung dibuka melalui payment_url. Pembayar dapat memilih channel dan mengikuti instruksi pembayaran tanpa merchant membangun antarmuka tambahan.

Merchant tidak wajib menggunakan tampilan Snap. Jika ingin memakai halaman pembayaran buatan sendiri, kirim payment_channel pada request lalu tampilkan instrumen yang dikembalikan API, seperti QRIS, Virtual Account, atau kode pembayaran retail.

Pilih metode pada Snap Checkout OnixPayz

Pilih metode

Pembayar memilih VA, QRIS, atau gerai retail.

Pembayaran QRIS pada Snap Checkout OnixPayz

Pembayaran QRIS

QRIS siap dipindai dari mobile banking atau e-wallet.

Virtual Account pada Snap Checkout OnixPayz

Virtual Account

Nomor VA dan nominal transfer ditampilkan dengan jelas.

Klik gambar untuk melihat tampilan dalam ukuran penuh.

Metode pembayaran

Pilih channel berdasarkan pengalaman pembayaran pelanggan dan kebutuhan settlement bisnis Anda.

QRIS

QRIS

Pembayaran instan · QRIS

Logo Mandiri

Mandiri

Virtual Account · MANDIRIVA

Logo BNI

BNI

Virtual Account · BNIVA

BBRI

BRI

Virtual Account · BRIVA

Logo CIMB Niaga

CIMB Niaga

Virtual Account · CIMBVA

PPermataBank

PermataBank

Virtual Account · PERMATAVA

DDanamon

Danamon

Virtual Account · DANAMONVA

BBSI

BSI

Virtual Account · BSIVA

Alfamart

Alfamart

Gerai retail · ALFAMART

Buat pembayaran

POST/pay

amount dan customer_email wajib dikirim. payment_channel boleh dikosongkan untuk Universal Checkout, sehingga pembayar dapat memilih VA, QRIS, atau retail di halaman checkout.

Lihat contoh Snap OnixPayz →

Parameter request

ParameterTipeWajibKeteranganContoh
amountnumberYaNominal pokok transaksi dalam Rupiah.50000
external_idstringTidakReferensi unik transaksi dari sistem merchant.ORDER-1001
payment_channelstringTidakKode channel pembayaran. Kosongkan untuk Universal Checkout.BNIVA
descriptionstringTidakKeterangan transaksi, maksimal 500 karakter.Pembayaran pesanan 1001
customer_namestringTidakNama pelanggan yang melakukan pembayaran.Devon
customer_emailstringYaAlamat email pelanggan yang valid.[email protected]
customer_phonestringTidakNomor telepon pelanggan.081234567890
callback_urlstringTidakURL HTTPS untuk menerima perubahan status transaksi.https://merchant.id/callback
success_urlstringTidakTujuan pelanggan setelah pembayaran selesai.https://merchant.id/success
metadataobjectTidakData tambahan milik merchant dalam format JSON.{"cart_id":"C-01"}

Catatan:Gunakan external_id yang berbeda untuk setiap transaksi baru. Nominal harus memenuhi batas minimum dan maksimum channel yang dipilih.

Parameter response

ParameterTipeWajibKeteranganContoh
reference_idstringYaReferensi transaksi OnixPayz untuk pengecekan status.TXN9NYSMCAYVK5I
channel_selection_requiredbooleanTidakBernilai true jika merchant tidak mengirim payment_channel dan pembayar perlu memilih channel di checkout.true
channelstringTidakKode channel yang digunakan. Kosong pada response Universal Checkout awal.BNIVA
channel_typestringTidakKelompok metode pembayaran setelah channel dipilih.virtual_account
payment_urlstringYaHalaman checkout yang diberikan kepada pelanggan.https://onixpayz.com/checkout/TXN...
amountnumberYaNominal pokok transaksi.50000
service_feenumberYaBiaya layanan untuk transaksi.3000
customer_amountnumberYaTotal yang dibayar pelanggan.53000
fee_bearerstringYaPihak yang menanggung biaya layanan.payer
virtual_accountobjectTidakNomor dan bank VA; hanya tersedia untuk Virtual Account.{"bank":"BNI","number":"988..."}
qris_stringstringTidakPayload QRIS dinamis; hanya tersedia untuk QRIS.00020101021226...
payment_codestringTidakKode bayar; hanya tersedia untuk channel retail.123456789012
expires_atdatetimeYaBatas waktu pembayaran dalam format ISO 8601.2026-07-06T12:00:00Z

Untuk QRIS, response direct channel memuat qris_string. Untuk retail, response direct channel memuat payment_code. Pada Universal Checkout, instrumen pembayaran dibuat setelah pembayar memilih channel.

Channel pembayaran

Channel berikut telah tersedia melalui alur OnixPayz. Hari settlement dihitung berdasarkan hari kerja dan kalender kliring.

KodeChannelNominalSettlement
QRISQRISRp1.000 – Rp5.000.000H+0
MANDIRIVAMandiri Virtual AccountRp10.000 – Rp50.000.000H+1
BNIVABNI Virtual AccountRp10.000 – Rp50.000.000H+1
BRIVABRI Virtual AccountRp10.000 – Rp10.000.000H+1
CIMBVACIMB Niaga Virtual AccountRp10.000 – Rp50.000.000H+1
PERMATAVAPermata Virtual AccountRp10.000 – Rp50.000.000H+1
DANAMONVADanamon Virtual AccountRp10.000 – Rp50.000.000H+1
BSIVABSI Virtual AccountRp10.000 – Rp2.000.000H+2
ALFAMARTAlfamartRp10.000 – Rp5.000.000H+2

QRIS saat ini dikenakan 0,7% + Rp200. Biaya VA, retail, batas nominal, dan ketersediaan dapat berubah; selalu gunakan angka yang dikembalikan API dan halaman Harga sebagai referensi terbaru.

Transaksi

Daftar transaksi

GET/pay?status=completed&per_page=20

Filter tersedia: status, external_id, start_date, end_date, dan per_page dengan maksimum 100.

Query parameter

ParameterTipeWajibKeteranganContoh
statusstringTidakMenyaring transaksi berdasarkan status.completed
external_idstringTidakMencari transaksi berdasarkan referensi merchant.ORDER-1001
start_datedateTidakTanggal awal dalam format YYYY-MM-DD.2026-07-01
end_datedateTidakTanggal akhir dalam format YYYY-MM-DD.2026-07-31
per_pageintegerTidakJumlah data per halaman, maksimal 100.20

Detail transaksi

GET/pay/{id}

id dapat berupa UUID, reference ID, atau external ID milik merchant yang terautentikasi.

Path parameter

ParameterTipeWajibKeteranganContoh
idstringYaUUID, reference_id, atau external_id transaksi.TXN9NYSMCAYVK5I

Catatan:API hanya mengembalikan transaksi yang dimiliki merchant dari API key tersebut.

Saldo

GET/balance

Parameter response

ParameterTipeWajibKeteranganContoh
availablenumberYaSaldo yang sudah tersedia dan dapat digunakan.472024
pendingnumberYaSaldo pembayaran yang masih berada dalam kliring.20000
totalnumberYaJumlah saldo tersedia dan saldo pending.492024
currencystringYaKode mata uang saldo merchant.IDR

available dapat digunakan, pending masih dalam kliring, dan total adalah jumlah keduanya.

Webhook

OnixPayz mengirim event ketika status transaksi berubah. Endpoint Anda harus menggunakan HTTPS, membalas HTTP 2xx dengan cepat, dan memproses event secara idempotent berdasarkan reference ID.

Payload webhook

ParameterTipeWajibKeteranganContoh
eventstringYaNama kejadian yang dikirim OnixPayz.payment.success
timestampdatetimeYaWaktu pembuatan webhook dalam format ISO 8601.2026-07-05T12:00:00Z
data.transaction_idstringYaUUID internal transaksi.550e8400-e29b-...
data.reference_idstringYaReferensi transaksi OnixPayz.TXN9NYSMCAYVK5I
data.external_idstringTidakReferensi transaksi dari merchant.ORDER-1001
data.statusstringYaStatus terbaru transaksi.completed
data.amountnumberYaNominal pokok transaksi.50000
data.settlement_statusstringTidakStatus kliring dana transaksi.scheduled
data.settlement_due_atdatetimeTidakPerkiraan waktu pelepasan saldo kliring.2026-07-06T11:59:00Z

Event yang digunakan: payment.success, payment.failed, dan payment.expired.

Verifikasi signature

Header memuat X-OnixPayz-Signature, X-OnixPayz-Event, dan X-OnixPayz-Webhook-Id. Signature adalah HMAC SHA-256 dari raw request body menggunakan webhook secret.

Catatan:Balas HTTP 2xx sesegera mungkin. Proses bisnis yang berat sebaiknya diteruskan ke antrean internal merchant.

Status

pending
Menunggu pembayaran pelanggan.
processing
Pembayaran sedang diverifikasi.
completed
Pembayaran berhasil; saldo dapat masih berada dalam kliring.
failed
Pembayaran gagal diproses.
cancelled
Transaksi dibatalkan.
refunded
Dana transaksi dikembalikan.

Error & batas request

Status HTTP: 200/201 untuk sukses, 401 untuk API key tidak valid, 404 untuk resource yang tidak ditemukan, 422 untuk validasi, dan 429 ketika batas request terlampaui.

Batas public merchant API saat ini 120 request per menit. Respons 429 menyertakan header rate limit dari server.

Pengujian

Sandbox dan endpoint simulasi publik belum tersedia. Gunakan transaksi produksi bernominal minimum dan akun merchant khusus pengembangan. Jangan menandai transaksi berhasil dari sisi merchant; tunggu webhook resmi atau periksa endpoint detail.

Butuh bantuan? Hubungi [email protected].

Checklist sebelum go-live

Gunakan daftar ini sebagai pemeriksaan akhir sebelum menerima transaksi pelanggan.

01

API key hanya disimpan pada server.

02

External ID unik untuk setiap transaksi.

03

Webhook menggunakan HTTPS yang valid.

04

Signature webhook selalu diverifikasi.

05

Pemrosesan webhook bersifat idempotent.

06

Status tidak diubah dari sisi frontend.

07

Nominal dan biaya dibaca dari response.

08

Alur gagal dan kedaluwarsa sudah diuji.