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.
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:
Buat akun di dashboard, lalu salin API Key dari menu Pengaturan.
Di Bot Telegram, ketik /login [email protected] lalu masukkan kode OTP untuk menghubungkan akun GoPay Merchant.
Pastikan akun memiliki minimal 1.300 poin. Setiap order membutuhkan saldo poin aktif.
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:
Jangan menyertakan API Key di client-side JavaScript, URL publik, atau repository kode publik. Gunakan hanya di server-side.
Sistem Poin
GoPay Gateway menggunakan sistem saldo poin sebagai biaya layanan. Setiap pembuatan order baru, sistem mengecek kecukupan poin Anda.
| Ketentuan | Detail |
|---|---|
| Minimum Poin | 1.300 poin wajib ada di akun sebelum membuat order. |
| Cara Top Up | Melalui menu Deposit Poin di halaman dashboard. |
| Cek Saldo | Tersedia di halaman dashboard utama Anda. |
| Error jika kurang | HTTP 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.
| Fitur | Keterangan |
|---|---|
| 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. |
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.
Membuat order baru dan menghasilkan QRIS dinamis sesuai nominal. Tampilkan QR kepada pelanggan menggunakan qr_url atau render sendiri dari qr_string.
Endpoint ini membutuhkan minimal 1.300 poin. Jika tidak mencukupi, mengembalikan error HTTP 402.
| Parameter | Tipe | Deskripsi |
|---|---|---|
| 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}'
{
"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"
}
}
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).
Tidak perlu API Key untuk endpoint ini. Polling setiap 5–10 detik menggunakan order_id. Setelah status paid, hentikan polling dan proses pesanan.
| Parameter | Tipe | Deskripsi |
|---|---|---|
| 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"
{
"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
}
}
Mengambil daftar riwayat transaksi milik akun merchant Anda. Mendukung filter status dan paginasi.
| Parameter | Tipe | Deskripsi |
|---|---|---|
| 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 -G "http://localhost:8080/api/get_transactions.php" \
-H "X-API-Key: gpg_live_xxxxxxxxxxxx" \
-d "status=paid&limit=20&page=1"
Memperbarui status transaksi secara manual. Berguna untuk testing atau integrasi callback eksternal.
| Parameter | Tipe | Deskripsi |
|---|---|---|
| order_idwajib | string | ID order yang ingin diperbarui statusnya. |
| statuswajib | string | Status baru: paid / failed / expired / pending. |
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:
| Status | Keterangan |
|---|---|
| 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:
{
"status": "error",
"code": 400,
"message": "Pesan error spesifik di sini"
}
| HTTP Code | Keterangan |
|---|---|
| 400 | Bad Request — parameter tidak valid atau parameter wajib yang hilang (mis. amount tidak diisi). |
| 401 | Unauthorized — API Key tidak disertakan atau tidak valid. |
| 402 | Payment Required — saldo poin tidak mencukupi. Minimum 1.300 poin diperlukan. |
| 404 | Not Found — order_id tidak ditemukan di database. |
| 405 | Method Not Allowed — menggunakan HTTP method yang salah (mis. GET ke endpoint POST). |
| 422 | Unprocessable — QRIS string belum dikonfigurasi. Hubungkan GoPay Merchant terlebih dahulu via Bot Telegram. |
| 500 | Internal Server Error — gagal generate QRIS atau error internal server. |
| 502 | Bad Gateway — gagal menghubungi GoBiz API (untuk mode Client ID resmi). |