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 ──── USSD MTN/Orange
                           POST /withdrawals ►                  ◄─── SMS confirmation
                           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.

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 (JWT RS256). Verify it with the public key from GET /api/v1/security/callback-public-key.

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 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 → {"winam_tx_id": "7c9e...", "status": "provider_acknowledged", "expires_at": "..."}
# → Player receives a USSD notification on their phone


# 3. Receive the outcome on your callback_url (a few seconds later)
# 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

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

Withdrawals

Webhooks

State machine

​What is winam-payments?

​What you need to implement

​Base URLs

​End-to-end deposit flow

​Quick links

Deposits

Withdrawals

Webhooks

State machine

What is winam-payments?

What you need to implement

Base URLs

End-to-end deposit flow

Quick links