Skip to main content

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.

​
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

1

Initiate a payment

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

Expose a webhook endpoint

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

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.

​
Base URLs

EnvironmentURL
Productionhttps://payments.winam.cm
Developmenthttp://localhost:8000 (docker-compose)

​
End-to-end deposit flow

# 1. Detect the player's operator automatically
curl -X POST https://payments.winam.cm/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://payments.winam.cm/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,
#   ...
# }

Deposits

Initiate a Mobile Money deposit

Withdrawals

Initiate a Mobile Money withdrawal

Webhooks

Receive and verify payment notifications

State machine

Transaction lifecycle diagram