Wallet & Payments
How the wallet works, topping up via payment providers, transaction history, auto top-up, and the referral program.
Every user has a wallet — a pre-loaded credit balance used to pay for plans and renewals. Users fund their wallet through a payment provider; the panel credits the balance when a webhook confirms the payment.
Topping up
Users navigate to /billing/wallet and click Top Up. The flow:
- Select a payment provider (any enabled provider appears as an option)
- Choose an amount — preset options ($5, $10, $25, $50) or a custom amount
- The panel creates a checkout session with the external provider
- The user completes payment on the provider's hosted page
- The provider sends a webhook to
/api/billing/webhook/[provider] - The webhook handler validates the payload, credits the wallet, and records a
topuptransaction
Admins can credit or debit a wallet directly from a user's page at Admin → Users → [user] without going through a payment provider. These show up as adjustment transactions. Referral bonuses and commissions are also recorded with type adjustment.
Transaction types
| Type | When it occurs |
|---|---|
topup | Wallet funded via a payment provider |
charge | A subscription purchase or renewal debits the wallet |
adjustment | Manual admin credit/debit, and referral bonuses/commissions |
refund | Reserved in the schema; nothing in the current code creates a refund transaction |
expired | Reserved in the schema; there is no balance-expiry feature |
The full transaction history is visible to users at /billing/wallet and to admins on the user's page at Admin → Users → [user].
Auto top-up
The wallet has autoTopUpEnabled/threshold/amount columns in the database, but there is currently no setting to configure them and no code that triggers an automatic top-up. This feature does not work yet — treat any mention of it elsewhere as aspirational.
Referral program
The referral program is enabled via the billing_referral_enabled setting in Admin → Billing → Settings.
Users generate a personal referral code in Wallet → Referrals (3–30 characters, alphanumeric plus - and _). When a new user applies the code and then completes their first wallet top-up:
- The referee gets an extra bonus credited to their wallet, on top of the amount they topped up (configurable percentage of the top-up amount) — it is a bonus credit, not a discount on the price they pay
- The referrer gets a commission credited to their wallet (configurable percentage of the referee's top-up)
Rules:
- The code is applied any time before the first top-up (via
applyReferralCode), but the bonus and commission are only credited when that first top-up webhook is processed - Bonuses are awarded only on the referee's first top-up
- A user cannot use their own referral code (self-referral is blocked)
- A user can only ever apply one referral code, ever (attempting a second one fails)
- Each code tracks its total usage count
Configure the bonus and commission percentages in Admin → Billing → Settings → Referrals.