Dokumentasi API v2

Diperbarui 12 Sep 2026. Halaman ini sengaja dibuat pendek. Kalau ada bagian yang belum jelas, itu kekurangan kami, bukan kekurangan Anda.

A. Persiapan

Daftar atau masuk, lalu buat Proyek. Proyek adalah identitas aplikasi/website Anda — dengan satu akun Anda bisa mengintegrasikan banyak aplikasi.

Catat tiga hal dari halaman proyek Anda:

• API Key — ditampilkan sekali saja, simpan di tempat aman
• Webhook Secret — untuk memverifikasi notifikasi yang kami kirim
• slug proyek — dipakai bila Anda memakai integrasi lewat URL

Penting: API Key terikat pada satu proyek. Tagihan tidak akan pernah masuk ke proyek lain, dan mencabut key satu proyek tidak mempengaruhi proyek lain.

B. Integrasi via URL (tanpa kode)

Arahkan pelanggan ke halaman pembayaran:

https://app.invoiceku.net/pay/{slug}/{amount}?order_id={order_id}

https://app.invoiceku.net/pay/depodomain/22000?order_id=BAYAR-97dasa7d

B.1 Opsi: kembali ke halaman Anda

Setelah pembayaran berhasil, tambahkan tujuan tombol kembali:

&redirect=https://situsanda.com/tujuan

B.2 Opsi: hanya QRIS

Pembeli langsung melihat QR dan tidak bisa memilih metode lain:

&qris_only=1

C. Integrasi via API

C.1 Otentikasi

Sertakan API Key di header Authorization dengan skema Bearer. Jangan menaruh key di body atau query string — keduanya mudah tersimpan di log.

Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

C.2 Buat tagihan

POST /api/v2/charges
Content-Type: application/json
Authorization: Bearer ik_live_...
Idempotency-Key: 9f2b1c7e-...      (opsional, sangat disarankan)

{
  "amount": 25000,
  "order_id": "BAYAR-97dasa7d"
}

Hanya amount yang wajib. Tidak perlu nama atau email pembeli. Tidak ada project_slug — proyek sudah ditentukan oleh API Key.

Contoh:

curl -X POST https://app.invoiceku.net/api/v2/charges \
  -H "Authorization: Bearer ik_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount":25000,"order_id":"BAYAR-97dasa7d"}'

Respons (HTTP 201):

{
  "status": "success",
  "data": {
    "id": "INV-7698-YU98",
    "order_id": "BAYAR-97dasa7d",
    "amount": 25000,
    "fee": 375,
    "total_payment": 25375,
    "status": "pending",
    "is_paid": false,
    "payment_method": "qris",
    "qris_string": "00020101021226...",
    "qr_url": "https://api.qrserver.com/v1/create-qr-code/?...",
    "payment_url": "https://app.invoiceku.net/pay/INV-7698-YU98",
    "expires_at": "2026-09-12 21:15:00"
  }
}

Simpan id dan order_id. id adalah kunci dari kami, order_id adalah kunci dari Anda.

C.3 Menampilkan QR

• Ubah qris_string menjadi gambar QR memakai library apa pun di sisi Anda, atau
• tampilkan langsung qr_url, atau
• arahkan pembeli ke payment_url.

C.4 Cek status

GET /api/v2/charges/INV-7698-YU98
Authorization: Bearer ik_live_...

Bisa juga dicari memakai order_id Anda. Pengecekan selalu dibatasi pada proyek pemilik key — key proyek lain akan menerima 404.

C.5 Batalkan tagihan

POST /api/v2/charges/INV-7698-YU98/cancel
Authorization: Bearer ik_live_...

Hanya tagihan berstatus pending yang bisa dibatalkan.

C.6 Uji coba (sandbox)

Key berawalan ik_test_ boleh memakai endpoint simulasi. Simulasi menandai tagihan lunas tanpa mengubah saldo dan tanpa mengirim webhook.

POST /api/v2/simulate
{ "id": "INV-7698-YU98" }

C.7 Idempotency-Key

Kirim header Idempotency-Key berisi UUID unik per order. Kalau jaringan terputus dan Anda mengirim ulang permintaan yang sama, kami mengembalikan tagihan yang sama — bukan membuat QRIS kedua.

D. Webhook

Isi Webhook URL di pengaturan proyek. Kami mengirim POST saat dana masuk.

Header:
X-InvoiceKu-Signature: t=1789123456,v1=9a8b7c6d...

Body:
{
  "event": "charge.paid",
  "id": "INV-7698-YU98",
  "order_id": "BAYAR-97dasa7d",
  "amount": 25000,
  "fee": 375,
  "net_amount": 25000,
  "status": "paid",
  "payment_method": "qris",
  "paid_at": "2026-09-12T20:15:00+07:00"
}

Verifikasi tanda tangan sebelum memproses (PHP):

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_INVOICEKU_SIGNATURE'] ?? '';
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $header, $m);
$t = (int)($m[1] ?? 0); $v1 = $m[2] ?? '';
if (abs(time() - $t) > 300) { http_response_code(400); exit('stale'); }
$expect = hash_hmac('sha256', $t . '.' . $raw, $WEBHOOK_SECRET);
if (!hash_equals($expect, $v1)) { http_response_code(401); exit('bad signature'); }

Node.js:

const crypto = require('crypto');
const [tPart, vPart] = (req.headers['x-invoiceku-signature'] || '').split(',');
const t = tPart.replace('t=', '');
const expect = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`).digest('hex');
if (expect !== vPart.replace('v1=', '')) return res.status(401).end();

Balas HTTP 200. Kalau gagal, kami mengirim ulang dengan jeda bertambah. Webhook hanyalah pemicu — sumber kebenaran tetap C.4. Cocokkan amount dan order_id dengan catatan Anda.

E. Kode error

503 berarti tidak ada tagihan yang dibuat. Silakan ulangi permintaan. Kami tidak pernah membuat tagihan dengan QR lama atau QR contoh.

Pertanyaan: detail support ada di dashboard. Sertakan id tagihan agar pengecekan cepat.