Aller au contenu principal

Installer le plugin WooCommerce pour Papi

Le plugin WooCommerce pour Papi permet d'intégrer l'agrégateur de paiement Papi dans une boutique WordPress WooCommerce.

Il permet d'accepter les paiements par Mobile Money (MVola, Orange Money, Airtel Money) et par cartes Visa et Mastercard à Madagascar.

Prérequis​

Avant d'installer le plugin, vérifiez les points suivants :

  • Vous utilisez WordPress 5.0 ou une version ultérieure
  • Vous utilisez WooCommerce 3.0 ou une version ultérieure (testé jusqu'à la version 9.9)
  • Votre site utilise PHP version 7.2 minimum
  • Vous avez créé une boutique chez Papi avec une clé API de boutique
  • Votre boutique WooCommerce est configurée pour utiliser la devise MGA (Ariary malgache)

Télécharger le plugin​

Téléchargez le fichier Zip officiel du plugin WooCommerce Papi depuis la page Téléchargements.

Utilisez la dernière version disponible, sauf si le support Papi vous a explicitement demandé d'installer une autre version. La page Téléchargements liste les versions officielles de la plus récente à la plus ancienne, avec pour chaque version le fichier Zip, le checksum SHA-256, les notes de compatibilité et le changelog.

Après le téléchargement, conservez le fichier au format Zip. Vous n'avez pas besoin de le décompresser avant de l'installer depuis le back-office WordPress.

Installer le plugin depuis le back-office WordPress​

Installation par téléversement​

  1. Dans le back-office WordPress, ouvrez Plugins → Add New Plugin.
  2. Cliquez sur Upload Plugin.
  3. Sélectionnez le fichier papi-woocommerce-gateway.zip téléchargé.
  4. Cliquez sur Install Now.
  5. Une fois l'installation terminée, cliquez sur Activate Plugin.
  6. Ouvrez WooCommerce → Settings → Payments et cliquez sur Manage en face de Papi Payment pour le configurer.

Installation manuelle via FTP​

Utilisez l'installation manuelle uniquement si votre back-office WordPress ne permet pas de téléverser le fichier Zip du plugin.

  1. Décompressez le fichier papi-woocommerce-gateway.zip téléchargé sur votre ordinateur.
  2. Vérifiez que le dossier extrait s'appelle bien papi-woocommerce-gateway.
  3. Copiez le dossier papi-woocommerce-gateway/ dans le répertoire wp-content/plugins/ de votre installation WordPress.
  4. Dans le back-office WordPress, ouvrez Plugins.
  5. Recherchez Papi Payment Gateway for WooCommerce et cliquez sur Activate.

Configuration obligatoire de la devise MGA​

Papi accepte uniquement aujourd'hui les paiements en Ariary malgache (MGA). Si la boutique WooCommerce n'est pas configurée avec MGA comme devise active, l'option de paiement Papi n'apparaîtra pas au checkout.

Définir MGA comme devise WooCommerce​

  1. Dans le back-office WordPress, ouvrez WooCommerce → Settings → General.
  2. Dans le champ Currency, sélectionnez Malagasy ariary (Ar).
  3. Enregistrez les paramètres.

Une fois MGA sélectionnée, les prix s'affichent en Ar sur les pages produit et dans le panier.

Configuration du plugin​

  1. Dans le back-office WordPress, ouvrez WooCommerce → Settings → Payments.
  2. Cliquez sur Manage en face de Papi Payment.
  3. Renseignez les champs nécessaires.
ChampDescription
Enable/DisableActive le moyen de paiement Papi au checkout. Désactivé par défaut.
TitleLe libellé que le client voit au checkout. Valeur par défaut : Paiement Mobile Money / Carte.
DescriptionLa description affichée sous l'option de paiement. Valeur par défaut : Payez par MVola, Airtel Money, Orange Money ou carte bancaire.
Papi API keyVotre clé API de boutique disponible sur dashboard.papi.mg sous Boutiques → Developer.

Après enregistrement, le moyen de paiement Papi est immédiatement disponible au checkout.

Configuration du webhook Papi​

Le webhook est l'URL de votre boutique appelée par Papi après chaque changement de statut de paiement. C'est ce mécanisme qui permet à WooCommerce de mettre à jour automatiquement le statut des commandes.

En production​

L'URL de notification est générée automatiquement par le plugin. Aucune configuration manuelle n'est nécessaire dans WooCommerce.

Dans le dashboard Papi, configurez l'URL de notification de votre boutique. L'URL suit ce format :

https://votre-boutique.mg/?wc-api=wc_gateway_papi

Si votre installation WordPress utilise les permaliens optimisés, l'URL peut également se présenter ainsi :

https://votre-boutique.mg/wc-api/wc_gateway_papi/

L'URL de notification doit être publiquement accessible depuis Internet. Un serveur local, un serveur derrière VPN ou un environnement non exposé publiquement ne recevra pas les notifications Papi.

En développement local​

Si WordPress tourne en local, par exemple sur http://localhost/my-store, Papi ne peut pas appeler directement votre machine.

Deux approches sont possibles.

Option A : tunnel ngrok​

  1. Installez et configurez ngrok.
  2. Démarrez un tunnel vers votre port local :
ngrok http 80
  1. Récupérez l'URL publique fournie par ngrok, par exemple https://abc123.ngrok-free.app.
  2. Dans le dashboard Papi, renseignez l'URL de notification suivante :
https://abc123.ngrok-free.app/?wc-api=wc_gateway_papi

Option B : test direct en ligne de commande​

Pour tester le traitement du webhook sans passer par Papi, récupérez un payload JSON valide et rejouez-le directement vers votre WordPress local.

Récupérez d'abord la valeur de la meta _papi_notification_token de la commande que vous souhaitez tester. Vous la trouverez dans la base de données WordPress (wp_postmeta, ou wp_wc_orders_meta si HPOS est activé) ou directement depuis la fiche de commande WooCommerce sous Custom Fields.

Envoyez ensuite une notification de test.

Exemple PowerShell :

$body = '{"paymentStatus":"SUCCESS","merchantPaymentReference":"WC-123","notificationToken":"VOTRE_TOKEN","paymentMethod":"MVOLA","currency":"MGA","amount":8000}'
Invoke-WebRequest -Uri "http://localhost/my-store/?wc-api=wc_gateway_papi" `
  -Method POST `
  -ContentType "application/json" `
  -Body $body

Exemple curl :

curl -X POST "http://localhost/my-store/?wc-api=wc_gateway_papi" \
  -H "Content-Type: application/json" \
  -d '{"paymentStatus":"SUCCESS","merchantPaymentReference":"WC-123","notificationToken":"VOTRE_TOKEN","paymentMethod":"MVOLA","currency":"MGA","amount":8000}'

Une réponse 200 OK avec le contenu {"success":true} confirme que le webhook a bien été traité.

Vérification du parcours d'achat​

Avant la mise en production, testez le parcours complet :

  1. Sélectionner un produit et l'ajouter au panier.
  2. Aller au checkout.
  3. À l'étape paiement, vérifier que Papi Payment apparaît avec le logo Papi.
  4. Sélectionner Papi Payment et cliquer sur Place Order.
  5. Vérifier que WooCommerce crée une commande en statut Pending payment.
  6. Vérifier la redirection vers la page de paiement hébergée par Papi.
  7. Effectuer un paiement de test sur la page Papi.
  8. Revenir sur la boutique et vérifier la page de confirmation de commande.
  9. Après réception du webhook, vérifier que le statut de commande passe à Processing ou Completed dans le back-office WooCommerce.

Statuts de commande​

Statut WooCommerceQuandNotes
Pending paymentDès que le client est redirigé vers la page de paiement PapiLe panier est vidé à ce moment-là.
ProcessingWebhook SUCCESS reçuDéclenché par payment_complete(). WooCommerce peut passer automatiquement à Completed selon les réglages de vos produits.
FailedWebhook FAILED reçuLa note de commande contient le motif d'échec retourné par Papi.
Pending payment (note ajoutée)Webhook PENDING reçuLe statut de commande reste inchangé ; une note est ajoutée pour indiquer que le paiement est en attente de confirmation.

Logs​

Le plugin consigne tous les événements webhook dans le système de logs de WooCommerce. Les logs sont accessibles depuis WooCommerce → Status → Logs. Sélectionnez la source papi-gateway dans la liste déroulante.

Niveau de logQuand
infoChaque notification webhook entrante (payload complet).
warningNotification malformée reçue (champs obligatoires manquants).
errorCommande introuvable pour la référence, ou token de notification non concordant.

Les fichiers de log sont stockés dans wp-content/uploads/wc-logs/ et font l'objet d'une rotation automatique par WooCommerce.

Points d'attention techniques​

Durée de validité du lien de paiement​

Le lien de paiement Papi est valide pendant 60 minutes après sa création. Si le client ne finalise pas le paiement dans ce délai, le lien expire. La commande reste en statut Pending payment et peut être annulée manuellement depuis le back-office WooCommerce.

Commandes multiples sur un même panier​

WooCommerce crée la commande et vide le panier avant la redirection vers Papi. Si le client abandonne le paiement et revient sur la boutique, le panier sera vide. L'ancienne commande reste en statut Pending payment et peut être annulée manuellement depuis le back-office si nécessaire.

Checkout à base de blocs​

Le plugin est entièrement compatible avec le checkout WooCommerce classique et avec le checkout WooCommerce à base de blocs (blocs Cart & Checkout, activés par défaut depuis WooCommerce 8+).

Compatibilité HPOS​

Le plugin est compatible avec le stockage de commandes haute performance de WooCommerce (HPOS / tables de commandes dédiées). Toutes les données de commande sont lues et écrites via l'API de commandes WooCommerce.

Absence de HTTPS en développement​

WooCommerce peut afficher un avertissement lorsque la boutique ne fonctionne pas en HTTPS. Cela n'empêche pas le moyen de paiement Papi d'apparaître au checkout dans un environnement de développement. En production, le HTTPS est obligatoire.

Structure du plugin​

papi-woocommerce-gateway/
├── papi-woocommerce-gateway.php
├── uninstall.php
├── readme.txt
├── assets/
│   ├── logo-papi-full.svg
│   └── zone.png
└── includes/
    └── class-papi-delivery-fee-module.php
FichierRôle
papi-woocommerce-gateway.phpFichier principal du plugin. Déclare la classe de passerelle de paiement WC_Gateway_Papi, enregistre la compatibilité avec les fonctionnalités WooCommerce (HPOS, checkout à base de blocs) et charge le module de frais de livraison.
uninstall.phpExécuté lors de la suppression du plugin depuis le back-office WordPress. Supprime de la base de données toutes les options du plugin et les meta de commande.
readme.txtReadme de plugin au format standard WordPress.org.
assets/logo-papi-full.svgLogo Papi affiché au checkout à côté du nom du moyen de paiement.
assets/zone.pngImage de la carte des zones de livraison (réservée à une version future).
includes/class-papi-delivery-fee-module.phpModule de frais de livraison par zone (désactivé en v1.0, prévu pour une version future).

Meta de commande​

Le plugin stocke les métadonnées suivantes sur les commandes WooCommerce.

Clé de metaDescription
_papi_payment_referenceRéférence marchand envoyée à Papi, au format WC-{order_number}.
_papi_notification_tokenToken de sécurité retourné par Papi à la création du lien de paiement. Utilisé pour vérifier les webhooks entrants.
_papi_payment_linkURL de la page de paiement hébergée par Papi.
_papi_merchant_referenceRéférence marchand confirmée dans le webhook SUCCESS.
_papi_payment_methodMoyen de paiement utilisé par le client (par exemple MVOLA, AIRTEL_MONEY, ORANGE_MONEY).

Désinstallation​

La désinstallation depuis Plugins → Installed Plugins → Delete effectue les opérations suivantes :

  • Suppression des réglages de la passerelle (option WordPress woocommerce_papi_gateway_settings).
  • Suppression de toutes les meta de commande liées à Papi en base de données (à la fois dans la table classique wp_postmeta et dans la table HPOS wp_wc_orders_meta si elle est présente).

La suppression des meta de commande est irréversible. Si l'historique des transactions doit être conservé, sauvegardez les clés de meta concernées avant de désinstaller le plugin.