Dokumentasi API & Integrasi - KicenPay Payment Gateway

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

POST /api/create

Generate QRIS Dinamis

Membuat tagihan transaksi baru lengkap dengan gambar QRIS dinamis, string QRIS EMVCo standar Bank Indonesia, tautan pembayaran, dan callback otomatis.

Parameter Request (JSON Body):

Field	Tipe	Wajib	Keterangan
amount	number	Ya	Nominal pembayaran Rupiah (minimal 1000).
refId	string	Opsional	ID invoice unik sistem Anda (misal: INV-2026-001).
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",
  "customerName": "Kiki Faizal",
  "webhookUrl": "https://websiteanda.com/api/webhook"
}

Response (JSON):

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

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,
  "fee": 500,
  "totalAmount": 50500,
  "status": "SUCCESS",
  "paidAt": "2026-09-15T17:35:12.000Z"
}

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"
}

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,
    "fee": 500,
    "totalAmount": 50500,
    "status": "SUCCESS",
    "paymentMethod": "QRIS",
    "paidAt": "2026-09-15T17:35:12.000Z"
  }
}

7. Contoh Integrasi Multi-Bahasa

cURL (CLI)

curl -X POST https://kicenpay.cloud/api/create \
  -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', 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"

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');
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!"
}

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."
}

Panduan Integrasi KicenPay API