Guide du module Passerelle de paiement MTN MoMo

Acceptez les paiements par mobile money des utilisateurs MTN Mobile Money (MoMo) à travers l’Afrique. S’intègre à l’API MTN MoMo Collections pour créer des transactions “Request to Pay”, permettant aux clients d’approuver les paiements directement depuis leur téléphone.

Cas d’utilisation

E-commerce en Afrique

Vous gérez une boutique en ligne sur Larapen ciblant les clients dans les pays desservis par MTN (Ouganda, Ghana, Cameroun, Côte d’Ivoire, Bénin, Congo, Libéria). Les clients paient leurs commandes en utilisant leur portefeuille MTN MoMo : aucune carte de crédit requise.

• Installez les add-ons Boutique et MoMo.
• Configurez les identifiants MTN MoMo dans le panneau d’administration.
• Les clients sélectionnent “MTN Mobile Money” au moment du paiement, entrent leur numéro de téléphone et approuvent le paiement sur leur téléphone.

Vente de produits numériques

Vous vendez des produits numériques (e-books, logiciels, modèles) à des utilisateurs mobile-first qui préfèrent le mobile money aux paiements par carte.

• Combinez avec la livraison de produits numériques de l’add-on Boutique.
• Après confirmation du paiement MoMo, le lien de téléchargement est automatiquement fourni.

Réservation de services

Toute entité payable implémentant le contrat Payable peut utiliser MoMo pour le paiement, ce qui le rend extensible au-delà de l’add-on Boutique.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• L’add-on Boutique (dépendance requise)
• Un compte développeur MTN MoMo sur momodeveloper.mtn.com
• Un abonnement au produit Collections sur le portail développeur MTN MoMo

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Téléverser un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Passerelle de paiement MTN MoMo dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → MTN MoMo → Paramètres et saisissez vos identifiants API. Pour les tests en sandbox, utilisez la fonctionnalité Provisionnement pour générer automatiquement des identifiants. Voir Configuration.

Code d’achat (clé de licence)

Passerelle de paiement MTN MoMo est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence) — distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Passerelle de paiement MTN MoMo dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée — acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous — il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Tous les paramètres sont gérés dans Admin → MTN MoMo → Paramètres (stockés dans la table settings, groupe momo). Les valeurs par défaut de configuration sont définies dans config/momo.php.

Variables d’environnement

Configuration du portail développeur MTN

1. Créez un compte sur momodeveloper.mtn.com.
2. Abonnez-vous au produit Collections.
3. Naviguez vers votre page Profil et copiez la Clé primaire (ou Clé secondaire) : c’est votre Clé d’abonnement.
4. Pour le sandbox : utilisez la fonctionnalité de Provisionnement du panneau d’administration pour générer automatiquement l’ID utilisateur API et la clé API.
5. Pour la production : obtenez les identifiants depuis le Portail partenaire MTN MoMo et saisissez-les dans Identifiants API.

Admin : Paramètres

La page de paramètres (MTN MoMo → Paramètres) est organisée en quatre sections :

Provisionnement des identifiants Sandbox

Cette section automatise le flux de génération des identifiants sandbox :

1. Entrez votre Clé d’abonnement (depuis la page Profil du portail développeur MTN).
2. Entrez optionnellement un Hôte de rappel (par défaut webhook.site pour le sandbox).
3. Cliquez sur Générer les identifiants API.
4. Le système automatiquement :
   • Génère un UUID v4 pour l’ID utilisateur API
   • Crée l’utilisateur API via POST /v1_0/apiuser
   • Génère la clé API via POST /v1_0/apiuser/{id}/apikey
   • Chiffre et stocke les trois identifiants dans la base de données
   • Définit l’environnement à sandbox et la devise à EUR
5. Les identifiants générés sont affichés une seule fois dans une alerte de succès avec des boutons de copie. Sauvegardez-les en externe : la clé API ne peut pas être récupérée à nouveau depuis MTN.

Tester la clé

Le bouton Tester la clé effectue un appel API de diagnostic (crée un utilisateur API temporaire) pour vérifier que la clé d’abonnement est valide. Renvoie HTTP 201 en cas de succès, avec les détails de requête/réponse pour le débogage.

Identifiants API

Trois champs de type mot de passe avec des boutons de basculement de visibilité :

• Clé d’abonnement : Ocp-Apim-Subscription-Key depuis le portail MTN.
• ID utilisateur API : UUID v4 créé lors du provisionnement de l’utilisateur API.
• Clé API : Générée à partir de l’utilisateur API.

Options de paiement

• Environnement : sandbox ou production. Détermine quelle URL de base de l’API MTN est utilisée.
• Environnement cible : Envoyé comme en-tête X-Target-Environment. Utilisez sandbox pour les tests, ou l’une des valeurs spécifiques au pays pour la production :

• Devise : Doit correspondre à l’environnement cible (voir le tableau ci-dessus). Doit être EUR en sandbox.
• Hôte de rappel : Votre domaine pour recevoir les rappels webhook (production uniquement). HTTPS est requis.

Informations d’intégration

Le bas de la page de paramètres affiche :

• L’URL de rappel (https://your-domain.com/momo/callback) à copier dans le portail MTN.
• Une liste de référence de toutes les valeurs d’environnement cible valides par pays.

Flux de paiement

Le parcours de paiement complet du passage en caisse à la confirmation :

1. Sélection au passage en caisse

Le client sélectionne “MTN Mobile Money” comme méthode de paiement sur la page de paiement. Un champ de saisie du numéro de téléphone est affiché (la vue Blade momo::payment-form).

2. Saisie du numéro de téléphone

Le client entre son numéro de téléphone MTN MoMo (ex. +233XXXXXXXXX). Le numéro est normalisé (espaces, tirets et parenthèses supprimés) avant la soumission.

3. Création de la commande

Le formulaire est soumis via AJAX. L’add-on Boutique crée l’enregistrement de commande, puis appelle MomoGateway::createPaymentIntent().

4. Request to Pay

La passerelle :

1. Obtient un jeton Bearer OAuth2 depuis MTN (POST /collection/token/).
2. Génère un identifiant de référence UUID pour la transaction.
3. Envoie un “Request to Pay” à MTN (POST /collection/v1_0/requesttopay).
4. Stocke un enregistrement MomoTransaction avec le statut PENDING.
5. Retourne l’identifiant de référence au frontend.

5. Approbation USSD

Le client reçoit une invite USSD sur son téléphone MTN et entre son code PIN pour approuver le paiement.

6. Vérification côté frontend

Pendant que le client approuve, le JavaScript frontend interroge GET /momo/status/{referenceId} toutes les 5 secondes (configurable), affichant une barre de progression.

7. Confirmation

Lorsque la vérification renvoie succeeded, le frontend redirige vers GET /momo/confirm?reference_id={id}. La méthode MomoController::confirm() vérifie le statut final, marque la commande comme payée et redirige vers la page de succès de la commande.

Webhooks

En production, MTN MoMo envoie des rappels à votre serveur lorsque le statut d’un paiement change. L’URL de rappel est https://your-domain.com/momo/callback.

Remboursements

Intégration avec l’add-on Boutique

L’add-on MoMo s’intègre avec l’add-on Boutique à travers le contrat PaymentGatewayInterface :

Découverte de la passerelle

La classe MomoGateway est taguée comme payment.gateways dans le conteneur de services. L’add-on Boutique la découvre automatiquement aux côtés des autres passerelles de paiement (ex. Stripe).

Interface Payable

Le modèle Order de la Boutique implémente App\Contracts\Payable, qui fournit :

• getPayableAmount() : le total de la commande
• getPayableIdentifier() : le numéro de commande
• getPaymentSuccessUrl() : URL de redirection après paiement réussi
• getPaymentCancelUrl() : URL de redirection après paiement échoué/annulé
• markAsPaid() : met à jour le statut de la commande à COMPLETED et le statut de paiement à PAID

Enregistrement des transactions

Deux types d’enregistrements de transaction sont créés :

• MomoTransaction : suit l’identifiant de référence API MTN, le statut et le numéro de téléphone du payeur.
• Transaction Boutique : créée par le gestionnaire de rappel/confirmation pour l’historique de paiement de la commande.

Support polymorphique

Le modèle MomoTransaction utilise une relation morphTo (payable_type / payable_id), permettant à tout modèle implémentant Payable d’utiliser MoMo pour les paiements : pas seulement les commandes de la Boutique.

Mise à jour

Il existe deux façons de mettre cet add-on à jour : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléversement via le panneau d’administration (recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

php artisan migrate

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 3 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 4 : Vérifier

Visitez MTN MoMo → Paramètres et utilisez Tester la clé pour confirmer que vos identifiants fonctionnent toujours.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez MTN MoMo Payment Gateway et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/momo/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez MTN MoMo Payment Gateway (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations — ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent — et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/momo/, public/vendor/momo/ et storage/app/public/addons/momo/ ;
• supprime le dossier de l’add-on extensions/addons/momo/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/momo/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

“Failed to obtain MTN MoMo access token”

Vérifiez que :

• Les trois identifiants API (Clé d’abonnement, ID utilisateur API, Clé API) sont correctement configurés.
• La clé d’abonnement n’a pas expiré ou n’a pas été révoquée.
• Votre serveur peut atteindre sandbox.momodeveloper.mtn.com (sandbox) ou proxy.momoapi.mtn.com (production).
• L’ID utilisateur API et la clé API correspondent : ils doivent provenir de la même session de provisionnement.

Le provisionnement échoue : HTTP 401

• Vérifiez que vous êtes abonné au produit Collections sur momodeveloper.mtn.com.
• Copiez la Clé primaire depuis votre page Profil, pas depuis la page du produit.
• Assurez-vous que l’abonnement est toujours actif (non expiré).
• Vérifiez les espaces en début/fin lors du collage de la clé.

Le provisionnement échoue : HTTP 409

Un utilisateur API avec l’UUID généré existe déjà. Cliquez simplement sur Générer les identifiants API à nouveau : un nouvel UUID est généré à chaque fois.

“A phone number is required for MTN MoMo payments”

Le client n’a pas saisi son numéro de téléphone dans le formulaire de paiement. Assurez-vous que la vue du formulaire de paiement MoMo (momo::payment-form) est correctement chargée et que le champ de saisie du téléphone est visible lorsque MoMo est sélectionné comme méthode de paiement.

Le paiement reste “en attente” indéfiniment

• En sandbox : utilisez l’un des numéros de téléphone de test (voir Tests Sandbox).
• En production : le client n’a peut-être pas approuvé l’invite USSD sur son téléphone.
• Après le délai d’expiration de la vérification (~5 minutes), un message de délai dépassé est affiché à l’utilisateur.
• Le paiement peut encore être confirmé ultérieurement via webhook si le client approuve après le délai.

“Payment was declined or cancelled”

• Le client a refusé l’invite USSD ou a saisi un code PIN incorrect.
• Le compte MoMo du client a des fonds insuffisants.
• Le code de raison MTN est ajouté au message d’erreur pour le débogage (ex. PAYER_NOT_FOUND, NOT_ENOUGH_FUNDS).

“Request was blocked” (réponse non JSON)

Un WAF (pare-feu d’application web) ou un proxy a bloqué la requête API. Cela peut arriver lorsque la passerelle API MTN rejette la requête au niveau de l’infrastructure. Vérifiez les journaux du serveur pour le corps de réponse complet et vérifiez votre clé d’abonnement et la configuration de l’hôte de rappel.

Le webhook ne fonctionne pas en production

• Assurez-vous que momo_callback_host est défini sur votre domaine (sans le préfixe https://).
• L’hôte de rappel dans vos paramètres doit correspondre au providerCallbackHost défini lors de la création de l’utilisateur API.
• Votre serveur doit accepter les requêtes PUT et POST à /momo/callback sans vérification CSRF.
• Vérifiez que HTTPS fonctionne correctement sur votre domaine.

Erreurs de non-concordance de devise

• Le sandbox requiert EUR : toute autre devise échouera.
• La production requiert la devise spécifique au pays correspondant à l’environnement cible (voir Options de paiement).

Numéros de téléphone de test Sandbox

Utilisez ces numéros de téléphone en mode sandbox pour tester différents résultats de paiement :