Dokumentasi API

Pakai API ini dari aplikasi atau toko kamu untuk membuat tagihan QRIS dan mengetahui kapan tagihan itu lunas. Semua endpoint memakai JSON.

Base URL
https://gobiz.qrismodule.web.id/api/v1

Alur pembayaran

  1. Aplikasi kamu memanggil POST /payments dengan harga barang.
  2. Gateway menambahkan kode unik Rp 1–999 supaya setiap tagihan yang masih terbuka punya nominal berbeda, lalu membuat QRIS dinamis dengan nominal itu.
  3. Arahkan pembeli ke checkout_url, atau tampilkan qris_string sebagai QR di aplikasi kamu sendiri.
  4. Pembeli membayar tepat sebesar nominal dengan aplikasi e-wallet atau m-banking apa pun.
  5. Gateway mencocokkan transaksi masuk di GoPay Merchant. Begitu cocok, status jadi paid dan webhook dikirim ke callback_url kamu.
  6. Tagihan yang tidak dibayar dalam 15 menit menjadi expired: kode tidak bisa dipakai lagi, QRIS-nya tidak ditampilkan lagi, dan pembeli harus membuat tagihan baru. Satu pengecualian: uang yang dibayar sebelum batas waktu tapi baru dilaporkan GoPay Merchant belakangan tetap melunasi tagihan, meskipun statusnya sudah expired. Lihat Masa berlaku & data.

Autentikasi

Kirim API key di header X-Api-Key, atau sebagai bearer token. Simpan API key hanya di server kamu, jangan di aplikasi frontend atau mobile.

Header
X-Api-Key: API_KEY_KAMU
# atau
Authorization: Bearer API_KEY_KAMU

POST /payments

Membuat tagihan baru. Respons 201 Created berisi objek payment.

FieldTipeKeterangan
amountinteger, wajibHarga dalam rupiah, 1 sampai 9.999.001. Kode unik ditambahkan otomatis.
external_idstring, opsionalID pesanan di sistem kamu (maks. 255 karakter), dikembalikan apa adanya.
callback_urlURL https, opsionalAlamat yang menerima webhook saat tagihan lunas atau kedaluwarsa. Harus mengarah ke alamat internet publik; localhost dan alamat jaringan lokal ditolak.
return_urlURL http(s), opsionalHalaman toko kamu untuk pembeli setelah membayar. checkout_url menampilkan tombol Kembali ke toko dan mengarahkan pembeli ke sana otomatis beberapa detik setelah lunas. Halaman kedaluwarsa juga menampilkan tombolnya.

Header Idempotency-Key (disarankan)

Kalau request terputus (timeout, koneksi putus), kamu tidak tahu apakah tagihannya sudah dibuat. Kirim header Idempotency-Key berisi nilai unik per tagihan (maks. 255 karakter, misalnya ID pesanan) supaya request itu aman diulang:

  • Request ulang dengan key dan isi yang sama mengembalikan tagihan yang sudah dibuat dengan status 200 OK (bukan 201), tanpa membuat tagihan baru.
  • Key yang sama dengan isi berbeda (amount, external_id, callback_url, atau return_url) ditolak dengan 409 Conflict. Pakai key baru untuk tagihan baru, misalnya untuk pesanan yang dibayar ulang setelah tagihannya kedaluwarsa.
  • Tanpa header ini, setiap request membuat tagihan baru.
Contoh request (curl)
curl -X POST https://gobiz.qrismodule.web.id/api/v1/payments \
  -H "X-Api-Key: API_KEY_KAMU" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-1001" \
  -d '{"amount": 25000, "external_id": "ORDER-1001", "callback_url": "https://toko-kamu.com/webhooks/qris", "return_url": "https://toko-kamu.com/pesanan/1001"}'
Contoh request (PHP / Laravel)
$response = Http::withHeaders([
        'X-Api-Key' => config('services.qris.key'),
        'Idempotency-Key' => 'order-'.$order->id,
    ])
    ->acceptJson()
    ->retry(3, 1000)
    ->post('https://gobiz.qrismodule.web.id/api/v1/payments', [
        'amount' => 25000,
        'external_id' => $order->id,
        'callback_url' => route('webhooks.qris'),
        'return_url' => route('orders.show', $order),
    ])
    ->throw();

$payment = $response->json('data');
return redirect($payment['checkout_url']);

GET /payments/{reference}

Mengambil status terbaru sebuah tagihan. Selama tagihan masih pending, gateway mengecek GoPay Merchant dulu sebelum menjawab. Kalau kamu sudah memakai webhook, endpoint ini cukup dipakai sesekali untuk memastikan.

Contoh request
curl https://gobiz.qrismodule.web.id/api/v1/payments/PAY-BP6VXQTJNSE6 \
  -H "X-Api-Key: API_KEY_KAMU" \
  -H "Accept: application/json"

Objek payment

Contoh respons
{
  "data": {
    "reference": "PAY-BP6VXQTJNSE6",
    "external_id": "ORDER-1001",
    "status": "pending",
    "base_amount": 25000,
    "unique_code": 784,
    "amount": 25784,
    "qris_string": "00020101021226610014COM.GO-JEK.WWW...6304A1B2",
    "checkout_url": "https://qrisfian.test/pay/PAY-BP6VXQTJNSE6",
    "return_url": "https://toko-kamu.com/pesanan/1001",
    "expires_at": "2026-10-16T19:59:31+07:00",
    "paid_at": null,
    "gobiz_transaction_id": null,
    "paid_manually": false,
    "created_at": "2026-10-16T19:44:31+07:00"
  }
}
referenceID tagihan di gateway, dipakai di URL.
statuspending (menunggu bayar), paid (lunas), atau expired (waktu habis). expired masih bisa berubah menjadi paid kalau uang yang dibayar sebelum batas waktu baru dilaporkan belakangan; paid tidak pernah berubah lagi.
amountNominal yang harus dibayar persis: base_amount + unique_code.
qris_stringIsi QRIS dinamis. Ubah jadi gambar QR kalau kamu tidak memakai checkout_url. Bernilai null begitu tagihan tidak lagi pending (lunas atau kedaluwarsa).
checkout_urlHalaman bayar siap pakai dengan QR, hitung mundur, dan status otomatis. Setelah waktu habis, halaman ini dialihkan ke halaman informasi kedaluwarsa.
return_urlreturn_url yang dikirim saat membuat tagihan, atau null.
paid_atWaktu transaksi di GoPay Merchant, terisi saat lunas. Untuk tagihan yang ditandai lunas manual, waktu admin menandainya.
gobiz_transaction_idID transaksi GoPay yang melunasi tagihan ini.
paid_manuallytrue kalau admin gateway menandai tagihan lunas secara manual, misalnya setelah menemukan uangnya di GoPay Merchant tapi gateway tidak bisa mencocokkannya. gobiz_transaction_id tetap null sampai transaksinya tercocokkan.

Semua waktu dalam format ISO 8601 dengan zona waktu WIB (+07:00).

Masa berlaku & data

Setiap kode pembayaran (PAY-…) hanya berlaku sekali dan punya batas waktu.

WaktuYang terjadi
0–15 menitTagihan pending. Pembeli bisa membayar QRIS-nya. Uang yang masuk dengan nominal tepat melunasi tagihan (paid).
Setelah 15 menitAPI langsung menampilkan tagihan sebagai expired. checkout_url dialihkan ke halaman informasi kedaluwarsa yang meminta pembeli membuat pembayaran baru, dan API tidak lagi mengirim qris_string. Status tersimpannya baru diubah, dan payment.expired baru dikirim, setelah gateway berhasil membaca transaksi GoPay Merchant sampai paling tidak 2 menit melewati batas waktu.
Sampai 2 jam setelah expiredNominalnya tetap dipesan dan tidak diberikan ke tagihan baru. Uang yang dibayar sebelum batas waktu tapi baru dilaporkan GoPay Merchant belakangan tetap melunasi tagihan: statusnya berubah dari expired menjadi paid. Uang yang dibayar setelah batas waktu dicatat sebagai pembayaran telat untuk direfund, bukan melunasi tagihan.
2 jam setelah expiredIsi QRIS dihapus dari gateway. Yang tersisa hanya data ringkas: kode, nominal, status, dan waktu.
30 hari setelah expiredData ringkas tagihan expired dan catatan pembayaran telatnya dihapus. Setelah itu kodenya menjawab 404. Tagihan yang paid tidak ikut dihapus.

Penting: QRIS yang sudah kedaluwarsa secara teknis masih bisa dibayar

QRIS dinamis di gateway ini dibuat dari QRIS statis merchant dan tidak terdaftar di jaringan pembayaran, jadi tidak bisa dibatalkan. Pembeli yang menyimpan screenshot QR tetap bisa membayarnya, dan uangnya tetap masuk ke saldo GoPay Merchant. Gateway tidak akan menganggapnya sebagai pelunasan. Uang itu dicatat sebagai pembayaran telat dan bisa dilihat pemilik gateway dengan php artisan payments:late, lalu direfund.

Hal yang sama berlaku untuk QRIS tagihan yang sudah paid: selama 2 jam setelah lunas nominalnya tetap dipesan, dan transfer kedua (pembeli membayar dua kali) dicatat sebagai pembayaran telat, bukan melunasi tagihan lain.

Webhook

Kalau tagihan dibuat dengan callback_url, gateway mengirim POST ke alamat itu saat tagihan berubah status. Isinya objek payment yang sama dengan respons API.

X-Eventpayment.paid atau payment.expired
X-Webhook-TimestampWaktu pengiriman dalam detik Unix. Dibuat ulang di setiap percobaan kirim.
X-Webhook-SignatureHMAC-SHA256 dari {X-Webhook-Timestamp}.{raw body} (timestamp, titik, lalu body apa adanya) dengan webhook secret sebagai kunci, dalam hex. Webhook secret ada di Admin → Pengaturan dan hanya bisa dipakai untuk verifikasi, bukan untuk memanggil API.
X-SignatureLama, masih dikirim. HMAC-SHA256 dari raw body dengan API key sebagai kunci, dalam hex. Tidak melindungi dari webhook yang dikirim ulang, jadi pakai X-Webhook-Signature untuk integrasi baru.
Contoh body
{
  "event": "payment.paid",
  "data": {
    "reference": "PAY-BP6VXQTJNSE6",
    "external_id": "ORDER-1001",
    "status": "paid",
    "amount": 25784,
    "paid_at": "2026-10-16T19:47:02+07:00",
    "gobiz_transaction_id": "e2b1c9f0-...",
    "...": "field lain sama dengan objek payment"
  }
}
Verifikasi di Laravel
// routes/web.php (kecualikan route ini dari CSRF)
Route::post('/webhooks/qris', function (Request $request) {
    $timestamp = (string) $request->header('X-Webhook-Timestamp');
    $expected = hash_hmac('sha256', $timestamp.'.'.$request->getContent(), config('services.qris.webhook_secret'));

    abort_unless(hash_equals($expected, (string) $request->header('X-Webhook-Signature')), 401);
    // Tolak webhook lama, supaya webhook yang disadap tidak bisa dikirim ulang.
    abort_if(! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300, 401);

    $payment = $request->input('data');

    if ($request->header('X-Event') === 'payment.paid') {
        Order::where('id', $payment['external_id'])->update(['paid_at' => now()]);
    }

    return response()->noContent();
});
Verifikasi di Node.js (Express)
app.post('/webhooks/qris', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Webhook-Timestamp') || '';
  const expected = crypto.createHmac('sha256', process.env.QRIS_WEBHOOK_SECRET)
    .update(`${timestamp}.`)
    .update(req.body)
    .digest('hex');
  const given = req.get('X-Webhook-Signature') || '';

  if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  // Tolak webhook lama, supaya webhook yang disadap tidak bisa dikirim ulang.
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.sendStatus(401);
  }

  const { event, data } = JSON.parse(req.body);
  // tandai pesanan data.external_id sebagai lunas
  res.sendStatus(204);
});
  • Balas dengan status 2xx secepatnya. Proses berat sebaiknya dijalankan di antrean kamu.
  • Kalau gagal (timeout, error 5xx, atau 429), webhook dicoba lagi setelah 1 menit, 5 menit, lalu 30 menit, sampai 5 kali percobaan.
  • Balasan 4xx selain 429 dianggap penolakan dan tidak dicoba lagi.
  • Redirect (3xx) tidak diikuti dan dianggap gagal tanpa dicoba lagi. Pakai URL akhir sebagai callback_url, termasuk https:// dan www kalau situsmu mengalihkan ke sana.
  • Alamat callback_url dicek lagi setiap kali webhook dikirim. Kalau domainnya kini mengarah ke alamat lokal atau privat, webhook tidak dikirim.
  • payment.expired dikirim sekitar 2 menit setelah batas waktu, karena GoPay Merchant kadang baru melaporkan transaksi beberapa saat kemudian. Kalau GoPay Merchant sedang tidak bisa dibaca (misalnya login perlu diulang), webhook ini ditunda sampai transaksinya berhasil dicek.
  • Dalam kasus yang jarang (laporan GoPay terlambat lebih lama dari itu), uang yang dibayar sebelum batas waktu baru terlihat setelah tagihan expired. Tagihan tetap menjadi paid dan payment.paid dikirim. Kalau ini terjadi sebelum payment.expired terkirim, payment.expired dibatalkan; kalau sesudahnya, kamu menerima keduanya. Jadi anggap paid selalu sebagai status yang benar, juga setelah expired.
  • Uang yang masuk setelah batas waktu tidak pernah memicu payment.paid. Lihat Masa berlaku & data.
  • Tagihan yang ditandai lunas manual oleh admin juga mengirim payment.paid, dengan paid_manually: true.
  • Webhook yang sama bisa sampai lebih dari sekali. Pastikan pemrosesanmu aman kalau dijalankan dua kali (idempoten), misalnya dengan mengecek reference.

Error & batasan

StatusArti
401API key kosong atau salah.
403Lisensi gateway tidak aktif (license_status berisi alasannya). Tagihan baru tidak bisa dibuat, tapi GET /payments/{reference} tetap bisa dipakai.
404Reference tidak ditemukan, atau tagihan expired sudah dihapus setelah 30 hari.
409Idempotency-Key sudah dipakai untuk tagihan dengan isi berbeda. Pakai key baru.
422Input tidak valid. Detail ada di field errors; header Idempotency-Key yang terlalu panjang muncul sebagai idempotency_key.
503Tagihan belum bisa dibuat, misalnya semua kode unik untuk harga itu sedang terpakai. Coba lagi beberapa saat kemudian.
429Terlalu banyak request: maksimal 60 per menit per alamat IP.

Gateway di belakang Cloudflare atau reverse proxy lain? Isi TRUSTED_PROXIES=cloudflare (atau daftar IP/range proxy, dipisah koma) di .env. Tanpa itu semua pengunjung terlihat memakai IP proxy, sehingga batas di atas berlaku untuk mereka bersama-sama.

Contoh 422
{
  "message": "The amount field is required.",
  "errors": {
    "amount": ["The amount field is required."]
  }
}

GET /api/health

Untuk uptime monitor (UptimeRobot, Better Stack, dan sejenisnya). Tanpa API key, tidak di-cache, maksimal 60 request per menit. Menjawab 200 kalau semuanya siap memproses pembayaran, dan 503 kalau ada yang perlu dicek.

Contoh request
curl https://gobiz.qrismodule.web.id/api/health
Contoh respons 503
{
  "status": "failing",
  "checks": {
    "database": "ok",
    "scheduler": "failing",
    "gobiz": "ok",
    "qris": "ok"
  }
}
databaseDatabase bisa dihubungi. Kalau gagal, cek lainnya dilewati.
schedulerCron job berjalan dalam 3 menit terakhir. Tanpa cron, tagihan tidak dicocokkan dan webhook tidak dikirim.
gobizAda login GoPay Merchant yang tokennya masih berlaku atau bisa diperbarui otomatis.
qrisQRIS statis sudah diisi, jadi tagihan baru bisa dibuat.