Lewati ke konten utama

Deposit & Prepaid Topup

Untuk model layanan Prepaid (Prabayar), pelanggan diwajibkan menyetorkan sejumlah dana ke dalam Wallet mereka sebelum dapat membuat atau menyewa Virtual Machine. Pemotongan biaya akan dilakukan setiap jam oleh mesin Cronjob Frog Cloud secara otomatis dari saldo ini.

1. Metode Pembayaran Tersedia​

Sebelum pelanggan mengetik nominal Topup, Frontend wajib menampilkan opsi metode pembayaran (BCA Virtual Account, GoPay, OVO, Kartu Kredit, dll) yang didukung oleh konfigurasi Payment Gateway saat ini.

Request
GET /api/billing/payment-methods

2. Mendapatkan Minimum Topup​

Setiap akun bisa saja memiliki kebijakan nilai ambang batas (threshold) top-up minimum yang berbeda-beda, tergantung konfigurasi sistem atau status promosi. Frontend harus memanggil endpoint ini untuk memvalidasi nilai input yang diketikkan pengguna.

Request
GET /api/billing/topup/minimum

Respons (200 OK): Mereturn nominal angka terkecil yang diizinkan untuk deposit.

3. Membuat Tiket Pengisian Saldo (Create Deposit)​

Setelah pelanggan memasukkan nominal (misal Rp 100.000) dan memilih metode pembayarannya, Frontend mem-POST request ke Backend untuk menerbitkan Invoice Topup.

Request
POST /api/billing/deposit
Content-Type: application/json
Request Body
{
  "amount": 100000,
  "method_code": "BC",
  "gateway_name": "duitku",
  "coupon_code": "MERDEKA45"
}

Catatan Parameter:

  • method_code dan gateway_name didapatkan dari response API Payment Methods.
  • coupon_code bersifat opsional (dapat dilewatkan atau null). Jika kupon valid, benefit kupon (seperti bonus saldo) akan otomatis masuk ke dompet pelanggan setelah pembayaran sukses (Post-Webhook Callback).

Respons (200 OK): Backend akan mendaftarkan transaksi ke Payment Gateway (seperti Duitku/Xendit) dan mengembalikan respons pembayaran yang telah distandardisasi. Bergantung pada metode pembayaran yang dipilih, API dapat mereturn URL Checkout/Redirect, Nomor Virtual Account (VANumber), dan/atau Kode QR (QRString) secara langsung.

Response Body
{
  "message": "success",
  "data": {
    "invoice_id": "c1f76d91-xxx-xxx",
    "payment_url": "https://app.sandbox.duitku.com/webapi/...",
    "status": "Pending",
    "actions": {
      "redirect_url": "https://app.sandbox.duitku.com/webapi/...",
      "va_number": "8923719028371",
      "qr_string": "00020101021126650014ID.CO.QRIS.WWW..."
    }
  }
}

Frontend dapat menggunakan atribut actions di atas untuk langsung menavigasikan URL, menampilkan instruksi Virtual Account, atau me-render gambar QR Code kepada pelanggan.

4. Melacak Riwayat Pengisian Saldo​

Pelanggan dapat melihat daftar tiket deposit (Topup Invoice) yang pernah mereka buat, baik yang sudah lunas (Paid), masih tertunda (Pending), atau kadaluarsa (Expired).

Request (Daftar Riwayat)
GET /api/billing/deposit?page=1&limit=10
Request (Detail Spesifik)
GET /api/billing/deposit/{invoice_id}

5. Ekspor PDF Riwayat Deposit​

Pelanggan korporat seringkali membutuhkan bukti cetak atau PDF dari riwayat pengisian saldo mereka untuk diserahkan ke bagian Finance.

Request
GET /api/billing/deposit/export/pdf

Respons (200 OK): Mereturn Raw Bytes dari dokumen PDF dengan header HTTP Content-Disposition: attachment.