Integrasi Payment Gateway¶

Payment Gateway (PG) memungkinkan pelanggan bayar online dengan QRIS, e-wallet (OVO/DANA/GoPay/ShopeePay), virtual account bank, atau transfer langsung — tanpa perlu Anda konfirmasi manual. Pembayaran sukses akan otomatis mark invoice sebagai LUNAS di TB Radius.

Pilihan Payment Gateway¶

TB Radius support 4 payment gateway populer di Indonesia:

Gateway	Method	Setup	Fee Transaksi
Tripay	QRIS, VA bank, e-wallet, retail (Alfamart/Indomaret)	Mudah, signup self-service	Mulai 0.7% per transaksi
Midtrans	QRIS, VA, e-wallet, credit card	Standar, butuh KYC	0.7% (QRIS), 2% (CC)
Xendit	QRIS, VA, e-wallet, retail	Standar, full SaaS	0.7-2.5%
Duitku	QRIS, VA, e-wallet, retail	Mudah, mirror Tripay	0.7-1.5%

Saran: Untuk ISP kecil-menengah, Tripay atau Duitku paling cepat onboarding. Untuk skala besar atau butuh fitur enterprise, pakai Midtrans atau Xendit.

Persyaratan¶

✅ Punya akun di payment gateway pilihan (signup sendiri dulu di website mereka)
✅ KYC verified (KTP + rekening bank atas nama tenant)
✅ Dapat kredensial API:
API Key (production)
Private Key / Merchant Code
Callback secret / signature key
✅ Domain TB Radius (app.tbradius.com atau custom) accessible dari internet (untuk webhook callback)

Arsitektur Payment Flow¶

[Pelanggan] 
   ↓ klik "Bayar Sekarang" di portal
[TB Radius] 
   ↓ create transaction → POST ke PG
[Payment Gateway] 
   ↓ generate VA/QRIS/link
[Pelanggan]
   ↓ bayar via app bank/e-wallet
[Payment Gateway]
   ↓ webhook callback (POST)
[TB Radius] 
   ↓ verify signature → mark invoice paid
[Pelanggan menerima notif] ← WhatsApp/email konfirmasi

Langkah Setup (Generic)¶

Buat akun di website PG pilihan Anda:

Selesaikan KYC (upload KTP & data rekening bank tenant Anda).

2. Dapat Kredensial API¶

Setelah akun aktif, masuk ke dashboard PG → menu "Integration" atau "API Keys". Salin:

API Key / Server Key
Private Key / Secret Key
Merchant Code / Merchant ID

Jangan share kredensial ini ke siapapun selain tim teknis Anda.

3. Set Webhook URL di Dashboard PG¶

Beritahu PG kemana kirim callback saat ada pembayaran sukses:

Gateway	Webhook URL
Tripay	`https://app.tbradius.com/tagihan-webhook/tripay`
Midtrans	`https://app.tbradius.com/tagihan-webhook/midtrans`
Xendit	`https://app.tbradius.com/tagihan-webhook/xendit`
Duitku	`https://app.tbradius.com/tagihan-webhook/duitku`

Paste URL di field "Callback URL" / "Webhook URL" di dashboard PG.

4. Aktifkan di TB Radius¶

Buka Settings → Payment Gateway
Pilih PG yang mau diaktifkan
Toggle Active
Paste kredensial:
API Key
Private/Secret Key
Merchant Code
Pilih mode:
Sandbox / Test — untuk testing (tidak ada uang real)
Production / Live — uang real
Klik Simpan

5. Test Pembayaran¶

Wajib test dengan transaksi sungguhan kecil sebelum go-live:

Bikin invoice test dengan nominal minimal (mis. Rp 1.000)
Klik "Bayar Sekarang" di portal pelanggan dummy
Pilih method (QRIS recommended — paling cepat)
Bayar via app bank/e-wallet Anda
Cek dalam 1-2 menit:
Status invoice berubah jadi PAID ✅
Pelanggan terima notif konfirmasi via WhatsApp/email
Dana masuk ke dashboard PG (tunggu settlement, biasanya T+1 atau T+2)

Best Practices¶

Pakai sandbox untuk development

Saat setup awal, gunakan mode Sandbox/Test dulu. Tidak ada uang real, tapi flow integrasi 100% sama dengan production. Bisa test berkali-kali tanpa biaya.

Aktifkan multiple PG

Best practice: aktifkan 2-3 PG sebagai fallback. Kalau 1 PG down (jarang tapi terjadi), pelanggan bisa pilih PG lain. Pelanggan happy, revenue tidak hilang.

Set fee per metode

Beberapa PG support different fee per method (QRIS 0.7%, VA 0.5%, CC 2.5%). Set di dashboard PG. Anda bisa pilih: charge fee ke pelanggan (mereka bayar +fee) atau absorb (Anda nett).

Keamanan kredensial

Jangan commit API key ke git/repository
Jangan share via WhatsApp/email
Rotate key periodically (mis. tiap 6 bulan)
Set IP whitelist di dashboard PG kalau supported (limit hanya IP server TB Radius)

Settlement bukan instan

Pembayaran masuk bukan langsung cair ke rekening Anda. Biasanya:

T+1 = uang masuk besok (Tripay/Duitku QRIS)
T+2 = lusa (e-wallet, VA bank tertentu)
T+7 = 1 minggu (credit card di beberapa PG)

Cek schedule settlement di dashboard PG.

Troubleshooting¶

Pembayaran sukses tapi invoice tetap UNPAID

Penyebab umum:

Webhook URL salah — cek di dashboard PG, harus persis match dengan TB Radius
Webhook signature tidak valid — kredensial private key di TB Radius beda dengan di dashboard PG. Re-paste private key
Webhook di-block firewall — pastikan IP PG ada di whitelist (kalau pakai whitelist)
Log webhook ada error — cek log di TB Radius (menu Settings → Webhook Log)

Pelanggan klik "Bayar" → error "Gateway not configured"

PG belum diaktifkan untuk tenant ini. Cek Settings → Payment Gateway → pastikan toggle ON.

QRIS dynamic dari TB Radius tidak bisa di-scan

Beberapa penyebab:

QRIS expired (default expire 1 jam) — generate ulang
Nominal di bawah minimum QRIS (Rp 1.000) atau di atas maksimum (Rp 10 juta)
Aplikasi pembayar (m-banking) belum support QRIS dynamic dari merchant aggregator

Fee transaksi terlalu tinggi

Negosiasi langsung dengan PG. Volume transaksi besar = leverage tawar fee lebih rendah. Hubungi sales PG, jangan hanya pakai pricing publik.

Pembayaran refund — bagaimana?

Refund harus dilakukan manual via dashboard PG (TB Radius tidak handle refund). Setelah refund di PG, edit invoice di TB Radius:

Tandai status: Refunded
Add note: alasan refund
Kalau pelanggan masih aktif, generate invoice baru (kalau perlu)

FAQ¶

Q: Bisa pakai PG yang tidak ada di list (mis. Doku, FasPay)? A: Saat ini official support 4 PG. Kalau Anda butuh PG lain, hubungi support — bisa diatur via custom integration (paket berbayar).

Q: Pembayaran cash/transfer manual masih bisa? A: Bisa. Anda atau staff Anda input manual via dashboard → fitur "Pembayaran Manual". Lihat: Pembayaran Manual.

Q: Fee TB Radius selain fee PG? A: TB Radius tidak charge transaction fee tambahan. Fee yang Anda bayar hanya fee dari PG langsung. TB Radius hanya charge subscription (paket bulanan/tahunan).

Q: Bisa lihat laporan revenue per PG? A: Bisa. Dashboard → Laporan → Revenue per Payment Gateway menampilkan total transaksi per PG, breakdown per method, dan fee yang dibayar.

Q: Multi-tenant — apakah tiap tenant pakai PG masing-masing? A: Ya. Tiap tenant config PG sendiri (account & kredensial sendiri). Dana masuk ke rekening tenant masing-masing, bukan ke TB Radius.