01
Buat transaksi
Kirim nominal, channel, dan referensi unik dari sistem Anda.
OnixPayz API v1
Buat pembayaran QRIS, Virtual Account, dan retail melalui satu API. Dokumentasi ini hanya memuat fitur yang tersedia saat ini.
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.
Semua endpoint merchant menggunakan API key aktif dengan awalan npk_ pada header X-API-Key.
| Parameter | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| X-API-Key | string | Ya | API key aktif milik merchant. | npk_xxxxxxxxxx |
| Content-Type | string | Ya | Format data yang dikirim ke API. | application/json |
| Accept | string | Tidak | Format 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.
Satu transaksi pembayaran berjalan melalui empat tahap. Merchant cukup membuat pembayaran dan menerima perubahan status; tampilan checkout serta instruksi pembayaran disediakan oleh OnixPayz.
01
Kirim nominal, channel, dan referensi unik dari sistem Anda.
02
Tampilkan payment_url agar pelanggan memperoleh instruksi pembayaran.
03
Validasi signature dan proses event secara idempotent.
04
Dana berhasil masuk ke saldo tersedia sesuai jadwal kliring.
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
Pembayar memilih VA, QRIS, atau gerai retail.

Pembayaran QRIS
QRIS siap dipindai dari mobile banking atau e-wallet.

Virtual Account
Nomor VA dan nominal transfer ditampilkan dengan jelas.
Klik gambar untuk melihat tampilan dalam ukuran penuh.
Pilih channel berdasarkan pengalaman pembayaran pelanggan dan kebutuhan settlement bisnis Anda.
QRIS
Pembayaran instan · QRIS

Mandiri
Virtual Account · MANDIRIVA

BNI
Virtual Account · BNIVA
BRI
Virtual Account · BRIVA

CIMB Niaga
Virtual Account · CIMBVA
PermataBank
Virtual Account · PERMATAVA
Danamon
Virtual Account · DANAMONVA
BSI
Virtual Account · BSIVA
Alfamart
Gerai retail · ALFAMART
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.
| Parameter | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| amount | number | Ya | Nominal pokok transaksi dalam Rupiah. | 50000 |
| external_id | string | Tidak | Referensi unik transaksi dari sistem merchant. | ORDER-1001 |
| payment_channel | string | Tidak | Kode channel pembayaran. Kosongkan untuk Universal Checkout. | BNIVA |
| description | string | Tidak | Keterangan transaksi, maksimal 500 karakter. | Pembayaran pesanan 1001 |
| customer_name | string | Tidak | Nama pelanggan yang melakukan pembayaran. | Devon |
| customer_email | string | Ya | Alamat email pelanggan yang valid. | [email protected] |
| customer_phone | string | Tidak | Nomor telepon pelanggan. | 081234567890 |
| callback_url | string | Tidak | URL HTTPS untuk menerima perubahan status transaksi. | https://merchant.id/callback |
| success_url | string | Tidak | Tujuan pelanggan setelah pembayaran selesai. | https://merchant.id/success |
| metadata | object | Tidak | Data 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 | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| reference_id | string | Ya | Referensi transaksi OnixPayz untuk pengecekan status. | TXN9NYSMCAYVK5I |
| channel_selection_required | boolean | Tidak | Bernilai true jika merchant tidak mengirim payment_channel dan pembayar perlu memilih channel di checkout. | true |
| channel | string | Tidak | Kode channel yang digunakan. Kosong pada response Universal Checkout awal. | BNIVA |
| channel_type | string | Tidak | Kelompok metode pembayaran setelah channel dipilih. | virtual_account |
| payment_url | string | Ya | Halaman checkout yang diberikan kepada pelanggan. | https://onixpayz.com/checkout/TXN... |
| amount | number | Ya | Nominal pokok transaksi. | 50000 |
| service_fee | number | Ya | Biaya layanan untuk transaksi. | 3000 |
| customer_amount | number | Ya | Total yang dibayar pelanggan. | 53000 |
| fee_bearer | string | Ya | Pihak yang menanggung biaya layanan. | payer |
| virtual_account | object | Tidak | Nomor dan bank VA; hanya tersedia untuk Virtual Account. | {"bank":"BNI","number":"988..."} |
| qris_string | string | Tidak | Payload QRIS dinamis; hanya tersedia untuk QRIS. | 00020101021226... |
| payment_code | string | Tidak | Kode bayar; hanya tersedia untuk channel retail. | 123456789012 |
| expires_at | datetime | Ya | Batas 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 berikut telah tersedia melalui alur OnixPayz. Hari settlement dihitung berdasarkan hari kerja dan kalender kliring.
| Kode | Channel | Nominal | Settlement |
|---|---|---|---|
| QRIS | QRIS | Rp1.000 – Rp5.000.000 | H+0 |
| MANDIRIVA | Mandiri Virtual Account | Rp10.000 – Rp50.000.000 | H+1 |
| BNIVA | BNI Virtual Account | Rp10.000 – Rp50.000.000 | H+1 |
| BRIVA | BRI Virtual Account | Rp10.000 – Rp10.000.000 | H+1 |
| CIMBVA | CIMB Niaga Virtual Account | Rp10.000 – Rp50.000.000 | H+1 |
| PERMATAVA | Permata Virtual Account | Rp10.000 – Rp50.000.000 | H+1 |
| DANAMONVA | Danamon Virtual Account | Rp10.000 – Rp50.000.000 | H+1 |
| BSIVA | BSI Virtual Account | Rp10.000 – Rp2.000.000 | H+2 |
| ALFAMART | Alfamart | Rp10.000 – Rp5.000.000 | H+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.
GET/pay?status=completed&per_page=20
Filter tersedia: status, external_id, start_date, end_date, dan per_page dengan maksimum 100.
| Parameter | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| status | string | Tidak | Menyaring transaksi berdasarkan status. | completed |
| external_id | string | Tidak | Mencari transaksi berdasarkan referensi merchant. | ORDER-1001 |
| start_date | date | Tidak | Tanggal awal dalam format YYYY-MM-DD. | 2026-07-01 |
| end_date | date | Tidak | Tanggal akhir dalam format YYYY-MM-DD. | 2026-07-31 |
| per_page | integer | Tidak | Jumlah data per halaman, maksimal 100. | 20 |
GET/pay/{id}
id dapat berupa UUID, reference ID, atau external ID milik merchant yang terautentikasi.
| Parameter | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| id | string | Ya | UUID, reference_id, atau external_id transaksi. | TXN9NYSMCAYVK5I |
Catatan:API hanya mengembalikan transaksi yang dimiliki merchant dari API key tersebut.
GET/balance
| Parameter | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| available | number | Ya | Saldo yang sudah tersedia dan dapat digunakan. | 472024 |
| pending | number | Ya | Saldo pembayaran yang masih berada dalam kliring. | 20000 |
| total | number | Ya | Jumlah saldo tersedia dan saldo pending. | 492024 |
| currency | string | Ya | Kode mata uang saldo merchant. | IDR |
available dapat digunakan, pending masih dalam kliring, dan total adalah jumlah keduanya.
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.
| Parameter | Tipe | Wajib | Keterangan | Contoh |
|---|---|---|---|---|
| event | string | Ya | Nama kejadian yang dikirim OnixPayz. | payment.success |
| timestamp | datetime | Ya | Waktu pembuatan webhook dalam format ISO 8601. | 2026-07-05T12:00:00Z |
| data.transaction_id | string | Ya | UUID internal transaksi. | 550e8400-e29b-... |
| data.reference_id | string | Ya | Referensi transaksi OnixPayz. | TXN9NYSMCAYVK5I |
| data.external_id | string | Tidak | Referensi transaksi dari merchant. | ORDER-1001 |
| data.status | string | Ya | Status terbaru transaksi. | completed |
| data.amount | number | Ya | Nominal pokok transaksi. | 50000 |
| data.settlement_status | string | Tidak | Status kliring dana transaksi. | scheduled |
| data.settlement_due_at | datetime | Tidak | Perkiraan waktu pelepasan saldo kliring. | 2026-07-06T11:59:00Z |
Event yang digunakan: payment.success, payment.failed, dan payment.expired.
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 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.
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].
Gunakan daftar ini sebagai pemeriksaan akhir sebelum menerima transaksi pelanggan.
API key hanya disimpan pada server.
External ID unik untuk setiap transaksi.
Webhook menggunakan HTTPS yang valid.
Signature webhook selalu diverifikasi.
Pemrosesan webhook bersifat idempotent.
Status tidak diubah dari sisi frontend.
Nominal dan biaya dibaca dari response.
Alur gagal dan kedaluwarsa sudah diuji.