API NusaPay

Bangun sistem pembayaran dan pencairan dana tak terbatas dengan REST API yang dirancang untuk kecepatan dan keandalan. Dokumentasi ini memberikan panduan lengkap untuk berintegrasi dengan ekosistem kami.

Satu Endpoint Universal

Seluruh request API dipusatkan melalui satu endpoint (Gateway). Sistem mendeteksi tujuan request Anda berdasarkan parameter "action" di dalam body JSON.

POST https://yangcepatx.com/api

Otentikasi & Kredensial

Setiap request ke API wajib menyertakan otentikasi menggunakan metode Bearer Token. Anda dapat menemukan kunci API Anda di menu "Kunci API" pada Dasbor Merchant.

Server Key (Secret)

Gunakan kunci ini (sk_live_...) pada Header Authorization untuk memanggil endpoint Charge, Check Status, dan Withdraw. Wajib dijaga kerahasiaannya.

Client Key (Public)

Kunci ini (ck_live_...) digunakan untuk integrasi sisi frontend (JS/Mobile). Saat ini hanya sebagai identifier publik, tidak untuk eksekusi API.

Hati-hati: Jangan pernah meng-hardcode Server Key di dalam kode aplikasi mobile (Android/iOS) atau browser Javascript. Jika kunci ini bocor, pihak lain dapat menarik dana Anda.

                            Format Header HTTP
                        
Authorization: Bearer sk_live_a1b2c3d4e5f6...
Content-Type: application/json
Accept: application/json

POST

Buat Tagihan (Charge)

Endpoint ini akan men-generate kode QRIS dinamis. Anda akan menerima string QR mentah yang bisa Anda olah sendiri, maupun URL gambar QR yang sudah siap ditampilkan ke pelanggan Anda.

Body Parameter (JSON)

action
Required

Harus bernilai "charge".

gross_amount
Required
Integer

Total tagihan kotor yang harus dibayar pelanggan. Minimal 100.

payment_type
Required
String

Metode pembayaran. Saat ini hanya mendukung "qris".

curl -X POST https://yangcepatx.com/api \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "charge",
    "payment_type": "qris",
    "gross_amount": 150000
}'

<?php
$payload = json_encode([
    "action" => "charge",
    "payment_type" => "qris",
    "gross_amount" => 150000
]);

$ch = curl_init('https://yangcepatx.com/api');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk_live_YOUR_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response));

<?php
use Illuminate\Support\Facades\Http;

$response = Http::withToken('sk_live_YOUR_KEY')
    ->post('https://yangcepatx.com/api', [
        'action' => 'charge',
        'payment_type' => 'qris',
        'gross_amount' => 150000
    ]);

return $response->json();

const axios = require('axios');

async function createCharge() {
  try {
    const response = await axios.post('https://yangcepatx.com/api', {
      action: 'charge',
      payment_type: 'qris',
      gross_amount: 150000
    }, {
      headers: { 'Authorization': 'Bearer sk_live_YOUR_KEY' }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
}

Example Response (201 Created)

{
  "status_code": "201",
  "status_message": "Berhasil membuat transaksi",
  "transaction_id": "NUSA-A1B2C3",
  "gross_amount": 150000,
  "net_amount_estimated": 147750, // Uang bersih yang akan masuk saldo
  "payment_type": "qris",
  "currency": "IDR",
  "qris_data": {
    "reference": "UPAY-998877",
    "qr_string": "00020101021126620014ID.CO.NMS...",
    "qr_image_url": "https://api.qrserver.com/v1/create-qr-code/..."
  }
}
                        

POST

Cek Status Transaksi

Jika server Anda melewatkan notifikasi Webhook, Anda dapat secara aktif (polling) memanggil endpoint ini untuk mengetahui status pembayaran terkini.

Body Parameter (JSON)

action
Required

Harus bernilai "check_status".

transaction_id
Required

ID Transaksi yang Anda dapatkan saat response pembuatan tagihan (Mulai dengan NUSA-...).

CURL EXAMPLE

curl -X POST https://yangcepatx.com/api \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "check_status",
    "transaction_id": "NUSA-A1B2C3"
}'

Example Response (200 OK)

{
  "status_code": "200",
  "transaction_id": "NUSA-A1B2C3",
  "payment_status": "PAID", // PENDING, PAID, FAILED
  "gross_amount": 150000,
  "net_amount": 147750
}
                        

POST

Penarikan Dana (Withdrawal)

Endpoint tingkat lanjut bagi mitra B2B (Aggregator/Platform) yang ingin mengotomatisasi pengiriman uang / pencairan dana (*disbursement*) langsung ke rekening pelanggan mereka tanpa harus login ke dashboard.

Penarikan via API akan mengurangi Saldo Settled Anda dan diproses secara langsung oleh sistem perbankan. Pastikan server Anda aman saat memanggil perintah ini.

Body Parameter (JSON)

action
Required

Harus bernilai "withdraw".

amount
Required

Nominal yang akan dikirimkan ke rekening tujuan. (Pajak/Fee Admin akan ditambahkan sebagai potongan ekstra ke saldo Anda).

bank_code
Required

Kode Bank Tujuan (contoh: "BCA", "MANDIRI", "DANA").

account_number
Required

Nomor rekening tujuan pengiriman.

account_name
Required

Nama pemilik rekening tujuan.

<?php
use Illuminate\Support\Facades\Http;

// Lakukan validasi saldo user Anda sebelum memanggil API ini
$response = Http::withToken('sk_live_YOUR_KEY')
    ->post('https://yangcepatx.com/api', [
        'action' => 'withdraw',
        'amount' => 500000,
        'bank_code' => 'BCA',
        'account_number' => '8912345678',
        'account_name' => 'PT MAJU JAYA'
    ]);

return $response->json();

const axios = require('axios');

async function disburseFunds() {
  const payload = {
    action: 'withdraw',
    amount: 500000,
    bank_code: 'BCA',
    account_number: '8912345678',
    account_name: 'PT MAJU JAYA'
  };

  const res = await axios.post('https://yangcepatx.com/api', payload, {
    headers: { 'Authorization': 'Bearer sk_live_YOUR_KEY' }
  });
  console.log(res.data);
}

Example Response (200 OK)

{
  "status_code": "200",
  "status_message": "Permintaan penarikan diproses oleh pusat.",
  "transaction_id": "WD-API-8F9A",
  "amount_sent_to_bank": 500000,
  "admin_fee": 5000,
  "total_deducted": 505000, // Saldo Settled yang terpotong total
  "status": "PROCESSING" // Tunggu Webhook untuk status akhir
}
                        

Menerima Webhook (Callbacks)

Daripada melakukan *polling* terus-menerus, NusaPay akan mengirimkan HTTP POST Request secara asinkron ke server Anda (*Callback URL*) segera setelah pembayaran pelanggan masuk, atau setelah penarikan dana berhasil diproses oleh bank.

Verifikasi Signature (Anti-Hacker)

Untuk memvalidasi bahwa Webhook benar-benar sah dikirim oleh server NusaPay (dan bukan peretas), kami menyisipkan HTTP Header khusus: X-NusaPay-Signature.

Anda WAJIB mencocokkan signature tersebut dengan menghitungnya sendiri menggunakan algoritma HMAC-SHA256 dari gabungan:
hash('sha256', RAW_JSON_BODY + SERVER_KEY)

Sistem Webhook kami memiliki Auto-Retry Engine. Jika server Anda membalas selain HTTP 200 (misalnya Error 500 atau Timeout), kami akan mencoba mengirim ulang secara eksponensial (1 menit, 3 menit, 5 menit, dst) hingga batas maksimal.

Contoh Payload dari NusaPay

{
  "event": "payment.success", // atau "withdrawal.success" / "withdrawal.failed"
  "data": {
    "transaction_id": "NUSA-A1B2C3",
    "provider_reference": "UPAY-998877",
    "gross_amount": 150000,
    "fee": 2250,
    "net_amount": 147750,
    "status": "success",
    "timestamp": "2026-06-25 15:30:00"
  }
}
                        

Cara Validasi (PHP Native)

<?php
// 1. Ambil Signature dari Header
$signature_header = $_SERVER['HTTP_X_NUSAPAY_SIGNATURE'];

// 2. Ambil Body JSON mentah persis apa adanya
$raw_payload = file_get_contents('php://input');
$my_server_key = 'sk_live_YOUR_KEY';

// 3. Hitung Hash secara lokal
$calculated = hash('sha256', $raw_payload . $my_server_key);

// 4. Bandingkan!
if ($calculated === $signature_header) {
    // SAH! Proses transaksi ke database Anda
    http_response_code(200);
    echo "OK";
} else {
    // PALSU! Jangan diproses.
    http_response_code(403);
}
                        