MTN Mobile Money Payment API Documentation

curl "https://winaggregator-mtn.com/api/v1/compliance/status?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1"

import requests

requests.post(
    "https://winaggregator-mtn.com/api/v1/compliance/documents",
    json={
        "company_name": "WinLib Enterprises",
        "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
        "documents": [
            {"type": "LBR_CERTIFICATE", "reference": "LBR-2026-004417"},
            {"type": "TIN", "reference": "500123456"}
        ],
        "note": "Registered 12 September 2026."
    }
)

curl -X POST "https://winaggregator-mtn.com/api/v1/request-secret-string" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "WinLib Enterprises",
    "company_phone_number": "231888123456"
  }'

import requests

url = "https://winaggregator-mtn.com/api/v1/request-secret-string"
payload = {
    "company_name": "WinLib Enterprises",
    "company_phone_number": "231888123456"
}
response = requests.post(url, json=payload)
print(response.json())

const response = await fetch('https://winaggregator-mtn.com/api/v1/request-secret-string', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ company_name: 'WinLib Enterprises', company_phone_number: '231888123456' })
});
console.log(await response.json());

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://winaggregator-mtn.com/api/v1/request-secret-string"
	payload := map[string]string{
		"company_name":        "WinLib Enterprises",
		"company_phone_number": "231888123456",
	}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

curl -X POST "https://winaggregator-mtn.com/api/v1/regenerate-secret-string" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "WinLib Enterprises",
    "company_phone_number": "231888123456",
    "old_secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1"
  }'

import requests

url = "https://winaggregator-mtn.com/api/v1/regenerate-secret-string"
payload = {
    "company_name": "WinLib Enterprises",
    "company_phone_number": "231888123456",
    "old_secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1"
}
response = requests.post(url, json=payload)
print(response.json())

const response = await fetch('https://winaggregator-mtn.com/api/v1/regenerate-secret-string', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    company_name: 'WinLib Enterprises',
    company_phone_number: '231888123456',
    old_secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1'
  })
});
console.log(await response.json());

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://winaggregator-mtn.com/api/v1/regenerate-secret-string"
	payload := map[string]string{
		"company_name":        "WinLib Enterprises",
		"company_phone_number": "231888123456",
		"old_secret_string":   "sec_w1nL1b_98a7b6c5d4e3f2a1",
	}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

curl -X POST "https://winaggregator-mtn.com/api/v1/collection" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "company_name": "WinLib Enterprises",
    "amount": "10.00",
    "currency": "USD",
    "externalID": "INV-2026-001",
    "msisdn": "231888123456"
  }'

import requests

url = "https://winaggregator-mtn.com/api/v1/collection"
payload = {
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "company_name": "WinLib Enterprises",
    "amount": "10.00",
    "currency": "USD",
    "externalID": "INV-2026-001",
    "msisdn": "231888123456"
}
response = requests.post(url, json=payload)
print(response.json())

const response = await fetch('https://winaggregator-mtn.com/api/v1/collection', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1',
    company_name: 'WinLib Enterprises',
    amount: '10.00',
    currency: 'USD',
    externalID: 'INV-2026-001',
    msisdn: '231888123456'
  })
});
console.log(await response.json());

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://winaggregator-mtn.com/api/v1/collection"
	payload := map[string]string{
		"secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
		"company_name":  "WinLib Enterprises",
		"amount":        "10.00",
		"currency":      "USD",
		"externalID":    "INV-2026-001",
		"msisdn":        "231888123456",
	}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

curl "https://winaggregator-mtn.com/api/v1/collection/status/98a7b6c5-d4e3-4f2a-8b1c-90123456789a?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1"

import time
import requests

reference_id = "98a7b6c5-d4e3-4f2a-8b1c-90123456789a"
url = f"https://winaggregator-mtn.com/api/v1/collection/status/{reference_id}"
params = {
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1"
}

# Poll until the payer confirms or declines.
for _ in range(30):
    data = requests.get(url, params=params).json()
    if data["transaction_status"] != "PENDING":
        break
    time.sleep(5)

print(data["transaction_status"])

const referenceId = '98a7b6c5-d4e3-4f2a-8b1c-90123456789a';
const params = new URLSearchParams({
  company_name: 'WinLib Enterprises',
  secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1'
});

let data;
for (let i = 0; i < 30; i++) {
  const res = await fetch(
    `https://winaggregator-mtn.com/api/v1/collection/status/${referenceId}?${params}`
  );
  data = await res.json();
  if (data.transaction_status !== 'PENDING') break;
  await new Promise(r => setTimeout(r, 5000));
}

console.log(data.transaction_status);

curl -X POST "https://winaggregator-mtn.com/api/v1/webhook/config" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "callback_url": "https://yourstore.com/hooks/momo"
  }'

import hmac, hashlib
from datetime import datetime, timezone
from flask import Flask, request, abort

SECRET = "sec_w1nL1b_98a7b6c5d4e3f2a1"
app = Flask(__name__)

@app.post("/hooks/momo")
def momo_webhook():
    raw = request.get_data()                     # verify the RAW body, not re-encoded JSON
    timestamp = request.headers["X-Winlib-Timestamp"]
    expected = hmac.new(
        SECRET.encode(),
        f"{timestamp}.{raw.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, request.headers["X-Winlib-Signature"]):
        abort(401)

    # Reject replays of an old, validly signed delivery.
    sent = datetime.fromisoformat(timestamp)
    if abs((datetime.now(timezone.utc) - sent).total_seconds()) > 300:
        abort(401)

    event = request.json
    if event["event"] == "payment.successful":
        mark_order_paid(event["externalID"], event["net_merchant_credited"])

    return "", 200                               # any 2xx stops the retries

const crypto = require('crypto');
const express = require('express');

const SECRET = 'sec_w1nL1b_98a7b6c5d4e3f2a1';
const app = express();

// Keep the raw body - re-serialising the JSON would change the signature.
app.post('/hooks/momo', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Winlib-Timestamp');
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${timestamp}.${req.body.toString()}`)
    .digest('hex');

  const received = req.get('X-Winlib-Signature');
  const ok = expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));

  if (!ok) return res.sendStatus(401);
  if (Math.abs(Date.now() - Date.parse(timestamp)) > 300000) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString());
  if (event.event === 'payment.successful') {
    markOrderPaid(event.externalID, event.net_merchant_credited);
  }

  res.sendStatus(200);   // any 2xx stops the retries
});

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"net/http"
)

const secret = "sec_w1nL1b_98a7b6c5d4e3f2a1"

func momoWebhook(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	timestamp := r.Header.Get("X-Winlib-Timestamp")

	mac := hmac.New(sha256.New, []byte(secret))
	fmt.Fprintf(mac, "%s.%s", timestamp, raw)
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Winlib-Signature"))) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	// Handle the event, then acknowledge with any 2xx to stop the retries.
	w.WriteHeader(http.StatusOK)
}

curl "https://winaggregator-mtn.com/api/v1/transactions?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1&limit=50"

import requests

response = requests.get(
    "https://winaggregator-mtn.com/api/v1/transactions",
    params={
        "company_name": "WinLib Enterprises",
        "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
        "limit": 50
    }
)

for tx in response.json()["transactions"]:
    print(tx["reference_id"], tx["status"], tx["amount"], tx["currency"])

# The same externalID sent twice within the window
curl -X POST "https://winaggregator-mtn.com/api/v1/collection" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "company_name": "WinLib Enterprises",
    "amount": "10.00",
    "currency": "USD",
    "externalID": "INV-2026-001",
    "msisdn": "231888123456"
  }'

import requests

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

if response.status_code == 409:
    # Already charged. Do NOT retry with the same externalID -
    # look up what happened to the original payment instead.
    detail = response.json()["detail"]
    original = detail["original_reference_id"]

    status = requests.get(
        f"https://winaggregator-mtn.com/api/v1/collection/status/{original}",
        params={
            "company_name": "WinLib Enterprises",
            "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1"
        }
    ).json()

    print("Original payment:", status["transaction_status"])

import time
import requests

def call_with_backoff(method, url, **kwargs):
    for attempt in range(5):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429:
            return response
        # Honour the server's own wait time.
        time.sleep(int(response.headers.get("Retry-After", 5)))
    raise RuntimeError("Still rate limited after 5 attempts")

async function callWithBackoff(url, options = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const wait = Number(response.headers.get('Retry-After') || 5);
    await new Promise(r => setTimeout(r, wait * 1000));
  }
  throw new Error('Still rate limited after 5 attempts');
}

curl -X GET "https://winaggregator-mtn.com/api/v1/subscriptions?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1&status=ACTIVE"

import requests

url = "https://winaggregator-mtn.com/api/v1/subscriptions"
params = {
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "status": "ACTIVE"
}
response = requests.get(url, params=params)
print(response.json())

const params = new URLSearchParams({
  company_name: 'WinLib Enterprises',
  secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1',
  status: 'ACTIVE'
});
const response = await fetch(`https://winaggregator-mtn.com/api/v1/subscriptions?${params}`);
console.log(await response.json());

package main

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

func main() {
	url := "https://winaggregator-mtn.com/api/v1/subscriptions?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1&status=ACTIVE"
	resp, err := http.Get(url)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

curl -X POST "https://winaggregator-mtn.com/api/v1/subscription/cancel" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "subscription_id": "SUB-8A7B6C5D4E3F"
  }'

import requests

url = "https://winaggregator-mtn.com/api/v1/subscription/cancel"
payload = {
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "subscription_id": "SUB-8A7B6C5D4E3F"
}
response = requests.post(url, json=payload)
print(response.json())

const response = await fetch('https://winaggregator-mtn.com/api/v1/subscription/cancel', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    company_name: 'WinLib Enterprises',
    secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1',
    subscription_id: 'SUB-8A7B6C5D4E3F'
  })
});
console.log(await response.json());

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://winaggregator-mtn.com/api/v1/subscription/cancel"
	payload := map[string]string{
		"company_name":    "WinLib Enterprises",
		"secret_string":   "sec_w1nL1b_98a7b6c5d4e3f2a1",
		"subscription_id": "SUB-8A7B6C5D4E3F",
	}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

curl -X POST "https://winaggregator-mtn.com/api/v1/withdraw" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "amount": "50.00",
    "currency": "USD",
    "externalID": "WD-2026-009",
    "msisdn": "231888123456"
  }'

import requests

url = "https://winaggregator-mtn.com/api/v1/withdraw"
payload = {
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "amount": "50.00",
    "currency": "USD",
    "externalID": "WD-2026-009",
    "msisdn": "231888123456"
}
response = requests.post(url, json=payload)
print(response.json())

const response = await fetch('https://winaggregator-mtn.com/api/v1/withdraw', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    company_name: 'WinLib Enterprises',
    secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1',
    amount: '50.00',
    currency: 'USD',
    externalID: 'WD-2026-009',
    msisdn: '231888123456'
  })
});
console.log(await response.json());

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://winaggregator-mtn.com/api/v1/withdraw"
	payload := map[string]string{
		"company_name":  "WinLib Enterprises",
		"secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
		"amount":        "50.00",
		"currency":      "USD",
		"externalID":    "WD-2026-009",
		"msisdn":        "231888123456",
	}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

curl -X GET "https://winaggregator-mtn.com/api/v1/account-balance?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1¤cy=USD"

import requests

url = "https://winaggregator-mtn.com/api/v1/account-balance"
params = {
    "company_name": "WinLib Enterprises",
    "secret_string": "sec_w1nL1b_98a7b6c5d4e3f2a1",
    "currency": "USD"
}
response = requests.get(url, params=params)
print(response.json())

const params = new URLSearchParams({
  company_name: 'WinLib Enterprises',
  secret_string: 'sec_w1nL1b_98a7b6c5d4e3f2a1',
  currency: 'USD'
});
const response = await fetch(`https://winaggregator-mtn.com/api/v1/account-balance?${params.toString()}`);
console.log(await response.json());

package main

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

func main() {
	url := "https://winaggregator-mtn.com/api/v1/account-balance?company_name=WinLib%20Enterprises&secret_string=sec_w1nL1b_98a7b6c5d4e3f2a1¤cy=USD"
	resp, err := http.Get(url)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

const secretKey = 'sec_w1nL1b_98a7b6c5d4e3f2a1';
const ws = new WebSocket(`wss://winaggregator-mtn.com/ws/v1/notification/${secretKey}`);

ws.onopen = () => console.log('Connected to WINAGGREGATOR WebSocket Stream');

ws.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  console.log('Real-Time Payment Event:', payload);
};

import asyncio
import websockets
import json

async def listen_notifications():
    uri = "wss://winaggregator-mtn.com/ws/v1/notification/sec_w1nL1b_98a7b6c5d4e3f2a1"
    async with websockets.connect(uri) as websocket:
        print("Connected to WebSocket notification stream")
        while True:
            msg = await websocket.recv()
            print("Real-time event:", json.loads(msg))

asyncio.run(listen_notifications())

package main

import (
	"context"
	"fmt"
	"nhooyr.io/websocket"
)

func main() {
	ctx := context.Background()
	url := "wss://winaggregator-mtn.com/ws/v1/notification/sec_w1nL1b_98a7b6c5d4e3f2a1"

	conn, _, err := websocket.Dial(ctx, url, nil)
	if err != nil {
		panic(err)
	}
	defer conn.Close(websocket.StatusNormalClosure, "")

	fmt.Println("Connected to WINAGGREGATOR Notification Stream")

	for {
		_, message, err := conn.Read(ctx)
		if err != nil {
			break
		}
		fmt.Printf("Real-Time Event Received: %s\n", message)
	}
}

# Install wscat: npm install -g wscat
npx wscat -c "wss://winaggregator-mtn.com/ws/v1/notification/sec_w1nL1b_98a7b6c5d4e3f2a1"