Dokumentasi Integrasi API MyPG

Panduan teknis untuk menghubungkan aplikasi Hotspot WiFi, Billing PPPoE, Barbershop, Kasir Toko/Warung, Laundry, Cafe, PPOB kecil, maupun web kustom Anda ke gerbang pembayaran QRIS GoPay Merchant MyPG melalui REST API dan Webhook HMAC-SHA256.

Peringatan Kebijakan Penggunaan: MyPG dilarang keras digunakan untuk judi online, gesek tunai (gestun), penipuan, pencucian uang, atau kegiatan lain yang melanggar peraturan perundang-undangan Republik Indonesia. Pelanggaran akan berakibat pemblokiran akun permanen tanpa pengembalian biaya sewa.
Base URL Aktif: https://mypg.my.id

1. Ringkasan & Alur Kerja

Setiap penyewa menggunakan akun GoPay Merchant dan HP Android Listener sendiri. Dana pembayaran masuk langsung ke saldo GoPay Merchant milik penyewa tanpa potongan perantara.

  1. Daftar akun penyewa di halaman pendaftaran, lalu aktifkan masa aktif melalui QRIS di menu Langganan.
  2. Upload gambar QRIS statis GoPay Merchant Anda di menu QRIS & API, isi Webhook URL aplikasi Anda, dan salin API Key.
  3. Install aplikasi MyPG Listener (APK) di HP Android yang login GoPay Merchant, masukkan Server URL dan Listener Token Anda.
  4. Aplikasi Anda memanggil POST /api/gopay/qris/create untuk membuat QRIS dinamis dengan kode unik otomatis (Rp 1 sampai Rp 10).
  5. Saat pembeli membayar QRIS, HP Listener meneruskan notifikasi ke MyPG, lalu MyPG mengirim Webhook HTTP POST ber-signature ke server Anda.

2. Base URL & Autentikasi

Seluruh endpoint transaksi wajib menggunakan HTTPS dan menyertakan API Key milik akun penyewa pada header Authorization.

HTTP Headers
Authorization: Bearer mypg_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Jaga kerahasiaan API Key Anda. Jangan pernah menaruh API Key di kode frontend browser; panggil endpoint MyPG hanya dari backend server Anda.

3. Buat QRIS Dinamis

POST /api/gopay/qris/create

Membuat kode QRIS dinamis baru dengan nominal unik otomatis (prioritas +Rp 1 sampai +Rp 10). Alias POST /api/shopeepay/qris/create juga tersedia dengan format identik.

Field Body Tipe Wajib Keterangan
amount integer Ya Nominal dasar transaksi dalam Rupiah (Rp 100 sampai Rp 20.000.000 sesuai batas maksimal QRIS Bank Indonesia).
order_sn string Opsional Nomor invoice unik dari aplikasi Anda (3-80 karakter: huruf, angka, titik, strip, garis bawah). Dibuat otomatis jika kosong.
expiry_minutes integer Opsional Masa berlaku QRIS dalam menit (5 sampai 60, default 15 menit).
Request (cURL)
curl -X POST "{{ORIGIN}}/api/gopay/qris/create" \
  -H "Authorization: Bearer API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "order_sn": "INV-2026-001",
    "expiry_minutes": 15
  }'
Response JSON (HTTP 200)
{
  "success": true,
  "message": "QRIS berhasil dibuat",
  "data": {
    "order_sn": "INV-2026-001",
    "provider": "gopay",
    "base_amount": 10000,
    "unique_code": 4,
    "amount": 10004,
    "qr_string": "00020101021226...6304ABCD",
    "qr_url": "{{ORIGIN}}/api/qris/image/INV-2026-001?uid=2&sig=...",
    "status": "pending",
    "transaction_status": "pending",
    "expires_at": "2026-11-21T00:18:00.000Z"
  }
}

Tampilkan data.amount (nominal sudah termasuk kode unik) dan gambar data.qr_url (atau render data.qr_string) pada halaman checkout Anda.

4. Cek Status Pembayaran

GET /api/qris/status?order_sn=...

Gunakan endpoint ini sebagai pengecekan cadangan (active polling) dari backend aplikasi Anda untuk memastikan status transaksi terbaru.

Request (cURL)
curl -X GET "{{ORIGIN}}/api/qris/status?order_sn=INV-2026-001" \
  -H "Authorization: Bearer API_KEY_ANDA"
Response JSON saat Lunas (HTTP 200)
{
  "success": true,
  "data": {
    "order_sn": "INV-2026-001",
    "provider": "gopay",
    "base_amount": 10000,
    "unique_code": 4,
    "amount": 10004,
    "status": "paid",
    "transaction_status": "settled",
    "paid": true,
    "paid_at": "2026-11-21T00:05:12.000Z",
    "expires_at": "2026-11-21T00:18:00.000Z"
  }
}

5. Endpoint Uji Koneksi

GET /api/gopay/transactions?limit=1

Endpoint ini digunakan untuk memvalidasi API Key dan status masa aktif akun tanpa membuat transaksi baru (kompatibel dengan tombol Uji Koneksi pada aplikasi Billing PPPoE dan Kasir).

Response JSON (HTTP 200)
{
  "success": true,
  "message": "Koneksi MyPG GoPay aktif.",
  "merchant_name": "NAMA MERCHANT ANDA",
  "data": []
}

6. Webhook & Verifikasi HMAC-SHA256

POST <WEBHOOK_URL_ANDA>

Begitu pembayaran terdeteksi lunas, MyPG mengirim HTTP POST ke Webhook URL yang Anda simpan di menu QRIS & API (mendukung hingga 10 URL sekaligus untuk multi-domain).

Payload JSON yang Dikirim MyPG
{
  "event": "payment.success",
  "data": {
    "order_sn": "INV-2026-001",
    "provider": "gopay",
    "base_amount": 10000,
    "unique_code": 4,
    "amount": 10004,
    "transaction_status": "settled",
    "paid_at": "2026-11-21T00:05:12.000Z"
  }
}

Wajib verifikasi signature webhook memakai HMAC-SHA256 dengan kunci API Key Anda, periksa x-webhook-timestamp (anti-replay, tolak jika selisih > 5 menit), cocokkan amount dengan tagihan, dan pastikan pelunasan bersifat idempotent agar webhook ulangan tidak menggandakan paket atau saldo.

Handler Webhook Aman (Node.js)
const crypto = require('crypto');

app.post('/api/webhook-mypg', (req, res) => {
  const rawBody = JSON.stringify(req.body);
  const ts = String(req.headers['x-webhook-timestamp'] || '');
  const sigV2 = String(req.headers['x-webhook-signature-v2'] || '');

  // 1. Tolak replay jika timestamp lebih dari 5 menit
  const nowSec = Math.floor(Date.now() / 1000);
  if (!ts || Math.abs(nowSec - Number(ts)) > 300) {
    return res.status(401).json({ error: 'Timestamp expired' });
  }

  // 2. Verifikasi HMAC-SHA256 v2 (timestamp + body)
  const expected = crypto
    .createHmac('sha256', process.env.MYPG_API_KEY)
    .update(`${ts}.${rawBody}`)
    .digest('hex');

  const sigBuf = Buffer.from(sigV2);
  const expBuf = Buffer.from(expected);
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 3. Cocokkan amount dan proses secara idempotent (hanya jika status masih pending)
  if (req.body.event === 'payment.success') {
    const { order_sn, amount } = req.body.data;
    // Pastikan order.status === 'pending' && Number(amount) >= Number(order.amount)
  }
  return res.status(200).json({ success: true });
});

7. Kode Status HTTP & Penanganan Error

HTTP Status Arti Tindakan yang Disarankan
200 OK Permintaan berhasil diproses. Baca objek data pada response JSON.
400 Bad Request Parameter tidak valid atau QRIS statis belum diatur. Periksa field amount, order_sn, dan pastikan QRIS statis sudah disimpan di dashboard.
401 Unauthorized API Key kosong atau tidak cocok. Pastikan header Authorization: Bearer <API_KEY> benar.
403 Forbidden Akun suspended atau masa aktif sudah habis. Login ke dashboard MyPG lalu perpanjang masa aktif di menu Langganan.
429 Too Many Requests Melebihi batas rate limit per menit. Tunggu beberapa detik sesuai header Retry-After.

8. Instalasi & Konfigurasi MyPG Listener (Android)

Download APK
Keamanan Akun GoPay Merchant Anda: MyPG tidak pernah meminta nomor HP, OTP, password, atau akses login GoPay Merchant Anda. Aplikasi MyPG Listener hanya membaca teks notifikasi pembayaran masuk di HP Android Anda dan mengirim nominalnya ke server MyPG melalui HTTPS. Dana tetap masuk langsung ke saldo GoPay Merchant Anda sendiri.

Agar setiap pembayaran QRIS terkonfirmasi otomatis secara real-time, install aplikasi MyPG Listener di HP Android yang terpasang aplikasi GoPay Merchant.

  1. Unduh dan pasang APK: Unduh MyPG-Listener.apk melalui tombol Download APK di atas atau dari menu HP Listener di dashboard Anda, lalu ketuk file APK untuk menginstal.
  2. Jika muncul peringatan Google Play Protect: Karena aplikasi ini didistribusikan langsung di luar Play Store, Android akan menampilkan popup keamanan. Ketuk Detail selengkapnya (More details) lalu pilih Tetap instal (Install anyway).
  3. Aktifkan Izin Notifikasi: Buka aplikasi MyPG Listener, ketuk tombol Izin Notifikasi, lalu nyalakan sakelar untuk MyPG Listener.
  4. Khusus Android 13, 14, dan 15 (jika tombol sakelar abu-abu / "Setelan dibatasi"): Buka Pengaturan HP > Aplikasi > MyPG Listener, ketuk ikon titik tiga (⋮) di pojok kanan atas, pilih Izinkan setelan terbatas (Allow restricted settings), lalu kembali aktifkan Izin Notifikasi.
  5. Aktifkan Bebas Baterai: Kembali ke aplikasi MyPG Listener, ketuk tombol Bebas Baterai lalu pilih Izinkan agar sistem Android tidak menghentikan layanan saat layar terkunci.
  6. Hubungkan dengan Token Akun Anda: Salin Server URL dan Listener Token (lst_...) dari menu HP Listener di dashboard web MyPG, tempel ke aplikasi MyPG Listener, lalu ketuk Simpan dan Aktifkan Listener.
  7. Pastikan status Online: Jika muncul pesan koneksi berhasil dan di dashboard menu HP Listener status berubah menjadi Online, instalasi selesai.
Kebutuhan Operasional Keterangan
Koneksi HP Android HP yang terpasang GoPay Merchant dan MyPG Listener harus tetap menyala dan tersambung internet (WiFi atau data seluler). Layar HP boleh dimatikan atau dikunci.
Auto-Start & Auto-Retry Jika HP sempat mati dan menyala kembali, MyPG Listener otomatis berjalan lagi. Jika sinyal internet terputus sesaat, aplikasi otomatis mencoba kirim ulang 3 kali.
Multi-Aplikasi dalam 1 HP Jika Anda memiliki lebih dari satu aplikasi (misal 2 hotspot atau billing PPPoE) yang memakai 1 akun GoPay Merchant yang sama, cukup 1 HP saja dan masukkan semua Webhook URL di menu QRIS & API (1 URL per baris).

9. Monitor Bot Telegram & Pemulihan Akun

Sangat disarankan menghubungkan Bot Telegram di menu HP Listener dashboard Anda agar layanan tetap terpantau dan akun Anda mudah dipulihkan jika lupa password atau username.

  1. Buka @BotFather di Telegram, kirim /newbot, ikuti petunjuknya, lalu salin Bot Token yang diberikan.
  2. Buka chat bot yang baru Anda buat di Telegram, lalu tekan tombol START (/start) agar bot diizinkan mengirim pesan ke Anda.
  3. Buka @userinfobot di Telegram, tekan START, lalu salin angka Id Anda sebagai Telegram Chat ID.
  4. Tempel Bot Token dan Chat ID di menu HP Listener dashboard MyPG, klik Simpan Telegram, lalu klik Tes Kirim Pesan untuk memastikan pesan masuk.

Setelah terhubung, MyPG akan mengirim laporan tiap pembayaran QRIS lunas, mengirim peringatan otomatis jika HP Listener offline lebih dari 12 menit, serta mengirim kode OTP 6 digit jika Anda menggunakan fitur Lupa Akun di halaman login.

10. Ketentuan Layanan & Kontak Support

MyPG adalah penyedia perangkat lunak otomasi QRIS (SaaS) independen dan tidak berafiliasi langsung dengan GoPay atau GoTo Financial. Kepemilikan, kepatuhan jenis usaha, serta kebijakan akun GoPay Merchant sepenuhnya menjadi tanggung jawab masing-masing penyewa sesuai ketentuan penyedia layanan pembayaran terkait. MyPG tidak mengakses login/OTP GoPay dan tidak menampung dana transaksi penyewa.

  • Batas Transaksi & Tarif QRIS: Maksimal Rp 20.000.000 per transaksi sesuai ketentuan QRIS Bank Indonesia. Tarif MDR mengikuti kategori akun GoPay Merchant Anda (untuk Usaha Mikro / UMI: 0% untuk nominal sampai Rp 500.000 dan 0,3% di atas Rp 500.000).
  • Larangan Penggunaan: Dilarang keras digunakan untuk judi online, gesek tunai (gestun), penipuan, pencucian uang, atau kegiatan melanggar hukum. Akun pelanggar akan dinonaktifkan permanen.
  • Keamanan Data: Password disimpan dengan scrypt, API Key dan Listener Token di-hash SHA-256 serta dienkripsi AES-256-GCM, dan data setiap penyewa terisolasi penuh.