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://shopee.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 akun ShopeePay. 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. Uang yang dibayar sebelum batas waktu tapi baru dilaporkan ShopeePay belakangan masih bisa membuatnyapaid. 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, atau 200 OK kalau request yang sama diulang dengan Idempotency-Key yang sama.
| 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 alamat internet publik; alamat lokal atau jaringan privat (mis. 127.0.0.1, 10.x.x.x, 100.64.x.x) ditolak, dan redirect tidak diikuti. |
| return_url | URL http/https, opsional | Halaman toko kamu untuk pembeli setelah bayar (maks. 2048 karakter). Halaman checkout_url menampilkan tombol Kembali ke toko dan mengalihkan pembeli ke sini 3 detik setelah lunas; halaman kedaluwarsa juga menampilkan tombolnya. Jangan anggap pesanan lunas hanya karena pembeli kembali; pakai webhook atau GET /payments/{reference}. |
| Header | Keterangan |
|---|---|
| Idempotency-Key | Opsional, maks. 255 karakter, mis. ID pesanan. Kalau request diulang (timeout, koneksi putus) dengan key dan isi yang sama (amount, external_id, callback_url, return_url), gateway mengembalikan tagihan yang sudah dibuat (200 OK) alih-alih membuat tagihan kedua. Key yang sama dengan isi berbeda ditolak dengan 409. |
curl -X POST https://shopee.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'),
// Aman dicoba ulang: request kedua dengan key ini mendapat tagihan yang sama.
'Idempotency-Key' => 'order-'.$order->id,
])
->acceptJson()
->post('https://shopee.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 ShopeePay dulu sebelum menjawab. Kalau kamu sudah memakai webhook, endpoint ini cukup dipakai sesekali untuk memastikan.
curl https://shopee.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": "00020101021226...6304A1B2",
"checkout_url": "https://domain-gateway-kamu.com/pay/PAY-BP6VXQTJNSE6",
"return_url": "https://toko-kamu.com/pesanan/1001",
"expires_at": "2026-10-16T19:59:31+07:00",
"paid_at": null,
"provider_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). |
| 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 | Alamat kembali ke toko yang dikirim saat membuat tagihan, atau null. |
| paid_at | Waktu transaksi di ShopeePay, terisi saat lunas. Untuk tagihan yang ditandai lunas manual: waktu admin menandainya. |
| provider_transaction_id | ID transaksi ShopeePay yang melunasi tagihan ini. |
| paid_manually | true kalau admin menandai tagihan ini lunas dari panel admin, mis. karena uangnya masuk tapi tidak terdeteksi otomatis. provider_transaction_id bisa kosong. |
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 | Tagihan expired: uang yang dibayar setelah batas waktu tidak melunasinya. checkout_url dialihkan ke halaman informasi kedaluwarsa yang meminta pembeli membuat pembayaran baru, dan API tidak lagi mengirim qris_string. Uang yang dibayar sebelum batas waktu tapi baru dilaporkan ShopeePay belakangan tetap melunasinya, jadi tagihan expired bisa berubah menjadi paid (jarang terjadi, lihat Webhook). |
| Sampai 2 jam setelah expired | Nominalnya tetap dipesan dan tidak diberikan ke tagihan baru. Kalau ada uang yang dibayar setelah batas waktu dengan nominal itu, uang tersebut 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 merchant ShopeePay.
Gateway tidak akan menganggapnya sebagai pelunasan. Uang itu dicatat sebagai pembayaran telat dan bisa dilihat pemilik gateway dengan php artisan payments:late, lalu direfund.
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. Tolak webhook yang lebih tua dari 300 detik supaya webhook lama tidak bisa dikirim ulang oleh orang lain. |
| X-Webhook-Signature | HMAC-SHA256 dari {X-Webhook-Timestamp}.{raw body} dengan webhook secret sebagai kunci, dalam hex. Webhook secret ada di panel admin, menu Pengaturan, dan hanya bisa dipakai untuk memverifikasi webhook, tidak untuk memanggil API. |
| X-Signature | Cara lama, tetap dikirim untuk integrasi yang sudah ada: HMAC-SHA256 dari raw body dengan API key sebagai kunci. Tidak melindungi dari webhook yang dikirim ulang, jadi pindahlah ke X-Webhook-Signature. |
{
"event": "payment.paid",
"data": {
"reference": "PAY-BP6VXQTJNSE6",
"external_id": "ORDER-1001",
"status": "paid",
"amount": 25784,
"paid_at": "2026-10-16T19:47:02+07:00",
"provider_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 tidak bisa dikirim ulang oleh orang lain.
abort_if(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 tidak bisa dikirim ulang oleh orang lain.
if (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, jadi pakai alamat akhir sebagai
callback_url. payment.expireddikirim sekitar 2 menit setelah batas waktu, dan baru setelah gateway berhasil membaca transaksi ShopeePay melewati batas waktu itu, karena ShopeePay kadang baru melaporkan transaksi beberapa saat kemudian. Kalau uang yang dibayar sebelum batas waktu ternyata masuk sebelum webhook itu terkirim,payment.expireddibatalkan dan hanyapayment.paidyang dikirim. Dalam kasus yang sangat jarang,payment.paidtetap bisa datang setelahpayment.expired. Ini hanya terjadi kalau uangnya masuk sebelum batas waktu, jadi anggappaidsebagai status yang benar.- Tagihan yang ditandai lunas manual oleh admin juga mengirim
payment.paid, denganpaid_manually: true. - Uang yang masuk setelah batas waktu tidak pernah memicu
payment.paid. Lihat Masa berlaku & data. - Webhook yang sama bisa sampai lebih dari sekali. Pastikan pemrosesanmu aman kalau dijalankan dua kali (idempoten), misalnya dengan mengecek
reference.
GET /api/health
Tidak butuh API key dan cocok untuk uptime monitor (UptimeRobot, BetterStack, dll.). Jawabannya 200 kalau semua beres, atau 503 kalau database tidak bisa dihubungi, cron tidak berjalan, token ShopeePay belum ada atau ditolak, atau QRIS statis belum diisi, yaitu kondisi yang membuat pembayaran tidak terdeteksi atau tagihan tidak bisa dibuat.
GET https://shopee.qrismodule.web.id/api/health
{
"status": "ok",
"checks": { "database": "ok", "scheduler": "ok", "shopeepay": "ok", "qris": "ok" }
}
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 untuk tagihan baru. |
| 422 | Input tidak valid, termasuk Idempotency-Key yang lebih dari 255 karakter. Detail ada di field errors. |
| 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 perlu TRUSTED_PROXIES di .env (mis. TRUSTED_PROXIES=cloudflare); tanpa itu semua pengunjung terlihat memakai IP proxy dan berbagi satu batas. |
{
"message": "The amount field is required.",
"errors": {
"amount": ["The amount field is required."]
}
}