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à.
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.
Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json X-MaishaPay-Version: 2024-01-01
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.
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 -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
{
"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"
}
}
mp_live_xxxx
par votre vraie clé API. Les appels sont simulés en démo.
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 |
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
{
"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"
}
}
A quoi sert le PAYMENTPAGE et comment l'atteindre ?
A quoi servent les CALLBACK_URL et comment la préparer ?
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.
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" }'
batch_id
et les notifications par webhook pour chaque transaction individuelle.{
"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
POST /services/paytv/pay
POST /services/airtime/topup
POST /services/utility/pay
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" }'
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.
X-MaishaPay-Signature
avant de traiter un webhook.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
{
"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é |