Statuses and accounting

Statuses

Status	Meaning	Vendor action
pending	Provider accepted, delivery not yet confirmed	keep the user's hold; poll
paid	Provider confirmed	release value / mark withdrawal complete
failed	Definitive rejection; vendor funds released	refund the user's hold
reversed	Provider reversed a paid payout (up to 30 days later)	reconcile with finance
needs_review	Outcome uncertain; funds held; ops investigating	keep the hold
cancelled	Cancelled before submission (batches only)	refund the hold

Only paid completes a withdrawal. OTT cash and bank payouts are checked for 30 days after payment. Vouchers return paid, failed, or needs_review, never pending. Paid vouchers are not polled automatically. Operator reversals are recorded through an explicit status check and require finance reconciliation. After a voucher timeout or Flash 409, retain the hold and poll the payout. The worker reads the existing gateway transaction by UUID or searches for the exact merchant reference, with bounded pages and work per run. It never purchases again. If recovery cannot find unambiguous evidence, the hold remains for operator review.

Accounting boundary

The vendor's gateway balance (prefunded, amount + fee reserved per payout) and the vendor's own user balances (e.g. USSD agent wallets) are different ledgers. Debit each exactly once: hold the user balance on request, release it on failed/cancelled, finalise on paid. Never pay the same entitlement through two channels.