Overview

What is winam-payments?

winam-payments is a payment abstraction layer between your sportsbook or frontend platform and Mobile Money providers in Cameroon (MTN MoMo, Orange Money).

Sportsbook / Frontend ──── POST /deposits ────► winam-payments ◄───► MTN MoMo / Orange Money
                           POST /withdrawals ►
                           GET  /transactions ►                 ────► webhook callback

What you need to implement

Initiate a payment

Call POST /api/v1/deposits or POST /api/v1/withdrawals with your unique reference key.

Handle both deposit collection modes

Depending on the operator, the player either confirms a payment request sent to their phone, or dials a USSD code that you display. Read collection_mode in the deposit response and render instructions when present. See Deposit collection modes.

Expose a webhook endpoint

Provide a callback_url that accepts POST JSON requests — this is where winam-payments sends the payment outcome.

Verify webhook signatures

Each webhook includes an X-Winam-Signature header (t=<unix>,v1=<hex>, HMAC-SHA256 with your application’s webhook secret). See Webhooks.

Always read the status field

A 200 HTTP response means the request was processed — not that the payment succeeded. Read the status field in the body, and treat the webhook (or GET /transactions/{id}) as the source of truth for the final outcome.

HTTP 200 ≠ payment success. winam-payments returns 200 whenever the request is processed, regardless of the transaction outcome. A merchant-initiated deposit rejected by the operator at initiation comes back as 200 with status: "failed" (reason in state_reason). Never treat the HTTP status alone as confirmation — always inspect the body status and rely on the webhook for terminal states.

Base URLs

Environment	URL
Production	`https://api.winampay.de`
Development	`http://localhost:8000` (docker-compose)

End-to-end deposit flow

# 1. Detect the player's operator automatically
curl -X POST https://api.winampay.de/api/v1/msisdn/detect \
  -H "Content-Type: application/json" \
  -d '{"msisdn": "+237670123456", "country_code": "CM"}'

# Response → {"operator": "mtn", "provider_suggestion": "sim_gateway_mtn", ...}


# 2. Initiate the deposit
curl -X POST https://api.winampay.de/api/v1/deposits \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "player_id":    "550e8400-e29b-41d4-a716-446655440000",
    "msisdn":       "+237670123456",
    "amount_xaf":   5000,
    "operator":     "mtn",
    "reference":    "bet-slip-98765",
    "callback_url": "https://your-platform.example.com/webhooks/payments"
  }'

# Response (MTN, merchant-initiated)
# → {"winam_tx_id": "7c9e...", "status": "pending", "collection_mode": "merchant_initiated",
#    "instructions": null, "expires_at": "..."}
# → The player receives a payment request on their phone and confirms with their PIN
#
# Response (Orange, customer-initiated)
# → {"winam_tx_id": "9b2f...", "status": "pending", "collection_mode": "customer_initiated",
#    "instructions": {"ussd_string": "#150*14*000000*659000000*5000#", "dial_uri": "tel:...",
#                     "steps": [...]}, "expires_at": "..."}
# → Display the instructions: the player dials the code from their own phone


# 3. Receive the outcome on your callback_url once the player has paid
# POST https://your-platform.example.com/webhooks/payments
# {
#   "winam_tx_id": "7c9e...",
#   "event": "payment.succeeded",
#   "amount_xaf": 5000,
#   ...
# }

Quick links

Deposits

Initiate a Mobile Money deposit

Collection modes

How each operator collects a deposit

Withdrawals

Initiate a Mobile Money withdrawal

Webhooks

Receive and verify payment notifications

State machine

Transaction lifecycle diagram

Get Started

Payments

Transactions

Providers

Security

Reference

What is winam-payments?

What you need to implement

Base URLs

End-to-end deposit flow

Quick links

Deposits

Collection modes

Withdrawals

Webhooks

State machine