Dokumentasi API & Integrasi

1. Pengenalan API

KicenPay REST API adalah gateway pembayaran QRIS berkecepatan tinggi. Setiap panggilan API wajib berformat application/json dan mengembalikan respons berformat JSON terstruktur.

Base Production URL:

https://kicenpay.cloud

2. Autentikasi: Single API Key & X-KicenPay-Signature

KicenPay menggunakan model autentikasi Single API Key yang praktis dan modern. Cukup gunakan API Key merchant Anda dan sertakan header X-KicenPay-Signature untuk validasi integritas data request.

Header HTTP Wajib:

x-api-key: KII_LIVE_882190A45B72C99A Atau gunakan Authorization: Bearer KII_LIVE_882190A45B72C99A

X-KicenPay-Signature: <HMAC_SHA256_HEX> Rumus: HMAC-SHA256(apiKey, JSON.stringify(body))

Content-Type: application/json

3. Rate Limiting & Batasan Request API

Untuk menjaga stabilitas performa sistem gateway, kecepatan verifikasi pembayaran realtime, dan perlindungan dari lonjakan traffic, KicenPay menerapkan sistem Rate Limiting per API Key berbasis algoritma Sliding Window Token Bucket.

Pembuatan QRIS

30 req / menit

Endpoint POST /api/create-qris

Cek Status / Polling

120 req / menit

Endpoint GET /api/status/:trxId

API Umum / Mutasi

60 req / menit

Cancel, Payout & Histori Transaksi

Header HTTP Response Rate Limit:

Setiap respons API dari server KicenPay akan selalu menyertakan header indikator kuota berikut:

X-RateLimit-Limit: 30 Batas total request yang diizinkan dalam periode 60 detik.

X-RateLimit-Remaining: 29 Jumlah kuota request yang masih tersisa sebelum reset.

X-RateLimit-Reset: 1789658259 Timestamp UNIX (detik) saat kuota Anda kembali penuh.

Retry-After: 18 Hanya muncul saat status 429 Too Many Requests. Menunjukkan detik wajib menunggu sebelum retry.

POST /api/create-qris

Buat Tagihan QRIS

Membuat tagihan transaksi baru lengkap dengan kode QRIS standar nasional Bank Indonesia, tautan pembayaran langsung, dan notifikasi callback otomatis.

Parameter Request (JSON Body):

Field	Tipe	Wajib	Keterangan
amount	number	Ya	Nominal pembayaran Rupiah yang masuk ke saldo merchant (minimal 1000).
refId	string	Opsional	ID invoice unik sistem Anda (misal: INV-2026-001). Otomatis berlaku sebagai pencegah transaksi ganda (Idempotent).
idempotencyKey	string	Opsional	Kunci idempotensi unik untuk menjamin request berulang tidak membuat transaksi ganda. Bisa juga dikirim via Header `Idempotency-Key`.
customerName	string	Opsional	Nama pelanggan atau pembeli.
webhookUrl	string	Opsional	URL webhook untuk menerima konfirmasi bayar instan.

Contoh Request & Respons JSON:

Request Body (JSON):

{
  "amount": 50000,
  "refId": "ORDER-9912",
  "idempotencyKey": "IDEMP-9912-A1",
  "customerName": "Kiki Faizal",
  "webhookUrl": "https://websiteanda.com/webhook"
}

Response (JSON):

{
  "success": true,
  "trxId": "KII-M891-A42F",
  "refId": "ORDER-9912",
  "idempotencyKey": "IDEMP-9912-A1",
  "amount": 50000,
  "totalAmount": 50000,
  "status": "PENDING",
  "paymentUrl": "https://kicenpay.cloud/pay/KII-M891-A42F",
  "qrisString": "0002010102122659...",
  "qrImage": "data:image/png;base64,...",
  "expiredAt": "2026-09-16T18:00:00.000Z"
}

amount: Nominal tagihan yang 100% masuk ke saldo merchant (tanpa potongan biaya).

totalAmount: Total pembayaran yang harus ditransfer oleh pembeli via scan QRIS.

GET /api/status/:trxId

Cek Status Pembayaran

Gunakan endpoint ini untuk mengecek status mutasi pembayaran QRIS secara real-time berdasarkan trxId.

Response JSON:

{
  "success": true,
  "trxId": "KII-M891-A42F",
  "refId": "ORDER-9912",
  "amount": 50000,
  "totalAmount": 50000,
  "status": "SUCCESS",
  "paidAt": "2026-09-15T17:35:12.000Z",
  "isSettled": 0,
  "settleAt": "2026-09-16T17:35:12.000Z",
  "settlementPolicy": "H+1 (Otomatis 24 Jam)"
}

POST /api/cancel

Batalkan Tagihan QRIS

Membatalkan tagihan transaksi QRIS yang masih berstatus PENDING jika pembeli membatalkan pesanan.

Request Body (JSON):

{
  "trxId": "KII-M891-A42F",
  "reason": "Dibatalkan oleh pembeli"
}

GET /api/transactions

Riwayat Transaksi Merchant

Mengambil daftar riwayat transaksi merchant Anda dengan filter status, limit, dan offset.

Response JSON:

{
  "success": true,
  "data": [
    {
      "trxId": "KII-M891-A42F",
      "refId": "ORDER-9912",
      "amount": 50000,
      "totalAmount": 50000,
      "status": "SUCCESS",
      "createdAt": "2026-09-15T17:30:00.000Z",
      "paidAt": "2026-09-15T17:35:12.000Z"
    }
  ]
}

6. Format Notifikasi Webhook & X-KicenPay-Signature

Ketika pelanggan selesai membayar QRIS, server KicenPay akan mengirimkan HTTP POST secara instan ke webhookUrl Anda dengan header X-KicenPay-Signature.

Webhook Payload (Event: payment.success):

{
  "event": "payment.success",
  "data": {
    "trxId": "KII-M891-A42F",
    "refId": "ORDER-9912",
    "amount": 50000,
    "totalAmount": 50000,
    "status": "SUCCESS",
    "paymentMethod": "QRIS",
    "paidAt": "2026-09-15T17:35:12.000Z",
    "isSettled": 0,
    "settleAt": "2026-09-16T17:35:12.000Z"
  }
}

7. Contoh Integrasi Multi-Bahasa

cURL (CLI)

curl -X POST https://kicenpay.cloud/api/create-qris \
  -H "Content-Type: application/json" \
  -H "x-api-key: KII_LIVE_882190A45B72C99A" \
  -H "X-KicenPay-Signature: 8f9b4c2e..." \
  -d '{
    "amount": 50000,
    "refId": "INV-001",
    "customerName": "Kiki Faizal",
    "webhookUrl": "https://serveranda.com/webhook"
  }'

Node.js (JavaScript / Axios & Crypto)

const axios = require('axios');
const crypto = require('crypto');

const API_KEY = 'KII_LIVE_882190A45B72C99A';
const payload = {
  amount: 50000,
  refId: 'INV-NODE-001',
  customerName: 'Kiki Faizal',
  webhookUrl: 'https://serveranda.com/webhook'
};

// Generate X-KicenPay-Signature
const signature = crypto
  .createHmac('sha256', API_KEY)
  .update(JSON.stringify(payload))
  .digest('hex');

async function createQris() {
  const res = await axios.post('https://kicenpay.cloud/api/create-qris', payload, {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
      'X-KicenPay-Signature': signature
    }
  });

  console.log('QRIS Checkout URL:', res.data.paymentUrl);
}

createQris();

Python 3 (Requests & HMAC)

import requests
import json
import hmac
import hashlib

API_KEY = "KII_LIVE_882190A45B72C99A"
url = "https://kicenpay.cloud/api/create-qris"

payload = {
    "amount": 50000,
    "refId": "INV-PY-001",
    "customerName": "Kiki Faizal",
    "webhookUrl": "https://serveranda.com/webhook"
}

body_json = json.dumps(payload, separators=(',', ':'))

# Generate X-KicenPay-Signature
signature = hmac.new(
    API_KEY.encode('utf-8'),
    body_json.encode('utf-8'),
    hashlib.sha256
).hexdigest()

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
    "X-KicenPay-Signature": signature
}

response = requests.post(url, data=body_json, headers=headers)
print(response.json())

PHP Native (cURL & hash_hmac)

<?php
$apiKey = 'KII_LIVE_882190A45B72C99A';
$payload = [
    'amount' => 50000,
    'refId' => 'INV-PHP-001',
    'customerName' => 'Kiki Faizal',
    'webhookUrl' => 'https://serveranda.com/webhook'
];

$bodyJson = json_encode($payload);

// Generate X-KicenPay-Signature
$signature = hash_hmac('sha256', $bodyJson, $apiKey);

$ch = curl_init('https://kicenpay.cloud/api/create-qris');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $bodyJson);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: ' . $apiKey,
    'X-KicenPay-Signature: ' . $signature
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Payment URL: " . $result['paymentUrl'];
?>

8. Kode Respon HTTP & Format Error

Standard REST Responses

API KicenPay mengembalikan kode status HTTP standar untuk mengindikasikan apakah permintaan berhasil (valid) atau mengalami kendala. Setiap respons selalu mengembalikan objek JSON dengan properti boolean success beserta keterangan lengkap.

200 OK Valid / Berhasil

Permintaan valid dan berhasil diproses. Objek QRIS, status transaksi, atau token verifikasi dikembalikan lengkap.

{
  "success": true,
  "trxId": "KII-MU2YS16D-Q0EW",
  "status": "PENDING",
  "amount": 50000,
  "paymentUrl": "https://..."
}

400 Bad Request Parameter Salah / Kurang

Payload JSON rusak, parameter wajib seperti amount tidak ada, atau nominal di bawah batas minimum (Rp 1.000).

{
  "success": false,
  "message": "Nominal pembayaran minimal Rp 1.000 cuy!"
}

401 Unauthorized Autentikasi Gagal

API Key tidak ditemukan/salah di header, atau header X-KicenPay-Signature tidak cocok dengan HMAC payload body.

{
  "success": false,
  "message": "X-KicenPay-Signature tidak valid. Request ditolak demi keamanan!"
}

403 Forbidden Akses Diblokir

Akun merchant sedang SUSPENDED, atau tindakan dilarang oleh sistem keamanan.

{
  "success": false,
  "message": "Akun merchant Anda dinonaktifkan sementara. Hubungi admin KicenPay."
}

404 Not Found Data Tidak Ditemukan

ID transaksi (trxId) atau payment link tidak ditemukan dalam database.

{
  "success": false,
  "message": "Transaksi tidak ditemukan!"
}

429 Too Many Requests Rate Limit Terlampaui

Frekuensi request melebihi batas kuota per menit untuk API Key Anda. Header Retry-After menunjukkan detik tunggu sebelum request berikutnya dapat diterima.

{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit terlampaui untuk pembuatan QRIS! Maksimal 30 invoice per menit per API Key.",
  "limit": 30,
  "remaining": 0,
  "retryAfter": 18
}

500 Server Error Gangguan Server

Terjadi kesalahan internal pada pemrosesan server atau database.

{
  "success": false,
  "message": "Terjadi kesalahan internal server. Silakan coba beberapa saat lagi."
}

10. Aturan Layanan & Ketentuan Transaksi

Ketentuan resmi operasional, kebijakan dana, dan batasan penggunaan KicenPay.

10.1 Batas Transaksi & Bebas Biaya

Nominal Minimum QRIS: Rp 1.000 per transaksi tagihan.
Nominal Maksimum QRIS: Rp 10.000.000 per transaksi (sesuai regulasi Bank Indonesia untuk merchant per QRIS).
Bebas Biaya Transaksi: 100% bebas biaya transaksi QRIS. Seluruh dana penjualan masuk utuh ke saldo merchant tanpa potongan per transaksi.

10.2 Kebijakan Settlement H+1 (24 Jam)

Saldo Tertunda: Dana transaksi sukses langsung tercatat di Saldo Tertunda (Pending Settlement) merchant masing-masing.
Otomatis Cair ke Saldo Tersedia: Setelah masa kliring 24 jam tepat (H+1), sistem secara otomatis memindahkan dana ke Saldo Tersedia yang siap ditarik (WD).
Alasan Keamanan: Sesuai standar industri kliring dan perbankan nasional guna mencegah penipuan, sengketa transaksi, serta menjaga keamanan saldo merchant.

10.3 Larangan Keras & Kebijakan Nol-Toleransi (Acceptable Use Policy)

KicenPay tunduk pada hukum perundang-undangan Republik Indonesia dan regulasi Bank Indonesia. Layanan gateway pembayaran KicenPay DILARANG KERAS digunakan untuk transaksi yang terkait:

Judi Online (Judol), Slot, Kasino, Togel & Taruhan

Narkotika, Psikotropika & Zat Adiktif Terlarang

Penipuan, Phishing, Scam, Carding & Skema Ponzi

Pencucian Uang (Money Laundering) & Terorisme

Sanksi Pelanggaran: Akun merchant akan langsung diblokir permanen (BANNED/SUSPENDED), saldo dibekukan untuk penyelidikan, dan bukti log transaksi akan diserahkan kepada pihak penegak hukum dan PPATK.

10.4 Ketentuan Penarikan Saldo (Withdrawal / Payout)

Batas Minimal WD

Rp 10.000

Minimal dana pada Saldo Tersedia yang dapat diajukan penarikan.

Proteksi Payout

Rekening Terverifikasi

Pencairan instan langsung ke rekening atau e-wallet terdaftar milik pemilik akun.

Metode Rekening

Bank & E-Wallet Lengkap

Dukungan BCA, Mandiri, BRI, BNI, Seabank, Bank Jago, DANA, GoPay, OVO, LinkAja.

11. Standar Kenyamanan & Keamanan Developer (DX)

Panduan arsitektur sistem pembayaran, perlindungan transaksi, dan integrasi yang mudah.

11.1 Idempotency Key (Bebas Double Charge)

Gunakan header Idempotency-Key atau body parameter idempotencyKey pada setiap pemanggilan API pembuatan QRIS.

Idempotency-Key: ORDER-INV-202609-001

Jika bot atau server Anda mengalami timeout jaringan dan mengirimkan request ulang, gateway KicenPay mengembalikan objek transaksi yang sama persis tanpa membuat tagihan dobel atau menduplikasi saldo.

11.2 Webhook Signature & Auto-Retry 3x

KicenPay mengirimkan header X-KicenPay-Signature (HMAC-SHA256) pada setiap callback. Validasi signature ini di server Anda sebelum memperbarui status pesanan.

Percobaan 1: Langsung saat mutasi cocok (0ms).
Percobaan 2: Otomatis retry +5 detik jika server Anda offline/500.
Percobaan 3: Retry terakhir +15 detik dengan log audit lengkap.

11.3 Keamanan Kunci Rahasia (Secret Key)

Jangan pernah mempublikasikan atau menyematkan API Key pada frontend JavaScript (browser), aplikasi mobile React Native, Flutter, atau repositori publik GitHub.

Selalu gunakan arsitektur Server-to-Server di mana backend Anda yang berkomunikasi dengan API KicenPay. Gunakan tombol rotasi kunci instan di dashboard jika mencurigai adanya kebocoran.

11.4 SLA 99.9% & Pemantauan Status Real-time

KicenPay dirancang dengan target uptime 99.9% dan proses verifikasi pembayaran instan. Anda dapat memeriksa status operasional infrastruktur sistem, database, dan layanan API kami secara berkala di halaman Status Server.

Sistem Beroperasi Normal

Dokumentasi API