Lompat ke konten utama
StableTerakhir diperbarui: 11 Nov 2026, 18.07

Panduan Top-up Saldo, Faktur Pajak & Ambang Batas

Ketersediaan saldo koin komputasi (Pay-As-You-Go) menentukan kelancaran operasional bot WhatsApp dalam melayani percakapan pelanggan. Modul ini menjelaskan secara detail alur pengisian saldo (top-up), parameter ambang batas transaksi, perhitungan konversi dari Rupiah ke token, serta mekanisme penerbitan faktur pajak otomatis berdasarkan kode sumber sistem.

Stable

1. Ikhtisar & Nilai Bisnis

Manajemen saldo komputasi dirancang untuk mencegah interupsi layanan pada saat volume percakapan sedang tinggi, dengan berpegang pada pengaturan ambang batas peringatan dan rekonsiliasi yang transparan:

  • Pengisian Instan Berbasis Gateway: Dukungan integrasi webhook untuk saluran QRIS dan Virtual Account (VA) memastikan saldo bertambah ke dalam dompet (wallet) secara langsung setelah pembayaran sukses divalidasi oleh sistem.
  • Konversi Nilai Token Tetap: Sistem memetakan nilai konversi token terhadap nominal Rupiah (IDR) secara pasti. Secara bawaan, konfigurasi menetapkan bahwa Rp 1 setara dengan 1 Token.
  • Akumulasi Top-Up Lifetime (cumulative_paid_topup): Saat mode Lifetime Top-Up atau Hybrid aktif, setiap pembayaran top-up berbayar (berdasarkan nominal pokok principal_amount sebelum PPN, biaya gateway, atau kode unik) menambah progres akumulasi tier secara permanen. Saldo bonus trial maupun bonus promo tidak ikut dihitung ke ambang tier.
  • Penerbitan Faktur Terdokumentasi: Setiap transaksi yang berhasil akan menghasilkan faktur (invoice) dalam format PDF yang tunduk pada pengaturan perpajakan (PPN), baik secara eksklusif maupun inklusif, sesuai konfigurasi global platform.
  • Pengendalian via Ambang Batas (Alert Threshold): Sistem memantau anggaran cabang (branch budget) dan memberikan peringatan ketika pemakaian mendekati persentase batas yang ditetapkan (bawaan 80%), menghindari habisnya saldo tanpa disadari.
Sistem Tidak Mendukung Auto-Topup

Meskipun peringatan saldo rendah berjalan secara otomatis, sistem platform tidak melakukan pemotongan kartu kredit atau dompet digital secara otomatis (auto-topup) ketika saldo habis. Seluruh proses penambahan saldo (top-up) wajib diinisiasi secara manual oleh merchant.

2. Alur Visual & Antarmuka

Berikut adalah cuplikan antarmuka dari jendela pengisian saldo (top-up) dan dasbor riwayat mutasi penagihan pada aplikasi:

Modal pengisian saldo koin via QRIS instan Midtrans atau Xendit
Dialog pemilihan nominal saldo dan pembayaran QRIS instan
Riwayat transaksi pemotongan saldo, status invoice, dan unduh faktur billing PDF
Dasbor riwayat mutasi saldo dan faktur langganan

3. Panduan Langkah-demi-Langkah Pengisian Saldo

Berikut adalah prosedur teknis alur pembuatan tagihan (invoice) top-up melalui dasbor:

  1. 1

    Langkah 1: Inisiasi Top-up di Dasbor

    Buka halaman Tagihan & Saldo dan pilih menu untuk melakukan top-up. Sistem akan meminta Anda memasukkan nominal pengisian. Anda dapat memilih prasetel (jika tersedia) atau memasukkan angka nominal kustom.

  2. 2

    Langkah 2: Validasi Nominal Top-up

    Sistem (backend) akan memvalidasi nominal berdasarkan pengaturan global aktif. Secara bawaan, pengisian kustom memenuhi batas minimum Rp 50.000 (mengikuti billing.topup_min_amount yang dinamis dan tersinkron dengan billing.topup_presets.custom_min_amount), maksimal Rp 10.000.000, serta mengikuti kelipatan yang berlaku (bawaan Rp 1.000). Jika syarat ini tidak terpenuhi, sistem akan menolak permintaan top-up.

  3. 3

    Langkah 3: Perhitungan Pajak dan Biaya Gateway

    Sebelum tagihan (invoice) diterbitkan, sistem akan mengevaluasi konfigurasi pajak global. Jika pajak diaktifkan, PPN 11% akan dihitung (berdasarkan model exclusive atau inclusive) dan ditambahkan ke total akhir yang harus dibayarkan.

  4. 4

    Langkah 4: Pembayaran via Gateway (QRIS/VA)

    Pilih metode pembayaran (contoh: QRIS atau VA). Sistem mengirimkan instruksi ke payment gateway (Midtrans/Xendit) untuk menghasilkan tautan atau kode pembayaran. Selesaikan transaksi menggunakan aplikasi perbankan Anda.

  5. 5

    Langkah 5: Rekonsiliasi Webhook dan Penambahan Saldo

    Setelah pembayaran berhasil, payment gateway mengirimkan webhook ke sistem. Sistem memvalidasi integritas data, menandai tagihan sebagai lunas (paid), mengkreditkan saldo token (dengan rasio bawaan 1 IDR = 1 Token), memperbarui akumulasi cumulative_paid_topup dari pokok pembayaran (untuk evaluasi tier Lifetime bila aktif), dan menghasilkan dokumen PDF final.

4. Parameter & Spesifikasi Teknis Billing

Tabel berikut menjabarkan parameter spesifik dari kode sumber terkait batas transaksi, pajak, dan perilaku penagihan:

Parameter Teknis Kunci Konfigurasi / Kode Nilai Ambang Batas / Perilaku
Batas Minimum Top-up billing.topup_min_amount / custom_min_amount Dinamis — bawaan Rp 50.000 (Transaksi di bawah nilai aktif ditolak)
Batas Maksimum Top-up topup_max_amount Rp 10.000.000
Kelipatan Transaksi multiple Harus kelipatan Rp 1.000
Konversi IDR ke Token tokens_per_idr Bawaan 1 Token per Rp 1 (Tergantung konfigurasi merchant)
Ambang Batas Peringatan alert_threshold_pct Bawaan 80% dari alokasi anggaran cabang
Pengaturan Pajak (PPN) invoice_tax_enabled, tax_percentage Bawaan Tidak Aktif (False). Jika aktif, standar pajak 11% (0.11)
Model Perhitungan Pajak invoice_tax_model Exclusive (Ditambahkan pada pokok) atau Inclusive
Batas Tagihan Manual maxPending Maksimal 3 tagihan pending, 10 tagihan per hari

5. Konsep Sistem Khusus dan Relasi

Sistem tagihan memiliki beberapa mekanisme unik yang berdampak pada siklus hidup dompet saldo Anda.

Kebijakan Pengembalian (Refund) dan Reservasi

Sistem tidak menyediakan fitur pencairan saldo koin menjadi uang tunai (cash refund) dalam alur kodenya. Namun, sistem mengimplementasikan refund internal (pengembalian token). Contohnya, saat pemrosesan Language Model (LLM), sistem akan mereservasi sejumlah token (category = 'chat_reserve'). Jika proses menghabiskan token lebih sedikit dari reservasi, sisa token akan dikembalikan ke dompet merchant dengan category = 'refund' dan reference_type = 'reservation'.

Perilaku Saat Saldo Kosong (Insufficient Balance)

Jika saldo token (Wallet) tidak mencukupi atau mencapai Rp 0, sistem menolak seluruh layanan berbayar. Handler pengiriman pesan (chat), pembuatan OTP, atau pemrosesan basis pengetahuan (KB) akan langsung mengembalikan galat INSUFFICIENT_BALANCE. Akibatnya, bot akan gagal membalas pelanggan. Pemilik harus melakukan top-up untuk mengaktifkan kembali layanan (tidak ada skema auto-billing).

Untuk melihat informasi kaitan fitur dengan arsitektur ini, Anda dapat merujuk pada integrasi silang berikut: lihat konsep pemotongan pada Fitur Tagihan dan detail katalog lengkap pada Paket & Harga.

6. Pemecahan Masalah (Troubleshooting)

Gejala Masalah Penyebab Solusi Tindakan
Gagal membuat tagihan top-up kustom Nominal yang dimasukkan di bawah batas minimum aktif (billing.topup_min_amount, bawaan Rp 50.000) atau bukan kelipatan yang berlaku. Pastikan memasukkan angka sesuai parameter minimal dan kelipatan aktif (contoh: 50.000, 100.000).
Bot WhatsApp berhenti membalas (Drop) Saldo habis dan memicu galat INSUFFICIENT_BALANCE di dalam sistem. Segera lakukan inisiasi top-up melalui dasbor. Bot otomatis aktif setelah webhook diterima.
Notifikasi peringatan anggaran tidak muncul Ambang batas (alert_threshold_pct) belum tersentuh atau budget tidak diatur. Periksa apakah pemakaian sudah melebihi 80% dari anggaran yang ditetapkan di cabang.
Token yang dipotong LLM terasa lebih tinggi di awal Sistem menerapkan potongan reservasi sementara (chat_reserve). Sisa token reservasi yang tak terpakai akan otomatis di-refund kembali pada akhir eksekusi pesan.

7. Referensi Terkait

content/docs/pricing/topup-billing.mdx
Terakhir diperbarui: 11 Nov 2026, 18.07

Dokumentasi teknis DagangBot