API PAYNEXA memungkinkan Anda mengintegrasikan layanan pembayaran QRIS, transfer saldo, dan manajemen akun. Semua permintaan menggunakan format JSON dan mengembalikan respons JSON. Endpoint API yang memerlukan autentikasi wajib menyertakan apikey yang valid.
GET untuk Data & Inisiasi
Endpoint read-only dan pembuatan resource seperti topup QRIS menggunakan GET dengan query parameter.
POST untuk State Change
Endpoint yang mengubah state server secara permanen (transfer, cancel) wajib menggunakan POST dengan request body.
HTTPS Wajib
Seluruh komunikasi wajib melalui HTTPS. Request HTTP biasa akan ditolak otomatis.
https://paynexa.web.id/api/v1. Contoh: GET https://paynexa.web.id/api/v1/topup?apikey=...&nominal=10000Hampir semua endpoint memerlukan API Key. Pengecualian hanya pada POST /check-user. API Key dapat dikirim melalui query parameter pada GET request, request body pada POST request, atau header x-api-key untuk integrasi backend.
1. Login Dashboard
Masuk ke dashboard PAYNEXA PPOB menggunakan akun Anda.
2. Buka Profil
Navigasi ke halaman Profil melalui menu akun di dashboard.
3. Generate Key
Klik tombol "Daftar Apikey Sekarang!" dan salin hasilnya.
GET /api/v1/check-saldo?apikey=AO_xxxxx221220241234abcdefghij
{
"apikey": "AO_xxxxx221220241234abcdefghij",
"email": "johndoe@email.com",
"nominal": 50000
}
x-api-key: AO_xxxxx221220241234abcdefghij atau Authorization: Bearer AO_xxxxx221220241234abcdefghij
x-api-key, maupun Authorization: Bearer. Jika sebelumnya mendapat error 401 — pastikan API Key sudah benar dan akun tidak diblokir.Multi-Method Auth
API Key diterima via query param, body, header x-api-key, maupun Authorization Bearer untuk fleksibilitas integrasi.
TLS Enforcement
Seluruh traffic dienkripsi menggunakan TLS 1.2+. Plain HTTP diblokir penuh.
Session & Expiry
QRIS yang dibuat memiliki masa berlaku 10 menit. Transaksi EXPIRED tidak bisa diproses.
Account Lockout
Akun yang melanggar kebijakan akan diblokir. API Key dari akun banned mengembalikan 403.
User-Agent Filtering
Request dari non-browser ditolak dengan 403 untuk mencegah penyalahgunaan otomatis.
Atomic Transactions
Operasi finansial menggunakan database transaction untuk menjamin konsistensi data.
| Parameter | Nilai Default | Keterangan |
|---|---|---|
| limit_per_minute | 60 request | Maksimum request per menit untuk setiap API Key. Jika terlampaui, server akan merespon 429 Too Many Requests. |
| limit_per_day | 10.000 request | Batas harian (reset setiap tengah malam). Anda dapat melihat sisa kuota di dashboard. |
| alert_threshold | 80% | Notifikasi akan dikirim (jika diaktifkan) ketika kuota harian mencapai persentase ini. |
429 Too Many Requests. Implementasikan exponential backoff pada klien Anda sebelum melakukan retry.Membuat permintaan TopUp saldo baru dan menghasilkan QRIS untuk pembayaran. Parameter dikirim melalui request body (JSON) — metode POST digunakan untuk mencegah spam dan menjaga keamanan parameter. Sistem menggunakan kode unik sekuensial (0–999) untuk membedakan setiap transaksi. Setelah QRIS dibuat, gunakan GET /check-status untuk memantau statusnya secara real-time.
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
| nominal | Number | Wajib | Nominal topup dalam Rupiah. Minimal Rp 1.000 |
POST /api/v1/topup Content-Type: application/json { "apikey": "AO_xxxxx221220241234abcdefghij", "nominal": 10000 }
{
"status": 200,
"message": "Topup Created",
"data": {
"trxId": "TOPUP-1743000000000",
"user_email": "user@email.com",
"type": "TOPUP",
"item": "Top Up Saldo API",
"amount": 10000,
"fee": 3,
"uniqueCode": 3,
"totalTransfer": 10003,
"expiry": 1735723200000,
"qr_string": "000201010211..."
}
}
GET /check-status?idTransaksi=trxId untuk memantau perkembangan secara real-time. totalTransfer adalah jumlah yang harus dibayar via QRIS (nominal + kode unik).totalTransfer. Pembayaran kurang dari jumlah ini tidak akan terdeteksi. QRIS kadaluarsa setelah 10 menit. Kode unik akan dikreditkan kembali ke saldo saat pembayaran berhasil.Membatalkan transaksi topup milik Anda yang berstatus PENDING. Hanya transaksi yang belum dibayar dan belum kadaluarsa yang bisa dibatalkan. Status akan berubah menjadi CANCELED dan kode unik dibebaskan untuk transaksi berikutnya.
{
"apikey": "AO_xxxxx221220241234abcdefghij",
"trxId": "674a3b8c9d0e1f2a"
}
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
| trxId | String | Wajib | Nilai trxId yang didapat dari response POST /topup. Contoh: TOPUP-1743000000000 |
{
"status": 200,
"message": "Transaksi berhasil dibatalkan"
}
Mengecek status pembayaran TopUp secara real-time dengan menghubungi gateway QRIS secara langsung. Lakukan polling dengan interval minimal 3 detik untuk menghindari rate limit.
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
| idTransaksi | String | Wajib | Nilai trxId yang didapat dari response POST /topup. Contoh: TOPUP-1743000000000 |
GET /api/v1/check-status?apikey=AO_xxxxx...&idTransaksi=TOPUP-1743000000000
{
"status": 200,
"data": {
"trxId": "TOPUP-1743000000000",
"status": "SUCCESS",
"amount": 10000,
"totalTransfer": 10003,
"uniqueCode": 3,
"type": "TOPUP",
"item": "Top Up Saldo API",
"expiry": 1743003600000
}
}
Mengambil saldo terkini berdasarkan API Key. Endpoint ini adalah read-only murni, sehingga menggunakan GET. Disarankan untuk melakukan cache lokal selama 30 detik untuk efisiensi.
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
GET /api/v1/check-saldo?apikey=AO_xxxxx221220241234abcdefghij
{
"status": 200,
"data": {
"saldo": 150000
}
}
Mengambil riwayat seluruh transaksi akun Anda. Mendukung pagination dan filter berdasarkan status. Transaksi PENDING yang telah melewati waktu expiry akan otomatis diperbarui menjadi EXPIRED.
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
| page | Number | Opsional | Halaman ke-N. Default: 1 |
| limit | Number | Opsional | Jumlah data per halaman. Default: 10, Maks: 50 |
| filter | String | Opsional | Filter: all | success | pending | canceled. Default: all |
GET /api/v1/history?apikey=AO_xxxxx...&page=1&limit=10&filter=success
{
"status": 200,
"hasMore": false,
"data": [
{
"trxId": "674a3b8c9d0e1f2a",
"type": "TOPUP",
"item": "Top Up Saldo API",
"amount": 10000,
"totalTransfer": 10003,
"date": "2024-01-01T12:00:00Z",
"status": "SUCCESS"
},
{
"trxId": "TF-API-1735723200000",
"type": "TF_OUT",
"item": "Transfer API ke John Doe",
"amount": 50000,
"totalTransfer": 50000,
"date": "2024-01-01T11:30:00Z",
"status": "SUCCESS",
"note": "Penerima: johndoe@email.com"
}
]
}
Memeriksa apakah email terdaftar di sistem PAYNEXA dan mengembalikan informasi dasar pengguna. Endpoint ini tidak memerlukan API Key. Email dikirim di body (POST) untuk menjaga privasi pengguna agar tidak terekam di server log URL.
{
"email": "johndoe@email.com"
}
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| String | Wajib | Alamat email user yang akan dicek |
{
"status": 200,
"data": {
"username": "John Doe",
"email": "johndoe@email.com",
"verified": false,
"profile_pic": "https://ui-avatars.com/api/?name=John+Doe&..."
}
}
verified bernilai true jika user sudah memiliki API Key. Gunakan endpoint ini untuk validasi penerima sebelum melakukan POST /transfer.Mentransfer saldo dari akun Anda ke akun penerima berdasarkan email. Transfer menggunakan database transaction (BEGIN/COMMIT) untuk menjamin atomisitas — saldo pengirim tidak akan berkurang jika saldo penerima gagal bertambah. Transfer tidak dapat dibatalkan setelah berhasil.
{
"apikey": "AO_xxxxx221220241234abcdefghij",
"email": "johndoe@email.com",
"nominal": 50000
}
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda (pengirim) |
| String | Wajib | Email penerima transfer | |
| nominal | Number | Wajib | Jumlah saldo yang ditransfer. Harus bilangan bulat positif |
{
"status": 200,
"message": "Transfer Berhasil"
}
POST /check-user terlebih dahulu untuk memverifikasi email penerima sebelum melakukan transfer.Endpoint ini memungkinkan Anda melakukan penarikan saldo (Withdraw) ke berbagai E-Wallet secara instan melalui sistem otomatis. Saldo akun akan dipotong sesuai harga produk yang dipilih. Response dapat berupa status SUCCESS (langsung atau akan diproses) atau PENDING (memerlukan pengecekan ulang).
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
| ewallet | String | Wajib | Jenis E-Wallet: dana, gopay, ovo, shopee, linkaja, dll |
| nomor | String | Wajib | Nomor HP tujuan E-Wallet (contoh: 08123456789) |
| kode | String | Wajib | Kode produk (contoh: d1 untuk Dana 1rb). Masukkan kode asal untuk melihat daftar produk |
GET /withdraw2?apikey=YOUR_APIKEY&ewallet=dana&nomor=08123456789&kode=d1
{
"status": 200,
"message": "Transaksi withdraw2 langsung sukses.",
"trxId": "WD2-171123456789",
"detail": {
"ewallet": "dana",
"nomor": "08123456789",
"namaEwallet": "Budi Santoso",
"product": "Dana 1.000",
"harga": 1038,
"status": "SUCCESS"
}
}
{
"status": 200,
"message": "Transaksi withdraw2 sedang diproses.",
"trxId": "WD2-171123456789",
"detail": {
"ewallet": "dana",
"nomor": "08123456789",
"namaEwallet": "Budi Santoso",
"product": "Dana 1.000",
"harga": 1038,
"status": "PENDING"
}
}
kode yang salah, API akan mengembalikan daftar kode produk yang tersedia beserta harganya dalam field available_products.Mengembalikan daftar seluruh request yang pernah dilakukan menggunakan API Key milik akun Anda. Setiap kali endpoint API dipanggil dengan API Key yang valid, sistem secara otomatis mencatat endpoint, metode, IP, dan waktu ke file database/mutasi-api.json. Akses endpoint ini memerlukan sesi login aktif (bukan API Key), sehingga hanya bisa diakses melalui dashboard. Tombol » di halaman Profil akan membuka daftar ini secara langsung.
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| page | Number | Opsional | Halaman pagination. Default: 1. Setiap halaman berisi 20 entri. |
{
"status": 200,
"data": [
{
"id": "REQ-1735723200001",
"apikey": "AO_xxxxx...",
"user_email": "user@email.com",
"username": "John",
"endpoint": "/api/v1/check-saldo",
"method": "GET",
"ip": "180.244.x.x",
"date": "2025-01-01T11:00:00.000Z"
}
],
"total": 1,
"hasMore": false
}
| Field | Type | Deskripsi |
|---|---|---|
| id | String | ID unik request dengan prefix REQ- |
| apikey | String | API Key yang digunakan untuk request |
| user_email | String | Email pemilik API Key |
| username | String | Username pemilik API Key |
| endpoint | String | Path endpoint yang dipanggil, contoh: /api/v1/topup |
| method | String | Metode HTTP: GET atau POST |
| ip | String | Alamat IP pemanggil request |
| date | String | Timestamp ISO 8601 saat request masuk |
checkApiKey sehingga tidak akan tercatat sebagai request API. Data disimpan di database/mutasi-api.json dan dapat dipantau oleh Admin dari panel.Melakukan validasi (inquiry) nomor tujuan untuk berbagai layanan dompet digital (E-Wallet). Gunakan endpoint ini untuk memverifikasi keberadaan akun E-Wallet penerima sebelum melakukan top-up atau transfer.
| Kode | Layanan | Deskripsi |
|---|---|---|
| CEKD | Dana | Cek nama akun Dana berdasarkan nomor HP |
| CEKGJK | Gojek / GoPay | Cek nama akun Gojek Customer berdasarkan nomor HP |
| CEKISAKU | iSaku | Cek nama akun iSaku berdasarkan nomor HP |
| CEKLINK | LinkAja | Cek nama akun LinkAja berdasarkan nomor HP |
| CEKOVO | OVO | Cek nama akun OVO berdasarkan nomor HP |
| CEKSHP | ShopeePay | Cek nama akun ShopeePay berdasarkan nomor HP |
| Parameter | Type | Status | Deskripsi |
|---|---|---|---|
| apikey | String | Wajib | API Key Anda |
| code | String | Wajib | Kode inquiry, contoh: CEKD |
| dest | String | Wajib | Nomor HP tujuan sesuai layanan E-Wallet yang dipilih |
POST /api/v1/cek Content-Type: application/json { "apikey": "AO_xxxxx221220241234abcdefghij", "code": "CEKD", "dest": "08123456789" }
{
"status": 200,
"code": "CEKD",
"dest": "08123456789",
"result": "Budi Santoso | 08123456789"
}
POST /api/v1/cek. Pembeda antar layanan hanya pada nilai parameter code yang dikirimkan.PAYNEXA dapat mengirim notifikasi outbound (dari server kami ke server Anda) setiap kali sebuah transaksi mengalami perubahan status, sehingga Anda tidak perlu melakukan polling ke endpoint Check Status secara berulang. Fitur ini terpisah dari endpoint API lainnya dan dikonfigurasi langsung dari Dashboard, bukan lewat kode.
| Langkah | Deskripsi |
|---|---|
| 1. Login Dashboard | Masuk ke dashboard PAYNEXA menggunakan akun Anda. |
| 2. Buka Profil | Navigasi ke halaman Profil, lalu klik tombol Webhook / Callback. |
| 3. Isi URL & Simpan | Masukkan URL endpoint HTTPS milik server Anda, lalu klik Simpan Pengaturan. |
| 4. Salin Secret Key | Secret Key akan dibuat otomatis pada penyimpanan pertama. Gunakan untuk verifikasi signature (lihat bagian di bawah). |
Endpoint berikut digunakan oleh dashboard untuk mengelola konfigurasi webhook Anda, dan memerlukan sesi login aktif (bukan API Key).
| Method | Endpoint | Deskripsi |
|---|---|---|
| GET | /api/webhook/config | Mengambil konfigurasi webhook aktif Anda saat ini. |
| POST | /api/webhook/config | Menyimpan atau memperbarui URL webhook. Body: { "webhook_url": "https://..." } |
| GET | /api/webhook/logs | Mengambil 50 log pengiriman webhook terbaru. |
Server Anda akan menerima request POST dengan Content-Type: application/json setiap kali sebuah transaksi mencapai status akhir (contoh: SUCCESS). Server Anda wajib merespons dengan HTTP 200 atau 201 agar pengiriman ditandai berhasil.
{
"transaction_id": "TOPUP-1735723200001",
"event_type": "PAYMENT_SUCCESS",
"amount": 55000,
"status": "SUCCESS"
}
| Field | Type | Deskripsi |
|---|---|---|
| transaction_id | String | ID transaksi di sistem PAYNEXA. Simpan untuk pencocokan dengan transaksi lokal Anda. |
| event_type | String | Jenis event, contoh: PAYMENT_SUCCESS. |
| amount, status, dll | Mixed | Field tambahan mengikuti jenis transaksi, dapat bervariasi antar event. |
Setiap callback ditandatangani menggunakan Secret Key unik milik akun Anda (dibuat otomatis saat pertama kali menyimpan konfigurasi webhook). Tanda tangan dikirim melalui header X-FR3-Signature.
| Langkah | Deskripsi |
|---|---|
| 1 | Ambil raw body (string JSON mentah, bukan hasil parse ulang) dari request yang masuk. |
| 2 | Hitung HMAC-SHA256 dari raw body tersebut menggunakan Secret Key Anda. |
| 3 | Bandingkan hasilnya dengan nilai header X-FR3-Signature menggunakan constant-time comparison (contoh: crypto.timingSafeEqual di Node.js), bukan operator === biasa, untuk mencegah timing attack. |
| 4 | Jika tidak cocok, tolak request dengan HTTP 401. Jangan proses payload sebagai transaksi valid. |
const crypto = require("crypto"); function isValidFr3Signature(rawBody, signatureHeader, secretKey) { if (!signatureHeader) return false; const expected = crypto.createHmac("sha256", secretKey).update(rawBody).digest("hex"); const a = Buffer.from(signatureHeader); const b = Buffer.from(expected); if (a.length !== b.length) return false; return crypto.timingSafeEqual(a, b); }
Semua error mengembalikan JSON dengan field status (HTTP status code) dan error berisi pesan deskriptif.
{
"status": 401,
"error": "API Key tidak valid atau tidak ditemukan"
}
| Error Message | HTTP | Endpoint | Penanganan |
|---|---|---|---|
| API Key diperlukan | 401 | Semua (kecuali check-user) | Sertakan parameter apikey |
| API Key tidak valid atau tidak ditemukan | 401 | Semua | Periksa kembali nilai API Key — pastikan sudah ter-generate di Profil |
| Akun Anda dibekukan | 403 | Semua | Hubungi admin |
| Minimum topup 1000 | 400 | POST /topup | Nominal minimal Rp 1.000 |
| Saldo tidak mencukupi | 400 | POST /transfer | Topup saldo terlebih dahulu |
| Email penerima tidak ditemukan | 404 | POST /transfer | Verifikasi dengan POST /check-user |
| Tidak bisa transfer ke diri sendiri | 400 | POST /transfer | Email penerima harus berbeda |
| Transaksi tidak ditemukan | 404 | GET /check-status | Periksa nilai idTransaksi |
| Internal server error | 500 | Semua | Retry dengan exponential backoff |
| code dan dest diperlukan | 400 | POST /cek | Lengkapi kedua parameter |
| Nomor tidak ditemukan atau tidak valid | 404 | POST /cek | Pastikan nomor benar dan terdaftar di layanan terkait |
Siap Mengintegrasikan API?
Dapatkan API Key Anda dan mulai integrasi sekarang. Kunjungi halaman Profil di dashboard untuk generate kredensial API.
Ke Dashboard