Documentation officielle · API REST · v2.1

API MaishaPay
Mobile payment for all

Intégrez les paiements mobile money, cartes bancaires, recharges et services en quelques lignes de code. Une API unifiée pour toute l'Afrique Centrale et au-delà.

Base URL https://marchand.maishapay.online/api
12+
Opérateurs
99.9%
Uptime SLA
<2s
Réponse moy.
TLS 1.3
Sécurité

Authentification

Toutes les requêtes vers l'API MaishaPay doivent inclure votre clé API dans le header Authorization. Les clés sont générées depuis votre tableau de bord.

API Key
Idéal pour les intégrations serveur-à-serveur. Gardez vos clés secrètes côté back-end.
OAuth 2.0
Pour les applications qui agissent au nom d'un utilisateur final. Flux authorization code.
Recommandé
Utilisez l'authentification Bearer Token avec rotation automatique toutes les 24h.
HTTP Header
Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxx
							Content-Type: application/json
							X-MaishaPay-Version: 2024-01-01
Ne jamais exposer vos clés API en production côté client (JavaScript front-end, applications mobiles). Utilisez toujours un proxy serveur sécurisé.

C2B — Collecte de paiements

Acceptez des paiements depuis les wallets Mobile Money (M-Pesa, Airtel Money, Orange Money, MTN Mobile Money…) et les cartes bancaires Visa/Mastercard de vos clients.

Votre App
Initie
→
MaishaPay API
Traitement
→
Mobile Money
Opérateur
→
Confirmation
Webhook
POST /collect/v2/store/mobileMoney Initier une collecte Mobile Money

Déclenche une invite de paiement USSD sur le téléphone du client. Compatible M-Pesa, Airtel Money, Orange Money, MTN MoMo, Vodacom, Africell.

Paramètres du corps (JSON)

Paramètre Type Requis Description
amount number Requis Montant en centimes. Ex: 500000 pour 5000 CDF
currency string Requis Code ISO 4217. Ex: CDF, USD, XAF, XOF, KES
phone string Requis Numéro au format E.164. Ex: +243812345678
operator string Requis mpesa | airtel | orange | mtn | vodacom | africell
reference string Requis Référence unique côté marchand (max 64 chars)
description string Optionnel Description affichée au client sur l'invite USSD
callback_url string Optionnel URL webhook pour la notification de résultat
metadata object Optionnel Données personnalisées retournées dans le webhook

Exemple de requête

cURL
curl -X POST https://marchand.maishapay.online/api/collect/v2/store/mobileMoney \
  -H "Authorization: Bearer mp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionReference" : "XXXX", // required|unique
    "gatewayMode" : "1",  // Gateway mode 1: Production; 0: Sandbox
    "publicApiKey" : "MP-LIVEPK-kK6yCY09V1jxxxxxxxxxx", // your public API key, required|string
    "secretApiKey" : "MP-LIVEPK-TpJWW05QUG$xxxxxxxxxx", // your secret API key, required|string
    "order" : {
        "amount" : "1000000",  
        "currency" : "CDF", // currency CDF, USD, XAF, XOF, ....
        "customerFullName" : "Hermacle Johnnson", 
        "customerEmailAdress" : "hermacle@email.com"
    },
    "paymentChannel" : {
        "channel" : "MOBILEMONEY",  
        "provider" : "AIRTEL",  // required : AIRTEL, ORANGE, MTN, ....
        "walletID" : "+24399XXXXXXX",
        "callbackUrl" : "https://your_domaine.com/mobile_calback"
    }   
}'

Réponse — 201 Created

JSON
{
  "status": "success",
  "data": {
    "transaction_id": "txn_MP2024_A7B3C9D1E",
    "reference": "ORDER-2024-00142",
    "amount": 500000,
    "currency": "CDF",
    "phone": "+243812345678",
    "operator": "mpesa",
    "payment_status": "PENDING",
    "ussd_code": "*150*00#",
    "expires_at": "2024-01-15T14:35:00Z",
    "created_at": "2024-01-15T14:20:00Z"
  }
}
Tester l'endpoint en direct
Remplacez mp_live_xxxx par votre vraie clé API. Les appels sont simulés en démo.
POST /collect/v3/store/card Initier un paiement par carte bancaire

Crée une session de paiement sécurisée 3DS pour cartes Visa et Mastercard. Retourne une URL de paiement hébergée ou les tokens pour un formulaire personnalisé.

Paramètres du corps (JSON)

Paramètre Type Requis Description
amount number Requis Montant en centimes. Ex: 500000 pour 5000 CDF
currency string Requis Code ISO 4217. Ex: CDF, USD, XAF, XOF, KES
phone string Requis Numéro au format E.164. Ex: +243812345678
operator string Requis mpesa | airtel | orange | mtn | vodacom | africell
reference string Requis Référence unique côté marchand (max 64 chars)
description string Optionnel Description affichée au client sur l'invite USSD
callback_url string Optionnel URL webhook pour la notification de résultat
metadata object Optionnel Données personnalisées retournées dans le webhook
MaishaPay est certifié PCI DSS Niveau 1. Utilisez le formulaire hébergé ou notre SDK JS pour une conformité totale sans manipuler les données de carte.
cURL
curl -X POST https://marchand.maishapay.online/api/collect/v3/store/card \
  -H "Authorization: Bearer mp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionReference": "XXXX", // required
    "gatewayMode": "0",
    "publicApiKey": "MP-SBPK-XXXXX", // your public API key, required|string
    "secretApiKey": "MP-SBPK-XXXXX", // your secret API key, required|string
    "order": {
        "amount": "1",  // required|numeric
        "currency": "USD",  // required, [USD|EURO]
        "customerFirstname": "Joe", // required
        "customerLastname": "Doe", // required
        "customerAddress": "1 Crystal Palace", // required
        "customerCity": "Kinshasa", // required
        "customerPhoneNumber": "+24381XXXXXXX", // required
        "customerEmailAdress": "myemail@email.com" // required
    },
    "paymentChannel": {
        "channel": "CARD", // required, CARD
        "provider": "MASTERCARD", // required, [VISA|MASTERCARD|AMERICAN EXPRESS]
        "callbackUrl": "https://your_domaine.com/mobile_calback" // required|Url, HTTPS
    }
}'

Réponse — Session de paiement

JSON
{
  "status": "success",
  "data": {
    "status_code": 202,
    "transactionId": 1234,
    "originatingTransactionId": "XXXX",
    "transactionStatus": "Pending",
    "transactionDescription": "Accepted",
    "paymentPage": "https://marchand.maishapay.online/api/collect/postRedirectionRequest/1234",
    "updated_at": "14-01-2025 14:14"
  }
}
Tester l'endpoint en direct
Certifié PCI DSS Niveau 1. Aucune donnée sensible ne transite par ce formulaire de démo.

A quoi sert le PAYMENTPAGE et comment l'atteindre ?

Le paymentPage(Attribut dans la réponse d'initialisation) contient l'url de paiement qui redirige vers la page de visa checkout où le client final éffectuéra son paiement en tout sécurité.

A quoi servent les CALLBACK_URL et comment la préparer ?

Le CALLBACK_URL sert à recevoir la réponse finale après que l'utilisateur a payé avec succès ou échac de la plate-forme de VISA Checkout.
Ces réponses sont transmises à partir des variables GET qui seront ajoutées dans l'Url de votre Callback.
Exemple succès : https://your_domaine.com/calback_url/?status=200&description=APPROVED&transactionRefId=XXXX&operatorRefId=1234.
Exemple échec : https://your_domaine.com/calback_url/?status=400&description=DECLINED&transactionRefId=XXXX&operatorRefId=1234.
Exemple abandon : https://your_domaine.com/calback_url/?status=400&description=CANCELED&transactionRefId=XXXX&operatorRefId=1234.
GET /transaction/rest/v2/check Vérifier le statut d'une transaction
cURL
curl https://marchand.maishapay.online/api/transaction/rest/v2/check \
    -H "Content-Type: application/json" \
  -d '{
    "gatewayMode": 1,
    "publicApiKey": "MP-LIVEPK-XXXXX",
    "secretApiKey": "MP-LIVEPK-XXXXX",
    "transactionId": "123456"
}'
  
  
curl https://marchand.maishapay.online/api/transaction/rest/v2/check?useRef=1 \
    -H "Content-Type: application/json" \
  -d '{
    "gatewayMode": 1,
    "publicApiKey": "MP-LIVEPK-XXXXX",
    "secretApiKey": "MP-LIVEPK-XXXXX",
    "transactionId": "123456"
}'
  
  

Statuts possibles

Statut Description
PENDING En attente de confirmation du client
PROCESSING En cours de traitement par l'opérateur
SUCCESS Paiement confirmé et fonds reçus
FAILED Échec (solde insuffisant, timeout, refus)
CANCELLED Annulé par le marchand ou le client
EXPIRED Délai de confirmation dépassé (15 min)

B2C — Décaissements

Envoyez des fonds directement sur les wallets Mobile Money de vos bénéficiaires. Idéal pour les remboursements, salaires, commissions, et transferts en masse.

POST /b2c/transfer Transférer des fonds vers un wallet mobile
cURL
curl -X POST https://marchand.maishapay.online/api/b2c/transfer \
  -H "Authorization: Bearer mp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "CDF",
    "recipient_phone": "+243812345678",
    "operator": "airtel",
    "reference": "SALARY-JAN2024-EMP001",
    "description": "Salaire Janvier 2024",
    "callback_url": "https://monapp.com/webhooks/b2c"
  }'
POST /b2c/bulk-transfer Paiement en masse (jusqu'à 1000 bénéficiaires)
Les transferts en masse sont traités de façon asynchrone. Vous recevrez un batch_id et les notifications par webhook pour chaque transaction individuelle.
JSON Body
{
  "batch_reference": "PAYROLL-JAN-2024",
  "currency": "CDF",
  "callback_url": "https://monapp.com/webhooks/bulk",
  "recipients": [
    {
      "phone": "+243812345678",
      "operator": "mpesa",
      "amount": 500000,
      "reference": "EMP-001",
      "name": "Jean Bolingo"
    },
    {
      "phone": "+243999001122",
      "operator": "airtel",
      "amount": 350000,
      "reference": "EMP-002",
      "name": "Do Lutumb"
    }
  ]
}

Services Connexes

Pay TV
Rechargez les abonnements Canal+, DStv, StarTimes pour vos clients en temps réel.
POST /services/paytv/pay
Airtime
Recharge de crédit téléphonique sur tous les réseaux : Vodacom, Airtel, Orange, MTN, Africell.
POST /services/airtime/topup
Utilités
Paiement des factures d'eau (REGIDESO), d'électricité (SNEL) et internet.
POST /services/utility/pay
POST /services/paytv/pay Paiement abonnement TV
cURL
curl -X POST https://marchand.maishapay.online/api/services/paytv/pay \
  -H "Authorization: Bearer mp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "canal_plus",
    "decoder_number": "1234567890",
    "package": "EVASION_PLUS",
    "duration_months": 1,
    "phone": "+243812345678",
    "payment_method": "mpesa",
    "reference": "PAYTV-2024-00099"
  }'
POST /services/airtime/topup Recharge crédit téléphonique
cURL
curl -X POST https://marchand.maishapay.online/api/services/airtime/topup \
  -H "Authorization: Bearer mp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+243812345678",
    "network": "vodacom",
    "amount": 5000,
    "currency": "CDF",
    "reference": "AIRT-2024-001"
  }'

Webhooks & Notifications

MaishaPay envoie des événements en temps réel vers votre endpoint HTTPS à chaque changement de statut d'une transaction.

Vérifiez toujours la signature HMAC-SHA256 dans l'en-tête X-MaishaPay-Signature avant de traiter un webhook.
PHP — Vérification signature
function verifyWebhook($payload, $signature, $secret): bool {
  $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
  return hash_equals($expected, $signature);
}

$payload  = file_get_contents('php://input');
$sig      = $_SERVER['HTTP_X_MAISHAPAY_SIGNATURE'];
$secret   = 'whsec_xxxxxxxxxxxxxx';

if (!verifyWebhook($payload, $sig, $secret)) {
  http_response_code(401);
  exit('Signature invalide');
}

$event = json_decode($payload, true);

Structure d'un événement webhook

JSON
{
  "id": "evt_MP_1234567890",
  "type": "transaction.success",
  "created_at": "2024-01-15T14:35:22Z",
  "data": {
    "transaction_id": "txn_MP2024_A7B3C9D1E",
    "reference": "ORDER-2024-00142",
    "amount": 500000,
    "currency": "CDF",
    "payment_status": "SUCCESS",
    "operator_reference": "MPESA20240115123456",
    "metadata": { "order_id": "142" }
  }
}

Événements disponibles

Événement Description
transaction.pending Transaction initiée, en attente de confirmation
transaction.success Paiement confirmé avec succès
transaction.failed Transaction échouée
transaction.cancelled Transaction annulée
b2c.transfer.success Transfert B2C réussi
b2c.transfer.failed Transfert B2C échoué
MaishaPay — Mobile payment for all
contact@maishapay.net · +243 800 000 000 · Statut API · Changelog