> ## 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.

# Overview

> Mobile Money payment abstraction layer for Cameroon. Integrate MTN MoMo and Orange Money in minutes.

## 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).

<img src="https://mintcdn.com/winampay/zR24v7hyn1yQcHa-/logo/what-is.png?fit=max&auto=format&n=zR24v7hyn1yQcHa-&q=85&s=c7fcfe08d8c8f502f6cd05a8745dcafa" alt="Ilustration how it works" width="1747" height="337" data-path="logo/what-is.png" />

```
Sportsbook / Frontend ──── POST /deposits ────► winam-payments ──── USSD MTN/Orange
                           POST /withdrawals ►                  ◄─── SMS confirmation
                           GET  /transactions ►                 ────► webhook callback
```

## What you need to implement

<Steps>
  <Step title="Initiate a payment">
    Call `POST /api/v1/deposits` or `POST /api/v1/withdrawals` with your unique `reference` key.
  </Step>

  <Step title="Expose a webhook endpoint">
    Provide a `callback_url` that accepts `POST` JSON requests — this is where winam-payments sends the payment outcome.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## Base URLs

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

## End-to-end deposit flow

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Deposits" icon="arrow-down-to-line" href="/api-reference/deposits">
    Initiate a Mobile Money deposit
  </Card>

  <Card title="Withdrawals" icon="arrow-up-from-line" href="/api-reference/withdrawals">
    Initiate a Mobile Money withdrawal
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Receive and verify payment notifications
  </Card>

  <Card title="State machine" icon="diagram-project" href="/api-reference/state-machine">
    Transaction lifecycle diagram
  </Card>
</CardGroup>