Dokumentasi API

Dokumentasi lengkap API PayGate. Generate QRIS dinamis, monitoring real-time, dan webhook otomatis.

Pengenalan

BASE URL: http://localhost:3000 (referensi asli: https://api.pgbst.site)

Semua endpoint mengembalikan JSON: {"success":true,"message":"...","data":{...}}

Autentikasi

Semua request memerlukan API Key via header Authorization dengan format Bearer Token.

# HTTP
Authorization: Bearer agp_your_api_key_here

Daftar Transaksi

Ambil daftar transaksi terbaru (filter tanggal & status opsional).

POST /transactions

curl -X POST http://localhost:3000/transactions \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"per":10,"from_date":"2026-01-01","to_date":"2026-12-31"}'

Response:

{
  "success": true,
  "data": {
    "transactions": [
      { "id": "TRX-001", "order_id": "AUTOGOPAY-1774618440-2411", "time": "2026-03-18 15:16:33",
        "amount": 50000, "currency": "IDR", "payment_type": "qris",
        "status": "settlement", "issuer": "gopay" }
    ],
    "total": 24, "page": 1, "per": 10, "total_amount": 1535000
  }
}

Generate QRIS

Buat transaksi QRIS baru. Order ID di-generate otomatis. Response termasuk checkout_url yang bisa dikirim ke pelanggan sebagai link pembayaran.

POST /qris/generate

curl -X POST http://localhost:3000/qris/generate \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000}'

Parameter	Tipe	Wajib	Keterangan
amount	integer	ya	Jumlah dalam IDR (1 - 10.000.000)

Response:

{
  "success": true, "message": "QRIS created successfully",
  "data": {
    "transaction_id": "53bc6ed2-441d-4bd0-bc39-11fdfff5fedb",
    "order_id": "AUTOGOPAY-1774618440-2411",
    "amount": 10000,
    "transaction_status": "pending",
    "qr_string": "00020101021226610014COM.GO-JEK.WWW...",
    "qr_url": "/qris/53bc6ed2-441d-4bd0-bc39-11fdfff5fedb/qr-code",
    "checkout_url": "/pay/abc123def456",
    "transaction_time": "2026-03-27 20:34:00",
    "expiry_time": "2026-03-27 20:49:00"
  }
}

💡 Payment Link (Checkout URL): setiap Generate QRIS otomatis membuat payment link (/pay/<token>). Kirim link ke pelanggan via WA/email — pelanggan buka, scan QR, dan status halaman otomatis update (polling 3 detik) saat dibayar.

Status Transaksi

Cek status pembayaran QRIS.

POST /qris/status

curl -X POST http://localhost:3000/qris/status \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "53bc6ed2-441d-4bd0-bc39-11fdfff5fedb"}'

Nilai status: pending → settlement | expire | cancel

Cancel QRIS

Batalkan transaksi QRIS yang masih pending.

POST /qris/cancel

curl -X POST http://localhost:3000/qris/cancel \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "53bc6ed2-441d-4bd0-bc39-11fdfff5fedb"}'

Webhook Callback

Terima notifikasi real-time saat transaksi dibayar. Sistem mengirim POST request ke URL webhook Anda (atur di halaman Pengaturan).

⚠️ VERIFIKASI SIGNATURE WAJIB — verifikasi header X-Signature di setiap webhook request menggunakan HMAC-SHA256 dengan API Key sebagai secret.

Header webhook:

Content-Type      application/json
User-Agent       AutoGopay-Callback/1.0
X-Callback-Event transaction.received
X-Signature      HMAC-SHA256 signature

Payload:

{
  "event": "transaction.received",
  "timestamp": "2026-03-29 14:30:45",
  "transaction": {
    "id": "TRX-001", "time": "2026-03-29 14:30:40", "amount": 50000,
    "currency": "IDR", "payment_type": "qris", "status": "settlement", "issuer": "gopay"
  }
}

Contoh implementasi Node.js:

const crypto = require('crypto');
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const expected = crypto.createHmac('sha256', API_KEY)
    .update(JSON.stringify(req.body)).digest('hex');
  if (signature !== expected) return res.status(401).end();
  const { transaction } = req.body;
  if (transaction.status === 'settlement') {
    // Process payment
  }
  res.json({ success: true });
});

Catatan: HTTPS wajib di production • Return HTTP 200 dalam 10 detik • Cek idempotency untuk mencegah duplikat.

OVO — Riwayat Transaksi

Ambil riwayat transaksi OVO (masuk & keluar). Akun OVO harus terhubung via dashboard.

GET /ovo/transactions?page=1&limit=10

{
  "data": [
    { "description": "Top Up", "source": "Bank CIMB", "amount": 10000, "fee": 2000,
      "date": "2026-05-19", "time": "20:54:34", "status": "SUCCESS", "type": "in" }
  ]
}

Field: type = "in" (masuk) / "out" (keluar), status = SUCCESS / PENDING

OVO — Preview QRIS

Scan QRIS dan dapatkan info merchant + nominal sebelum membayar.

POST /ovo/qris/preview

curl -X POST http://localhost:3000/ovo/qris/preview \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qr_string": "00020101021226610014..."}'

Response (amount terdeteksi):

{ "data": { "checkout_id": "ck_abc123", "qr_type": "dynamic",
  "merchant_name": "TOKO SEJAHTERA", "merchant_city": "JAKARTA", "amount": 50000 } }

Response (static tanpa nominal):

{ "data": { "preview_id": "pending_sc_xyz789", "qr_type": "static",
  "amount_required": true, "message": "Please provide 'amount' in confirm request." } }

💡 Flow 2 tahap: ada checkout_id → confirm dengan checkout_id + pin. Ada preview_id + amount_required → confirm dengan preview_id + amount + pin.

OVO — Konfirmasi Bayar QRIS

POST /ovo/qris/confirm

curl -X POST http://localhost:3000/ovo/qris/confirm \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"checkout_id": "ck_abc123", "pin": "123456"}'

Response:

{ "success": true, "message": "QRIS payment successful",
  "data": { "amount": 50000, "checkout_id": "ck_abc123" } }

Error saldo tidak cukup:

{ "success": false, "message": "Insufficient OVO Cash balance",
  "data": { "ovo_cash_balance": 15000, "amount_required": 50000, "shortage": 35000 } }

Kirim checkout_id ATAU preview_id (tidak keduanya) • berlaku 10 menit • PIN salah 3x bisa mengunci akun OVO.

OVO — Daftar Bank

GET /ovo/banks

{ "data": [ { "code": "014", "name": "BANK BCA" },
  { "code": "002", "name": "BANK BRI" }, { "code": "008", "name": "BANK MANDIRI" } ] }

OVO — Transfer Inquiry

Cek nama penerima dan biaya admin sebelum transfer.

POST /ovo/transfer/inquiry

curl -X POST http://localhost:3000/ovo/transfer/inquiry \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bank_code": "008", "account_number": "1770025694909", "amount": 10000}'

{ "data": { "account_name": "FA** TE**", "amount": 10000,
  "admin_fee": 2500, "total_amount": 12500 } }

OVO — Transfer Bank

POST /ovo/transfer/execute

curl -X POST http://localhost:3000/ovo/transfer/execute \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bank_code": "008", "account_number": "1770025694909",
       "amount": 10000, "pin": "123456", "notes": "Invoice #001"}'

{ "success": true, "message": "Transfer successful",
  "data": { "amount": 10000, "admin_fee": 2500, "total_amount": 12500,
    "bank_name": "BANK MANDIRI", "account_name": "FAZA TEAM",
    "reference_id": "p01-260613-c2f2b39d-92e7-4382-8cd9-6d44409f1ddc" } }

Fitur harus di-enable oleh admin • minimal transfer Rp 10.000 • admin fee Rp 2.500 • selalu panggil /inquiry dulu.

ShopeePay — Status

Cek status koneksi ShopeePay dan validitas token.

GET /shopeepay/status

{ "data": { "connected": true, "token_valid": true } }

Sistem otomatis mengecek token setiap 5 menit; jika expired, notifikasi dikirim ke Telegram.

ShopeePay — Transaksi

GET /shopeepay/transactions?pageSize=10

curl "http://localhost:3000/shopeepay/transactions?pageSize=10&startTime=1750000000&endTime=1751000000" \
  -H "Authorization: Bearer agp_API_KEY"

{ "data": { "transactions": [
  { "amount": 100, "status": "success", "issuer": "Bank Mandiri", "time": "2026-06-10 23:21:44" } ] } }

Status transaksi: pending | success | failed | refunded | expired

ShopeePay — Generate QRIS

Generate QRIS dinamis dari static QRIS merchant. QR URL valid 15 menit.

POST /shopeepay/qris/create

curl -X POST http://localhost:3000/shopeepay/qris/create \
  -H "Authorization: Bearer agp_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50000, "qris_static": "00020101021226610016ID.CO.SHOPEE.WWW..."}'

{ "data": { "amount": 50000,
  "qr_string": "00020101021226610016ID.CO.SHOPEE.WWW...",
  "qr_url": "/shopeepay/qr/6ff2cd1d04c5e4e7",
  "expiry_time": "2026-06-11 14:45:00" } }

Contoh Bot Payment (ShopeePay)

Bot membuat QRIS dengan nominal unik (dasar + acak 1-99), lalu polling transaksi untuk deteksi pembayaran.

// Node.js — buat nominal unik, tampilkan QR, polling tiap 5 detik
const API_URL = 'http://localhost:3000';
const API_KEY = 'agp_API_KEY_KAMU';
const QRIS_STATIC = '00020101021226610016ID.CO.SHOPEE.WWW...';

const headers = { 'Content-Type': 'application/json',
                  'Authorization': 'Bearer ' + API_KEY };

function buatNominalUnik(dasar) {
  return dasar + Math.floor(Math.random() * 99) + 1;
}
async function buatQRIS(nominal) {
  const r = await fetch(API_URL + '/shopeepay/qris/create',
    { method: 'POST', headers,
      body: JSON.stringify({ amount: nominal, qris_static: QRIS_STATIC }) });
  const d = await r.json();
  if (!d.success) throw new Error(d.message);
  return d.data;
}
async function cekPembayaran(nominal, waktuMulai) {
  const q = new URLSearchParams({ pageSize: '20', startTime: String(waktuMulai) });
  const r = await fetch(API_URL + '/shopeepay/transactions?' + q, { headers });
  const d = await r.json();
  const txs = (d.data && d.data.transactions) || [];
  return txs.find(tx => tx.amount === nominal && tx.status === 'success') || null;
}
(async () => {
  const nominal = buatNominalUnik(10000);
  const mulai = Math.floor(Date.now() / 1000) - 60;
  const qris = await buatQRIS(nominal);
  console.log('QR: ' + qris.qr_url + ' | Nominal: Rp ' + qris.amount);
  for (let i = 0; i < 180; i++) {           // cek 15 menit
    await new Promise(r => setTimeout(r, 5000));
    const bayar = await cekPembayaran(nominal, mulai);
    if (bayar) { console.log('PEMBAYARAN BERHASIL: ' + bayar.amount); return; }
  }
  console.log('Timeout.');
})();

Menghubungkan QRIS / E-Wallet (PENTING)

Dari mana QRIS-nya? QRIS yang Anda terima bukan dibuat oleh PayGate — melainkan berasal dari akun e-wallet merchant milik Anda sendiri (GoPay Merchant, OVO Business, atau ShopeePay Merchant). PayGate hanya menghubungkan dan mengotomasi akun tersebut.

Alur koneksi (GoPay QRIS)

1. Anda punya akun GoPay Merchant (aplikasi GoPay Merchant / dashboard GoBiz) yang sudah punya QRIS statis atau merchant ID.
2. Di PayGate: Pengaturan → Akun GoPay → Hubungkan GoPay, masukkan nomor HP GoPay.
3. Sistem mengirim OTP ke nomor Anda → masukkan kode OTP → sesi GoPay merchant terhubung (seperti login otomatis, sama seperti sistem pgbst.site via bot Telegram).
4. Setelah terhubung, PayGate bisa generate QRIS dinamis (dengan nominal custom) atas nama merchant Anda, dan mendeteksi otomatis saat pembayaran masuk ke akun GoPay Anda.
5. Dana masuk langsung ke saldo GoPay Anda — PayGate tidak menahan dana (bukan escrow).

Koneksi lain

OVO: hubungkan via OTP + PIN OVO → bisa scan QRIS untuk bayar dan transfer bank (fitur transfer di-enable admin).
ShopeePay: masukkan token dari aplikasi Shopee Merchant → sistem generate QRIS dinamis dari QRIS statis Anda, valid 15 menit.

⚠️ Penting untuk dipahami: di versi demo ini, koneksi e-wallet disimulasikan (pembayaran masuk lewat tombol "Simulasi Pembayaran"). Di produksi, bagian OTP login + deteksi transaksi ini disambungkan ke sesi asli akun e-wallet Anda — alur kodenya sudah disiapkan di endpoint /gopay/login/request|verify, /ovo/*, dan /shopeepay/*.

Tips keamanan

• Gunakan akun e-wallet khusus merchant, jangan akun pribadi.
• Jangan bagikan OTP ke siapa pun — sistem hanya memintanya saat koneksi.
• Putuskan koneksi jika akun tidak dipakai (halaman Pengaturan / OVO / ShopeePay).