Payment and payout lifecycle
How money-in and money-out statuses connect, links to the canonical state machine, balances, and webhooks.
Use this page as the merchant-facing map for payment and payout status. For the full transition tables and diagrams, see Payment state machine.
Money in (payments)
| Phase | Typical status | What it means for you |
|---|---|---|
| Customer starts pay | pending | Show a pending UI; do not fulfill |
| Provider confirms | completed | Credit test/live balance; safe to fulfill after verification |
| Timeout / abandon | failed or expired | Release inventory; offer retry |
| Refund issued | refunded | Reverse fulfillment if applicable |
Test vs live: test keys often complete mobile money immediately; live keys stay pending until the customer approves on device.
Money out (payouts and refunds)
Payouts move through pending → processing → completed or failed. Treat completed as “funds left the platform” for withdrawals and beneficiary payouts.
See Payout lifecycle and Refunds.
Balances and settlement
Completed payments update your merchant balance according to fee rules and availability windows. See Balance and settlement.
Webhooks tie it together
Configure webhooks so your system reacts when status changes without polling: