NovPay API v1.0

Dokumentasi lengkap buat integrasi pembayaran QRIS ke platform kamu.

Auth: Authorization: Bearer nvp_... Nominal dalam integer rupiah

Buat Payment

POST /api/v1/payment/create

Header

Content-Type: application/json
Authorization: Bearer API_KEY

Request Body

{
  "amount": 50000,          // integer, wajib (Rp 1 - Rp 10.000.000)
  "description": "Order #123", // opsional
  "customer_name": "John",    // opsional
  "customer_email": "j@x.co", // opsional
  "callback_url": "https://...", // opsional, override webhook URL
  "metadata": { "order_id": "123" } // opsional, JSON object bebas
}

Response

{
  "success": true,
  "data": {
    "invoice_id": "NVP-20260909-ABCD1234",
    "amount": 50000,             // nominal asli
    "fee": 500,                  // biaya layanan
    "amount_charged": 50500,      // yang dibayar pembeli (buyer mode)
    "fee_mode": "buyer",          // "seller" atau "buyer"
    "status": "pending",
    "payment_method": "QRIS",     // Metode pembayaran
    "qr_url": "https://novpay.id/api/v1/qr/NVP-xxx.png",   // URL gambar QR (selalu tersedia)
    "qr_string": "00020101021226...",  // raw QRIS payload (untuk render sendiri)
    "qr_content": "00020101021226...", // alias qr_string
    "checkout_url": "https://novpay.id/pay/NVP-xxx",  // halaman checkout
    "payment_url": "https://novpay.id/pay/NVP-xxx",   // alias checkout_url
    "expired_at": "2026-09-09 15:30:00",
    "created_at": "2026-09-09 15:15:00"
  }
}

Catatan:
• qr_url — URL gambar PNG QR code. Selalu tersedia untuk semua gateway. Bisa langsung di-download atau ditampilkan sebagai <img>.
• qr_string / qr_content — Raw payload QRIS (EMVCo string). Bisa dirender jadi QR code menggunakan library seperti qrcode (Node.js) atau QRious (browser). Bernilai null jika gateway return gambar saja.
• checkout_url / payment_url — Link halaman pembayaran NovPay (bisa dibuka di browser, sudah ada QR + countdown).
• Gunakan field yang paling cocok untuk kebutuhan kamu. Semua field selalu tersedia di setiap response.

Cek Status

GET /api/v1/payment/status/{invoice_id}

Status: pending | success | expired | failed

Response

{
  "success": true,
  "data": {
    "invoice_id": "NVP-20260909-ABCD1234",
    "amount": 50000,
    "fee": 500,
    "amount_charged": 50500,
    "net_amount": 50000,
    "fee_mode": "buyer",
    "status": "success",
    "payment_method": "QRIS",
    "qr_url": "https://novpay.id/api/v1/qr/NVP-xxx.png",
    "qr_string": "00020101021226...",
    "qr_content": "00020101021226...",
    "checkout_url": "https://novpay.id/pay/NVP-xxx",
    "payment_url": "https://novpay.id/pay/NVP-xxx",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "description": "Order #123",
    "metadata": { "order_id": "123" },
    "paid_at": "2026-09-09 15:20:00",
    "expired_at": "2026-09-09 15:30:00",
    "created_at": "2026-09-09 15:15:00"
  }
}

QR Code Image

GET /api/v1/qr/{invoice_id}.png

Endpoint publik (tanpa auth) untuk mendapatkan gambar QR code dalam format PNG. Berguna jika kamu butuh URL gambar QR yang bisa langsung di-embed di <img> tag atau di-download.

Parameter

// URL parameter
invoice_id  // Invoice ID dari response payment/create

// Query parameter (opsional)
size        // Ukuran gambar dalam pixel (100-1000, default: 400)

Contoh

// Sebagai img tag
<img src="https://novpay.id/api/v1/qr/NVP-20260909-ABCD1234.png" />

// Dengan ukuran custom
<img src="https://novpay.id/api/v1/qr/NVP-20260909-ABCD1234.png?size=300" />

// Download via curl
curl -o qr.png https://novpay.id/api/v1/qr/NVP-20260909-ABCD1234.png

Webhook

Event: payment.success — POST ke webhook URL kamu saat pembayaran berhasil.

Header: X-Signature (HMAC dengan webhook secret)

Payload

{
  "event": "payment.success",
  "data": {
    "invoice_id": "NVP-20260909-ABCD1234",
    "amount": 50000,
    "fee": 500,
    "net_amount": 50000,
    "status": "success",
    "payment_method": "QRIS",       // Metode pembayaran
    "paid_at": "2026-09-09 15:20:00",
    "customer_name": "John Doe"
  }
}

Verifikasi Signature

// Verifikasi: HMAC-SHA256(body, webhook_secret) === X-Signature header

// Node.js
const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody).digest('hex');
if (hash !== req.headers['x-signature']) reject();

// PHP
$hash = hash_hmac('sha256', $rawBody, $webhookSecret);
if ($hash !== $_SERVER['HTTP_X_SIGNATURE']) reject();

// Python
import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
if expected != headers['X-Signature']: reject()

Mau Docs Lebih Lengkap?

Masuk ke Dashboard