Dokumentasi Resmi KeysPay Gateway

Panduan integrasi API lengkap untuk memproses transaksi QRIS instan, cek status pembayaran otomatis, dan mutasi saldo real-time.

Pengenalan API

KeysPay Gateway menyediakan RESTful API berkinerja tinggi untuk memfasilitasi pembuatan QRIS dinamis, penerimaan pembayaran otomatis dari seluruh bank & e-wallet di Indonesia, serta verifikasi status pembayaran instan.

API ini didesain khusus agar mudah diintegrasikan baik untuk aplikasi web modern (E-Commerce, Web Store) maupun bot otomatis (Bot WhatsApp, Bot Telegram, Bot Discord).

Base URL Endpoint API

Seluruh endpoint API dapat diakses melalui Base URL berikut:

Production Base URL 
https://keyysstore.web.id/api/v1

Langkah Cepat Mulai (Quickstart)

  1. Daftar akun di website KeysPay Gateway dan verifikasi email Anda.
  2. Buka menu Create API Key di navigasi samping untuk mendapatkan API Key unik.
  3. Gunakan API Key pada header X-API-Key di setiap request HTTP yang Anda kirimkan.
  4. Panggil endpoint POST /deposit/create untuk membuat pembayaran QRIS dan lakukan polling status ke GET /deposit/status/{depositid}.

Keunggulan API KeysPay

Settlement Instan

Deteksi pembayaran QRIS dalam hitungan detik setelah pelanggan membayar.

Perlindungan Penuh

Validasi HMAC SHA-256, enkripsi end-to-end, dan sistem anti-fraud terpercaya.

99.9% Uptime

Infrastruktur berdaya tahan tinggi siap melayani transaksi 24 jam nonstop.

Dukungan Multi-Language

Dukungan kode siap pakai untuk Node.js, Python, PHP, dan cURL.

Autentikasi API

Setiap request ke endpoint terproteksi wajib menyertakan API Key yang dikirim melalui HTTP Header berikut:

Header Name Tipe Deskripsi
X-API-Key String API Key rahasia Anda (Contoh: kp_live_a1b2c3d4e5...)
Content-Type String application/json (Wajib untuk request body POST)
PERINGATAN KEAMANAN: Jangan pernah mengekspos API Key Anda di frontend (aplikasi browser publik) atau commit ke repository publik. Simpan selalu di backend server atau file environment bot Anda.

1. Mendapatkan Saldo Akun

Meminta informasi detail akun merchant serta sisa saldo saat ini.

GET /balance

Header Request

HeaderWajibNilai
X-API-KeyYaAPI Key Merchant Anda

Contoh Response (200 OK)

Response Body (JSON)
{
  "success": true,
  "code": 200,
  "message": "Informasi saldo berhasil diambil",
  "data": {
    "email": "[email protected]",
    "name": "KeysPay Merchant",
    "balance": 2500000,
    "currency": "IDR",
    "status": "active"
  }
}

2. Membuat Deposit QRIS Baru

Sistem akan merespon dengan URL gambar QRIS dinamis dan string QRIS standar yang dapat digunakan langsung pada payment gateway Anda.

POST /deposit/create

Header Request

HeaderWajibNilai
X-API-KeyYaAPI Key Merchant Anda
Content-TypeYaapplication/json

Request Body (JSON)

ParameterTipeStatusDeskripsi Singkat
amountNumberRequiredNominal deposit (Rp1.000 – Rp1.000.000.000)
feeNumberOptionalBiaya tambahan transaksi (default: 0)
order_idStringOptionalID pesanan unik dari bot atau website Anda
customer_nameStringOptionalNama pelanggan atau pembeli

Contoh Request Body

Request Payload
{
  "amount": 50000,
  "fee": 0,
  "order_id": "ORD-20261010-098",
  "customer_name": "KeysPay User"
}

Contoh Response (200 OK)

Response Payload
{
  "success": true,
  "code": 200,
  "message": "Deposit QRIS berhasil dibuat",
  "data": {
    "deposit_id": "bvjqtw",
    "amount": 50000,
    "fee": 0,
    "total_amount": 50000,
    "status": "pending",
    "qr_url": "https://qriskuu.web.id/img/qr-phcagpzg.png",
    "qr_string": "00020101021126610014COM.GO-JEK.WWW0118...",
    "payment_link": "https://qriskuu.web.id/pay/bvjqtw",
    "created_at": "2026-10-10T07:30:00.000Z",
    "expired_at": "2026-10-10T07:35:00.000Z"
  }
}

3. Cek Status Deposit QRIS

Memeriksa status transaksi pembayaran QRIS secara real-time berdasarkan deposit ID.

GET /deposit/status/{depositid}

Path Parameter

ParameterTipeStatusDeskripsi
depositidStringRequiredID transaksi (Contoh: bvjqtw)

Varian Status Response

StatusArti & Deskripsi
successPembayaran sukses diterima dan diverifikasi.
pendingMenunggu pelanggan melakukan pembayaran via QRIS.
expiredWaktu pembayaran telah habis (melewati 5 menit).
alreadyTransaksi sudah pernah diselesaikan sebelumnya.
Catatan Status: Lakukan polling status secara berkala dengan interval rekomendasi 3 hingga 5 detik sampai status berubah menjadi success atau expired.

Contoh Response (200 OK)

Response Body
{
  "success": true,
  "code": 200,
  "message": "Status transaksi berhasil diambil",
  "data": {
    "deposit_id": "bvjqtw",
    "status": "success",
    "amount": 50000,
    "paid_at": "2026-10-10T07:32:15.000Z",
    "payment_from": "BCA",
    "reference_id": "05202610100335478dE9h4SSlpID"
  }
}

Kode Status & Error HTTP

HTTP CodeNama StatusPenjelasan Masalah
200 OKSuccessPermintaan berhasil dieksekusi secara normal.
400 Bad RequestInvalid PayloadFormat payload salah atau nominal di luar jangkauan minimal/maksimal.
401 UnauthorizedInvalid API KeyHeader X-API-Key tidak disertakan atau API Key tidak valid.
403 ForbiddenAccess DeniedAkses ditolak atau akun dinonaktifkan oleh administrator.
404 Not FoundNot FoundEndpoint atau deposit ID tidak ditemukan dalam basis data.
429 Too Many RequestsRate LimitBatas laju permintaan terlampaui (maks 60 req/menit).
500 Internal ErrorServer ErrorTerjadi kendala pada gateway pemroses transaksi.

Contoh Kode Penggunaan (Multi-Language)

Pilih bahasa pemrograman favorit Anda untuk melihat contoh implementasi alur lengkap: cek saldo, buat deposit QRIS, dan polling status pembayaran:

Node.js Integration Code