mobupay / module-payment

v1.1.0 2026-08-27 02:36 UTC

Requires

• php: >=7.4
• mobupay/mobupay-php: *

MIT

Published on Packagist.org on 2026-08-27 02:49 UTC

README

Passerelle de paiement Mobupay pour Magento 2.3+ / Adobe Commerce. Modèle redirect / page hébergée : le client paie sur une page sécurisée Mobupay (widget Monext), la carte ne touche jamais votre serveur, et la commande est mise à jour par webhook signé.

Réutilise le SDK PHP mobupay/mobupay-php (même client + vérification de signature que les connecteurs WooCommerce et PrestaShop).

Prérequis

• Magento 2.3+ / Adobe Commerce, PHP >= 7.4.
• Une clé API Mobupay (sk_test_* pour tester, sk_live_* en production), depuis votre espace marchand > Développeurs > Clés API. C'est le seul secret à saisir : le secret de signature des webhooks est récupéré automatiquement à l'enregistrement.

Installation

Via Composer (recommandé)

composer require mobupay/module-payment
bin/magento module:enable Mobupay_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Le SDK mobupay/mobupay-php est tiré automatiquement comme dépendance.

Installation manuelle (app/code)

1. Copier le dossier dans app/code/Mobupay/Payment/.
2. Copier le SDK dans app/code/Mobupay/Payment/lib/mobupay-php/ (le module charge ce fallback si Composer ne l'a pas autoloadé).
3. bin/magento module:enable Mobupay_Payment && bin/magento setup:upgrade && bin/magento cache:flush.

Configuration

Admin > Stores > Configuration > Sales > Payment Methods > Mobupay (carte bancaire) :

Champ	Valeur
Activer	Oui
Libellé affiché au client	ex. « Carte bancaire (Mobupay) »
Mode test (sandbox)	Oui pour démarrer
Clé API de test / production	Vos clés sk_test_* / sk_live_* (chiffrées en base)
Détail de la commande	Oui par défaut. Articles, taxes par ligne, frais de port, remises
Coordonnées du client	Oui par défaut. Nom, adresse de facturation, téléphone, adresse de livraison
Facture Mobupay	Non par défaut. Si des mentions manquent, le paiement aboutit quand même et la facture reste en brouillon à compléter
Base API	https://api.mobupay.nc (ne modifier que sur instruction du support Mobupay)

URL de webhook (notificationUrl) : https://votre-boutique/mobupay/webhook. Elle est transmise automatiquement à chaque paiement ; aucun enregistrement manuel n'est nécessaire côté Mobupay.

Fonctionnement

1. Le client choisit « Carte bancaire (Mobupay) » et place la commande.
2. Le navigateur est redirigé vers mobupay/redirect, qui crée une session Mobupay (reference = increment_id, externalId = id de commande, Idempotency-Key anti double-paiement) et redirige vers la page hébergée. La commande reste en attente de paiement.
3. Le client paie. Mobupay envoie un webhook signé à mobupay/webhook.
4. Le module vérifie la signature (Webhook::verify, V2 anti-rejeu + repli V1), rapproche la commande via externalId, puis :
   • payment.captured / payment.authorized → facture offline créée, commande en traitement ;
   • payment.failed → commande annulée ;
   • payment.expired / payment.cancelled → commande annulée (si non payée) ;
   • payment.refunded / payment.partially_refunded → commentaire d'historique.
5. Le statut est piloté par le webhook, jamais par le retour navigateur (non fiable). Idempotent (déduplication par event.id).

Remboursement

Admin > Sales > Orders > (commande) > Credit Memo > Refund (en ligne) : appelle l'API Mobupay (total ou partiel). Nécessite une facture (créée à l'encaissement).

Matrice de test (sandbox)

À exécuter avec une clé sk_test_* et une carte de test sandbox (ex. 5476 4309 9999 9892) :

Scénario	Attendu
Paiement réussi	Commande en attente → en traitement (facture offline) après payment.captured
Refus carte	payment.failed → commande annulée
Abandon / fermeture onglet	Pas de capture ; à l'expiration, payment.expired → annulée
Double soumission	Idempotency-Key → un seul paiement
Rejeu de webhook (même event.id)	Ignoré (idempotence receiver)
Remboursement total puis partiel (avoir)	API refund OK, commentaires d'historique
Signature invalide	Webhook rejeté (403), commande inchangée