docs QRIS (Publik)

Pengenalan

Gateway ini memakai QRIS merchant admin di server. Setiap penyewa yang punya lisensi aktif dapat membuat pembayaran, mendeteksi lunas, dan menarik saldo lewat portal (Withdraw).

Env bot / web store (wajib per pengguna)

Setiap penyewa mendapat API Key unik di portal. Taruh key itu di env bot / store masing-masing agar request terikat ke akun mereka: transaksi, payment_id, dan saldo tidak campur dengan toko lain.

Autentikasi

Semua request (kecuali gambar QR) pakai header Bearer API Key dari portal.

Authorization: Bearer js_API_KEY_ANDA

Authorization: Bearer …

Cara Mulai

1. Daftar di /portal (OTP Telegram) → sistem buat API Key unik
2. Salin API Key dari Settings → taruh di env bot/store: API_KEY + BASE_URL
3. Setiap request pakai header Authorization: Bearer API_KEY → transaksi & saldo terpisah per toko
4. Panggil create QRIS → tampilkan ke pelanggan → cek bayar dengan payment_id

Buat QRIS (Payment)

Membuat QRIS dinamis memakai QRIS admin di server. Response berisi payment_id dan nominal yang harus dibayar persis.

Request Body

{
  "amount": 50000,
  "ref": "ORDER-123",
  "note": "Top up user"
}

Response

{
  "success": true,
  "message": "QRIS created successfully (shared PG)",
  "data": {
    "payment_id": "pay_abc123",
    "amount": 50550,
    "requested_amount": 50000,
    "credit_amount": 50000,
    "qr_string": "00020101...",
    "qr_url": "https://YOUR-DOMAIN/gateaway/qr/xxxxx",
    "expiry_time": "2026-07-23 15:00:00",
    "mode": "tenant_shared"
  }
}

Cek Pembayaran

Cek apakah customer sudah bayar. Jika success, saldo penyewa otomatis di-credit.

{ "payment_id": "pay_abc123" }

Response (lunas)

{
  "success": true,
  "data": {
    "paid": true,
    "expired": false,
    "cancelled": false,
    "credit_amount": 50000,
    "payment": { "id": "pay_abc123", "amount": 50350, "status": "paid" },
    "balance": { "balance": 50000, "locked": 0, "available": 50000 }
  }
}

Response (belum bayar)

{
  "success": true,
  "data": {
    "paid": false,
    "expired": false,
    "cancelled": false,
    "payment": { "id": "pay_abc123", "status": "pending", "expires_at": "..." }
  }
}

Response (QRIS expired → auto cancelled)

{
  "success": true,
  "message": "QRIS expired — otomatis dibatalkan",
  "data": {
    "paid": false,
    "expired": true,
    "cancelled": true,
    "payment": {
      "id": "pay_abc123",
      "status": "cancelled",
      "cancel_reason": "expired",
      "expires_at": "..."
    }
  }
}

Status pembayaran & auto-cancel expire

Setelah qris/create, payment berstatus pending sampai lunas atau lewat expiry_time (default ~15 menit, env QRIS_EXPIRY_MINUTES).

Kapan auto-cancel jalan?

• Saat ada yang memanggil GET/POST payment (list / check) lewat findById
• Job periodik server (~setiap 30 detik) membatalkan semua pending yang lewat expires_at

Setelah cancelled, nominal unik dibebaskan untuk payment baru. Gambar QR (/gateaway/qr/:id) juga tidak valid lagi setelah expiry store QR.

Riwayat & Saldo

Alias riwayat juga: GET /gateaway/transactions (mode shared PG otomatis).

QR Image

Gambar QR publik (tanpa API Key). ID random & berumur pendek (~15 menit).

Contoh Bot / Web Store

Node.js

Python

PHP / Laravel (cURL)

Webhook & Verifikasi Signature (HMAC-SHA256)

Selain polling, Anda dapat menyertakan callback_url saat membuat QRIS (atau mengatur Default Callback URL di Portal → Pengaturan). Begitu pembayaran lunas, server kami mengirim HTTP POST JSON dengan header tanda tangan kriptografi:

const crypto = require('crypto');

app.post('/webhook/janspay', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.WEBHOOK_SECRET; // dari Portal → Pengaturan
  const ts = req.headers['x-webhook-timestamp'];
  const sig = req.headers['x-signature'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(`${ts}.${req.body.toString('utf8')}`)
    .digest('hex');

  if (sig !== expected) return res.status(401).send('Invalid signature');
  const event = JSON.parse(req.body.toString('utf8'));
  // Proses order lunas: event.payment_id, event.credit_amount, event.ref
  res.json({ ok: true });
});

Integrasi PHP & Laravel

Contoh lengkap integrasi payment gateway di PHP native (cURL) dan framework Laravel (Guzzle / HTTP Client).

1. PHP Native (cURL) — Buat Tagihan & Redirect

2. Laravel Framework (HTTP Client) — Controller & Checkout

3. Verifikasi Webhook Signature (HMAC-SHA256) di PHP

Uji simulasi pembuatan tagihan QRIS secara langsung dari browser Anda tanpa perlu koding. Jika Anda belum punya API Key, sistem otomatis menggunakan Demo Sandbox publik.

API Key Penyewa (Opsional)

Nominal Order (IDR)

Ref / Order ID

Coba Buat QRIS Sekarang Menghubungi gateway...

TOTAL HARUS DIBAYAR

Rp 0

Menunggu Pembayaran

Buka Halaman Bayar Customer →

Response JSON dari Gateway Cek Status Bayar

Error Umum