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://shopee.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 akun ShopeePay. 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. Uang yang dibayar sebelum batas waktu tapi baru dilaporkan ShopeePay belakangan masih bisa membuatnya paid. 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, atau 200 OK kalau request yang sama diulang dengan Idempotency-Key yang sama.

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 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_urlURL http/https, opsionalHalaman 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}.
HeaderKeterangan
Idempotency-KeyOpsional, 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.
Contoh request (curl)
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"}'
Contoh request (PHP / Laravel)
$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.

Contoh request
curl https://shopee.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": "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"
  }
}
referenceID tagihan di gateway, dipakai di URL.
statuspending (menunggu bayar), paid (lunas), atau expired (waktu habis).
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_urlAlamat kembali ke toko yang dikirim saat membuat tagihan, atau null.
paid_atWaktu transaksi di ShopeePay, terisi saat lunas. Untuk tagihan yang ditandai lunas manual: waktu admin menandainya.
provider_transaction_idID transaksi ShopeePay yang melunasi tagihan ini.
paid_manuallytrue 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.

WaktuYang terjadi
0–15 menitTagihan pending. Pembeli bisa membayar QRIS-nya. Uang yang masuk dengan nominal tepat melunasi tagihan (paid).
Setelah 15 menitTagihan 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 expiredNominalnya 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 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 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-Eventpayment.paid atau payment.expired
X-Webhook-TimestampWaktu pengiriman dalam detik Unix. Tolak webhook yang lebih tua dari 300 detik supaya webhook lama tidak bisa dikirim ulang oleh orang lain.
X-Webhook-SignatureHMAC-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-SignatureCara 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.
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",
    "provider_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 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();
});
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 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.expired dikirim 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.expired dibatalkan dan hanya payment.paid yang dikirim. Dalam kasus yang sangat jarang, payment.paid tetap bisa datang setelah payment.expired. Ini hanya terjadi kalau uangnya masuk sebelum batas waktu, jadi anggap paid sebagai status yang benar.
  • Tagihan yang ditandai lunas manual oleh admin juga mengirim payment.paid, dengan paid_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.

Contoh
GET https://shopee.qrismodule.web.id/api/health

{
  "status": "ok",
  "checks": { "database": "ok", "scheduler": "ok", "shopeepay": "ok", "qris": "ok" }
}

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 untuk tagihan baru.
422Input tidak valid, termasuk Idempotency-Key yang lebih dari 255 karakter. Detail ada di field errors.
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 perlu TRUSTED_PROXIES di .env (mis. TRUSTED_PROXIES=cloudflare); tanpa itu semua pengunjung terlihat memakai IP proxy dan berbagi satu batas.
Contoh 422
{
  "message": "The amount field is required.",
  "errors": {
    "amount": ["The amount field is required."]
  }
}