Dokumentasi API v1.0

Dokumentasi API GoPay Gateway

Selamat datang di dokumentasi resmi GoPay Gateway — sistem pembayaran QRIS otomatis berbasis GoPay Merchant / GoBiz. Integrasikan pembayaran QRIS ke dalam website, aplikasi, atau bot Anda.

Sistem bekerja dengan mengambil QRIS statis dari akun GoPay Merchant Anda (terhubung via Bot Telegram), lalu mengubahnya menjadi QRIS dinamis bernominal khusus setiap kali transaksi baru dibuat. Konfirmasi pembayaran dilakukan otomatis setiap ~15 detik melalui polling ke API GoBiz.

💡 Prasyarat Utama

Sebelum menggunakan API: (1) hubungkan akun GoPay Merchant via Bot Telegram perintah /login, dan (2) pastikan akun memiliki minimal 1.300 poin aktif.

Mulai Cepat

Ikuti 4 langkah berikut untuk mulai menerima pembayaran QRIS secara otomatis:

1
Daftar & Dapatkan API Key

Buat akun di dashboard, lalu salin API Key dari menu Pengaturan.

2
Hubungkan GoPay Merchant

Di Bot Telegram, ketik /login [email protected] lalu masukkan kode OTP untuk menghubungkan akun GoPay Merchant.

3
Top Up Poin

Pastikan akun memiliki minimal 1.300 poin. Setiap order membutuhkan saldo poin aktif.

4
Panggil API

Gunakan POST /api/create_order.php untuk membuat transaksi dan mendapatkan QRIS dinamis siap bayar.

Autentikasi

Semua request ke API harus menyertakan API Key unik dari dashboard. Tersedia dua cara:

⚠️ Jaga Kerahasiaan API Key

Jangan menyertakan API Key di client-side JavaScript, URL publik, atau repository kode publik. Gunakan hanya di server-side.

Metode 1 — HTTP Header (Direkomendasikan)
X-API-Key: gpg_live_xxxxxxxxxxxx
Metode 2 — Query Parameter
?apikey=gpg_live_xxxxxxxxxxxx
Base URL API
https://yourdomain.com/api

Sistem Poin

GoPay Gateway menggunakan sistem saldo poin sebagai biaya layanan. Setiap pembuatan order baru, sistem mengecek kecukupan poin Anda.

KetentuanDetail
Minimum Poin1.300 poin wajib ada di akun sebelum membuat order.
Cara Top UpMelalui menu Deposit Poin di halaman dashboard.
Cek SaldoTersedia di halaman dashboard utama Anda.
Error jika kurangHTTP 402 — "Poin Anda tidak mencukupi (Minimum 1.300 poin)."

Cara Kerja QRIS Dinamis

Sistem menggunakan QRIS statis GoPay Merchant yang diambil otomatis saat menghubungkan akun via Bot Telegram, lalu mengubahnya menjadi QRIS dinamis setiap transaksi.

FiturKeterangan
Nominal Unik Setiap order mendapat suffix acak +1 s/d +99 rupiah agar tidak bentrok antar transaksi aktif. Contoh: order Rp 150.000 → final Rp 150.037. Simpan amount dari response untuk verifikasi.
Auto Konfirmasi Sistem melakukan polling ke GoBiz API setiap ~15 detik. Ketika pembayaran masuk dan nominal cocok, status order otomatis berubah ke paid.
Auto Expire Jika tidak dibayar sampai batas waktu, status berubah otomatis ke expired saat endpoint check_status dipanggil.
Format Order ID GPG-XXXXXXXX-YYYYMMDDHHMMSS — unik untuk setiap transaksi.
✅ Cara Polling yang Benar

Anda tidak perlu implement webhook receiver. Cukup polling endpoint check_status dari aplikasi Anda setiap 5–10 detik selama QR ditampilkan. Sistem akan auto-sync dan mengembalikan status terbaru.

POST /api/create_order.php

Membuat order baru dan menghasilkan QRIS dinamis sesuai nominal. Tampilkan QR kepada pelanggan menggunakan qr_url atau render sendiri dari qr_string.

⚠️ Membutuhkan Poin

Endpoint ini membutuhkan minimal 1.300 poin. Jika tidak mencukupi, mengembalikan error HTTP 402.

Request Body (JSON)
ParameterTipeDeskripsi
amountwajib integer Nominal pembayaran dalam Rupiah. Min: Rp 100, Maks: Rp 50.000.000.
Catatan: nominal akhir akan bertambah 1–99 rupiah sebagai suffix unik.
ref_idopsional string ID referensi dari sistem Anda (misal: ID order website). Disimpan sebagai metadata.
descriptionopsional string Deskripsi transaksi untuk pelacakan internal.
expired_minutesopsional integer Masa berlaku QR dalam menit. Default: 15, Maks: 1440 (24 jam). Nilai di luar range akan di-reset ke 15.
curl -X POST "http://localhost:8080/api/create_order.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gpg_live_xxxxxxxxxxxx" \
  -d '{"amount":150000,"ref_id":"ORDER-001","description":"Pembelian Produk A","expired_minutes":15}'
Response JSON (200 OK)
JSON RESPONSE
{
  "status":  "success",
  "code":    200,
  "message": "Order berhasil dibuat. Tampilkan QR kepada pelanggan.",
  "data": {
    "order_id":         "GPG-B2E8D1A3-20260701161500",  // simpan untuk polling status
    "transaction_id":   128,
    "ref_id":           "ORDER-001",
    "merchant_name":    "Lempeur Store",
    "amount":           150037,          // nominal akhir (sudah + suffix unik)
    "amount_formatted": "Rp 150.037",
    "qr_string":        "00020101021226...",  // QRIS dinamis
    "qr_url":           "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=...",
    "status":           "pending",
    "description":      "Pembelian Produk A",
    "expired_minutes":  15,
    "expires_at":       "2026-07-01 16:30:00",
    "created_at":       "2026-07-01 16:15:00"
  }
}
GET /api/check_status.php?order_id={order_id}

Memeriksa status pembayaran. Saat dipanggil pada order pending, sistem otomatis sync ke GoBiz API untuk mendeteksi pembayaran (rate limit 1x/15 detik, bypass dengan &force=1).

💡 Polling dari Aplikasi Anda

Tidak perlu API Key untuk endpoint ini. Polling setiap 5–10 detik menggunakan order_id. Setelah status paid, hentikan polling dan proses pesanan.

Query Parameters
ParameterTipeDeskripsi
order_idwajib string ID Order dari response create_order. Format: GPG-XXXXXXXX-YYYYMMDDHHMMSS.
forceopsional integer Set 1 untuk paksa sync ke GoBiz API sekarang, bypass rate limit 15 detik.
# Cek status biasa
curl -G "http://localhost:8080/api/check_status.php" \
  --data-urlencode "order_id=GPG-B2E8D1A3-20260701161500"

# Force sync sekarang
curl -G "http://localhost:8080/api/check_status.php" \
  --data-urlencode "order_id=GPG-B2E8D1A3-20260701161500" \
  -d "force=1"
Response JSON (200 OK)
JSON RESPONSE
{
  "status":  "success",
  "code":    200,
  "message": "Success",
  "data": {
    "order_id":         "GPG-B2E8D1A3-20260701161500",
    "merchant_name":    "Lempeur Store",
    "ref_id":           "ORDER-001",
    "amount":           150037,
    "amount_formatted": "Rp 150.037",
    "qr_string":        "00020101021226...",
    "qr_url":           "https://api.qrserver.com/...",
    "status":           "paid",        // pending | paid | expired | failed
    "description":      "Pembelian Produk A",
    "expired_minutes":  15,
    "expires_at":       "2026-07-01 16:30:00",
    "created_at":       "2026-07-01 16:15:00",
    "paid_at":          "2026-07-01 16:18:55"   // null jika belum dibayar
  }
}
GET /api/get_transactions.php

Mengambil daftar riwayat transaksi milik akun merchant Anda. Mendukung filter status dan paginasi.

Query Parameters
ParameterTipeDeskripsi
statusopsional string Filter: pending, paid, expired, failed. Kosongkan untuk semua.
limitopsional integer Jumlah data per halaman. Default: 20.
pageopsional integer Nomor halaman. Default: 1.
cURL EXAMPLE
curl -G "http://localhost:8080/api/get_transactions.php" \
  -H "X-API-Key: gpg_live_xxxxxxxxxxxx" \
  -d "status=paid&limit=20&page=1"
POST /api/update_status.php

Memperbarui status transaksi secara manual. Berguna untuk testing atau integrasi callback eksternal.

Request Body (JSON)
ParameterTipeDeskripsi
order_idwajib string ID order yang ingin diperbarui statusnya.
statuswajib string Status baru: paid / failed / expired / pending.
cURL EXAMPLE
curl -X POST "http://localhost:8080/api/update_status.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gpg_live_xxxxxxxxxxxx" \
  -d '{"order_id":"GPG-B2E8D1A3-20260701161500","status":"paid"}'

Kode Status Transaksi

Setiap transaksi memiliki salah satu dari 4 status berikut:

pending paid expired failed
StatusKeterangan
pending Order aktif, menunggu pembayaran. QRIS masih bisa discan hingga expires_at.
paid Pembayaran dikonfirmasi otomatis. Field paid_at berisi timestamp pembayaran masuk.
expired Order kadaluarsa karena tidak dibayar sebelum expires_at. Diubah otomatis saat check_status dipanggil.
failed Transaksi gagal atau dibatalkan secara manual via update_status.

Kode Error HTTP

Semua error dikembalikan dalam format JSON:

FORMAT ERROR RESPONSE
{
  "status":  "error",
  "code":    400,
  "message": "Pesan error spesifik di sini"
}
HTTP CodeKeterangan
400Bad Request — parameter tidak valid atau parameter wajib yang hilang (mis. amount tidak diisi).
401Unauthorized — API Key tidak disertakan atau tidak valid.
402Payment Required — saldo poin tidak mencukupi. Minimum 1.300 poin diperlukan.
404Not Found — order_id tidak ditemukan di database.
405Method Not Allowed — menggunakan HTTP method yang salah (mis. GET ke endpoint POST).
422Unprocessable — QRIS string belum dikonfigurasi. Hubungkan GoPay Merchant terlebih dahulu via Bot Telegram.
500Internal Server Error — gagal generate QRIS atau error internal server.
502Bad Gateway — gagal menghubungi GoBiz API (untuk mode Client ID resmi).