API MolediPay

Encaissez et payez par mobile money dans 21 pays africains avec une seule intégration. Utilisez l'orchestrateur (MolediPay choisit la passerelle et bascule en cas de panne) ou appelez directement la passerelle de votre choix.

Présentation

Authentification

Toutes les requêtes portent la clé API de votre application. URL de base : https://moledipay.com/v1.

Authorization: Bearer mp_votre_cle_api

Sécurité

• HTTPS obligatoire ; clés API stockées uniquement sous forme d'empreinte.
• Les notifications des passerelles ne sont jamais crues sur parole : MolediPay redemande le statut à la passerelle avant toute mise à jour.
• Webhooks sortants signés (HMAC-SHA256 + horodatage) ; un statut final ne change plus jamais.
• 300 requêtes par minute et par application ; une application suspendue est refusée.

Toutes les adresses

Orchestrateur : comment il choisit

1. Il détermine le pays (country, ou l'indicatif du numéro) et l'opérateur (network, ou détection à partir du numéro).
2. Il prend les passerelles dans l'ordre défini pour ce pays, cet opérateur et cette opération : règle de votre application, sinon de la plateforme, sinon la moins chère.
3. Il écarte celles hors service (surveillance toutes les 5 minutes) et place en dernier celles dégradées.
4. Il essaie la première ; si elle refuse immédiatement, il essaie la suivante. Les essais sont listés dans attempts.

Champs

Encaissement orchestré

POST/v1/deposits

curl -X POST https://moledipay.com/v1/deposits \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CM","amount":5000,"phone":"670000000","reference":"CMD-1042","description":"Commande 1042"}'

Lien de paiement orchestré

POST/v1/links — la passerelle est choisie par la règle du pays pour les liens ; la réponse contient payment_url.

curl -X POST https://moledipay.com/v1/links \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CI","amount":10000,"phone":"0707000000","customer_name":"Awa Koné","reference":"CMD-1043"}'

Retrait orchestré

POST/v1/payouts — refusé (INSUFFICIENT_BALANCE) si aucune passerelle possible n'a assez de solde pour votre application dans ce pays, frais compris.

curl -X POST https://moledipay.com/v1/payouts \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"SN","network":"WAVE","amount":20000,"phone":"771234567","customer_name":"Moussa Diop","reference":"RETRAIT-88"}'

Retraits groupés (tout-ou-rien)

POST/v1/payouts/batch — plusieurs retraits (jusqu'à 20) envoyés ensemble. MolediPay vérifie d'abord que chaque retrait est couvert par un portefeuille de votre application, frais compris et en cumulant les parts qui tombent sur le même portefeuille. Si une seule part n'est pas couverte, tout le lot est refusé (BATCH_NOT_COVERED) et aucun retrait n'est envoyé. Chaque retrait garde sa propre reference ; le lot entier partage batch_reference (idempotent).

curl -X POST https://moledipay.com/v1/payouts/batch \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"reference":"RETRAIT-GROUPE-12","items":[
        {"reference":"RG12-A","country":"CM","network":"MTN","amount":10000,"phone":"670000000","customer_name":"Awa"},
        {"reference":"RG12-B","country":"CM","network":"MTN","amount":1000,"phone":"670000000","customer_name":"Awa"}]}'

Node.js

const res = await fetch("https://moledipay.com/v1/deposits", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MOLEDIPAY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ country: "CM", amount: 5000, phone: "670000000", reference: orderId }),
});
const payment = await res.json();
if (!res.ok && !payment.id) throw new Error(`${payment.code} : ${payment.error}`);

PHP

$ch = curl_init('https://moledipay.com/v1/deposits');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MOLEDIPAY_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['country' => 'CM', 'amount' => 5000, 'phone' => '670000000', 'reference' => $orderId]),
]);
$payment = json_decode(curl_exec($ch), true);

Python

import os, requests
payment = requests.post("https://moledipay.com/v1/deposits",
    headers={"Authorization": f"Bearer {os.environ['MOLEDIPAY_API_KEY']}"},
    json={"country": "CM", "amount": 5000, "phone": "670000000", "reference": order_id}, timeout=30).json()

Réponse

HTTP/1.1 201 Created
{
  "id": "4806bd66-9565-48d6-885f-59c34d021832", "reference": "CMD-1042",
  "type": "deposit", "mode": "direct", "routing": "auto",
  "provider": "pawapay", "operator": "MTN", "network": "MTN_MOMO_CMR",
  "status": "PENDING", "amount": 5000, "fee": 87.5, "fee_source": "grid", "currency": "XAF", "country": "CM",
  "phone": "237670000000", "payment_url": null, "failure_reason": null,
  "attempts": [ { "provider": "pawapay", "outcome": "PENDING", "provider_status": "ACCEPTED" } ],
  "created_at": "2026-09-28T10:00:00.000Z"
}

• 201 : créé · 200 + "idempotent": true : référence déjà utilisée · 422 + "status": "FAILED" : refusé par la ou les passerelles.
• routing : auto (orchestrateur) ou direct (passerelle imposée).
• fee : frais estimés selon la grille ; fee_source: "actual" quand ils ont été relevés chez la passerelle.

PawaPay

Ces adresses utilisent uniquement PawaPay, sans bascule vers une autre passerelle. L'opération est fixée par l'adresse : n'envoyez pas type, mode ni provider.

Particularités PawaPay

• 13 pays. L'opérateur est détecté automatiquement à partir du numéro ; network est facultatif (MTN, ORANGE, ou le code PawaPay, ex. MTN_MOMO_CMR).
• Numéro avec ou sans indicatif ; PawaPay le valide et le normalise.
• Lien : page de paiement PawaPay hébergée, téléphone facultatif (le client choisit son opérateur sur la page), retour vers return_url. Un lien non utilisé est clôturé en FAILED au bout d'une heure.
• Montants sans décimales pour les francs CFA ; limites propres à chaque opérateur (tableau ci-dessous).
• Frais : frais de l'opérateur + 1 % PawaPay, déduits du montant encaissé ; frais de retrait ajoutés au montant envoyé.

Encaissement direct

curl -X POST https://moledipay.com/v1/pawapay/deposits \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CM","amount":5000,"phone":"670000000","reference":"CMD-2001","description":"Commande 2001"}'

Lien de paiement

curl -X POST https://moledipay.com/v1/pawapay/links \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CM","amount":5000,"reference":"CMD-2002","description":"Commande 2002","return_url":"https://monsite.com/merci"}'

Retrait

curl -X POST https://moledipay.com/v1/pawapay/payouts \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CM","amount":10000,"phone":"690000000","customer_name":"Paul Mbarga","reference":"RET-2003"}'

Pays, opérateurs et valeurs de network

Swychr

Ces adresses utilisent uniquement Swychr, sans bascule vers une autre passerelle. L'opération est fixée par l'adresse : n'envoyez pas type, mode ni provider.

Particularités Swychr

• 18 pays. network est exigé quand le pays a plusieurs opérateurs (sauf au Cameroun, où il est déduit du préfixe). Valeurs : colonne network ci-dessous (ex. Wave, Orange, MTN) ou l'opérateur commun (WAVE).
• Numéro au format national du pays (colonne « Format »), avec ou sans indicatif.
• Lien : le téléphone du client est obligatoire.
• Frais d'encaissement inclus : le client paie le montant, Swychr crédite montant ÷ (1 + taux). Exemple Cameroun 2,5 % : 10 000 payés → 9 756 crédités.
• Frais de retrait : un pourcentage avec un minimum par pays, prélevé en plus du montant envoyé. Exemple Cameroun 1,5 %, minimum 450 XAF : un retrait de 5 000 coûte 450 (pas 75) ; au-delà de 30 000, c'est 1,5 %. Un retrait échoué est remboursé, frais compris.

Encaissement direct

curl -X POST https://moledipay.com/v1/swychr/deposits \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CI","network":"WAVE","amount":5000,"phone":"0707000000","customer_name":"Awa Koné","reference":"CMD-3001"}'

Lien de paiement

curl -X POST https://moledipay.com/v1/swychr/links \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"CM","amount":5000,"phone":"690000000","customer_name":"Jean Nkodo","reference":"CMD-3002"}'

Retrait

curl -X POST https://moledipay.com/v1/swychr/payouts \
  -H "Authorization: Bearer mp_votre_cle" -H "Content-Type: application/json" \
  -d '{"country":"SN","network":"WAVE","amount":20000,"phone":"771234567","customer_name":"Moussa Diop","reference":"RET-3003"}'

Pays, opérateurs et valeurs de network

Consulter un paiement

GET/v1/payments/{id ou reference} — s'il est en attente, MolediPay interroge la passerelle avant de répondre. À utiliser en secours ; le webhook reste la méthode normale.

Moyens de paiement

GET/v1/methods (ou /v1/pawapay/methods, /v1/swychr/methods) — pays et opérateurs activés pour votre application, avec pour chaque opération les passerelles dans l'ordre de routage, leur état et leurs frais.

[ { "country": "CM", "name": "Cameroun", "operators": [
  { "operator": "ORANGE", "name": "Orange Money",
    "deposit": { "available": true, "providers": [
      { "provider": "pawapay", "network": "ORANGE_CMR", "currency": "XAF", "status": "UP",
        "fees": { "deposit_percent": 1.77, "payout_percent": 1, "payout_min": 0, "payout_fixed": 0, "inclusive": false } },
      { "provider": "swychr", "network": "ORANGE", "currency": "XAF", "status": "UP",
        "fees": { "deposit_percent": 2.5, "payout_percent": 1.5, "payout_min": 450, "payout_fixed": 0, "inclusive": true } } ] },
    "payout": { "available": true, "providers": [ … ] } } ] } ]

Soldes

GET/v1/balance (ou /v1/pawapay/balance, /v1/swychr/balance) — un solde par portefeuille (passerelle + pays + devise). L'argent encaissé via une passerelle dans un pays se retire depuis cette même passerelle, dans ce même pays.

[ { "provider": "pawapay", "country": "CM", "currency": "XAF",
    "collected": 150000, "fees": 2625, "paid_out": 50000, "reserved": 0, "available": 97375, "withdrawable": 96125 } ]

• available : encaissé − frais − payé − retraits en cours.
• withdrawable : plus gros retrait possible, ses propres frais déduits (minimums compris).

Frais

• Encaissement : déduit du montant encaissé. Chez Swychr il est inclus : crédité = montant ÷ (1 + taux).
• Retrait : ajouté au montant envoyé et prélevé sur votre solde. Il peut comporter un minimum : chez Swychr au Cameroun, 1,5 % avec un minimum de 450 XAF. Un retrait de 1 000 XAF coûte donc 450 XAF de frais, et il faut au moins 451 XAF de solde pour retirer 1 XAF.
• Les taux appliqués à votre application sont renvoyés par /v1/methods.

Webhooks

À chaque changement de statut, MolediPay envoie un POST JSON à l'URL de webhook de votre application (ou au callback_url du paiement).

POST https://votre-site.com/webhooks/moledipay
X-MolediPay-Event: payment.updated
X-MolediPay-Delivery: 1289
X-MolediPay-Timestamp: 1790343528
X-MolediPay-Signature: 5f2b1c…

{ "event": "payment.updated", "created_at": "…", "data": { "id": "…", "reference": "CMD-1042", "status": "SUCCESSFUL", "amount": 5000, "fee": 87.5, "provider": "pawapay", … } }

• Répondez 2xx en moins de 15 secondes, puis traitez en arrière-plan.
• Sans 2xx, nouvelles tentatives pendant environ 12 heures (8 essais).
• Traitez chaque événement une seule fois (clé : data.id + data.status).

Vérifier la signature

Signature = HMAC-SHA256 hexadécimal de {timestamp}.{corps brut} avec votre secret whsec_…. Rejetez toute signature invalide ou tout horodatage de plus de 5 minutes.

import crypto from "node:crypto";
app.post("/webhooks/moledipay", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("X-MolediPay-Timestamp"), sig = req.get("X-MolediPay-Signature") || "";
  const expected = crypto.createHmac("sha256", process.env.MOLEDIPAY_WEBHOOK_SECRET).update(`${ts}.${req.body}`).digest("hex");
  const ok = Math.abs(Date.now() / 1000 - Number(ts)) < 300 && expected.length === sig.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  if (!ok) return res.status(401).end();
  res.status(200).end();
  const event = JSON.parse(req.body);
});

<?php
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_MOLEDIPAY_TIMESTAMP'] ?? ''; $sig = $_SERVER['HTTP_X_MOLEDIPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $ts . '.' . $raw, getenv('MOLEDIPAY_WEBHOOK_SECRET'));
if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) { http_response_code(401); exit; }
http_response_code(200);
$event = json_decode($raw, true);

import hmac, hashlib, time
def verify(raw_body: bytes, ts: str, sig: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(expected, sig)

Statuts

Erreurs

Format : { "error": "message", "code": "CODE", "details": … }

Couverture complète

Lue en direct chez les passerelles. La colonne « Opérateur » donne la valeur network pour l'orchestrateur ; les autres colonnes, la valeur propre à chaque passerelle.

Bonnes pratiques

• Une reference unique par paiement, réutilisée en cas de nouvel essai réseau.
• N'accordez le service qu'à réception d'un webhook SUCCESSFUL vérifié.
• Proposez uniquement les opérateurs renvoyés par /v1/methods.
• Vérifiez withdrawable avant de proposer un retrait à vos utilisateurs.