Deposits

Initiate a Mobile Money deposit

curl --request POST \
  --url https://api.winampay.de/api/v1/deposits \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "player_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "msisdn": "<string>",
  "amount_xaf": 101,
  "operator": "<string>",
  "reference": "<string>",
  "callback_url": "https://sportsbook.example.com/webhooks/payments"
}
'

import requests

url = "https://api.winampay.de/api/v1/deposits"

payload = {
    "player_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "msisdn": "<string>",
    "amount_xaf": 101,
    "operator": "<string>",
    "reference": "<string>",
    "callback_url": "https://sportsbook.example.com/webhooks/payments"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    player_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    msisdn: '<string>',
    amount_xaf: 101,
    operator: '<string>',
    reference: '<string>',
    callback_url: 'https://sportsbook.example.com/webhooks/payments'
  })
};

fetch('https://api.winampay.de/api/v1/deposits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.winampay.de/api/v1/deposits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'player_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'msisdn' => '<string>',
    'amount_xaf' => 101,
    'operator' => '<string>',
    'reference' => '<string>',
    'callback_url' => 'https://sportsbook.example.com/webhooks/payments'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.winampay.de/api/v1/deposits"

	payload := strings.NewReader("{\n  \"player_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"msisdn\": \"<string>\",\n  \"amount_xaf\": 101,\n  \"operator\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"callback_url\": \"https://sportsbook.example.com/webhooks/payments\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.winampay.de/api/v1/deposits")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"player_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"msisdn\": \"<string>\",\n  \"amount_xaf\": 101,\n  \"operator\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"callback_url\": \"https://sportsbook.example.com/webhooks/payments\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.winampay.de/api/v1/deposits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"player_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"msisdn\": \"<string>\",\n  \"amount_xaf\": 101,\n  \"operator\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"callback_url\": \"https://sportsbook.example.com/webhooks/payments\"\n}"

response = http.request(request)
puts response.read_body

{
  "winam_tx_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "<string>",
  "amount_xaf": 123,
  "operator": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}

POST

api

deposits

Initiate a Mobile Money deposit

curl --request POST \
  --url https://api.winampay.de/api/v1/deposits \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "player_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "msisdn": "<string>",
  "amount_xaf": 101,
  "operator": "<string>",
  "reference": "<string>",
  "callback_url": "https://sportsbook.example.com/webhooks/payments"
}
'

import requests

url = "https://api.winampay.de/api/v1/deposits"

payload = {
    "player_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "msisdn": "<string>",
    "amount_xaf": 101,
    "operator": "<string>",
    "reference": "<string>",
    "callback_url": "https://sportsbook.example.com/webhooks/payments"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    player_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    msisdn: '<string>',
    amount_xaf: 101,
    operator: '<string>',
    reference: '<string>',
    callback_url: 'https://sportsbook.example.com/webhooks/payments'
  })
};

fetch('https://api.winampay.de/api/v1/deposits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.winampay.de/api/v1/deposits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'player_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'msisdn' => '<string>',
    'amount_xaf' => 101,
    'operator' => '<string>',
    'reference' => '<string>',
    'callback_url' => 'https://sportsbook.example.com/webhooks/payments'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.winampay.de/api/v1/deposits"

	payload := strings.NewReader("{\n  \"player_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"msisdn\": \"<string>\",\n  \"amount_xaf\": 101,\n  \"operator\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"callback_url\": \"https://sportsbook.example.com/webhooks/payments\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.winampay.de/api/v1/deposits")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"player_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"msisdn\": \"<string>\",\n  \"amount_xaf\": 101,\n  \"operator\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"callback_url\": \"https://sportsbook.example.com/webhooks/payments\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.winampay.de/api/v1/deposits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"player_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"msisdn\": \"<string>\",\n  \"amount_xaf\": 101,\n  \"operator\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"callback_url\": \"https://sportsbook.example.com/webhooks/payments\"\n}"

response = http.request(request)
puts response.read_body

{
  "winam_tx_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "status": "<string>",
  "amount_xaf": 123,
  "operator": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}

How it works

Call POST /deposits

Your backend sends the player’s MSISDN, amount, and a unique reference.

USSD notification sent

winam-payments triggers a USSD collection on the merchant SIM. The player receives a phone notification asking them to enter their MoMo PIN.

Player confirms

The player confirms on their phone. winam-payments receives an SMS confirmation.

Webhook fired

Your callback_url receives a POST with event: "payment.succeeded" (or "payment.failed" if refused or timed out).

Notes

Use POST /api/v1/msisdn/detect to automatically detect the player’s operator from their phone number — no need to ask them. The deposit endpoint rejects with 422 any request whose msisdn prefix clearly contradicts operator (MTN: 67x/68x/650-654 · Orange: 69x/655-659).

The reference field is your idempotency key. Two calls with the same reference return the same transaction without creating a duplicate. Always use a different reference for each distinct payment. See Idempotency.

The expires_at timestamp in the response indicates when the USSD confirmation window closes (typically +10 minutes). If the player does not confirm before this deadline, the transaction transitions to expired.

HTTP 200 does not mean the deposit succeeded. A 200 only means the request was processed — always read the status field in the response body. The deposit USSD is initiated synchronously, so a deposit that the operator rejects at initiation (invalid number, amount below the operator minimum, USSD error…) comes back as 200 with status: "failed". The reason is available in the state_reason field of GET /api/v1/transactions/{winam_tx_id}.

Response states

`status`	Meaning
`pending`	USSD is being sent to the player’s phone
`provider_acknowledged`	USSD sent — player has received the notification
`failed`	Operator rejected the deposit at initiation (see `state_reason` via `GET /transactions/{id}`)

Terminal states arrive via webhook:

Event	Meaning
`payment.succeeded`	Player confirmed payment
`payment.failed`	Player refused, timed out, or provider error

Authorizations

X-API-Key

string

header

required

Body

application/json

player_id

string<uuid>

required

Player UUID on the sportsbook side

msisdn

string

required

Player MoMo number (E.164)

Example:

"+237670123456"

amount_xaf

integer

required

Amount in XAF (min 100). XAF has no sub-unit.

Required range: x >= 100

operator

string

required

MoMo operator

Examples:

"mtn"

"orange"

reference

string

required

Unique sportsbook reference (idempotency key). Same reference = same transaction returned.

Required string length: 1 - 128

callback_url

string | null

POST URL for notification when payment is confirmed or fails.

Example:

"https://sportsbook.example.com/webhooks/payments"

Response

Successful Response

winam_tx_id

string<uuid>

required

Winam internal transaction UUID. Use this with GET /api/v1/transactions/{id}.

reference

string

required

Your idempotency key, echoed back from the request

status

string

required

Initial state. Typically provider_acknowledged (USSD sent to player) or pending (being sent). Terminal states arrive via webhook.

Example:

"provider_acknowledged"

amount_xaf

integer

required

Amount in XAF

Example:

5000

operator

string

required

"mtn" or "orange"

Example:

"mtn"

expires_at

string<date-time> | null

USSD confirmation deadline (typically +10 minutes from creation). The transaction transitions to expired if the player does not confirm before this time.

Get Started

Payments

Transactions

Providers

Security

Reference

How it works

Notes

Response states

Authorizations

Body

Response

​How it works

​Notes

​Response states

Authorizations

Body

Response

How it works

Notes

Response states