mobupay/module-payment

Passerelle de paiement Mobupay pour Magento 2 / Adobe Commerce (modele redirect / page hebergee).

v1.0.0 2026-07-23 01:15 UTC

Requires

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

MIT

Published on Packagist.org on 2026-07-24 04:07 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) et le secret whsec_*, depuis votre espace marchand > Développeurs > Clés API.

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)
Secret de signature des webhooks	Votre whsec_*
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

Limite connue : remboursement impossible pendant la fenêtre de transit (~24 h) côté Mobupay ; réessayer après le règlement (le lendemain matin, heure de Nouméa).