Dokumentasi API

Integrasikan pembayaran QRIS dinamis ke website atau aplikasi kamu hanya dengan satu endpoint. Kirim nominal, terima QR Code — semudah itu.

Response < 200ms

API Key Auth

REST + WebSocket

Quick Start

Untuk mulai menggunakan API, kamu hanya butuh 2 hal: API Key dan String QRIS Statis milikmu.

Buka Dashboard

Daftar dan masuk ke dashboard, lalu buat API Key baru di menu "API Key".

Simpan Konfigurasi QRIS

Upload atau paste string QRIS statis kamu di menu "Pengaturan". Cukup sekali saja.

Panggil API Generate

Kirim nominal pembayaran, terima QR code dinamis siap bayar.

Base URL

https://setqris.vercel.app

Ganti dengan domain server kamu saat di-deploy ke production.

POST

/api/v1/qris/generate

Endpoint utama. Mengonversi QRIS statis menjadi QRIS dinamis dengan nominal + kode unik anti-duplikat. Response berisi string QRIS baru dan gambar QR code (base64).

Header

Parameter	Tipe	Wajib	Keterangan
Content-Type	string	Ya	application/json
x-api-key	string	Ya	API Key milik kamu

Request Body

Parameter	Tipe	Wajib	Keterangan
amount	number	Ya	Nominal pembayaran (Rupiah). Contoh: 50000
qrisString	string	Tidak	Opsional. Jika tidak diisi, akan pakai QRIS dari config

Contoh Request

curl

curl -X POST https://setqris.vercel.app/api/v1/qris/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: API_KEY_KAMU" \
  -d '{
    "amount": 50000
  }'

Response Sukses (200)

json

{
  "success": true,
  "data": {
    "originalAmount": 50000,
    "uniqueCode": 3,
    "finalAmount": 50003,
    "qrisString": "00020101021226570011ID.DANA.WWW...6304ABCD",
    "qrImageUrl": "data:image/png;base64,iVBORw0KGgo...",
    "expiryMinutes": 15,
    "expiresAt": "2026-08-01T20:15:00.000Z"
  },
  "message": "QRIS Dinamis berhasil dibuat"
}

💡 Kode Unik: Sistem otomatis menambahkan kode unik (misal +3) ke nominal agar setiap transaksi bisa diidentifikasi. Customer bayar Rp 50.003 — sistem tahu ini pembayaran dari order kamu.

POST

/api/v1/qris/config

Simpan konfigurasi QRIS statis agar tidak perlu mengirim qrisString setiap kali generate. Cukup simpan sekali, lalu panggil generate hanya dengan amount.

Request Body

Parameter	Tipe	Wajib	Keterangan
qrisString	string	Ya	String QRIS statis lengkap
expiryMinutes	number	Tidak	Masa berlaku QR (default: 15 menit)
uniqueCodeMin	number	Tidak	Kode unik minimum (default: 1)
uniqueCodeMax	number	Tidak	Kode unik maksimum (default: 100)

Contoh Request

curl

curl -X POST https://setqris.vercel.app/api/v1/qris/config \
  -H "Content-Type: application/json" \
  -H "x-api-key: API_KEY_KAMU" \
  -d '{
    "qrisString": "00020101021126570011ID.DANA.WWW...",
    "expiryMinutes": 15,
    "uniqueCodeMin": 1,
    "uniqueCodeMax": 99
  }'

POST

/api/v1/qris/callback

Endpoint untuk menerima notifikasi pembayaran dari payment gateway atau aplikasi monitoring. Data yang dikirim ke endpoint ini akan langsung di-broadcast ke semua client yang terhubung via WebSocket.

Request Body (dari Payment Gateway)

json

{
  "key": "API_KEY_KAMU",
  "amount": 50003,
  "status": "Settlement",
  "merchantName": "Toko ABC",
  "transactionId": "TXN-123456"
}

WebSocket (Real-time)

Untuk menerima notifikasi pembayaran secara real-time di frontend, hubungkan ke WebSocket server:

javascript

import { io } from "socket.io-client";

const socket = io("https://setqris.vercel.app");

socket.on("payment_received", (data) => {
  console.log("Pembayaran diterima!", data);
  // data.amount = 50003
  // data.status = "Settlement"
});

Contoh Integrasi

Copy-paste kode di bawah ke project kamu. Tinggal ganti API_KEY dan BASE_URL.

javascript

const API_KEY = "API_KEY_KAMU";
const BASE_URL = "https://setqris.vercel.app";

async function generateQris(amount) {
  const res = await fetch(BASE_URL + "/api/v1/qris/generate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
    },
    body: JSON.stringify({ amount }),
  });

  const json = await res.json();

  if (json.success) {
    // json.data.qrImageUrl  → Gambar QR (base64), taruh di <img src="...">
    // json.data.finalAmount  → Nominal yang harus dibayar customer
    // json.data.expiresAt    → Kapan QR expired
    return json.data;
  } else {
    throw new Error(json.message);
  }
}

// Contoh pemakaian:
// const qr = await generateQris(50000);
// document.getElementById("qr-img").src = qr.qrImageUrl;

Kode Error

Semua error response menggunakan format JSON yang konsisten:

json

{
  "statusCode": 400,
  "message": "Deskripsi error"
}

Kode	Penyebab	Solusi
400	Parameter tidak lengkap atau QRIS tidak valid	Pastikan `amount` terisi dan QRIS sudah dikonfigurasi
401	API Key tidak valid atau tidak disertakan	Cek header `x-api-key` sudah benar
500	Kesalahan internal server	Hubungi admin atau cek log server