Billing & Wallet Top-Ups

The prepaid wallet model

Your balance lives in two pools that spend together:

• Extra pool — one-time top-ups plus your signup starter credit ($5 by default for a new account). This balance does not expire on its own.
• Subscription pool — refreshed each billing period when you are on a paid plan. A subscription credits more wallet balance per dollar than a 1:1 top-up: monthly plans add a +10% bonus and yearly plans +20% (a $50/mo plan credits about $55 of wallet balance).

Both pools are shown, rounded to cents, in the Billing tab of the web app.

Buying a credit pack (the Stripe flow)

Three one-time packs are offered, each credited 1:1 (no bonus today):

Pack         Price    Wallet credit
$10 Credits  $10      $10
$50 Credits  $50      $50
$200 Credits $200     $200

The flow, step by step:

• The app lists packs from GET /api/topup/packs and you pick one.
• POST /api/checkout/topup creates a Stripe Checkout session in one-time payment mode and returns a redirect URL. You enter card details on Stripe’s hosted page.
• On success Stripe redirects back to Prowl. A background Stripe webhook credits your wallet; if that webhook lags, the redirect page also calls POST /api/checkout/topup/verify as a fallback.

Crediting is idempotent: both the webhook and the verify fallback key the grant on checkout:<session_id>, so whichever arrives first credits the pack and the other is a no-op. You are never double-credited for one purchase.

Declined cards, cancels & pending payments

A card that Stripe declines is handled entirely on Stripe’s checkout page — the charge does not go through, so no money moves and no credit is granted. You can retry with another card or back out.

• You cancel / abandon checkout — Stripe returns you to Prowl with no charge and no wallet change.
• Payment not yet settled (e.g. an async bank debit that has not cleared) — verify returns HTTP 200 with a pending status and grants nothing yet. Prowl only credits once the funds actually settle, so you are never credited before payment clears.

Because the wallet is credited strictly on settled payment, a failed or cancelled top-up simply leaves your existing balance untouched.

Receipts & managing billing

Payments run through Stripe Checkout, and Stripe emails a receipt to your account email for every successful charge — that emailed receipt is your record of the transaction. Prowl does not host its own separate receipts page.

If you are on a paid plan, the manage subscription button opens the Stripe Customer Portal (POST /api/billing/portal), Stripe’s own self-service page where you can view invoices and payment history, update your card, and change or cancel your subscription.

Refund policy

Wallet credits are prepaid. Prowl does not advertise an automatic money-back guarantee: per the Terms of Service, refunds are handled on a case-by-case basis at Prowl’s discretion. If a top-up charge is refunded or charged back through Stripe, Prowl automatically claws the corresponding credit back out of your extra pool (proportionally for a partial refund), so a reversed payment does not leave spendable credit behind.

Rate limits, coupons & errors

Every billing endpoint (top-up, verify, subscribe, change, cancel, coupon redeem) is throttled per user at 5 requests per 60 seconds. Exceeding it returns HTTP 429 with a Retry-After header — wait a moment and retry.

Other responses you may see:

• 400 for an unknown pack slug — message Credit pack '<slug>' not found.
• 502 Payment provider error when Stripe itself is unreachable or errors.

Coupons / access codes: if you have a code, redeem it under Billing (POST /api/coupon/redeem). A valid code adds wallet credit and refreshes your balance; an invalid, expired, or already-used code returns HTTP 400 with an explanatory message.