Dokumentasi API

v1.0 REST

Integrasikan pembayaran Factqris Gateway / Cloud Pay ke website atau bot Anda.

Factqris Gateway menyediakan REST API sederhana berbasis HTTP GET & POST dengan autentikasi API key. Semua endpoint merespon dalam format application/json — cocok untuk diintegrasikan ke website, bot WhatsApp/Telegram, atau aplikasi apa pun. Buat invoice, tampilkan QRIS kepada pelanggan Anda, dan saldo otomatis masuk ke akun Anda setelah pembayaran lunas.

API Key Anda

Masuk atau daftar untuk melihat API key pribadi Anda di halaman Dashboard → Integrasi & API. Setiap akun mendapatkan API key yang berbeda dan dibuat otomatis satu kali.

Lihat API Key Saya Format key: csk_live_...

Autentikasi

Gunakan header Authorization: Bearer <API_KEY> atau X-License-Key (Direkomendasikan agar API key tidak tercatat pada URL access log/proxy). Untuk kompatibilitas bot/script sederhana, parameter query apikey tetap didukung melalui HTTPS. API key bersifat rahasia — jangan pernah menaruhnya di kode frontend publik (HTML/JavaScript browser).

Base URL:https://app.cloudnet.web.id

Daftar Endpoint API

4 REST Endpoints

1. Cek Saldo

GET/api/public/invoices?action=balance

Mengembalikan saldo terkini akun Factqris / Cloud Pay Anda dalam format JSON. Gunakan untuk memantau saldo secara real-time dari sistem Anda sendiri.

Contoh Request

curl -X GET 'https://app.cloudnet.web.id/api/public/invoices?action=balance&apikey=YOUR_API_KEY'

Contoh Response (HTTP 200 OK)

{
  "balance": 150000
}

2. Membuat Deposit (Invoice QRIS)

GETPOST/api/public/invoices

Membuat invoice deposit QRIS baru. Parameter amount adalah nominal deposit (bilangan bulat Rupiah, Rp 1.000 – Rp 2.000.000). Setelah pelanggan Anda membayar QRIS, saldo otomatis masuk ke akun Anda.

Contoh Request

curl -X GET 'https://app.cloudnet.web.id/api/public/invoices?apikey=YOUR_API_KEY&amount=50000'

Contoh Response (HTTP 200 / 201)

{
  "success": true,
  "invoice_id": "INV64c8d9e",
  "amount": 50000,
  "fee": 482,
  "total": 50482,
  "qris_image": "https://app.cloudnet.web.id/pay/INV64c8d9e",
  "pay_url": "https://app.cloudnet.web.id/pay/INV64c8d9e",
  "expired_at": "2026-09-24T20:35:00+07:00"
}

3. Cek Status Deposit

GET/api/public/invoices?invoice_id=...

Mengecek status pembayaran sebuah invoice. Parameter invoice_id diambil dari response saat membuat deposit. Nilai status: pending, paid, expired, atau failed. Disarankan polling setiap 5–10 detik hingga status berubah.

Contoh Request

curl -X GET 'https://app.cloudnet.web.id/api/public/invoices?apikey=YOUR_API_KEY&invoice_id=YOUR_INVOICE_ID'

Contoh Response (Status: Paid)

{
  "invoice_id": "INV64c8d9e",
  "amount": 50000,
  "fee": 482,
  "total": 50482,
  "status": "paid",
  "paid_via": "BCA QRIS",
  "qris_image": "https://app.cloudnet.web.id/pay/INV64c8d9e",
  "expired_at": "2026-09-24T20:35:00+07:00",
  "created_at": "2026-09-24T20:30:00+07:00"
}

4. Batalkan Deposit (Batal QRIS)

GET/api/public/invoices?action=cancel&invoice_id=...

Membatalkan invoice deposit QRIS yang belum dibayar (status masih pending). Jika pelanggan batal bertransaksi, panggil endpoint ini. Invoice yang berhasil dibatalkan otomatis tidak dapat dibayar lagi dan statusnya berubah menjadi cancelled.

Contoh Request

curl -X GET 'https://app.cloudnet.web.id/api/public/invoices?action=cancel&apikey=YOUR_API_KEY&invoice_id=YOUR_INVOICE_ID'

Contoh Response (HTTP 200 OK)

{
  "success": true,
  "message": "Invoice berhasil dibatalkan.",
  "invoice_id": "INV64c8d9e",
  "status": "cancelled"
}

Parameter Endpoint

Ringkasan parameter query pada seluruh endpoint

Endpoint	Parameter	Keterangan
/api/balance	apikey	API key akun Anda (wajib)
/api/invoice	apikey	API key akun Anda (wajib)
/api/invoice	amount	Nominal deposit dalam Rupiah, bilangan bulat 1.000 – 2.000.000 (wajib)
/api/invoice/status	apikey	API key akun Anda (wajib)
/api/invoice/status	invoice_id	ID invoice dari response membuat deposit (wajib)
/api/invoice/cancel	apikey	API key akun Anda (wajib)
/api/invoice/cancel	invoice_id	ID invoice yang ingin dibatalkan (wajib)
/api/invoice/cancel	action	Nilai `cancel` atau `batal` untuk membatalkan invoice (wajib jika via /api/public/invoices)

Format Error

Kesalahan dikembalikan sebagai JSON dengan field error beserta kode HTTP yang sesuai (401 API key salah, 403 akun diblokir, 404 invoice tidak ditemukan, 429 terlalu banyak permintaan).

{
  "error": "API key tidak valid."
}

401API key salah / tidak valid

403Akun diblokir / terlarang

404Invoice tidak ditemukan

429Terlalu banyak permintaan

Catatan Penting

Invoice QRIS berlaku 5 menit sejak dibuat. Jika tidak dibayar dalam batas waktu, status otomatis berubah menjadi expired — buat invoice baru.
Tampilkan qris_image sebagai gambar QR kepada pelanggan Anda (endpoint publik, tanpa perlu sesi login). Pelanggan tinggal scan dan bayar seperti QRIS biasa melalui BCA, GoPay, DANA, ShopeePay, OVO, atau m-Banking apa pun.
Rate limit: 60 request/menit per API key. Simpan API key hanya di server backend Anda, jangan di kode frontend.

Webhook Callback Real-time (HMAC-SHA256)

Alih-alih polling /api/invoice/status secara periodik, server QRIS Gateway akan mengirimkan HTTP POST event seketika ke URL webhook Anda setiap kali transaksi terverifikasi.

HTTP Headers yang Dikirimkan:

x-signature: sha256=<hmac_sha256_hex>
x-signature-timestamp: ISO 8601 UTC timestamp
x-event: invoice.paid
content-type: application/json

Contoh Payload Webhook (JSON)

{
  "event": "invoice.paid",
  "invoice_ref": "INVMVCJ5AJEUB21",
  "external_id": "ORDER-9921",
  "amount": 50482,
  "amount_base": 50000,
  "status": "PAID",
  "paid_at": "2026-10-17T15:06:12Z",
  "paid_via": "id.dana",
  "description": "Topup Saldo",
  "customer_name": "Budi Santoso",
  "timestamp": "2026-10-17T15:06:13Z"
}

Verifikasi Signature (Node.js)

import crypto from "crypto";

// Pastikan payloadRaw adalah string mentah persis seperti yang diterima dari request body
function verifyWebhook(payloadRaw, signatureHeader, webhookSecret) {
  const cleanSignature = signatureHeader.replace(/^sha256=/, "");
  const computed = crypto.createHmac("sha256", webhookSecret).update(payloadRaw).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(cleanSignature), Buffer.from(computed));
}

Atur Webhook URL & Kunci di Dashboard

Siap Mengintegrasikan Pembayaran?

Daftar gratis hari ini, dapatkan API Key Anda dalam 1 menit, dan mulai terima pembayaran QRIS otomatis langsung ke rekening Anda.

Daftar Akun Gratis Buka Dashboard