Phase 1 billing is per organization. All apps in a workspace share organization_balances. The ledger is organization_credit_ledger; app_id on entries is attribution only.

Organization pool

When App A verifies a phone, credits are held/captured from the org pool - not a separate app wallet.

Account access vs plan

Account access (trial_outcome) is separate from your subscription/plan. Test keys (pk_test_/sk_test_) and live keys (pk_live_/sk_live_) both use real gateways and consume credits. Account access controls free trial credits and pending review - not whether test keys work.

• Register → verify email → risk evaluation → FULL_TRIAL or SANDBOX_ONLY (no free trial credits)
• Trial credits are granted after email verification - not when you create an app
• SANDBOX_ONLY: no free trial credits; pk_live_ works when the org has balance
• Subscribe to a plan or top up for ongoing credits regardless of trial outcome

Recharge (automatic confirmation)

• Dashboard → Billing → Top up credits tab → enter your wallet payment phone number and the amount → create the request
• Pay from that same wallet number using the shown link / QR (USSD) — the balance is added automatically as soon as the transfer completes; no proof upload needed
• Automatic confirmation runs on verified payment listeners (e.g. InstaPay / Vodafone Cash SMS listeners). If confirmation is temporarily delayed, the order is reviewed by the team and still completes automatically once the listener reconnects
• Credit rate and min/max from platform config (billing.recharge), not hardcoded
• Top-up purchase gate: an active paid plan is required — trial/free accounts must subscribe first, and an expired plan must be renewed first (paid_subscription_required / plan_expired)

Subscribe to a plan (automatic confirmation)

• Dashboard → Billing → Subscribe to plan tab (or Pricing → choose plan → /dashboard/billing?plan=…)
• Pick a billing package + payment method → enter your wallet payment phone number → create the subscription request
• Pay from that number using the shown link / QR (USSD) — the subscription activates automatically when the transfer completes, without uploading any proof
• Fulfillment uses app_subscriptions + org ledger; if automatic confirmation is temporarily unavailable, the team reviews the transfer and activation completes automatically afterwards

Ledger types

CREDIT, HOLD, RELEASE, CAPTURE. View org ledger: GET /v1/organizations/:id/billing/ledger.

Legacy app billing API

GET /v1/apps/:id/billing returns org balance for the app's organization (compatibility shim).

Dashboard

• Developer: /dashboard/billing - org balance, subscribe to plan, top-up credits
• Admin: /admin/billing - trial/abuse, payment methods, recharge queue, subscription request queue