> ## 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.
# Withdrawals
> Initiate a Mobile Money withdrawal. Requires manual approval by a Winam operator before execution.
## How it works
Your backend sends the player's MSISDN, amount, and a unique `reference`.
The withdrawal enters `pending_approval` state. A Winam operator reviews and approves (or rejects) it from the operator dashboard.
Once approved, winam-payments sends a USSD disbursement to the player's phone.
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
| `status` | Meaning |
| ------------------ | ----------------------------------------- |
| `pending_approval` | Queued for manual Winam operator approval |
Terminal states arrive via webhook:
| Event | Meaning |
| ------------------- | ------------------------------------------ |
| `payment.succeeded` | Transfer confirmed — player received funds |
| `payment.failed` | Rejected by operator or provider error |
## OpenAPI
````yaml POST /api/v1/withdrawals
openapi: 3.1.0
info:
title: Winam Payments API
description: >
## winam-payments — Mobile Money API
Payment abstraction layer between your **sportsbook or frontend platform**
and Mobile Money providers in Cameroon (MTN MoMo, Orange Money).
### Deposit flow
1. Your platform calls `POST /api/v1/deposits` with a unique `reference`
2. winam-payments triggers a USSD collection on the merchant SIM
3. The player receives a notification on their phone and confirms with their
PIN
4. The confirmation SMS is received → transaction `succeeded`
5. Webhook sent to your `callback_url`
### Withdrawal flow
1. Your platform calls `POST /api/v1/withdrawals`
2. A Winam operator approves manually
3. winam-payments sends the USSD transfer
4. Result webhook sent to your `callback_url`
### Authentication
All requests to `/deposits` and `/withdrawals` must include the header:
```
X-API-Key:
```
In development (`SPORTSBOOK_API_KEY` empty), authentication is disabled.
### Full documentation
See [docs.winampay.de](https://docs.winampay.de) for the complete public
documentation with guides, examples, and interactive playground.
contact:
name: Eins Innovativ
email: support@eins-innovativ.de
version: 0.1.0
servers: []
security: []
tags:
- name: deposits
description: >-
Initiate Mobile Money deposits. The player receives a USSD notification on
their phone to confirm payment.
- name: withdrawals
description: >-
Initiate Mobile Money withdrawals. Requires manual approval from a Winam
operator before execution.
- name: transactions
description: >-
Query and manage existing transactions. Use for status polling or incident
recovery.
- name: providers
description: >-
List available providers and detect the operator from an MSISDN. Use to
populate payment options in your player interface.
- name: security
description: >-
Public key endpoint for verifying JWT signatures on outbound webhooks.
Fetch this key once and cache it.
paths:
/api/v1/withdrawals:
post:
tags:
- withdrawals
summary: Initiate a Mobile Money withdrawal
description: >-
Creates a withdrawal request pending Winam operator approval. The
disbursement is only submitted to the provider after manual approval.
Final result is delivered via webhook to `callback_url`.
**HTTP 200 does not mean the withdrawal succeeded** — it only means the
request was accepted and queued (`status: "pending_approval"`). Always
read the body `status` and treat the webhook (or `state` from `GET
/transactions/{winam_tx_id}`) as the final outcome.
The `msisdn` prefix must match the requested `operator` (Cameroon — MTN:
67x, 68x, 650-654 · Orange: 69x, 655-659). A clear mismatch is rejected
with **422** — critical for payouts, which would otherwise be submitted
on the wrong merchant SIM after human approval. Unknown prefixes are
accepted as-is.
operationId: create_withdrawal_api_v1_withdrawals_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WithdrawalRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WithdrawalResponse'
'422':
description: >-
MSISDN prefix contradicts the requested operator (e.g. a 67x MTN
number with `operator=orange`).
security:
- APIKeyHeader: []
components:
schemas:
WithdrawalRequest:
properties:
player_id:
type: string
format: uuid
title: Player Id
description: Player UUID on the sportsbook side
msisdn:
type: string
title: Msisdn
description: Recipient MoMo number (E.164)
examples:
- '+237670123456'
amount_xaf:
type: integer
minimum: 100
title: Amount Xaf
description: Amount in XAF (min 100)
operator:
type: string
title: Operator
description: MoMo operator
examples:
- mtn
- orange
reference:
type: string
maxLength: 128
minLength: 1
title: Reference
description: Unique sportsbook reference
callback_url:
anyOf:
- type: string
- type: 'null'
title: Callback Url
description: POST URL for withdrawal result notification.
type: object
required:
- player_id
- msisdn
- amount_xaf
- operator
- reference
title: WithdrawalRequest
WithdrawalResponse:
properties:
winam_tx_id:
type: string
format: uuid
title: Winam Tx Id
description: >-
Winam internal transaction UUID. Use this with `GET
/api/v1/transactions/{id}`.
reference:
type: string
title: Reference
description: Your idempotency key, echoed back from the request
status:
type: string
title: Status
description: >-
`pending_approval` — the withdrawal is queued for manual approval by
a Winam operator. Your platform will be notified via webhook when
the status changes.
examples:
- pending_approval
amount_xaf:
type: integer
title: Amount Xaf
description: Amount in XAF
examples:
- 10000
operator:
type: string
title: Operator
description: '`"mtn"` or `"orange"`'
examples:
- mtn
type: object
required:
- winam_tx_id
- reference
- status
- amount_xaf
- operator
title: WithdrawalResponse
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
````