> ## 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.
# Deposits
> Initiate a Mobile Money deposit. The player receives a USSD notification to confirm with their PIN.
## How it works
Your backend sends the player's MSISDN, amount, and a unique `reference`.
winam-payments triggers a USSD collection on the merchant SIM. The player receives a phone notification asking them to enter their MoMo PIN.
The player confirms on their phone. winam-payments receives an SMS confirmation.
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 deposit endpoint rejects with **422** any request whose `msisdn` prefix clearly contradicts `operator` (MTN: 67x/68x/650-654 · Orange: 69x/655-659).
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](/api-reference/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`.
**HTTP `200` does not mean the deposit succeeded.** A `200` only means the
request was processed — always read the `status` field in the response body.
The deposit USSD is initiated synchronously, so a deposit that the operator
rejects at initiation (invalid number, amount below the operator minimum,
USSD error…) comes back as `200` with `status: "failed"`. The reason is
available in the `state_reason` field of `GET /api/v1/transactions/{winam_tx_id}`.
## Response states
| `status` | Meaning |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `pending` | USSD is being sent to the player's phone |
| `provider_acknowledged` | USSD sent — player has received the notification |
| `failed` | Operator rejected the deposit at initiation (see `state_reason` via `GET /transactions/{id}`) |
Terminal states arrive via webhook:
| Event | Meaning |
| ------------------- | -------------------------------------------- |
| `payment.succeeded` | Player confirmed payment |
| `payment.failed` | Player refused, timed out, or provider error |
## OpenAPI
````yaml POST /api/v1/deposits
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/deposits:
post:
tags:
- deposits
summary: Initiate a Mobile Money deposit
description: >-
Creates a deposit request and submits the USSD collection to the
provider. If `reference` already exists, returns the existing
transaction (idempotent). Final confirmation is delivered via webhook to
`callback_url`.
**HTTP 200 does not mean the deposit succeeded.** The response is
returned synchronously after the merchant USSD is initiated: a deposit
rejected by the operator at initiation comes back as `200` with `status:
"failed"`. Always read the body `status`; the failure cause is in
`state_reason` via `GET /transactions/{winam_tx_id}`.
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** before any USSD is sent; unknown prefixes are accepted
as-is.
operationId: create_deposit_api_v1_deposits_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DepositRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DepositResponse'
'422':
description: >-
MSISDN prefix contradicts the requested operator (e.g. a 655… Orange
number with `operator=mtn`).
security:
- APIKeyHeader: []
components:
schemas:
DepositRequest:
properties:
player_id:
type: string
format: uuid
title: Player Id
description: Player UUID on the sportsbook side
msisdn:
type: string
title: Msisdn
description: Player MoMo number (E.164)
examples:
- '+237670123456'
amount_xaf:
type: integer
minimum: 100
title: Amount Xaf
description: Amount in XAF (min 100). XAF has no sub-unit.
operator:
type: string
title: Operator
description: MoMo operator
examples:
- mtn
- orange
reference:
type: string
maxLength: 128
minLength: 1
title: Reference
description: >-
Unique sportsbook reference (idempotency key). Same reference = same
transaction returned.
callback_url:
anyOf:
- type: string
- type: 'null'
title: Callback Url
description: POST URL for notification when payment is confirmed or fails.
examples:
- https://sportsbook.example.com/webhooks/payments
type: object
required:
- player_id
- msisdn
- amount_xaf
- operator
- reference
title: DepositRequest
DepositResponse:
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: >-
Initial state. Typically `provider_acknowledged` (USSD sent to
player) or `pending` (being sent). Terminal states arrive via
webhook.
examples:
- provider_acknowledged
amount_xaf:
type: integer
title: Amount Xaf
description: Amount in XAF
examples:
- 5000
operator:
type: string
title: Operator
description: '`"mtn"` or `"orange"`'
examples:
- mtn
expires_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Expires At
description: >-
USSD confirmation deadline (typically +10 minutes from creation).
The transaction transitions to `expired` if the player does not
confirm before this time.
type: object
required:
- winam_tx_id
- reference
- status
- amount_xaf
- operator
title: DepositResponse
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
````