State Machine - Winam Payments API

Deposit states

State	Description
`pending`	Transaction created, USSD being sent
`provider_acknowledged`	USSD sent — player has received the notification on their phone
`succeeded`	Player confirmed with PIN — payment received on merchant SIM
`failed`	Player refused, timeout, or provider error
`expired`	Confirmation window (`expires_at`) passed without player confirmation
`requires_manual_resolution`	A confirmation (operator SMS/USSD) arrived after the deposit expired or failed. The money may have been received, so it is held for a Winam operator to confirm or reject — never auto-credited. Not a terminal state.

A deposit only reaches requires_manual_resolution via a late confirmation. No webhook is sent in this state — it fires when the operator resolves it to succeeded or failed.

Withdrawal states

State	Description
`pending_approval`	Awaiting manual approval from a Winam operator
`approved`	Approved — being submitted to the provider
`provider_submitted`	USSD transfer sent. Transient: a successful USSD response is final for a withdrawal, so the transaction moves straight to `succeeded` in the same step
`succeeded`	Transfer confirmed — player received funds (the operator `provider_tx_id` may be backfilled from the SMS afterwards, without re-sending the webhook)
`failed`	Rejected by operator, provider refusal, or insufficient SIM balance
`requires_manual_resolution`	Transaction stuck — human intervention required (escalated automatically after 1 hour)

Terminal states & webhooks

Only the two terminal states trigger a webhook to your callback_url:

Event	Terminal state
`payment.succeeded`	`succeeded`
`payment.failed`	`failed`

requires_manual_resolution is not terminal and sends no webhook. It is a holding state awaiting a Winam operator decision; once resolved to succeeded or failed, the matching webhook is sent.