Installer le module PrestaShop pour Papi

Le module PrestaShop pour Papi permet d'intégrer l'agrégateur de paiement Papi dans une boutique PrestaShop 1.7 ou 8.x.

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 module, vérifiez les points suivants :

• Vous travaillez avec PrestaShop 1.7.x ou 8.x
• Votre site utilise PHP version 7.4 minimum
• L'extension cURL de PHP est activée
• Vous avec créé une boutique chez Papi avec une clé API de boutique
• Vous avec créé une boutique PrestaShop
• La boutique PrestaShop doit être configurée pour accepter la devise MGA (Ariary malgache)

Télécharger le module

Téléchargez le fichier Zip officiel du module PrestaShop 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 PrestaShop.

Installer le module depuis le back-office PrestaShop

1. Dans le back-office PrestaShop, ouvrez Modules > Gestionnaire de modules.
2. Cliquez sur Téléverser un module.
3. Sélectionnez le fichier papi_prestashop.zip téléchargé.
4. Attendez que PrestaShop téléverse et installe le module.
5. Une fois l'installation terminée, cliquez sur Configurer.

Si le téléversement réussit, PrestaShop extrait automatiquement le fichier Zip et place le module dans le bon répertoire modules/papi_prestashop/.

Installation manuelle

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

1. Décompressez le fichier papi_prestashop.zip téléchargé sur votre ordinateur.
2. Vérifiez que le dossier extrait s'appelle bien papi_prestashop.
3. Copiez le dossier papi_prestashop/ dans le répertoire modules/ de votre installation PrestaShop.
4. Dans le back-office PrestaShop, ouvrez Modules > Gestionnaire de modules.
5. Recherchez le module Papi.
6. Cliquez sur Installer, puis sur Configurer.

Pendant l'installation, le module effectue automatiquement les opérations suivantes :

• Création du statut de commande En attente de paiement Papi.
• Stockage de l'identifiant de ce statut dans la configuration PAPI_OS_AWAITING.
• Association du module à toutes les devises via une entrée -1 dans ps_module_currency, afin que l'option de paiement puisse apparaître au checkout.
• Création de la table ps_papi_transaction en base de données.

Si vous réinstallez le module, le statut de commande n'est pas recréé s'il existe déjà. L'installation est prévue pour éviter les doublons.

Configuration obligatoire de la devise MGA

Papi accepte uniquement aujourd'hui les paiements en Ariary malgache (MGA). Si la boutique ne propose pas MGA comme devise active, le bouton Payer avec Papi peut ne pas apparaître au checkout, ou le client peut être renvoyé au panier avec un message d'erreur.

Importer la devise MGA

1. Dans le back-office, ouvrez International > Localisation.
2. Dans l'onglet Localisation, utilisez le bloc Importer un pack de localisation.
3. Sélectionnez Madagascar.
4. Lancez l'import.

Cette opération crée notamment la devise MGA et la zone géographique Madagascar.

Définir MGA comme devise par défaut

1. Dans le back-office, ouvrez International > Localisation.
2. Descendez jusqu'au panneau Paramètres.
3. Dans le champ Devise par défaut, sélectionnez Ariary malgache (MGA).
4. Enregistrez.

Le changement de devise par défaut peut ne pas être visible immédiatement sur le front-office si le navigateur conserve une ancienne devise en session. Pour tester correctement, utilisez le sélecteur de devise de la boutique et basculez explicitement en MGA.

Vérifier l'affichage en boutique

Les prix doivent s'afficher en Ar sur les pages produit et dans le panier. Si les prix restent en euros, basculez la devise depuis le sélecteur de devise du thème PrestaShop.

Lorsque MGA est la devise active, certains modules de paiement natifs comme le chèque, le virement ou le paiement à la livraison peuvent disparaître du checkout. C'est un comportement normal de PrestaShop lorsque ces modules ne déclarent pas leur compatibilité avec la devise active.

Configuration du module

1. Dans le back-office, ouvrez Modules > Gestionnaire de modules.
2. Recherchez le module Papi.
3. Cliquez sur Configurer.
4. Renseignez les champs nécessaires.

Champ	Description
Clé API	Clé de boutique fournie par le dashboard Papi. Le module effectue un appel de validation lors de l'enregistrement.
URL de notification (override)	À laisser vide en production. À utiliser uniquement dans certains scénarios de développement local.
Mode test	À activer pendant les tests. En mode test, Papi ne débite pas réellement les cartes. À désactiver avant la mise en production.

Après enregistrement, un message de succès confirme que la configuration a été sauvegardée et que la clé API est valide.

Si la validation de la clé API échoue avec une erreur 401 ou 403, la clé est incorrecte ou révoquée. Les autres erreurs réseau, comme un timeout ou une erreur serveur temporaire, ne bloquent pas nécessairement l'enregistrement de la clé, mais doivent être surveillées avant la mise en production.

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 à votre boutique PrestaShop de mettre à jour automatiquement le statut de paiement des commandes.

En production

1. Dans le dashboard Papi, configurez l'URL de notification de votre boutique.
2. L'URL générée par le module suit ce format :

https://votre-boutique.mg/fr/module/papi_prestashop/notification

Cette URL est affichée dans la description du champ URL de notification sur la page de configuration du module.

En production, laissez le champ URL de notification (override) vide. PrestaShop génère alors l'URL correcte automatiquement.

Lorsque vous enregistrez la configuration du module avec une clé API valide, le module transmet l'URL de notification à 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 PrestaShop tourne en local, par exemple sur http://localhost:8080, 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 8080

3. Récupérez l'URL publique fournie par ngrok.
4. Dans la configuration du module, renseignez l'URL complète dans le champ override :

https://xxx.ngrok-free.app/fr/module/papi_prestashop/notification

Limitation connue : PrestaShop effectue une vérification de domaine et peut rediriger les requêtes entrantes vers le domaine canonique de la boutique. Dans ce cas, une requête relayée par ngrok peut recevoir une réponse 302 Found au lieu d'être traitée comme webhook. En production, ce problème ne se présente pas lorsque Papi appelle le vrai domaine public de la boutique.

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 PrestaShop local.

Exemple PowerShell :

$body = '{"paymentStatus":"SUCCESS","merchantPaymentReference":"VOTRE_REF","notificationToken":"VOTRE_TOKEN","paymentMethod":"MVOLA","currency":"MGA","amount":89661}'
Invoke-WebRequest -Uri "http://localhost:8080/fr/module/papi_prestashop/notification" `
  -Method POST `
  -ContentType "application/json" `
  -Body $body

Exemple curl :

curl -X POST http://localhost:8080/fr/module/papi_prestashop/notification \
  -H "Content-Type: application/json" \
  -d '{"paymentStatus":"SUCCESS","merchantPaymentReference":"VOTRE_REF","notificationToken":"VOTRE_TOKEN","paymentMethod":"MVOLA","currency":"MGA","amount":89661}'

Une réponse 200 OK avec le contenu OK 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 le bouton Payer avec Papi apparaît avec le logo Papi.
4. Cliquer sur Payer avec Papi.
5. Vérifier que PrestaShop crée une commande en statut En attente de paiement Papi.
6. Vérifier la redirection vers la page de paiement Papi.
7. Effectuer un paiement de test sur la page Papi.
8. Revenir sur la boutique et vérifier la page de confirmation.
9. Après réception du webhook, vérifier que le statut de commande passe à Paiement accepté dans le back-office.

Un transporteur (livreur) doit être configuré et actif pour la zone géographique du client. Sans transporteur disponible, le checkout peut bloquer à l'étape livraison avant même d'afficher les moyens de paiement. Pour Madagascar, vérifiez qu'au moins un transporteur couvre la zone Afrique ou la zone utilisée par votre configuration PrestaShop.

Statuts de commande

Statut PrestaShop	Quand	Notes
En attente de paiement Papi	Dès le clic sur Payer avec Papi	Statut créé par le module à l'installation.
Paiement accepté	Webhook SUCCESS reçu	Statut natif PrestaShop _PS_OS_PAYMENT_.
Erreur de paiement	Webhook FAILED reçu	Statut natif PrestaShop _PS_OS_ERROR_.
Annulé	Erreur API Papi lors de la création du lien de paiement	La commande est annulée et le client est renvoyé au panier.

Si l'appel à l'API Papi échoue au moment de créer le lien de paiement, la commande PrestaShop a déjà pu être créée. Dans ce cas, le module la passe automatiquement au statut Annulé et renvoie le client vers le panier avec un message d'erreur.

Panneau Transaction Papi dans le back-office

Sur chaque fiche de commande payée via Papi, un panneau Transaction Papi s'affiche à la fin de la fiche.

Ce panneau contient :

• Référence commande : référence PrestaShop, par exemple YHTFKHOIH.
• Statut Papi : accepté, en attente ou échoué, avec badge visuel.
• Montant : montant formaté en MGA.
• Lien de paiement : lien Papi généré lors du paiement.
• Dates : date de création et date de dernière mise à jour de la transaction.
• Réponse brute Papi : JSON complet reçu lors du dernier webhook, affichable pour diagnostic.

La réponse brute affichée correspond au webhook de notification envoyé par Papi après le paiement. Elle ne correspond pas à la réponse de création du lien de paiement. Ces deux échanges sont distincts : le premier crée le paymentLink, le second notifie le résultat du paiement.

Tester le webhook en développement local

Pour tester le webhook localement, récupérez d'abord la valeur notification_token associée à la dernière transaction :

SELECT payment_reference, notification_token
FROM ps_papi_transaction
ORDER BY date_add DESC
LIMIT 1;

Puis envoyez une notification de test :

$body = '{
  "paymentStatus": "SUCCESS",
  "merchantPaymentReference": "VOTRE_REFERENCE_COMMANDE",
  "notificationToken": "VOTRE_NOTIFICATION_TOKEN",
  "paymentMethod": "MVOLA",
  "currency": "MGA",
  "amount": 89661
}'
Invoke-WebRequest -Uri "http://localhost:8080/fr/module/papi_prestashop/notification" `
  -Method POST `
  -ContentType "application/json" `
  -Body $body

Résultat attendu : StatusCode: 200 et contenu OK.

La documentation Papi peut mentionner paymentReference comme champ contenant la référence commande marchand. En pratique, le champ reçu pour cette référence est merchantPaymentReference, tandis que paymentReference contient l'UUID interne Papi. Le module tient compte de ce comportement.

Points d'attention techniques

Envoi d'email lors du changement de statut

Lors de la mise à jour du statut de commande par webhook, le module tente d'envoyer un email de notification au client via OrderHistory::addWithemail().

Si le container Symfony de PrestaShop n'est pas disponible dans le contexte d'exécution, ce qui peut arriver dans certains environnements, le module bascule sur OrderHistory::add() afin de mettre à jour le statut sans email. Un avertissement est consigné dans les logs PrestaShop.

Sur une installation PrestaShop standard en production, OrderHistory::addWithemail() doit fonctionner normalement.

Affichage du module au checkout

Le module vérifie la devise au moment du contrôleur de redirection, pas uniquement à l'affichage du bouton. Si la boutique est en euro au moment du clic, le client peut voir le bouton mais être renvoyé au panier avec un message expliquant que la devise MGA est requise.

Durée de validité du lien de paiement

Le lien de paiement Papi affiché dans la fiche commande reste valide pendant la durée configurée lors de sa création, par défaut 60 minutes. Après expiration, il reste affiché à titre informatif.

Commandes multiples sur un même panier

PrestaShop crée la commande avant la redirection vers Papi. Si le client abandonne le paiement et retente depuis le panier, un nouveau panier et une nouvelle commande peuvent être créés. L'ancienne commande reste en statut En attente de paiement Papi et peut être annulée manuellement depuis le back-office si nécessaire.

Structure du module

papi_prestashop/
├── papi_prestashop.php
├── logo.png
├── classes/
│   ├── PapiApiClient.php
│   └── PapiApiException.php
├── controllers/
│   └── front/
│       ├── redirect.php
│       ├── notification.php
│       ├── success.php
│       └── failure.php
├── sql/
│   ├── install.sql
│   └── uninstall.sql
└── views/
    ├── img/
    │   └── logo-papi.png
    ├── css/
    │   └── checkout.css
    └── templates/
        ├── hook/
        │   ├── payment_option.tpl
        │   └── admin_order.tpl
        └── front/
            ├── success.tpl
            └── failure.tpl

Fichier	Rôle
papi_prestashop.php	Classe principale du module, héritant de PaymentModule.
classes/PapiApiClient.php	Client HTTP vers l'API Papi.
classes/PapiApiException.php	Exception métier utilisée pour les erreurs Papi.
controllers/front/redirect.php	Reçoit le clic checkout, crée la commande et appelle Papi.
controllers/front/notification.php	Endpoint webhook POST appelé par Papi.
controllers/front/success.php	Page de retour après paiement réussi.
controllers/front/failure.php	Page de retour après paiement échoué.
sql/install.sql	Création de la table ps_papi_transaction.
sql/uninstall.sql	Suppression de la table ps_papi_transaction.
views/templates/hook/payment_option.tpl	Bloc affiché sous le bouton Payer avec Papi.
views/templates/hook/admin_order.tpl	Panneau Transaction Papi dans la fiche commande back-office.

Table ps_papi_transaction

Le module stocke les transactions Papi dans la table ps_papi_transaction.

Colonne	Type	Description
id_order	int	ID de la commande PrestaShop.
id_cart	int	ID du panier PrestaShop.
payment_reference	varchar	Référence commande PrestaShop, par exemple YHTFKHOIH.
notification_token	varchar	Token de sécurité retourné par Papi à la création du lien de paiement.
payment_link	varchar	URL de la page de paiement Papi.
amount	decimal	Montant en MGA.
currency	varchar	Code devise, normalement MGA.
status	varchar	Statut interne : pending, success ou failed.
raw_response	text	JSON complet du dernier webhook reçu.
date_add	datetime	Date de création.
date_upd	datetime	Date de dernière mise à jour.

Désinstallation

La désinstallation depuis Modules > Désinstaller effectue les opérations suivantes :

• Suppression du statut de commande En attente de paiement Papi.
• Suppression des valeurs de configuration du module, comme PAPI_API_KEY et PAPI_TEST_MODE.
• Suppression de la table ps_papi_transaction.

La suppression de la table ps_papi_transaction est irréversible. Si la boutique contient des transactions en cours ou si l'historique doit être conservé, sauvegardez cette table avant de désinstaller le module.