Skip to main content
POST
/
api
/
v1
/
deposits
Initiate a Mobile Money deposit
curl --request POST \
  --url https://payments.winam.cm/api/v1/deposits \
  --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": "https://sportsbook.example.com/webhooks/payments"
}
'
{
  "winam_tx_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "<string>",
  "amount_xaf": 123,
  "operator": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}

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 /deposits

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

USSD notification sent

winam-payments triggers a USSD collection on the merchant SIM. The player receives a phone notification asking them to enter their MoMo PIN.
3

Player confirms

The player confirms on their phone. winam-payments receives an SMS confirmation.
4

Webhook fired

Your callback_url receives a POST with event: "payment.succeeded" (or "payment.failed" if refused or timed out).

​
Notes

Use POST /api/v1/msisdn/detect to automatically detect the player’s operator from their phone number — no need to ask them.
The reference field is your idempotency key. Two calls with the same reference return the same transaction without creating a duplicate. Always use a different reference for each distinct payment. See Idempotency.
The expires_at timestamp in the response indicates when the USSD confirmation window closes (typically +10 minutes). If the player does not confirm before this deadline, the transaction transitions to expired.

​
Response states

statusMeaning
pendingUSSD is being sent to the player’s phone
provider_acknowledgedUSSD sent — player has received the notification
Terminal states arrive via webhook:
EventMeaning
payment.succeededPlayer confirmed payment
payment.failedPlayer refused, timed out, 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

Player MoMo number (E.164)

Example:

"+237670123456"

​
amount_xaf
integer
required

Amount in XAF (min 100). XAF has no sub-unit.

Required range: x >= 100
​
operator
string
required

MoMo operator

Examples:

"mtn"

"orange"

​
reference
string
required

Unique sportsbook reference (idempotency key). Same reference = same transaction returned.

Required string length: 1 - 128
​
callback_url
string | null

POST URL for notification when payment is confirmed or fails.

Example:

"https://sportsbook.example.com/webhooks/payments"

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

Initial state. Typically provider_acknowledged (USSD sent to player) or pending (being sent). Terminal states arrive via webhook.

Example:

"provider_acknowledged"

​
amount_xaf
integer
required

Amount in XAF

Example:

5000

​
operator
string
required

"mtn" or "orange"

Example:

"mtn"

​
expires_at
string<date-time> | null

USSD confirmation deadline (typically +10 minutes from creation). The transaction transitions to expired if the player does not confirm before this time.