State Machine - Winam Payments API

Deposit states

State	Description
`pending`	Transaction created, waiting for the player. Merchant-initiated: the payment request is sent to the player’s phone. Customer-initiated: the player has to dial the code shown in `instructions`
`provider_acknowledged`	The provider acknowledged the payment request (merchant-initiated). A customer-initiated deposit normally goes from `pending` straight to `succeeded`
`succeeded`	Payment received
`failed`	Player refused, or provider error
`expired`	`expires_at` passed without a confirmed payment
`requires_manual_resolution`	A payment confirmation arrived after the deposit expired or failed and could not be completed automatically. The money may have been received, so the deposit is held for a Winam operator to confirm or reject. Not a terminal state.

The two collection modes differ on late payments:

	Payment confirmed after `expires_at`
`merchant_initiated`	`expired` → `requires_manual_resolution` → `succeeded` or `failed` after a Winam operator decision
`customer_initiated`	`expired` → `succeeded` automatically when the payment matches the deposit. A payment that does not match (other amount, other merchant number) leaves the deposit `expired` until a Winam operator reviews it; if validated, it goes through `requires_manual_resolution` to `succeeded`

No webhook is sent while a deposit is in requires_manual_resolution. It is sent 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

These states trigger a webhook to your callback_url:

Event	State	Applies to
`payment.succeeded`	`succeeded`	Deposits and withdrawals
`payment.failed`	`failed`	Deposits and withdrawals
`payment.expired`	`expired`	Deposits

For a customer-initiated deposit, payment.succeeded can follow payment.expired for the same winam_tx_id. See Webhooks. 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.