DEVELOPER DOCUMENTATION

Integrasikan QRIS dengan beberapa baris kode.

REST API Kianara Gateway pada https://kianarapay.biz.id memungkinkan backend Anda membuat payment order, mengambil status pembayaran, memicu pengecekan mutasi, dan menerima webhook.

Gunakan API hanya dari backend

Jangan memasukkan API key ke JavaScript frontend, aplikasi mobile, repository publik, atau chat.

Autentikasi

Kirim API key melalui header Authorization pada setiap request.

HTTP Header

Authorization: Bearer kg_live_YOUR_API_KEY

Mode	Prefix	Penggunaan
Test	`kg_test_`	Pengembangan dan pengujian
Live	`kg_live_`	Transaksi produksi

POST/api/v1/payments

Buat pembayaran

Membuat QRIS dinamis berdasarkan QRIS statis merchant yang terhubung.

Request

Node.js — contoh lengkap

// Node.js 18+ — simpan sebagai payment.mjs lalu jalankan: node payment.mjs
const BASE_URL = "https://kianarapay.biz.id";
const API_KEY = process.env.KIANARA_API_KEY;

async function request(path, options = {}) {
  const response = await fetch(BASE_URL + path, {
    ...options,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...(options.headers || {}),
    },
  });
  const json = await response.json();
  if (!response.ok) throw new Error(json.error?.message || "Request gagal");
  return json.data;
}

const reference = `INV-${Date.now()}`;
const payment = await request("/api/v1/payments", {
  method: "POST",
  headers: { "Idempotency-Key": reference },
  body: JSON.stringify({
    reference,
    amount: 25000,
    customer_name: "Aditya",
    description: "Pembayaran pesanan",
  }),
});

console.log("Buka checkout:", payment.checkout_url);

const status = await request(
  `/api/v1/payments/${encodeURIComponent(reference)}/check`,
  { method: "POST" },
);
console.log("Status:", status.status);

Lihat contoh cURL

cURL

curl -X POST https://kianarapay.biz.id/api/v1/payments \
  -H 'Authorization: Bearer kg_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-001' \
  -d '{
    "reference": "INV-2026-001",
    "amount": 25000,
    "customer_name": "Aditya"
  }'

Response 201

JSON

{
  "data": {
    "reference": "INV-2026-001",
    "status": "pending",
    "amount": 25000,
    "payment_source": "api",
    "checkout_url": "https://kianarapay.biz.id/pay/INV-2026-001",
    "expires_at": "2026-08-03T14:15:00Z"
  }
}

Parameter

Field	Tipe	Wajib	Keterangan
`reference`	string	Ya	Referensi unik transaksi
`amount`	integer	Ya	Nominal pembayaran dalam rupiah
`customer_name`	string	Tidak	Nama pelanggan
`description`	string	Tidak	Keterangan transaksi

GET/api/v1/payments/:reference

Ambil status pembayaran

Mengambil status terakhir yang tersimpan, termasuk payment_method,payment_source, dan provider_transaction_id saat tersedia. Gunakan endpoint check untuk meminta pencocokan transaksi ke merchant.

POST/api/v1/payments/:reference/check

Memeriksa transaksi terbaru dan mengubah status menjadi paid saat ditemukan mutasi yang sesuai.

Verifikasi webhook

Setiap request webhook menyertakan signature HMAC-SHA256 pada header X-Kianara-Signature. Hitung HMAC dari raw request body menggunakan signing secret Anda, lalu bandingkan secara timing-safe.

Node.js

import crypto from 'node:crypto';

const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(signature)
);

Error codes

HTTP	Code	Arti
401	`unauthorized`	API key atau sesi tidak valid
409	`duplicate_payment`	Reference sudah digunakan
409	`amount_in_use`	Nominal masih dipakai payment pending
422	`validation_error`	Payload request tidak valid
502	`provider_unavailable`	Provider tidak dapat dihubungi
503	`maintenance_active`	Transaksi baru sementara dikunci oleh administrator