Skip to main content

2026-10-09 — Sandbox

Added

  • Sandbox at https://sandbox.winampay.de: same API and webhooks, no real money, wk_test_ keys. Trigger outcomes with POST /api/v1/sandbox/transactions/{id}/simulate. See Sandbox.

2026-10-08 — One API key per application

Breaking

  • X-Winam-Signature now carries an HMAC-SHA256 signature: t=<unix>,v1=<hex> with v1 = HMAC-SHA256(webhook_secret, "<t>.<raw_body>"), computed with your application’s own webhook secret. The former JWT RS256 signature, when enabled, moved to the X-Winam-Signature-Jwt header. Update your webhook verification — see Webhooks.
  • Transactions are isolated per application. GET /api/v1/transactions/{id}, GET /api/v1/players/{player_id}/transactions and POST /api/v1/transactions/{id}/replay-webhook only see transactions created by the calling application; others return 404 (or are not listed).
  • reference used by another application → 409 ("Reference already used by another application."). Re-sending your own reference still returns your original transaction.

Added

  • One API key per application, format wk_live_<prefix>_<secret>. An application can hold several keys at once for zero-downtime rotation. See Authentication.
  • Scopes per application: deposits, withdrawals, transactions. A valid key without the required scope receives 403 ("API key lacks scope '<scope>'."). Reference routes (providers, MSISDN detection, public key) need no scope.
  • Default callback URL per application, used when a deposit or withdrawal request has no callback_url.

Unchanged

  • Existing keys keep working during the migration: Winam registers your current key on your application. No request or response field was removed or renamed.

Unreleased

Breaking

  • Removed POST /api/v1/transactions/{id}/replay-callback. It conflated replaying an inbound provider callback with re-sending the outbound webhook. Replaced by POST /api/v1/transactions/{id}/replay-webhook, which re-sends the outbound payment.succeeded / payment.failed notification for a terminal transaction (does not change its state; 409 if non-terminal, 400 if no callback_url).

Added

  • Deposit collection modes. A deposit is collected in one of two modes, returned as collection_mode: merchant_initiated (a payment request is sent to the player’s phone) or customer_initiated (the player dials a USSD code from their own phone). See Deposit collection modes. All changes are additive:
    • POST /api/v1/deposits accepts an optional lang field (fr default, en) and returns collection_mode and an instructions object (ussd_string, dial_uri, copy_text, merchant, localized steps, optional illustration, polling_interval_seconds); instructions is null for merchant-initiated deposits.
    • GET /api/v1/transactions/{winam_tx_id} accepts ?lang=fr|en and returns the same collection_mode and instructions while a customer-initiated deposit is pending.
    • A customer-initiated deposit stays pending until the payment is confirmed. If it expired, a late payment that matches it completes the same transaction: payment.succeeded can follow payment.expired for the same winam_tx_id.
    • When a customer-initiated channel cannot confirm payments, new deposits are refused with 503 and GET /api/v1/{country}/providers/status reports the provider as degraded or unavailable.
    • No field, route, state or webhook event was removed or renamed.
  • Customer-initiated deposits: stricter matching, operator review. No field, route, state or webhook event changed.
    • A payment is credited automatically only when it is sent to the merchant number given in that deposit’s instructions. A payment sent to another Winam merchant number is held for review instead of being credited.
    • A Winam operator can complete a deposit from held or partial payments of the player’s number once they add up to at least the declared amount. The amount credited stays the deposit’s amount_xaf. You receive the usual payment.succeeded, possibly after a payment.expired for the same winam_tx_id. See Payments reviewed by an operator.
  • Late deposit confirmation handling. A confirmation (operator SMS/USSD) arriving after a deposit expired or failed no longer auto-credits and is no longer silently dropped. The transaction moves to requires_manual_resolution and is held for a Winam operator to confirm or reject. No webhook is sent until it resolves to succeeded or failed. See State Machine.

Changed

  • 503 responses of POST /api/v1/deposits and POST /api/v1/withdrawals caused by an unavailable payment channel now return a fixed detail: "Deposits are temporarily unavailable for this operator. Please retry later or use another payment method." (withdrawals: "Withdrawals are temporarily unavailable…"). It no longer describes the internal cause. Messages for maintenance and for a direction or operator switched off are unchanged.
  • All API response messages are now in English (were previously French).
  • Successful withdrawals settle to succeeded immediately on USSD success — provider_submitted is now a transient step, not a waiting state.
  • POST /deposits and POST /withdrawals now validate the coherence between the msisdn prefix and the operator field. A clear contradiction (e.g. a 655… Orange number with operator=mtn) is rejected with 422 before any USSD is sent. Cameroon prefixes — MTN: 67x, 68x, 650-654 · Orange: 69x, 655-659. Numbers with unknown prefixes are accepted as-is. Use POST /msisdn/detect to pre-fill the right operator.

v0.1.0 — Initial release

Released: June 2026 (Coupe du Monde launch)

Endpoints

  • POST /api/v1/deposits — Initiate Mobile Money deposits (MTN MoMo, Orange Money)
  • POST /api/v1/withdrawals — Initiate withdrawals with manual operator approval
  • GET /api/v1/transactions/{id} — Get transaction state
  • GET /api/v1/players/{player_id}/transactions — List player transactions
  • POST /api/v1/transactions/{id}/replay-webhook — Manual webhook re-delivery for recovery
  • GET /api/v1/{country}/providers — Provider catalogue with fees
  • GET /api/v1/{country}/providers/status — Real-time provider health
  • POST /api/v1/msisdn/detect — Operator detection from phone number
  • GET /api/v1/security/callback-public-key — Webhook signature public key

Providers

  • MTN MoMo — via SIM gateway (primary) + Campay (backup)
  • Orange Money — via SIM gateway (primary) + Campay (backup)

Countries

  • CM (Cameroon)
Future releases will be documented here. For breaking changes, existing integrators will be notified at least 30 days in advance.