Dokumentasi API
Pakai API ini dari aplikasi atau toko kamu untuk membuat tagihan QRIS dan mengetahui kapan tagihan itu lunas. Semua endpoint memakai JSON.
https://gobiz.qrismodule.web.id/api/v1
Alur pembayaran
- Aplikasi kamu memanggil POST /payments dengan harga barang.
- Gateway menambahkan kode unik Rp 1–999 supaya setiap tagihan yang masih terbuka punya nominal berbeda, lalu membuat QRIS dinamis dengan nominal itu.
- Arahkan pembeli ke
checkout_url, atau tampilkanqris_stringsebagai QR di aplikasi kamu sendiri. - Pembeli membayar tepat sebesar nominal dengan aplikasi e-wallet atau m-banking apa pun.
- Gateway mencocokkan transaksi masuk di GoPay Merchant. Begitu cocok, status jadi
paiddan webhook dikirim kecallback_urlkamu. - 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 sudahexpired. 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.
X-Api-Key: API_KEY_KAMU
# atau
Authorization: Bearer API_KEY_KAMU
POST /payments
Membuat tagihan baru. Respons 201 Created berisi objek payment.
| Field | Tipe | Keterangan |
|---|---|---|
| amount | integer, wajib | Harga dalam rupiah, 1 sampai 9.999.001. Kode unik ditambahkan otomatis. |
| external_id | string, opsional | ID pesanan di sistem kamu (maks. 255 karakter), dikembalikan apa adanya. |
| callback_url | URL https, opsional | Alamat yang menerima webhook saat tagihan lunas atau kedaluwarsa. Harus mengarah ke alamat internet publik; localhost dan alamat jaringan lokal ditolak. |
| return_url | URL http(s), opsional | Halaman 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, ataureturn_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.
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"}'
$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.
curl https://gobiz.qrismodule.web.id/api/v1/payments/PAY-BP6VXQTJNSE6 \
-H "X-Api-Key: API_KEY_KAMU" \
-H "Accept: application/json"
Objek payment
{
"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"
}
}
| reference | ID tagihan di gateway, dipakai di URL. |
| status | pending (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. |
| amount | Nominal yang harus dibayar persis: base_amount + unique_code. |
| qris_string | Isi QRIS dinamis. Ubah jadi gambar QR kalau kamu tidak memakai checkout_url. Bernilai null begitu tagihan tidak lagi pending (lunas atau kedaluwarsa). |
| checkout_url | Halaman bayar siap pakai dengan QR, hitung mundur, dan status otomatis. Setelah waktu habis, halaman ini dialihkan ke halaman informasi kedaluwarsa. |
| return_url | return_url yang dikirim saat membuat tagihan, atau null. |
| paid_at | Waktu transaksi di GoPay Merchant, terisi saat lunas. Untuk tagihan yang ditandai lunas manual, waktu admin menandainya. |
| gobiz_transaction_id | ID transaksi GoPay yang melunasi tagihan ini. |
| paid_manually | true 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.
| Waktu | Yang terjadi |
|---|---|
| 0–15 menit | Tagihan pending. Pembeli bisa membayar QRIS-nya. Uang yang masuk dengan nominal tepat melunasi tagihan (paid). |
| Setelah 15 menit | API 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 expired | Nominalnya 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 expired | Isi QRIS dihapus dari gateway. Yang tersisa hanya data ringkas: kode, nominal, status, dan waktu. |
| 30 hari setelah expired | Data 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-Event | payment.paid atau payment.expired |
| X-Webhook-Timestamp | Waktu pengiriman dalam detik Unix. Dibuat ulang di setiap percobaan kirim. |
| X-Webhook-Signature | HMAC-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-Signature | Lama, 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. |
{
"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"
}
}
// 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();
});
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, termasukhttps://danwwwkalau situsmu mengalihkan ke sana. - Alamat
callback_urldicek lagi setiap kali webhook dikirim. Kalau domainnya kini mengarah ke alamat lokal atau privat, webhook tidak dikirim. payment.expireddikirim 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 menjadipaiddanpayment.paiddikirim. Kalau ini terjadi sebelumpayment.expiredterkirim,payment.expireddibatalkan; kalau sesudahnya, kamu menerima keduanya. Jadi anggappaidselalu sebagai status yang benar, juga setelahexpired. - 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, denganpaid_manually: true. - Webhook yang sama bisa sampai lebih dari sekali. Pastikan pemrosesanmu aman kalau dijalankan dua kali (idempoten), misalnya dengan mengecek
reference.
Error & batasan
| Status | Arti |
|---|---|
| 401 | API key kosong atau salah. |
| 403 | Lisensi gateway tidak aktif (license_status berisi alasannya). Tagihan baru tidak bisa dibuat, tapi GET /payments/{reference} tetap bisa dipakai. |
| 404 | Reference tidak ditemukan, atau tagihan expired sudah dihapus setelah 30 hari. |
| 409 | Idempotency-Key sudah dipakai untuk tagihan dengan isi berbeda. Pakai key baru. |
| 422 | Input tidak valid. Detail ada di field errors; header Idempotency-Key yang terlalu panjang muncul sebagai idempotency_key. |
| 503 | Tagihan belum bisa dibuat, misalnya semua kode unik untuk harga itu sedang terpakai. Coba lagi beberapa saat kemudian. |
| 429 | Terlalu 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.
{
"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.
curl https://gobiz.qrismodule.web.id/api/health
{
"status": "failing",
"checks": {
"database": "ok",
"scheduler": "failing",
"gobiz": "ok",
"qris": "ok"
}
}
| database | Database bisa dihubungi. Kalau gagal, cek lainnya dilewati. |
| scheduler | Cron job berjalan dalam 3 menit terakhir. Tanpa cron, tagihan tidak dicocokkan dan webhook tidak dikirim. |
| gobiz | Ada login GoPay Merchant yang tokennya masih berlaku atau bisa diperbarui otomatis. |
| qris | QRIS statis sudah diisi, jadi tagihan baru bisa dibuat. |