Dokumentasi API

0. Base URL

https://www.ruangnotif.com/api/v1

Semua endpoint di bawah memakai prefix ini. Request & response memakai JSON (Content-Type: application/json).

Production vs Sandbox

Saat mengintegrasikan payment gateway di website/aplikasi kamu, sediakan pilihan mode (Sandbox / Production). Mode menentukan apakah transaksi bersifat uji coba atau live.

Contoh di backend developer: jika user memilih Sandbox di panel kamu, kirim body dengan "mode":"sandbox"; jika Production, kirim "mode":"production" atau omit field tersebut. Jangan memakai mode production untuk pelanggan sungguhan sebelum merchant disetujui dan uji sandbox selesai.

Alternatif uji tanpa API: menu Sandbox di dashboard akun RuangNotif (setelah login) — hasilnya sama-sama tidak memengaruhi saldo.

1. Autentikasi

Setiap request wajib menyertakan 2 header. Secret Key jangan pernah dipakai di sisi browser — selalu panggil API dari backend kamu.

API Key & Secret Key — Production vs Merchant Sandbox

Contoh signature (PHP) — production

$apiKey    = 'pk_live_xxxxxxxx';
$secretKey = 'sk_live_xxxxxxxx';

$body = json_encode([
    'order_id' => 'INV-001',
    'amount'   => 50000,
    'method'   => 'qris',
    'mode'     => 'production',
], JSON_UNESCAPED_SLASHES);

$signature = hash_hmac('sha256', $body, $secretKey);
// Header: X-Api-Key: {apiKey}
// Header: X-Signature: {signature}

Contoh signature (PHP) — merchant sandbox

$apiKey    = 'pk_test_xxxxxxxx';  // dari Sandbox → Merchant Sandbox
$secretKey = 'sk_test_xxxxxxxx';

$body = json_encode([
    'order_id' => 'TEST-001',
    'amount'   => 10000,
    'method'   => 'qris',
    'mode'     => 'sandbox',
], JSON_UNESCAPED_SLASHES);

$signature = hash_hmac('sha256', $body, $secretKey);

Pastikan string yang di-hash identik dengan body yang dikirim (urutan field & encoding). SDK resmi sudah menangani ini otomatis.

Membuat transaksi pembayaran baru. Respons berisi payment_url — arahkan pelanggan ke URL tersebut untuk bayar (QRIS / VA / e-wallet, white-label, countdown timer otomatis).

Endpoint ini selalu production (transaksi asli). Untuk uji coba tanpa memengaruhi saldo — terutama saat pengajuan merchant masih di-review — gunakan mode Sandbox (lihat Production vs Sandbox).

Body Request

Contoh cURL

curl -X POST https://www.ruangnotif.com/api/v1/transaction \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: API_KEY_KAMU" \
  -H "X-Signature: HASIL_HMAC_SHA256" \
  -d '{"order_id":"INV-001","amount":50000,"method":"qris","description":"Pembelian A","customer_name":"Budi","mode":"production"}'

Uji coba: ganti "mode":"sandbox". Response order_id akan berprefix SANDBOX-.

Contoh Respons (201 Created)

{
  "success": true,
  "data": {
    "order_id": "INV-001",
    "amount": 51250,
    "method": "qris",
    "status": "pending",
    "mode": "production",
    "payment_url": "https://www.ruangnotif.com/bayar/MCH-XXXX/checkout/INV-001",
    "expired_at": "2026-08-22T15:30:00+07:00"
  }
}

Field Respons

Angka amount 51250 di contoh hanya ilustrasi setelah margin. Nilai aktual mengikuti pengaturan channel di dashboard. Kredit ke saldo merchant tetap = amount request (50000).

Cek status transaksi. Di-scope per merchant — kamu hanya bisa melihat transaksi milik merchant sendiri. Endpoint ini juga dipakai untuk memverifikasi webhook.

Header

Wajib X-Api-Key. Untuk GET tanpa body, signature mengikuti aturan middleware (biasanya body kosong / string kosong — SDK menangani otomatis).

Contoh Respons (200)

{
  "success": true,
  "data": {
    "order_id": "INV-001",
    "amount": 51250,
    "method": "qris",
    "status": "berhasil",
    "mode": "production",
    "paid_amount": 50000,
    "created_at": "2026-08-22T14:30:00+07:00",
    "expired_at": "2026-08-22T15:30:00+07:00"
  }
}

3. Alur pembayaran & halaman checkout

1. Backend kamu memanggil POST /api/v1/transaction.
2. Simpan order_id, lalu redirect / tampilkan payment_url ke pelanggan.
3. Di halaman bayar: QR/VA, instruksi, dan timer countdown hingga expired_at (format HH:MM:SS).
4. Setelah bayar berhasil: webhook (jika di-set) + status API menjadi berhasil.
5. Jika waktu habis tanpa bayar: status expired.

4. Daftar Channel (method)

Real-time sesuai channel yang aktif. Bisa memakai kode custom white-label (di-set di dashboard) tanpa mengekspos nama provider. Detail biaya: Biaya Channel Pembayaran.

5. Notifikasi Webhook

Atur URL Webhook di pengaturan Merchant. Sistem akan POST JSON ke URL tersebut saat pembayaran berhasil.

Body yang dikirim

{
  "order_id": "INV-001",
  "amount": 50000,
  "status": "success",
  "merchant_code": "MCH-XXXX"
}

amount pada webhook = nominal yang dikreditkan ke merchant (request), bukan total tagihan pelanggan.

6. Kode Status HTTP

7. Integrasi Siap Pakai

Tanpa coding berat — pasang modul, isi API Key & Secret Key, langsung jalan.

Callback (Webhook Merchant)

Setelah pembayaran berhasil, sistem mengirim HTTP POST JSON ke URL callback merchant kamu. Gunakan ini agar backend bisa menandai order lunas tanpa menunggu polling status.

1. Cara mendaftarkan URL Callback

1. Merchant production: saat Tambah Merchant, isi field URL Webhook, atau edit merchant di dashboard.
2. Merchant sandbox: saat Buat Merchant Sandbox, isi URL Webhook (opsional tapi disarankan untuk uji callback).
3. URL harus publik (HTTPS disarankan), menerima method POST, dan merespons cepat (timeout server ~5 detik).
4. Contoh: https://tokokamu.com/api/payment/callback

2. Request yang dikirim ke endpoint kamu

Body JSON (payload)

{
  "order_id": "INV-001",
  "amount": 50000,
  "status": "success",
  "merchant_code": "MCH-A1B2C3"
}

3. Contoh endpoint penerima (PHP Laravel)

// routes/api.php
Route::post('/payment/callback', [PaymentCallbackController::class, 'handle']);

// app/Http/Controllers/PaymentCallbackController.php
public function handle(Request $request)
{
    $orderId = $request->input('order_id');
    $status  = $request->input('status');
    $amount  = (int) $request->input('amount');
    $mch     = $request->input('merchant_code');

    if ($status !== 'success' || ! $orderId) {
        return response()->json(['ok' => false], 400);
    }

    // 1) Idempotent: jangan proses order yang sama dua kali
    // 2) (Opsional) verifikasi ulang ke API status RuangNotif
    // 3) Update order lokal → lunas / kirim barang / aktivasi layanan

    return response()->json(['ok' => true], 200);
}

4. Contoh Node.js (Express)

app.post('/api/payment/callback', express.json(), async (req, res) => {
  const { order_id, amount, status, merchant_code } = req.body;

  if (status !== 'success') {
    return res.status(400).json({ ok: false });
  }

  // updateOrderPaid(order_id, amount);
  return res.json({ ok: true });
});

5. Best practice

• Jadikan handler idempotent — callback bisa saja diterima lebih dari sekali untuk order yang sama.
• Setelah menerima callback, verifikasi ulang dengan GET /api/v1/transaction/status/{order_id} sebelum menandai order lunas (lebih aman).
• Jangan mengandalkan callback sebagai satu-satunya sumber kebenaran; sediakan polling/cron status sebagai cadangan.
• Log semua payload callback untuk audit.
• Uji dulu dengan Merchant Sandbox + URL ngrok/localtunnel sebelum production.

SDK PHP Resmi

Signing, HTTP, dan verifikasi webhook sudah dibungkus — cukup panggil method create & status.