Go live — Wallet Collect

Four go-live gates

Wallet Collect enforces four independent gates in code. Each must pass before live collections succeed.

Operator sequence

Complete these steps in order. Sandbox testing is free; live steps require subscription and founder enablement.

1. Sandbox aha path — create a test Payment Order with route: "managed" and confirm ledger + webhook in Test mode.
2. Subscribe (Paystack live) — unlocks live secret keys.
3. Complete ≥5 wallet-accept interviews — founder review (DEC-CTX-040).
4. Founder sets live_funds_enabled — unlocks live Wallet Collect and live fee-wallet top-up.
5. Live fee-wallet top-up — KES STK; TOPUP-* bypasses the fee-wallet balance gate.
6. First live managed collection — debits fee wallet on success.

Subscribe

An active Paystack subscription unlocks live API keys. The org owner completes checkout from the billing page; CarlPay syncs status via webhook.

Operators: see docs/ops/paystack-live-verification.md in the repo for the production verification checklist.

Wallet interviews (DEC-CTX-040)

Before CarlPay enables live Wallet Collect, your organization must complete at least five interviews where the merchant explicitly accepts the Wallet Collect custody model — CarlPay holds merchant collection balances on shortcode 4138969 and debits usage fees from a separate fee wallet.

This gate applies to Wallet Collect only. BYOK and Crosscharge routes are not blocked by live_funds_enabled (DEC-CTX-046).

CarlPay founders enable the flag manually after review. There is no self-serve toggle in the dashboard.

Operator runbook: docs/ops/live-funds-enablement.md — interview log template, SQL enablement, and revocation steps.

Settlement & withdrawals

Wallet Collect credits your merchant balance when a live payment succeeds. That balance is held on CarlPay shortcode 4138969. Wallet disbursements (B2C) require a separate live_payouts_enabled flag after ops enablement — independent of live_funds_enabled. Third-party payouts always need dashboard approval on live.

If you need money on your own Till or PayBill immediately, use Crosscharge or Dedicated BYOK (Settings → Routes). Those routes settle off-platform when M-Pesa succeeds. They are not the same as connected accounts (marketplace seller balances on Wallet Collect).

For marketplaces, create connected accounts (Settings or POST /api/v1/connected_accounts). On managed payments, pass connected_account_id and application_fee_cents so the platform fee credits your merchant balance and the remainder credits the seller ledger. Pay sellers out with source: connected_account payouts — not from the platform wallet.

Reconcile payments from the dashboard (payments list, timeline, ledger, webhooks). Export CSV from Payments, Payouts, or Ledger (status, account, and date filters apply). Operator runbook: docs/ops/reconciliation-v1.md.

Top up before you collect

After live_funds_enabled is set, your first live action must be a fee-wallet top-up — not a customer collection. Live top-up requires the flag but bypasses the fee-wallet balance check because CarlPay assigns a customer_reference prefix of TOPUP-.

Regular managed collections (without the TOPUP- prefix) require fee wallet balance > 0. Top up KES 10–50 from the dashboard, then create your first live Payment Order.

Smoke test

After all gates pass, run this checklist with a small live amount (KES 1–10):

1. Switch the dashboard to Live.
2. Top up the fee wallet (KES 10–50) via STK — confirm TOPUP-* reference.
3. Create a managed Payment Order for KES 1–10 with route: "managed".
4. Complete the STK prompt on the payer phone.
5. Verify ledger entries balance; merchant collection balance credited.
6. Verify fee wallet debited per usage rules.
7. Verify signed webhook delivered (payment_order.succeeded).
8. Confirm STK org is CarlPay (4138969).

Full post-enable steps: docs/ops/live-funds-enablement.md.