#FE: Billing screens (from backend Phase 6)

Frontend spec for backend Phase 6 — Billing: wallet, payments & managed servers — requirements complete 2026-10-05 (written by Pair 1, copied into Pair 2's doc at 07:32, so both backend docs now carry it identically), not built. V8 requirement This phase finally says how credit is bought, which unblocks every screen Phase 7 left hanging: it names the gateways (D-5), keeps the prepaid wallet, and adds a second kind of server that is billed by the hour.

Billing area

Setup — gateways the admin enabled, billing details on the account

Wallet — paid / free / promo credits, add credit, promo code, tax

Cards & automation — saved Stripe card, auto-recharge, low-credit reminder

History — payments, charges, receipts

Managed servers — monthly price list, hourly charges, usage per server

Negative balance — managed servers only

due, powered off, deleted

i18n namespaces: billing.*, billing.wallet.*, billing.cards.*, billing.receipts.*, billing.managed.*, billing.overdue.*.

#Setup & gateways

#	Feature	Screen / control	Rules from the backend doc	Frontend notes
6.1	Payment gateways	Gateway choice inside Add credit	Stripe, PayPal, Instamojo. The admin turns each one on/off and sets test/live mode. The user sees only enabled gateways	Build the picker from the API, never from a hard-coded list of three — a disabled gateway must simply not appear. One enabled gateway → no picker at all, just continue. None enabled → "Payments are temporarily unavailable", no dead button. Test mode must be visible to the user (a badge next to the gateway), otherwise people will think a test payment was real
6.2	Billing details	Billing profile tab	Name, address, country, tax number, stored on the account (the one who pays) and copied onto every receipt	One form, account level — this matches the frontend's account-level pattern (see D-27 on the integrations side). Because the details are copied at payment time, a saved receipt never changes when the profile is edited: say so under the form ("new receipts only"). Country drives the tax the API quotes, so re-quote after it changes

#A. Wallet & adding credit

Note

Resolved 2026-10-06 12:03 — the two docs now agree, and they agree on Pair 1's version. V8 requirement For a few hours they did not: Pair 1 kept V7's "+3 servers per payment" on a separate managed-server limit and recorded the split on purpose, while Pair 2's copy of 6.4 still called the bonus dropped and its 6.9 had no such limit. Pair 2 has now taken Pair 1's wording in full — 6.4 adds +3 per successful payment, including auto-recharge, and 6.9 carries the whole rule: trial and cloud-hosting accounts cannot exceed the limit, it starts from an admin setting (default 1, 10 for redeem-code signups), the admin can change it, and it counts managed servers only. Phase 6 is now identical in both docs.

This site already followed Pair 1, so nothing had to change — and the user-facing answer is the same one it has always been: that limit is invisible, because Bhavik removed the way to create a managed server (D-36). The top-up success message still says only that credit was added, and the only server limit anyone meets is the plan's (D-32).

#	Feature	Screen / control	Rules	Frontend notes
6.3	Wallet	Wallet tab header	Paid, free and promo credits. Promo credits expire. Spent in the same order as V7. V7's separate server credits balance is dropped	Show the three balances separately with one total, because they behave differently: promo credits need an expiry date on the row, and only paid credits can pay for managed servers (6.10). The spend order is "as V7" but is not written out in the backend doc, so the frontend never explains the order — it shows the balances and lets the API do the maths
6.4	Add credit	Add credit `MODAL` → gateway → return page	Minimum amount from settings; maximum $4,000 per payment. Promo codes as V7 — not allowed on the minimum amount or below. Tax as V7 (Instamojo, or Stripe for India). Credits are added only after the gateway confirms, and each payment is credited once. Changed 2026-10-05, contested, and settled on 2026-10-06 (see the note above) V8 requirement: the plan carries the server limit with no bonus, and V7's "+3 per payment" survives on a separate managed-server limit — every successful payment, including auto-recharge, adds +3 to it, and it counts managed servers only (6.9). Both docs now say this	Amount field validates against the API's minimum and the fixed $4,000 maximum, with the amount and the limit in the message. The promo field is disabled with the reason while the amount is at or below the minimum, instead of failing after the user types a code. Show base + tax + discount = total before the button. After the gateway, the return page shows "Confirming payment…" and asks the API — it never trusts the query string, and never adds credit optimistically. The success message says only that credit was added. The "+3" is not on the plan's limit, and the counter it may live on is for managed servers — which users cannot create (D-36), so it is never shown to them. There is still nothing to announce, and claiming the plan allowance moved would be wrong (D-32)
6.6	Low-credit reminder	Auto recharge tab	The user sets a minimum between $1 and $1,000	A single number field next to auto-recharge, since both react to the same balance. Make clear this one only warns and never charges
7.23	Redeem a credit code	Redeem code dialog, reachable from the wallet	Phase 7 (2026-10-05): a redeem code can give credit instead of a plan, and each code works once	Credit from a code is not a payment: there is no gateway, no tax and no receipt. Show it in the wallet history as its own kind of row so the balance still adds up. Full spec: FE: Plans & subscription

#B. Saved cards & auto-recharge

#	Feature	Screen / control	Rules	Frontend notes
6.5	Saved cards	Cards tab	Stripe saved card	Add / set default / remove, with the card entered in Stripe's own fields — card numbers never reach our code. Removing the card that auto-recharge depends on must warn that auto-recharge will stop
6.5	Auto-recharge	Auto recharge tab	When credits fall to the user's minimum, the chosen amount is charged automatically	Switch + minimum + amount, and the switch is blocked with a reason when no card is saved ("Add a card first"). Show the last automatic charge and whether it worked, because the user otherwise only learns from an email. A failed automatic charge needs an in-app banner that matches the email

#C. History & receipts

#	Feature	Screen / control	Rules	Frontend notes
6.7	Payments & charges	Transactions tab	A list of payments and charges	Two kinds of row in one table, so the type must be obvious at a glance (money in vs money out) with a filter for each. Paginated, newest first, from the API only
6.7	Receipts	Receipt view / download	A receipt for every payment, with the billing details and tax	A receipt exists for payments, not for hourly charges — don't show a download link on a charge row. Receipts are produced by the backend; the frontend only opens or downloads them

#D. Managed servers (hourly billing)

#	Feature	Screen / control	Rules	Frontend notes
6.8	Price list	Size picker in the create flow	Monthly price per provider, region and size, set by the admin. Providers: DigitalOcean, Vultr, Linode, Hetzner	Prices come from the API for the chosen provider + region, so the picker re-reads them when either changes. Note the gap: Phase 5 lets a user connect AWS Lightsail with their own token, but there is no managed price list for Lightsail — the managed flow must offer only the four providers the API prices
6.9	Create a managed server	Not built — Conflict D-36	Normal mode: needs credits of at least one month's price, otherwise "please add $X". Trial mode: only the popular sizes unless credits are enough. Managed-server limit (now in both docs — settled 2026-10-06): V8 requirement trial and cloud-hosting accounts cannot exceed it — it starts from an admin setting (default 1, 10 for redeem-code signups), grows +3 per payment (6.4), counts managed servers only, and the admin can change it. The monthly price is saved with the server	Recorded because the backend owns the rule, but the frontend builds no screen for it — which also means the managed-server limit is invisible to users, so none of its numbers appear anywhere: Bhavik removed the "Managed server" choice from the add-server wizard (see the conflict above). If that decision is ever reversed, the review step would need the monthly price, the hourly rate and the balance before the create button, with the exact shortfall and Add credit. Also note "popular sizes" is our reading of the doc's "popular plans" Assumption
6.10	Hourly charging	Nothing to build (a job)	Rate = monthly price ÷ (days in the current month × 24). Full hours only, from paid credits only. One charge record per server per month, each hour charged once	Two consequences the screens must respect: the rate changes between months (February costs more per hour than March), so never cache or recompute it in the browser; and a user with plenty of promo credit can still be refused a managed server, so the "not enough credit" message must mean paid credit
6.11	Usage	Usage tab + a line on the server page	Per server: hours used, amount so far, last charged	One table in Billing for all managed servers plus the same three numbers on each managed server's own page. "Amount so far" is this month's running total, so label it with the month — otherwise it reads as a bill that is due

#E. Negative balance — managed servers only

#	Feature	Rules	What the screens show
6.12	Negative-balance process	One daily process. Starts when paid credits reach 0 or below, and the dates are worked out once and saved. Due date (+4 days): reminders until then → expire date (+3 days) → deletion date (+7 days). Trial: 2 / 2 / 4 days. Those numbers are V7 defaults	Three clearly different states, not one: due, powered off, about to be deleted. Because the dates are saved once, the screens show the stored dates and never recount from today's balance — a user who went negative, topped up and went negative again must not see shifting deadlines. Trial users get the same screens with shorter counters, so every date comes from the API
6.12	What happens on the expire date	Refined 2026-10-05 (reworded the same day to put the deletion first): servers with no apps and no databases are deleted; the others are powered off. Central asks each server's OSS panel whether it has apps or databases	This is the sharpest edge in the phase: on one date, two servers in the same list meet opposite fates, and the empty one is gone for good. So the warning before that date must say which servers will be powered off and which will be deleted, named, not counted — and the only way to save an empty server is to add credit. Note the dependency: the split needs an answer from each server's panel, so an unreachable panel leaves the outcome unknown. The frontend shows what the API says and never guesses from its own app count
6.12	Deletion date	The remaining servers (the ones powered off earlier) are deleted	A powered-off managed server stays in the list with the reason and its deletion date — not looking offline and not looking broken, because the user can still rescue it with credit
6.13	Back to positive	Expanded 2026-10-05: when paid credits go above 0 the process stops and the saved dates are cleared; a trial account leaves trial mode; and powered-off servers are not powered on automatically (all as in V7)	Three things for the screens. The cleared dates mean the banner and every deletion date must disappear after a successful top-up, not linger from cached data. Leaving trial mode changes what the account may do, so re-read the plan and limits too. And the last one is the important one: adding credit does not bring a powered-off server back up — so the success message must not imply it does, and the server keeps a clear "powered off — start it again" state with the deletion threat removed

#Who sees these screens

Billing is the account owner's business, as in V7: the organization permissions for usage, invoices and plan are owner-only unless a role grants them. V7 only Members of someone else's organization see the banners and the consequences, with "Ask the organization owner to add credit" and no pay button — the same rule the plan screens already use.

#Existing users

Case	Rule from the backend doc	What the screens must handle
Wallet	Paid, free and active promo credits carry over	Show the imported balances; an expired promo balance must not appear as spendable
Server credits	V7's separate server-credits balance is dropped and the leftover is added to paid credits	No "server credits" row anywhere, and the V7 user's total must still add up — the migration report is the place that explains the move, not the wallet screen
Cards & automation	Saved Stripe cards, auto-recharge and reminder settings carry over	The forms open pre-filled; never show a migrated user an empty auto-recharge form that implies it is off
Billing details	Carry over	Pre-filled profile
History	Transactions, receipts and charges carry over	The list mixes V7 and V8 history, so it must cope with older rows that have fewer fields
Managed servers	Managed servers and their charges carry over	A migrated managed server already has a monthly price and hours used — the usage screen must not assume it started this month

#What this phase answers

Was open	Now
D-5 Which payment gateway is authoritative?	Stripe, PayPal and Instamojo (6.1), each enabled or disabled by the admin, with test/live mode. The user sees only the enabled ones — so the frontend builds the gateway choice from the API and names no gateway of its own
D-4 (last part) How is credit bought?	Through a gateway top-up: minimum from settings, maximum $4,000, promo codes, tax, and credit added only after the gateway confirms (6.4). The prepaid wallet is now fully specified
Does the wallet keep V7's three balances?	No — two of three. Paid, free and promo stay; server credits are dropped and folded into paid credits at migration (6.3)

#Still open after this phase

~~D-31~~ answered 2026-10-05 (7.12): the plan-expiry outcome depends on the server type — managed servers are powered off at the warning day and deleted at the provider at the lock day, self-managed servers are only removed from Central. Pair 1's and Pair 2's wordings each described one half, so there was no real contradiction.
~~D-32~~ answered 2026-10-05 (6.4): V7's "+3 servers per payment" is dropped. The server limit comes only from the plan, so the usage bar shows the plan's own number and a top-up must not claim the allowance grew.
D-22 Currency and tax: sharper but not answered. Phase 6 says tax is charged "as V7 (Instamojo, or Stripe for India)" and names amounts in $, but no currency rule, no tax calculation and no display rule are written down.
Admin screens for gateways and the managed price list are not in this phase ("admin panel phase"), so the frontend has no admin billing screens yet — only the user side.
Referral / affiliate is still its own phase (D-23).