PANDUAN

Buat transaksi yang tetap terhubung dengan order Anda

Kirim nominal dan referensi order, simpan identitas publik transaksi, lalu gunakan response KiPay sebagai sumber data checkout.

7 menit Diperbarui 29 Agustus 2026

FIELD LINEAGEDari input order ke data transaksi yang harus disimpan.

Endpoint

POST/api/pay/{apiKey}/transactions

Endpoint ini membuat transaksi baru untuk project pemilik API key. Mode transaksi mengikuti mode project ketika request diterima.

Request

Field	Tipe	Wajib	Keterangan
amount	integer	Ya	Nominal sebelum unique_code
note	string atau null	Tidak	Referensi order atau pembeli

request.json

JSON

{
  "amount": 285000,
  "note": "order_nusa_2048"
}

Response

Gunakan trx_id untuk semua operasi berikutnya. Field amount berisi jumlah final yang harus dibayar pelanggan setelah unique_code ditambahkan. Field qr_url siap dipakai langsung sebagai src gambar, atau pakai qr_payload kalau ingin me-render QR sendiri — lihat panduan "Tampilkan QR".

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 relasi dengan order

order-mapping.ts

TypeScript

await orders.update(orderId, {
  kipayTransactionId: response.trx_id,
  paymentStatus: response.status,
  payableAmount: response.amount,
  paymentExpiresAt: response.expires_at
});

Gunakan note sebagai referensi, bukan primary key

trx_id tetap menjadi identitas transaksi KiPay. Simpan relasi eksplisit antara trx_id dan order internal Anda.

Error yang perlu ditangani

HTTP	Kondisi	Tindakan aplikasi
400	amount tidak valid atau QRIS belum diatur	Perbaiki input atau konfigurasi project
404	API key tidak ditemukan	Hentikan request dan periksa project
409	unique_code tidak dapat dibuat	Kirim request baru dengan batas retry yang jelas