Base URL & Autentikasi
Base URL — klik untuk membuka, atau gunakan tombol salin:
Semua endpoint mengembalikan JSON. Autentikasi memakai header X-API-Key.
sk_live_...) untuk produksi dan key sandbox (sk_test_...) untuk pengujian.Autentikasi
Kirim API key Anda lewat header X-API-Key pada setiap permintaan.
API key Anda (sk_live_... untuk produksi, sk_test_... untuk sandbox) dan webhook secret tersedia di halaman Beranda dashboard. Status pembayaran dipantau lewat webhook dan halaman Riwayat.
1. Payment Link & Gateway — QRIS
Buat pembayaran
Header: X-API-Key: sk_live_... (untuk sandbox pakai sk_test_...).
| Parameter | Tipe | Wajib | Keterangan |
|---|---|---|---|
amount | integer | Ya | Nominal dasar, 100 — 10.000.000 |
customer_name | string | Tidak | Nama pelanggan (maks 120 karakter) |
merchant_ref | string | Tidak | Nomor order/id dari sistem Anda (maks 100 karakter). Dikirim balik pada respons dan setiap webhook PAID untuk mencocokkan transaksi ke order Anda. |
metadata | object | Tidak | Objek JSON bebas yang Anda pilih untuk identifikasi order (maks 2000 karakter). Contoh di atas (mis. "sku") hanyalah ilustrasi — sistem tidak menghasilkan atau mewajibkan kunci apa pun; isi terserah Anda dan hanya dikirim balik mentah pada webhook PAID. |
| Aturan | Nilai |
|---|---|
| Nominal dasar | integer, 100 — 10.000.000 |
| Masa berlaku | 30 menit — setelah itu status EXPIRED |
| Kredit saldo | berdasar base_amount dikurangi MDR 0,7% |
| Kode unik | sistem menambahkan angka unik acak (250 — 500) ke setiap transaksi untuk membedakan pembayaran bersamaan yang masuk ke QRIS admin bersama |
Kode unik tersebut ditambahkan ke nominal dasar, sehingga jumlah yang harus dibayar pelanggan (total_amount) = base_amount + kode unik.
Respons sukses:
Penting: qris_string adalah teks QRIS mentah (format EMVCo) — untuk menampilkan QR di layar, integrasi Anda HARUS merender string tersebut menjadi gambar QR (mis. library qrcode/qrcode-generator). Ini bukan URL gambar.
qr_code_svg adalah gambar QR siap tampil (SVG self-contained, tidak bergantung aset eksternal) yang kami generate dari qris_string. Bisa dirender langsung sebagai data:image/svg+xml;base64,<...> atau data:image/svg+xml;utf8,<...>. Field ini opsional — jika kosong, render qris_string.
Webhook Pembayaran
Saat transaksi PAID, sistem mengirim POST ke URL webhook yang diatur di panel Pengaturan → Webhook (satu URL untuk live, satu untuk sandbox).
| Header | Isi |
|---|---|
X-Webhook-Secret | Webhook secret Anda (untuk akses cepat / sambungan langsung) |
X-MauPay-Signature | sha256=<base64-HMAC-SHA256> dari body (tanpa _signature), pakai webhook secret Anda |
_signature (di body) | Nilai tanda tangan yang sama dengan X-MauPay-Signature, disertakan di dalam body JSON |
Content-Type | application/json |
User-Agent | MauPay-Webhook/1.0 |
Keamanan: verifikasi tanda tangan _signature = 'sha256=' + base64(HMAC-SHA256(sisa body, webhook_secret)), dan header X-Webhook-Secret serta X-MauPay-Signature.
base_amount sebelum mengkredit saldo merchant. Field mdrFee = nominal potongan, dan netAmount = jumlah bersih yang benar-benar masuk ke saldo Anda (base_amount − mdrFee). Contoh: base Rp 132.000 → MDR Rp 924 → saldo masuk Rp 131.076. Transaksi sandbox tidak dipotong, dan angka di atas hanya ilustrasi.Penting: _signature dihitung dari body tanpa kunci _signature itu sendiri, dihitung dengan webhook_secret Anda (diatur di Pengaturan → Webhook). Selalu verifikasi signature sebelum memproses webhook untuk memastikan berasal dari MauPay. Buat handler webhook Anda idempoten (aman terhadap webhook berulang, mis. dengan memeriksa transactionId sebelum mengkredit/mengerjakan order).
Contoh verifikasi signature
Contoh integrasi
2. Sandbox
Gunakan API key sk_test_.... Buat transaksi seperti biasa; respons menyertakan simulatePayUrl untuk menandai transaksi sebagai PAID dan memicu webhook sandbox ke sandbox_webhook_url Anda.
Header: X-API-Key: sk_test_... milik pemilik transaksi.
Status transaksi (lifecycle)
Setiap perubahan status diberitahukan lewat webhook. Status yang mungkin:
| Status | Keterangan | Pemicu |
|---|---|---|
PENDING | Menunggu pembayaran | Transaksi dibuat |
PAID | Pembayaran diterima, saldo dikredit | Uang masuk cocok (atau simulate-payment di sandbox) |
EXPIRED | Kedaluwarsa, tidak dapat dibayar lagi | Melebihi 30 menit tanpa pembayaran |
FAILED | Gagal / dibatalkan | Kondisi gagal (mis. pembayaran tidak valid) |
PENDING → PAID. Jika tidak dibayar dalam 30 menit: PENDING → EXPIRED.3. Dashboard & Status
Operasi selain pembuatan pembayaran dilakukan di dalam dashboard (app.maupay.online):
| Fitur | Cara | Keterangan |
|---|---|---|
| Status transaksi | Menu Transaksi & Riwayat | Status per transaksi dan riwayat lengkap. Perubahan status penting (mis. PAID / EXPIRED / FAILED) juga dikirim lewat webhook |
| Tarik dana | Menu Tarik Dana | Minimal Rp 20.000, fee Rp 3.000. E-wallet DANA / OVO / GoPay / ShopeePay / LinkAja |
| Webhook URL | Menu Pengaturan | URL webhook untuk notifikasi pembayaran (live & sandbox) |
| Webhook Logs | Menu Webhook Logs | Riwayat pengiriman webhook ke server Anda |
| Akun & auth | Halaman register / masuk / lupa password / ganti password di aplikasi | Daftar dengan OTP email; sesi login valid 30 hari |
| API keys | Halaman Beranda | sk_live_…, sk_test_…, webhook secret |
POST /api/v1/payments untuk membuat pembayaran, halaman status/pay dari respons untuk menampilkan QRIS, dan webhook untuk mengetahui transaksi PAID.4. Kode Error
| Kode | Arti |
|---|---|
| 200 / 201 | Sukses |
| 400 | Parameter salah / validasi gagal (mis. amount tidak integer, metadata bukan objek) |
| 401 | API key salah / tidak valid |
| 403 | Akses ditolak (bukan transaksi Anda) |
| 404 | Sumber daya tidak ditemukan |
| 429 | Terlalu banyak request — pembayaran dibatasi 30/menit per IP & per API key; penarikan 5×/5 menit; verifikasi OTP 5×/10 menit. |
| 500 | Kesalahan internal server |
Respons error dikembalikan sebagai JSON: