Developer resources

Dokumentasi API

Referensi integrasi saldo, invoice deposit, status pembayaran, dan penarikan. Contoh menggunakan endpoint yang tersedia pada gateway ini.

Kelola API key Metode pembayaran
Base URL: https://YOUR_BASE_URL. Contoh di bawah otomatis memakai domain yang sedang kamu buka. Autentikasi sebaiknya dikirim melalui header X-Api-Key, bukan ditanam di URL atau kode frontend publik.

Mulai integrasi

Siapkan akun dan kredensial sebelum mengirim request.

  1. Login ke akun Mallss Nexus, lalu buka Profil & API key.
  2. Buat API key dan simpan di environment variable server kamu, misalnya NEXUS_API_KEY.
  3. Kirim request dari backend menggunakan HTTPS dan header X-Api-Key.
  4. Untuk deposit, buka URL invoice / checkout yang dikembalikan API dan tunggu status pembayaran terverifikasi.
Endpoint API dibatasi menjadi satu request setiap lima detik per batas rate limiter yang terpasang saat ini. Hindari polling terlalu sering; gunakan backoff saat menerima respons pembatasan.

Autentikasi

Semua endpoint API berikut membutuhkan API key yang valid.

HEADER X-Api-Key: YOUR_API_KEY

Server juga menerima parameter query apikey atau api_key untuk kompatibilitas lama. Header lebih disarankan karena query string dapat tersimpan dalam log server dan riwayat URL.

cURL · autentikasi
curl -sS "YOUR_BASE_URL/api/balance" \
  -H "X-Api-Key: YOUR_API_KEY"
01

Cek saldo

Mengambil username, email, dan saldo akun yang terkait dengan API key.

GET /api/balance
cURL
curl -sS "YOUR_BASE_URL/api/balance" \
  -H "X-Api-Key: YOUR_API_KEY"
Respons sukses{ "username": "merchant", "email": "merchant@example.com", "balance": 150000 }
02

Membuat invoice deposit

Membuat invoice dan URL checkout untuk pelanggan.

GET /api/invoice?amount=50000
  • amount — nominal deposit dalam Rupiah; minimal mengikuti pengaturan gateway.
  • Maksimum nominal saat ini Rp1.000.000 per invoice.
  • Gunakan checkout_url atau payment_link dari respons untuk mengarahkan pelanggan ke pembayaran.
cURL
curl -G "YOUR_BASE_URL/api/invoice" \
  --data-urlencode "amount=50000" \
  -H "X-Api-Key: YOUR_API_KEY"
Field respons pentingsuccess, invoice_id, amount, fee, total, checkout_url, payment_link, expired_at, dan callback_url.
Endpoint deposit ini mengisi saldo wallet akun; total pembayaran bisa mencakup biaya/kode unik yang dibuat otomatis.

Alternatif: endpoint POST untuk proyek lain

POST /api/v1/checkout

Gunakan endpoint ini dari backend proyek kamu. Respons berisi checkout_url yang bisa dibuka pelanggan; pemilihan metode dan instruksi pembayaran ditangani oleh halaman checkout Mallss Nexus.

cURL · proyek eksternal
curl -X POST "YOUR_BASE_URL/api/v1/checkout" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"amount":50000,"reference":"ORDER-1001","description":"Pembelian produk","return_url":"https://shop.example.com/payment-result","metadata":{"cart_id":"CART-1001"}}'
Respons{ "success": true, "invoice_id": "INVxxxxxxxx", "amount": 50000, "fee": 0, "total": 50000, "checkout_url": "https://gateway.example/checkout/INVxxxxxxxx" }
Invoice endpoint ini adalah pembayaran pesanan proyek eksternal: pembayaran sukses tidak menambah saldo wallet Mallss Nexus. Server mengirim event payment.succeeded ke Callback URL akun dan statusnya bisa dicek lewat /api/invoice/status?invoice_id=....
Perbedaan URL

return_url adalah halaman browser pelanggan setelah pembayaran. Atur Callback URL di Profil ke endpoint backend proyekmu untuk menerima webhook. Jangan gunakan halaman frontend sebagai Callback URL.

Contoh callback
{
  "event": "payment.succeeded",
  "data": {
    "invoice_id": "INVxxxxxxxx",
    "reference": "ORDER-1001",
    "amount": 50000,
    "fee": 0,
    "total": 50000,
    "status": "paid"
  },
  "timestamp": "2026-11-04T00:00:00.000Z"
}
03

Cek status invoice

Memeriksa status invoice tertentu milik akun pemilik API key.

GET /api/invoice/status?invoice_id=INVxxxxxxxx

Parameter yang diterima adalah invoice_id atau id. Endpoint ini hanya mengembalikan invoice milik API key yang digunakan.

cURL
curl -G "YOUR_BASE_URL/api/invoice/status" \
  --data-urlencode "invoice_id=INVxxxxxxxx" \
  -H "X-Api-Key: YOUR_API_KEY"
Statuspending = menunggu pembayaran · paid = pembayaran terverifikasi · expired = invoice kedaluwarsa. Respons juga berisi nominal, link pembayaran, dan waktu transaksi.
04

Melihat metode withdraw

Mengambil metode penarikan manual dan instan yang dikonfigurasi admin.

GET /api/withdraw/methods
cURL
curl -sS "YOUR_BASE_URL/api/withdraw/methods" \
  -H "X-Api-Key: YOUR_API_KEY"
Field responsmanual_methods dan instant_methods. Tiap metode dapat berisi name, method, fee, min, dan max.
05

Mengajukan withdraw

Mengajukan penarikan manual atau instan dengan parameter query.

GET /api/withdraw
  • amount — nominal penarikan.
  • method — nama metode; ambil daftar terbaru dari /api/withdraw/methods.
  • account_number — nomor akun tujuan.
  • instant — gunakan false untuk manual atau true untuk instan.
cURL · manual
curl -G "YOUR_BASE_URL/api/withdraw" \
  --data-urlencode "amount=50000" \
  --data-urlencode "method=dana" \
  --data-urlencode "account_number=08123456789" \
  --data-urlencode "instant=false" \
  -H "X-Api-Key: YOUR_API_KEY"
cURL · instan
curl -G "YOUR_BASE_URL/api/withdraw" \
  --data-urlencode "amount=20000" \
  --data-urlencode "method=gopay" \
  --data-urlencode "account_number=08129876543" \
  --data-urlencode "instant=true" \
  -H "X-Api-Key: YOUR_API_KEY"
Contoh nomor tujuan dan nama metode hanya ilustrasi. Pastikan metode, minimum, maksimum, dan biaya sesuai hasil endpoint metode withdraw. Request GET ini menimbulkan transaksi; jangan letakkan di tautan publik atau pramuat otomatis browser.
06

Cek status withdraw

Memeriksa status permintaan penarikan berdasarkan ID transaksi.

GET /api/withdraw/status?id=WDxxxxxxxx
cURL
curl -G "YOUR_BASE_URL/api/withdraw/status" \
  --data-urlencode "id=WDxxxxxxxx" \
  -H "X-Api-Key: YOUR_API_KEY"
Field respons pentingid, amount, fee, method, account_number, instant, status, admin_note, created_at, dan completed_at.

Error & status

Periksa HTTP status dan field error pada respons JSON.

  • 401 — API key tidak ada atau tidak valid. Pastikan header X-Api-Key benar.
  • 400 — parameter tidak valid, saldo tidak cukup, metode tidak tersedia, atau batas nominal terlewati.
  • 404 — invoice / transaksi tidak ditemukan atau bukan milik akun tersebut.
  • 429 — terlalu banyak request. Tunggu sebelum mencoba lagi.
  • 500 — kesalahan internal atau layanan penarikan gagal diproses.
Untuk deposit, perpindahan ke halaman sukses bukan bukti pembayaran. Gunakan status invoice dan webhook server yang sudah diverifikasi sebagai sumber status pembayaran.