Le verdict en trois phrases
Le STK Push est le meilleur flux de paiement M-Pesa pour le web : le client reçoit un prompt, saisit son PIN, c'est terminé, 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 systématique et relance SMS, vous perdez des ventes déjà gagnées.
Le flux STK Push, étape par étape
Le Sim Toolkit (STK) Push déclenche un prompt directement sur le téléphone du client. Côté 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 résultat sur votre callback URL. Règle d'or : ne jamais faire confiance au seul callback. Doublez-le d'un appel STK Push Query pour confirmer le statut réel, car les callbacks manquants sont la première cause de commandes bloquées en "en attente".
La validation du callback impose de vérifier le MerchantRequestID, le CheckoutRequestID et le ResultCode. Un ResultCode à 0 signifie succès ; toute autre valeur est un échec avec sa cause.
| Étape | 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 résultat | 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 retournés évite de traiter un simple timeout comme un vrai échec de paiement. Voici les codes les plus fréquents et leur traitement recommandé.
| Code Daraja | Signification | Fréquence (est.) | Action |
|---|---|---|---|
| 0 | Succès | ~82 % | Valider la commande |
| 1037 | Timeout, pas de réponse | ~8 % | Relance SMS + retry |
| 1032 | Annulé par l'utilisateur | ~4 % | Proposer un nouveau lien |
| 1 | Solde insuffisant | ~3 % | Message + autre opérateur |
| 2001 | PIN incorrect | ~2 % | Relancer le prompt |
| 1019 | Transaction expirée | ~1 % | Réinitialiser |
Le code 1037 (timeout) est le plus trompeur : le client a peut-être juste rate la fenêtre de 60 secondes. Une relance immédiate par SMS avec un lien de reprise récupère en moyenne +11 % de ces transactions.
Mini cas pratique
Wanjiru gère une plateforme de livraison de repas à Nairobi, avec 6 000 tentatives de paiement STK par mois. Sans gestion fine : 82 % de succès, soit 4 920 paiements. Les 1 080 échecs incluent environ 480 timeouts (code 1037). En ajoutant une relance SMS automatique sur les timeouts, elle récupère 11 % de ces 480, soit 53 commandes/mois, plus la baisse des abandons grâce à un message clair sur les soldes insuffisants. À un panier moyen de 1 500 KES, c'est +79 500 KES/mois récupérés pour un coût SMS négligeable.
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. Implémentez un STK Push Query automatique 30 à 60 secondes après l'init pour résoudre le statut de façon fiable.
Combien de temps le client a-t-il pour saisir son PIN ?
Le prompt STK expire au bout de 60 secondes. Au-delà, vous recevez un code 1037 et devez proposer une relance plutôt que de considérer la vente perdue.
Faut-il retenter automatiquement un paiement en timeout ?
Oui, mais avec parcimonie : un seul retry déclenché par le client via un lien SMS, jamais une boucle automatique qui multiplierait les prompts et agacerait l'utilisateur.
Quelle différence entre callback et C2B confirmation ?
Le callback STK confirme le résultat de la demande de paiement ; la confirmation C2B sert au rapprochement comptable côté 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 fidèlement les pertes réseau réelles. 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.
