Dokumentasi

Semua yang kamu butuhkan untuk menyambungkan gateway ini ke toko online, bot, atau backend apa pun.

Base URLhttps://api.tokomu.id

GoPay API Gateway adalah API self-hosted dari Kazama Tech untuk menerima pembayaran lewat akun GoPay / GoBiz Merchant milikmu. Halaman ini menjelaskan cara menyambungkannya ke toko online, bot, atau backend apa pun.

Tiga hal yang perlu kamu tahu sebelum mulai:

  • Server sudah terpasang dan login GoBiz sudah dilakukan oleh pemilik server. Kamu hanya butuh alamat server dan API_KEY.
  • Semua endpoint backend memakai API_KEY. Halaman bayar untuk pembeli tidak membutuhkannya.
  • QRIS berlaku 5 menit sejak dibuat.
Request pertama
curl "https://api.tokomu.id/create-qris?amount=25000" \
  -H "X-Api-Key: API_KEY_KAMU"

Alamat pada contoh mengikuti server yang sedang kamu buka. Ganti bila kamu memanggil API dari domain lain.

Autentikasi

Kirim API_KEY lewat header atau query string. Header lebih aman karena tidak tercatat di log akses server.

CaraContoh
Header (disarankan)X-Api-Key: API_KEY_KAMU
Query string?api_key=API_KEY_KAMU

Setiap endpoint yang menerima GET juga menerima POST dengan body JSON bila disebutkan di bawah. Panggil API dari backend toko, jangan dari browser pembeli, supaya API_KEY tidak bocor.

Jangan taruh API_KEY di JavaScript frontend. Untuk pembeli, pakai qris_url. Halaman itu memeriksa status lewat endpoint publik tanpa key.

Alur integrasi

  1. Backend toko memanggil /create-qris dengan nominal pesanan, lalu menyimpan trx_id bersama pesanan.
  2. Pembeli dikirim ke qris_url atau kamu tampilkan qris_code sendiri sebagai gambar QR.
  3. Backend toko memanggil /check-payment dengan amount dan trx_id yang sama, setiap 5 sampai 10 detik, sampai paid bernilai true atau 5 menit habis.
  4. Saat paid: true, tandai pesanan lunas. Simpan transaction_id untuk catatan.

Selalu kirim trx_id. Tanpa itu, dua pembeli yang membayar nominal sama bisa saling mengambil transaksi. Dengan trx_id, satu transaksi hanya bisa diklaim satu pembayaran.

Endpoint

MethodPathAksesFungsi
GET POST/create-qrisAPI keyBuat QRIS dinamis
GET POST/check-paymentAPI keyCek pembayaran masuk
GET/qr/:idPublikHalaman bayar pembeli
GET/api/qr-status/:idPublikStatus satu QRIS
GET/transactionsAPI keyRiwayat mutasi
GET/token-statusAPI keyStatus sesi GoPay
GET/api/logsAPI keyLog aktivitas
GET/healthPublikHealth check
GET / POST

/create-qris

API key

Membuat QRIS dinamis dari QRIS statis merchant. Dibuat lokal di server, tanpa memanggil API GoPay.

ParameterTipeKeterangan
amountintegerWajib. Nominal Rupiah, bilangan bulat lebih dari 0.
Respon 200
{
  "success": true,
  "data": {
    "qris_id": "k3x9m2q7ab",
    "trx_id": "TRX-A3F8K2M9",
    "qris_url": "https://api.tokomu.id/qr/k3x9m2q7ab",
    "qris_code": "00020101021226...6304ABCD",
    "amount": 25000,
    "expires_at": "2026-11-01T10:05:00.000Z",
    "expires_in": "5 menit"
  }
}

qris_code adalah isi QR (string EMVCo). Ubah jadi gambar dengan library QR pilihanmu, atau pakai qris_url yang sudah menampilkannya.

GET / POST

/check-payment

API key

Mencari transaksi lunas dengan nominal yang sama persis, sejak waktu tertentu. Hanya status SETTLEMENT dan CAPTURE yang dihitung, refund tidak dianggap pembayaran.

ParameterTipeKeterangan
amountintegerWajib. Nominal yang dicari.
trx_idstringSangat disarankan. Nilai trx_id dari /create-qris.
startTimeISO 8601Opsional. Awal pencarian. Bawaan 24 jam terakhir. Isi dengan expires_at dikurangi 5 menit agar akurat.
Contoh request
curl "https://api.tokomu.id/check-payment?amount=25000&trx_id=TRX-A3F8K2M9" \
  -H "X-Api-Key: API_KEY_KAMU"
Respon saat lunas
{
  "success": true,
  "paid": true,
  "transaction": {
    "transaction_id": "gopay-internal-tx-id",
    "order_id": "GOPAY-1234567890",
    "amount": 25000,
    "payer_issuer": "GoPay / BCA",
    "payment_type": "QRIS",
    "transaction_time": "2026-11-01T10:02:12.000Z"
  }
}
Respon saat belum lunas
{ "success": true, "paid": false, "message": "Pembayaran belum ditemukan atau sudah pernah diklaim" }

Header opsional X-Gopay-Merchant-Id menimpa GOPAY_MERCHANT_ID di server untuk request itu.

GET

/qr/:id

Publik

Halaman bayar untuk pembeli. Berisi QR, nominal, hitung mundur 5 menit, tombol cek pembayaran, dan opsi cek otomatis setiap 8 detik. Kirim qris_url ke pembeli apa adanya.

Untuk gambar QR saja, buka /qr/:id/image.svg atau tambahkan ?format=raw ke URL halaman. Gambar berupa SVG dan dibuat di server, jadi isi QRIS tidak dikirim ke layanan lain.

GET

/api/qr-status/:id

Publik

Status satu QRIS, dipakai halaman bayar. Tidak butuh API key dan dibatasi 40 request per menit per IP. Server juga menahan pengecekan ke GoPay agar tidak lebih sering dari sekali per 3 detik per QRIS.

statusArti
PENDINGBelum ada pembayaran masuk.
PAIDLunas. Detail ada di transaction.
EXPIREDLewat 5 menit.
NOT_FOUNDID tidak dikenal atau data sudah dihapus dari memori server.
Respon
{
  "success": true,
  "status": "PENDING",
  "paid": false,
  "order": { "amount": 25000, "created_at": "...", "expires_at": "..." },
  "message": "Belum ada pembayaran masuk"
}
GET

/transactions

API key

Riwayat mutasi QRIS, GoPay, dan kartu.

ParameterTipeBawaanKeterangan
startTimeunix (detik)3 hari laluAwal rentang.
endTimeunix (detik)sekarangAkhir rentang.
pageSizeinteger20Jumlah data, maksimal 100.
Respon
{
  "success": true,
  "total_amount": "75000",
  "data": {
    "transactions": [
      {
        "amount": 25000,
        "status": "settlement",
        "time": "2026-11-01T10:02:12.000Z",
        "issuer": "GoPay / BCA",
        "order_id": "GOPAY-1234567890",
        "transaction_id": "..."
      }
    ]
  }
}

GET /transactions/all mengambil hingga 100 transaksi sejak awal bulan ini, tanpa parameter.

GET

/token-status

API key

Memeriksa apakah sesi GoPay di server masih aktif. Cocok untuk monitoring.

Respon
{ "success": true, "data": { "token_status": "valid", "message": "Token dan sesi GoPay Merchant aktif" } }

Bila token_status bernilai invalid, minta pemilik server menjalankan npm run login ulang.

GET

/api/logs

API key

100 log aktivitas terakhir (terbaru di atas), tersimpan di memori server dan hilang saat server restart.

GET

/health

Publik

Mengembalikan { "status": "OK" } bila server hidup. /api/health berfungsi sama dengan format success. Keduanya tidak memeriksa sesi GoPay, untuk itu pakai /token-status.

Contoh kode

Contoh lengkap alur buat QRIS lalu cek pembayaran dari backend toko.

Node.js 18+
const BASE = 'https://api.tokomu.id';
const headers = { 'X-Api-Key': process.env.GOPAY_API_KEY };

async function createPayment(amount) {
  const res = await fetch(`${BASE}/create-qris?amount=${amount}`, { headers });
  const { data } = await res.json();
  return data; // { trx_id, qris_url, expires_at, ... }
}

async function waitUntilPaid({ amount, trx_id, expires_at }) {
  const since = new Date(new Date(expires_at) - 5 * 60 * 1000).toISOString();
  while (Date.now() < new Date(expires_at).getTime()) {
    const url = `${BASE}/check-payment?amount=${amount}&trx_id=${trx_id}&startTime=${since}`;
    const body = await (await fetch(url, { headers })).json();
    if (body.paid) return body.transaction;
    await new Promise((r) => setTimeout(r, 8000));
  }
  return null; // kedaluwarsa
}

Kode error

Semua error berbentuk { "success": false, "code": "...", "message": "..." }.

HTTPcodePenyebab dan solusi
400BAD_REQUESTParameter salah, misalnya amount bukan bilangan bulat. Perbaiki request.
401INVALID_API_KEYAPI key kosong atau salah.
409SESSION_MISSINGServer belum login GoBiz. Pemilik server menjalankan npm run login.
429-Terlalu banyak request ke endpoint publik. Tunggu sesuai header Retry-After.
500API_KEY_NOT_CONFIGUREDAPI_KEY belum diisi di .env server.
500QRIS_NOT_CONFIGUREDQRIS_STATIC belum diisi di .env server.
502UPSTREAM_ERRORAPI GoPay menolak atau sedang bermasalah. Cek /token-status, lalu coba lagi.

Pasang di server

Bagian ini untuk pemilik server. Kamu butuh server dengan penyimpanan permanen dan Node.js 18 atau lebih baru.

1. Siapkan proyek

Terminal
git clone https://github.com/kazamaofficial-git/gopay-api.git
cd gopay-api
npm install
cp .env.example .env

2. Isi .env

VariabelWajibKeterangan
API_KEYYaKunci rahasia untuk endpoint backend. Buat yang panjang dan acak.
QRIS_STATICYaIsi QRIS statis dari aplikasi GoBiz (teks yang diawali 000201).
GOPAY_MERCHANT_IDDisarankanID merchant GoBiz.
PORTTidakBawaan 3000. Di cPanel biarkan bawaan.
PUBLIC_BASE_URLTidakAlamat publik, misal https://api.tokomu.id. Dipakai untuk membentuk qris_url bila server di belakang proxy.
TRUST_PROXYTidakJumlah proxy di depan server. Bawaan 1 (cocok dengan Nginx).

3. Login GoBiz sekali

Terminal
npm run login

Masukkan nomor HP GoBiz dan kode OTP. Sesi tersimpan di .GOPAY_SESI_JANGAN_DIHAPUS.json dan diperbarui otomatis di background, jadi login cukup sekali. Jangan hapus atau commit file ini.

4. Jalankan

VPS dengan PM2
sudo npm install -g pm2
pm2 start server.js --name gopay-api
pm2 save
pm2 startup   # jalankan perintah yang ditampilkan

Batasan dan catatan

Proyek tidak resmi. Tidak berafiliasi dengan PT GoTo Gojek Tokopedia Tbk atau GoPay. Endpoint yang dipakai bisa berubah sewaktu-waktu. Risiko ditanggung pengguna.

  • Jangan polling agresif. Interval 5 sampai 10 detik sudah cukup. Pengecekan terlalu sering bisa memicu pembatasan akun merchant.
  • Hosting serverless gratis tidak cocok (Vercel, Netlify, Render Free). Container tidur dan file sesi hilang, sehingga harus login OTP ulang.
  • Data QRIS dan klaim transaksi disimpan di memori. Restart server menghapus QRIS yang masih aktif. Karena berlaku 5 menit, dampaknya kecil, tapi hindari restart saat jam ramai.
  • Satu nominal, satu transaksi. Bila dua pembeli membayar nominal sama dalam waktu berdekatan, pembeli kedua bisa menunggu transaksi berikutnya. Untuk toko ramai, tambahkan kode unik kecil ke nominal (misal Rp 25.017).