Skip to main content
POST
/
api
/
v1
/
withdrawals
Initiate a Mobile Money withdrawal
curl --request POST \
  --url https://payments.winam.cm/api/v1/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "player_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "msisdn": "<string>",
  "amount_xaf": 101,
  "operator": "<string>",
  "reference": "<string>",
  "callback_url": "<string>"
}
'
{
  "winam_tx_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "<string>",
  "amount_xaf": 123,
  "operator": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.winampay.de/llms.txt

Use this file to discover all available pages before exploring further.

​
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.

​
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

statusMeaning
pending_approvalQueued for manual Winam operator approval
Terminal states arrive via webhook:
EventMeaning
payment.succeededTransfer confirmed — player received funds
payment.failedRejected by operator or provider error

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"