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.
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.
- Daftar akun penyewa di halaman pendaftaran, lalu aktifkan masa aktif melalui QRIS di menu Langganan.
- Upload gambar QRIS statis GoPay Merchant Anda di menu QRIS & API, isi Webhook URL aplikasi Anda, dan salin API Key.
- Install aplikasi MyPG Listener (APK) di HP Android yang login GoPay Merchant, masukkan Server URL dan Listener Token Anda.
- Aplikasi Anda memanggil
POST /api/gopay/qris/createuntuk membuat QRIS dinamis dengan kode unik otomatis (Rp 1 sampai Rp 10). - 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.
Authorization: Bearer mypg_live_xxxxxxxxxxxxxxxxxxxx Content-Type: application/json
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). |
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
}'
const resp = await fetch('{{ORIGIN}}/api/gopay/qris/create', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MYPG_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 10000,
order_sn: 'INV-2026-001',
expiry_minutes: 15
})
});
const result = await resp.json();
// Tampilkan result.data.qr_url dan nominal result.data.amount ke pembeli
$ch = curl_init('{{ORIGIN}}/api/gopay/qris/create');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 10000,
'order_sn' => 'INV-2026-001',
'expiry_minutes' => 15
])
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
{
"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.
curl -X GET "{{ORIGIN}}/api/qris/status?order_sn=INV-2026-001" \
-H "Authorization: Bearer API_KEY_ANDA"
{
"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=1Endpoint 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).
{
"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).
{
"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.
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 });
});
<?php
$rawBody = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$sigV2 = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_V2'] ?? '';
// 1. Tolak replay jika selisih waktu > 5 menit
if (!$ts || abs(time() - (int)$ts) > 300) {
http_response_code(401);
exit('Timestamp expired');
}
// 2. Verifikasi HMAC-SHA256 v2
$expected = hash_hmac('sha256', $ts . '.' . $rawBody, $apiKey);
if (!hash_equals($expected, $sigV2)) {
http_response_code(401);
exit('Invalid signature');
}
// 3. Cocokkan amount dan proses idempotent (hanya jika order masih pending)
$payload = json_decode($rawBody, true);
if (($payload['event'] ?? '') === 'payment.success') {
$orderSn = $payload['data']['order_sn'] ?? '';
$amount = (int)($payload['data']['amount'] ?? 0);
// UPDATE orders SET status='paid' WHERE order_sn=? AND status='pending' AND amount <= ?
}
http_response_code(200);
echo json_encode(['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 APKAgar setiap pembayaran QRIS terkonfirmasi otomatis secara real-time, install aplikasi MyPG Listener di HP Android yang terpasang aplikasi GoPay Merchant.
-
Unduh dan pasang APK: Unduh
MyPG-Listener.apkmelalui tombol Download APK di atas atau dari menu HP Listener di dashboard Anda, lalu ketuk file APK untuk menginstal. - 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).
- Aktifkan Izin Notifikasi: Buka aplikasi MyPG Listener, ketuk tombol Izin Notifikasi, lalu nyalakan sakelar untuk MyPG Listener.
- 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.
- Aktifkan Bebas Baterai: Kembali ke aplikasi MyPG Listener, ketuk tombol Bebas Baterai lalu pilih Izinkan agar sistem Android tidak menghentikan layanan saat layar terkunci.
-
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. - 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.
- Buka
@BotFatherdi Telegram, kirim/newbot, ikuti petunjuknya, lalu salin Bot Token yang diberikan. - Buka chat bot yang baru Anda buat di Telegram, lalu tekan tombol START (
/start) agar bot diizinkan mengirim pesan ke Anda. - Buka
@userinfobotdi Telegram, tekan START, lalu salin angka Id Anda sebagai Telegram Chat ID. - 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-hashSHA-256serta dienkripsiAES-256-GCM, dan data setiap penyewa terisolasi penuh.