VibeFox CCAvenue for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur, avec l'extension OpenSSL (utilisée pour chiffrer la requête et déchiffrer la réponse). Le module refuse de s'installer sur les anciennes versions de PHP ou sans OpenSSL.

Compte CCAvenue : vous avez besoin d'un compte marchand CCAvenue avec un Merchant ID, un Access Code et une Working Key. L'Access Code et la Working Key sont émis pour un domaine de site web ; générez-les donc pour le domaine de cette boutique. CCAvenue utilise les mêmes identifiants pour l'environnement de test ; l'accès test doit être activé pour votre compte par CCAvenue. Le module utilise les points d'accès CCAvenue Inde.

Devise : la devise du panier est transmise telle quelle à CCAvenue. Les comptes CCAvenue acceptent l'INR par défaut ; les autres devises nécessitent le traitement multidevise sur votre compte CCAvenue.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox CCAvenue Payment dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez le Merchant ID, l'Access Code et la Working Key de votre tableau de bord CCAvenue, puis activez Enable/Disable.

5. Gardez Test mode activé pendant les tests, puis désactivez-le pour accepter de vrais paiements.

À l'installation, le module crée deux statuts de commande, Awaiting CCAvenue payment et CCAvenue payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox CCAvenue Payment > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque CCAvenue est activé mais que le Merchant ID, l'Access Code ou la Working Key manque (le moyen de paiement est alors masqué à la commande tant que les trois ne sont pas renseignés), affiche CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken. tant que le mode test est activé, et vous rappelle le traitement multidevise lorsque la devise par défaut de la boutique n'est pas l'INR.

CCAvenue

Enable/Disable : Enable CCAvenue Payment Gateway active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que le client voit à la commande. C'est aussi le nom enregistré dans la commande. Par défaut : CCAvenue.

Description : le texte affiché sous le moyen de paiement à la commande. Par défaut : Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

Identifiants API

Connectez-vous à votre tableau de bord marchand CCAvenue (M.A.R.S.) et ouvrez Settings > API Keys. Générez l'Access Code et la Working Key pour le domaine de cette boutique. Les espaces présents dans les identifiants sont supprimés à l'enregistrement.

Merchant ID : votre Merchant ID CCAvenue, composé de chiffres. S'il contient autre chose que des chiffres, le message CCAvenue: the Merchant ID must contain digits only — the previous value was kept. s'affiche à l'enregistrement, la valeur précédemment enregistrée est conservée et les autres réglages sont enregistrés.

Access Code : l'Access Code de ce site web (Settings > API Keys).

Working Key : la Working Key (clé de chiffrement) de ce site web. Elle chiffre la requête de paiement et est le seul moyen de vérifier la réponse de CCAvenue : gardez-la donc secrète. Une Working Key enregistrée n'est plus jamais affichée. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Clear saved Working Key : cochez la case et cliquez sur Save pour supprimer la Working Key enregistrée. Un champ vide conserve la valeur enregistrée.

Test mode : envoie les clients vers l'environnement de test de CCAvenue (test.ccavenue.com). CCAvenue utilise le même Merchant ID, le même Access Code et la même Working Key pour le test et la production ; l'accès test doit être activé pour votre compte par CCAvenue. En mode test, la page de commande affiche TEST MODE: no real transactions will be processed. sous le moyen de paiement. Par défaut : activé. Désactivez-le pour les paiements réels.

URL de retour

CCAvenue renvoie le client vers l'adresse affichée dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_ccavenue_payment/return, éventuellement avec un code de langue tel que /en/. Le module transmet cette URL à chaque paiement (comme URL de redirection et d'annulation) : vous n'avez donc rien à configurer chez CCAvenue. Elle doit appartenir au domaine enregistré auprès de CCAvenue.

Avancé

Debug log : écrit les événements CCAvenue dans logs/ccavenue_p_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Seuls les références de commande, les identifiants de suivi et les statuts sont journalisés ; les clés, les données de carte, les e-mails et les adresses ne le sont pas. Par défaut : désactivé. Tant qu'il est désactivé, rien n'est écrit, erreurs comprises.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : lorsque l'option est activée, la désinstallation du module supprime les réglages du module, le journal et les références de commande CCAvenue. Les commandes et les statuts de commande du module sont conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut CCAvenue) et confirme. Une page affiche Thank you for your order. You are being redirected to CCAvenue to complete the payment. et envoie le client vers la page de paiement CCAvenue. Sans JavaScript, le client clique sur Pay via CCAvenue ou sur Back to checkout. Aucune commande n'existe encore à ce stade.

Chaque tentative reçoit une nouvelle référence de commande CCAvenue composée du numéro de panier et de l'heure. Le total et la devise du panier, les coordonnées de facturation, l'adresse de livraison (lorsqu'elle diffère de l'adresse de facturation) et un jeton secret de la tentative sont transmis dans la requête chiffrée. Les noms et adresses sont nettoyés pour ne conserver que les caractères et longueurs acceptés par CCAvenue ; le pays et la région sont envoyés sous forme de noms, et le téléphone uniquement sous forme de chiffres. Le client choisit la carte, la banque en ligne, UPI, le portefeuille ou l'EMI sur la page CCAvenue.

Après le paiement, CCAvenue renvoie le client avec une réponse chiffrée. La commande n'est marquée comme payée qu'après confirmation par CCAvenue : la réponse doit se déchiffrer avec votre Working Key, appartenir à une tentative de cette boutique et porter le même montant et la même devise que ceux envoyés et que le total du panier. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your CCAvenue payment has been received. Pour un paiement Awaited, la page affiche Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. Après un écart de montant ou de devise, elle affiche Your payment was received and is being reviewed by the shop. Si une commande en attente est ensuite annulée ou échoue sans paiement, la page de confirmation affiche Your CCAvenue payment was not completed. Please contact us about this order.

Si le paiement échoue, le client revient au paiement avec Payment was not completed. Please try again or choose a different payment method. S'il annule sur la page CCAvenue, le message est Payment was cancelled. You may try again. Si la réponse ne peut pas être vérifiée, le message est We could not confirm the payment result. If your account was charged, please contact us before paying again. Dans ces cas, aucune commande n'est créée et le panier est conservé, afin que le client puisse payer à nouveau. Si le panier possède déjà une commande, une nouvelle tentative mène directement à la page de confirmation de cette commande au lieu de lancer un second paiement.

Le résultat n'est pris en compte que lors du retour du client depuis CCAvenue : il n'y a ni notifications serveur à serveur, ni demandes de statut. Si le client ferme son navigateur avant de revenir, aucune commande n'est créée ; vérifiez alors le paiement dans le tableau de bord CCAvenue. Le module ne gère pas les remboursements depuis PrestaShop, ni les cartes enregistrées, abonnements ou paiements récurrents, ni le formulaire de carte sur le site, ni CCAvenue UAE ou d'autres plateformes régionales.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers CCAvenue et n'est pas revenu, ou le paiement a échoué ou a été annulé. Seul le panier existe. Vérifiez le paiement dans le tableau de bord CCAvenue si le client ne revient pas.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant de suivi CCAvenue comme identifiant de transaction, et une note indique la référence bancaire, l'identifiant de suivi et le mode de paiement.

Awaiting CCAvenue payment : CCAvenue a signalé le paiement comme Awaited (la banque ne l'a pas encore confirmé). La commande n'est jamais marquée comme échouée tant que l'argent peut encore être capturé. Vérifiez-la dans le tableau de bord CCAvenue avant de traiter la commande. Une réponse ultérieure portant le même identifiant de suivi est tout de même appliquée : Success passe la commande en Payment accepted, Failure en Payment error et Aborted en Canceled.

CCAvenue payment on hold : CCAvenue a confirmé un paiement dont le montant ou la devise diffère du panier ou de ce qui a été envoyé (par exemple, le panier a été modifié dans un autre onglet après le début du paiement), ou le client a payé après l'annulation de la commande. La note indique le montant reçu et le montant attendu. Le montant signalé par CCAvenue est enregistré comme paiement de la commande lorsque la devise correspond. Vérifiez le paiement dans le tableau de bord CCAvenue, puis traitez la commande ou remboursez le paiement.

Un échec tardif ne modifie jamais une commande payée. Si un autre paiement réussi arrive pour une commande déjà payée (par exemple depuis deux onglets du navigateur), la commande n'est pas modifiée. Une note vous demande de rembourser le doublon dans le tableau de bord CCAvenue.

Bloc de paiement CCAvenue

La page de commande affiche un bloc CCAvenue payment avec l'identifiant de commande CCAvenue, l'identifiant de suivi, le statut, la référence bancaire, le mode de paiement et le nom de la carte, le montant envoyé et le montant reçu, la date et le message de CCAvenue, ainsi qu'un badge Test mode pour les paiements test. Les notes CCAvenue sont des messages privés de la commande, visibles uniquement dans le back-office.

Remboursements

Les remboursements depuis PrestaShop ne sont pas pris en charge. Remboursez le paiement dans le tableau de bord CCAvenue, puis enregistrez le remboursement manuellement dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox CCAvenue Payment est le premier bloc de Modules > Module Manager > VibeFox CCAvenue Payment > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-ccavenue et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : celui de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, CCAvenue n'est pas affiché aux clients lors de la commande. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine de PrestaShop ne sait pas que vous êtes connecté au back-office, donc le mode de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à la commande. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés lorsque le client revient de CCAvenue.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

CCAvenue n'apparaît pas lors de la commande : vérifiez que la licence est active, que Enable/Disable est activé et que les trois identifiants sont renseignés : Merchant ID, Access Code et Working Key. La page des réglages affiche un avertissement si l'un d'eux manque. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : le client n'est pas revenu de CCAvenue vers votre boutique, par exemple parce qu'il a fermé le navigateur. Le module n'a pas de notifications serveur à serveur. Vérifiez le paiement dans le tableau de bord CCAvenue et créez ou mettez à jour la commande manuellement.

Chaque paiement se termine par We could not confirm the payment result : la réponse ne peut pas être déchiffrée. La Working Key est erronée, appartient à un autre domaine ou a été copiée avec des caractères en trop. Générez les clés pour le domaine de cette boutique et collez-les à nouveau. Activez Debug log et consultez le champ Log sur la page du module.

CCAvenue affiche une erreur avant la page de paiement : vérifiez que l'Access Code et la Working Key ont été générés pour ce domaine, que l'URL de retour appartient au domaine enregistré auprès de CCAvenue et, en mode test, que CCAvenue a activé l'accès test pour votre compte. Pour une devise autre que l'INR, le traitement multidevise doit être activé sur votre compte CCAvenue.

Le client voit This payment method is temporarily unavailable : l'un des identifiants manque, ou le total du panier est égal à zéro. Debug log indique la raison.

Le client voit This payment method is not available : le module est désactivé, ou il n'est pas autorisé pour la devise du panier, le pays ou le groupe de clients dans Payment > Preferences.

Le client voit Payment gateway error: encryption failed : la requête n'a pas pu être chiffrée. Vérifiez que l'extension OpenSSL de PHP est installée.

Le Merchant ID ne change pas à l'enregistrement : la valeur contient autre chose que des chiffres. Saisissez uniquement les chiffres de votre Merchant ID.

La commande est CCAvenue payment on hold ou Awaiting CCAvenue payment : lisez la note de la commande (voir Statuts de commande). Vérifiez le paiement dans le tableau de bord CCAvenue, puis traitez la commande ou remboursez le paiement.

Pour les développeurs, le module propose le hook actionCcavenueRequestParams (modifie les données envoyées à CCAvenue avant le chiffrement, par exemple de merchant_param2 à merchant_param5 ; les valeurs ne doivent pas contenir & ; ne modifiez pas amount, currency, order_id ni merchant_param1).

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox CCAvenue Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. La confirmation rappelle que les réglages et les références CCAvenue sont conservés, sauf si Delete data on uninstall est activé. Si l'option est activée, les réglages du module, le journal et les références de commande CCAvenue sont supprimés. Si elle est désactivée, tout est conservé pour une future réinstallation. Les statuts de commande Awaiting CCAvenue payment et CCAvenue payment on hold sont toujours conservés. Les commandes existantes gardent leurs notes de paiement et leurs identifiants de transaction.

CCAvenue est une marque de son propriétaire respectif. Ce module n'est ni affilié à CCAvenue, ni approuvé par CCAvenue.