Le verdict en trois phrases
Le STK Push est le meilleur flux de paiement M-Pesa pour le web : le client recoit un prompt, saisit son PIN, c'est termine, sans quitter votre site. Mais il est fragile par nature : le prompt expire en 60 secondes, environ 14 % des clients abandonnent avant de saisir le PIN, et les callbacks Daraja se perdent parfois. Sans query status systematique et relance SMS, vous perdez des ventes deja gagnees.
Le flux STK Push, etape par etape
Le Sim Toolkit (STK) Push declenche un prompt directement sur le telephone du client. Cote serveur, le cycle est le suivant : vous appelez STK Push sur l'API Daraja, M-Pesa envoie le prompt, le client saisit son PIN, puis Daraja notifie le resultat sur votre callback URL. Regle d'or : ne jamais faire confiance au seul callback. Doublez-le d'un appel STK Push Query pour confirmer le statut reel, car les callbacks manquants sont la premiere cause de commandes bloquees en "en attente".
La validation du callback impose de verifier le MerchantRequestID, le CheckoutRequestID et le ResultCode. Un ResultCode a 0 signifie succes ; toute autre valeur est un echec avec sa cause.
| Etape | Action serveur | Point de vigilance |
|---|---|---|
| 1. Init | POST STK Push (Daraja) | Timestamp + password corrects |
| 2. Prompt | M-Pesa affiche le prompt | Expire en 60 s |
| 3. PIN | Client saisit son code | ~14 % d'abandon |
| 4. Callback | Daraja notifie le resultat | Peut se perdre |
| 5. Query | STK Push Query de secours | Obligatoire |
| 6. C2B confirm | Confirmation finale | Rapprochement compte |
Codes d'erreur Daraja et taux d'abandon
Comprendre les codes retournes evite de traiter un simple timeout comme un vrai echec de paiement. Voici les codes les plus frequents et leur traitement recommande.
| Code Daraja | Signification | Frequence (est.) | Action |
|---|---|---|---|
| 0 | Succes | ~82 % | Valider la commande |
| 1037 | Timeout, pas de reponse | ~8 % | Relance SMS + retry |
| 1032 | Annule par l'utilisateur | ~4 % | Proposer un nouveau lien |
| 1 | Solde insuffisant | ~3 % | Message + autre operateur |
| 2001 | PIN incorrect | ~2 % | Relancer le prompt |
| 1019 | Transaction expiree | ~1 % | Reinitialiser |
Le code 1037 (timeout) est le plus trompeur : le client a peut-etre juste rate la fenetre de 60 secondes. Une relance immediate par SMS avec un lien de reprise recupere en moyenne +11 % de ces transactions.
Mini cas pratique
Wanjiru gere une plateforme de livraison de repas a Nairobi, avec 6 000 tentatives de paiement STK par mois. Sans gestion fine : 82 % de succes, soit 4 920 paiements. Les 1 080 echecs incluent environ 480 timeouts (code 1037). En ajoutant une relance SMS automatique sur les timeouts, elle recupere 11 % de ces 480, soit 53 commandes/mois, plus la baisse des abandons grace a un message clair sur les soldes insuffisants. A un panier moyen de 1 500 KES, c'est +79 500 KES/mois recuperes pour un cout SMS negligeable.
Besoin d'un site web professionnel ?
Kolonell crée des sites web qui attirent des clients, optimisés pour le marché sénégalais. Devis gratuit en 2 minutes.
FAQ
Pourquoi mes commandes restent-elles "en attente" ?
Parce que le callback Daraja s'est perdu et que vous ne faites pas de query status. Implementez un STK Push Query automatique 30 a 60 secondes apres l'init pour resoudre le statut de facon fiable.
Combien de temps le client a-t-il pour saisir son PIN ?
Le prompt STK expire au bout de 60 secondes. Au-dela, vous recevez un code 1037 et devez proposer une relance plutot que de considerer la vente perdue.
Faut-il retenter automatiquement un paiement en timeout ?
Oui, mais avec parcimonie : un seul retry declenche par le client via un lien SMS, jamais une boucle automatique qui multiplierait les prompts et agacerait l'utilisateur.
Quelle difference entre callback et C2B confirmation ?
Le callback STK confirme le resultat de la demande de paiement ; la confirmation C2B sert au rapprochement comptable cote compte marchand. Les deux sont utiles pour un rapprochement fiable.
Le sandbox Daraja simule-t-il les timeouts ?
Le sandbox permet de tester le flux nominal et certains codes d'erreur, mais pas fidelement les pertes reseau reelles. Gardez donc une logique de query et de relance robuste en production.
Discutons de votre projet. Nous mettons en place un STK Push M-Pesa fiabilise, avec query status et relance SMS automatique. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionné par le digital et l'entrepreneuriat en Afrique, Mohamed accompagne les entreprises sénégalaises dans leur transformation digitale depuis 2020. Fondateur de Kolonell, il croit que chaque PME mérite une présence en ligne professionnelle et accessible.
