MULAI

Terima pembayaran pertama di sandbox

Ikuti satu alur lengkap untuk membuat transaksi, menampilkan QRIS, menyimulasikan pembayaran, dan memastikan order berstatus paid.

10 menit Diperbarui 29 Agustus 2026

ALUR PEMBAYARAN PERTAMAEmpat operasi yang membawa satu order sampai hasil terverifikasi.

Sebelum memulai

Siapkan satu project dalam mode sandbox beserta API key-nya. Kirim semua request dalam quickstart ini dari backend Anda. Jangan pernah menaruh API key di JavaScript browser, aplikasi mobile, atau repository publik.

Project sandbox aktif
API key project tersedia
Server dapat mengirim request HTTPS
Endpoint lokal siap menerima webhook selama pengujian

1. Buat transaksi

Kirim nominal sebelum kode unik. KiPay akan menambahkan unique_code, menghitung biaya, membuat QR payload, dan mengembalikan transaksi berstatus pending. Simpan trx_id untuk menghubungkan transaksi ini dengan order Anda.

create-transaction.sh

cURL

curl --request POST \
  --url https://api.kipay.biz.id/api/pay/apg_your_project_key/transactions \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 285000,
    "note": "order_nusa_2048"
  }'

201-response.json

JSON

{
  "trx_id": "SBX-20260825-VG57V5",
  "mode": "sandbox",
  "requested_amount": 285000,
  "unique_code": 215,
  "amount": 285215,
  "fee_amount": 2925,
  "fee_bearer": "merchant",
  "status": "pending",
  "provider": null,
  "note": "order_nusa_2048",
  "qr_payload": "0002010102122661...",
  "qr_url": "https://api.kipay.biz.id/api/pay/apg_your_project_key/transactions/SBX-20260825-VG57V5/qr.png",
  "matched_at": null,
  "created_at": "2026-08-26 06:35:08",
  "expires_at": "2026-08-26 06:50:08"
}

Simpan trx_id, bukan hanya nominal

trx_id adalah identitas publik transaksi. Gunakan nilai ini saat membaca status, mengambil QR, menjalankan simulasi, dan melakukan rekonsiliasi.

2. Tampilkan QR

Minta gambar PNG 500 x 500 melalui backend Anda, lalu teruskan hasilnya ke checkout. Backend memanggil endpoint KiPay menggunakan API key, sedangkan browser hanya menerima gambar dari route internal Anda.

checkout.html

HTML

<img
  src="/api/checkout/qr/SBX-20260825-VG57V5"
  width="250"
  height="250"
  alt="QRIS untuk order_nusa_2048"
/>

Route internal melindungi credential

Jangan memasukkan API key ke atribut src. Backend mengambil qr.png dari KiPay, lalu meneruskan response image/png tanpa mengekspos credential.

3. Simulasikan pembayaran

Pada sandbox, Anda dapat mengubah transaksi pending menjadi paid tanpa pembayaran nyata. Endpoint simulasi akan menolak project production.

simulate.sh

cURL

curl --request POST \
  --url https://api.kipay.biz.id/api/pay/apg_your_project_key/transactions/SBX-20260825-VG57V5/simulate \
  --header "Content-Type: application/json" \
  --data '{ "provider": "shopeepay" }'

200-response.json

JSON

{
  "trx_id": "SBX-20260825-VG57V5",
  "mode": "sandbox",
  "requested_amount": 285000,
  "unique_code": 215,
  "amount": 285215,
  "fee_amount": 2925,
  "fee_bearer": "merchant",
  "status": "paid",
  "provider": "shopeepay",
  "note": "order_nusa_2048",
  "qr_payload": "0002010102122661...",
  "qr_url": "https://api.kipay.biz.id/api/pay/apg_your_project_key/transactions/SBX-20260825-VG57V5/qr.png",
  "matched_at": "2026-08-26 06:35:14",
  "created_at": "2026-08-26 06:35:08",
  "expires_at": "2026-08-26 06:50:08"
}

4. Konfirmasi status sebelum memenuhi order

Webhook adalah sinyal utama bahwa status telah berubah. Sebelum mengirim barang atau mengaktifkan layanan, baca kembali transaksi dari backend dan pastikan statusnya paid.

Jangan percaya status dari browser

Backend harus memutuskan pemenuhan order berdasarkan webhook dan verifikasi status server-to-server.