Skip to main content
POST
Initiate a Mobile Money withdrawal

How it works

1

Call POST /withdrawals

Your backend sends the player’s MSISDN, amount, and a unique reference.
2

Queued for approval

The withdrawal enters pending_approval state. A Winam operator reviews and approves (or rejects) it from the operator dashboard.
3

Transfer executed

Once approved, winam-payments sends a USSD disbursement to the player’s phone.
4

Webhook fired

Your callback_url receives a POST with event: "payment.succeeded" or "payment.failed".
Withdrawals always return status: "pending_approval" immediately. Do not credit the player before receiving a payment.succeeded webhook. Winam guarantees player payment regardless of partner liquidity.
HTTP 200 does not mean the withdrawal succeeded — it only means the request was accepted and queued. Always read the status field in the response body, and treat the final outcome as the payment.succeeded / payment.failed webhook (or the state from GET /transactions/{id}).

Approval time

Manual approvals typically happen within minutes to a few hours during business hours. Your callback_url will be notified as soon as the outcome is known. If no callback_url is provided, poll GET /api/v1/transactions/{winam_tx_id} for status updates.

Response states

Terminal states arrive via webhook:

Authorizations

X-API-Key
string
header
required

Body

application/json
player_id
string<uuid>
required

Player UUID on the sportsbook side

msisdn
string
required

Recipient MoMo number (E.164)

Example:

"+237670123456"

amount_xaf
integer
required

Amount in XAF (min 100)

Required range: x >= 100
operator
string
required

MoMo operator

Examples:

"mtn"

"orange"

reference
string
required

Unique sportsbook reference

Required string length: 1 - 128
callback_url
string | null

POST URL for withdrawal result notification.

Response

Successful Response

winam_tx_id
string<uuid>
required

Winam internal transaction UUID. Use this with GET /api/v1/transactions/{id}.

reference
string
required

Your idempotency key, echoed back from the request

status
string
required

pending_approval — the withdrawal is queued for manual approval by a Winam operator. Your platform will be notified via webhook when the status changes.

Example:

"pending_approval"

amount_xaf
integer
required

Amount in XAF

Example:

10000

operator
string
required

"mtn" or "orange"

Example:

"mtn"