VibeFox Autopay for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

PHP : 8.0 ou ultérieur.

Service Autopay : vous avez besoin du Service ID et de la Shared key (clé de hachage) de votre service Autopay. Ils sont affichés dans le portail marchand d'Autopay : portal.autopay.eu pour la production et testportal.autopay.eu pour les tests. Les services de test ont leur propre Service ID et Shared key ; demandez à Autopay d'en ouvrir un. La fonction de hachage du service doit être SHA-256.

Devise : la devise de la commande doit être PLN, EUR, GBP, USD ou CZK et être acceptée par votre service Autopay.

Boutique accessible : Autopay doit pouvoir envoyer des notifications à votre boutique ; elle doit donc être accessible depuis Internet, sans authentification de base ni pare-feu bloquant les requêtes POST. Le mode maintenance ne bloque pas les notifications, car OpenCart laisse passer les requêtes des extensions de paiement.

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

Installation

Le téléchargement est un unique fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_autopay_payment-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_autopay_payment.ocmod.zip. Installez uniquement le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_autopay_payment-oc3-(version).ocmod.zip. L'extension ne contient aucune modification OCMOD, il n'est donc pas nécessaire de rafraîchir Extensions > Modifications. Au lieu de l'installateur, vous pouvez aussi copier le contenu du dossier upload de l'archive dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox Autopay Payment et cliquez sur Install (le bouton vert +). Votre utilisateur administrateur doit avoir le droit de modifier la liste des extensions de paiement.

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des réglages. Collez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez le Service ID et la Shared key (test et production), puis choisissez les devises de votre service.

5. Dans le portail Autopay, définissez l'URL ITN, l'URL de retour et la fonction de hachage SHA-256 pour votre service (voir Configuration).

6. Activez Enable/Disable et cliquez sur Save. Passez une commande de test en mode test, puis désactivez Test mode pour les paiements réels.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_autopay_payment.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît sur la même page, dans la liste des extensions installées. Cliquez sur Install (le bouton vert +) à côté.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Payments. Repérez VibeFox Autopay Payment, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 3 à 6 pour OpenCart 3. La page des réglages et ses champs sont identiques dans les deux versions. Seules les adresses ITN et de retour diffèrent (voir Adresses ITN et de retour).

Une nouvelle installation démarre avec le mode de paiement désactivé, le mode test activé et le PLN comme seule devise.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit. Les sections sont listées à gauche ; le bouton Save situé sous la liste enregistre la page entière. Au-dessus des réglages, la page vous avertit lorsque le Service ID ou la Shared key de l'environnement sélectionné est vide (le mode de paiement est alors masqué lors du paiement) et lorsque la devise par défaut de la boutique n'est pas sélectionnée dans Currencies (le mode de paiement est alors masqué dans cette devise). Tant que le mode test est activé, elle affiche Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

Lors de l'enregistrement, Title doit comporter de 1 à 128 caractères, Sort Order doit être un nombre entier, Total doit être un nombre égal ou supérieur à 0, et un Service ID ne peut contenir que des lettres, des chiffres, des tirets et des tirets bas. Si un champ comporte une erreur, rien n'est enregistré et la page indique le champ concerné.

Autopay

Enable/Disable : Enable Autopay payment gateway active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voient les clients lors du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Autopay. Obligatoire, jusqu'à 128 caractères.

Description : le texte affiché au client à l'étape Confirm Order, au-dessus du bouton de confirmation. Par défaut : Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

Sort Order : la position d'Autopay parmi les modes de paiement proposés lors du paiement. Laissez le champ vide ou saisissez un nombre entier.

Geo Zone : proposez Autopay uniquement pour les adresses de facturation situées dans la zone géographique sélectionnée. Par défaut : All zones. Les zones géographiques se configurent dans System > Localisation > Geo Zones.

Total : le montant total du paiement, dans la devise par défaut de la boutique, que la commande doit atteindre pour que Autopay soit proposé. Laissez le champ vide pour proposer Autopay quel que soit le montant.

Service Autopay

Le Service ID et la Shared key sont affichés dans le portail marchand d'Autopay (portal.autopay.eu ou testportal.autopay.eu, liens fournis dans cette section).

Test mode : utilise l'environnement de test d'Autopay (testpay.autopay.eu) et les identifiants de test ci-dessous. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements sur pay.autopay.eu avec les identifiants de production. Tant qu'il est activé, les clients voient Test mode: no real payment is taken. à l'étape Confirm Order.

Service ID (production) : l'identifiant numérique du service sur portal.autopay.eu.

Shared key (production) : la clé de hachage du service de production. Gardez-la secrète.

Service ID (test) : l'identifiant numérique du service sur testportal.autopay.eu.

Shared key (test) : la clé de hachage du service de test.

Les Shared keys enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Pour supprimer une clé enregistrée, cochez Clear the saved key on save sous le champ et cliquez sur Save.

Currencies : les devises acceptées par votre service Autopay : PLN, EUR, GBP, USD, CZK. Autopay ouvre généralement un service distinct par devise. Le mode de paiement n'est proposé que lorsque la devise du paiement est sélectionnée ici. Par défaut : PLN.

Adresses ITN et de retour

Saisissez ces adresses dans le portail Autopay pour votre service, en production comme en test. Les adresses exactes sont affichées dans le champ Addresses de cette section et sont construites à partir de l'adresse de la boutique de votre installation OpenCart :

Ce sont les adresses d'OpenCart 3. Sur OpenCart 4, elles sont :

Copiez les adresses exactement telles que les réglages les affichent. Sans l'URL ITN, les commandes ne sont jamais confirmées : OpenCart garde la commande sans statut tant qu'Autopay ne confirme pas le paiement. Chaque ITN est vérifié à l'aide du hachage SHA-256 calculé avec la Shared key du service nommé dans la notification. Les notifications sans hachage valide, ou avec un Service ID inconnu, sont rejetées. Une notification n'est appliquée à une commande que si son paiement a été lancé avec le même service Autopay ; ainsi, une notification de test ne confirme jamais un paiement de production. Les notifications des paiements lancés avant que vous ne changiez Test mode sont toujours vérifiées avec la bonne clé, tant que les deux identifiants restent enregistrés.

L'extension gère ces statuts de paiement dans l'ITN :

Orders

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). La commande ne reçoit un statut que lorsqu'Autopay confirme le paiement (ITN SUCCESS). Un paiement échoué ou abandonné la laisse sans statut. Sur OpenCart 4, une commande non payée issue du paiement peut recevoir le statut Voided, que OpenCart 4 attribue lorsque le client revient à l'étape Confirm Order ; l'extension traite une telle commande comme une commande sans statut, et une notification ITN SUCCESS ultérieure la marque toujours comme payée. Chaque champ ci-dessous indique vos statuts de commande OpenCart.

Order Status After Payment : le statut attribué lorsqu'Autopay confirme le paiement avec le montant et la devise attendus. Par défaut : Processing.

On Hold Status : le montant ou la devise payés ne correspondent pas à la commande, ou le paiement est arrivé après que le statut de la commande a été modifié (par exemple annulée). La commande n'est pas marquée comme payée ; une note explique pourquoi. Par défaut : Pending, car OpenCart n'a pas de statut On hold. Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

Advanced

Logging : écrit les événements de paiement dans wc_ap_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web ; à 5 Mo, il est déplacé vers wc_ap_debug.old.log.php. Les clés et les données clients ne sont jamais journalisées. Par défaut : désactivé. Tant que cette option est désactivée, 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.

Import / Export

Export : Download JSON enregistre les réglages dans un fichier JSON. Les Shared keys ne sont pas exportées.

Import : collez un JSON précédemment exporté et cliquez sur Import pour restaurer les réglages. Les Shared keys enregistrées sont conservées.

Paiement

À l'étape Payment Method, le client choisit le mode de paiement (par défaut Autopay). À l'étape Confirm Order, le client voit votre description et la mention You will be redirected to the secure Autopay payment page to complete the payment. OpenCart crée la commande à cette étape, toujours sans statut. Lorsque le client clique sur Confirm Order, le navigateur envoie à Autopay un formulaire de paiement signé, avec le montant total de la commande dans la devise de la commande, le numéro de commande OpenCart comme OrderID, la description Order suivie du numéro, et l'adresse e-mail du client. Sur la page d'Autopay, le client choisit son mode de paiement et paie.

La commande n'est marquée comme payée qu'après qu'Autopay l'a confirmé par un ITN signé et que le montant et la devise correspondent à la commande. La commande reçoit alors son statut de la manière standard d'OpenCart, avec les e-mails habituels de commande et la mise à jour du stock. Après le paiement, le client revient dans votre boutique. L'adresse de retour est signée, mais elle ne modifie jamais une commande. Si la commande a déjà un statut, le client voit la page de confirmation de commande d'OpenCart. Si l'ITN n'est pas encore arrivé, une page Payment confirmation affiche Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. avec les boutons Check again et Back to checkout.

Si Autopay a signalé un paiement échoué, le client revient à la page de paiement avec le message The payment was not completed. You can try again or choose another payment method. Le panier est conservé. Chaque nouvelle tentative crée une nouvelle commande OpenCart (sur OpenCart 4, le client paie à nouveau la même commande, avec une nouvelle tentative sous le même OrderID). Si une autre commande du même panier (les mêmes produits lors de la même visite) a déjà été payée, le client est dirigé vers la page de succès au lieu de payer à nouveau. Un nouvel achat après un achat terminé constitue un nouveau panier et est payé normalement. Si le paiement ne peut pas être lancé, le client reste à l'étape Confirm Order avec un bref message au-dessus du bouton, par exemple Autopay payments are not configured. Please choose another payment method or contact the store. ou indiquant qu'Autopay ne peut pas accepter de paiements dans cette devise.

Sur OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc des modes de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order en bas de la page de paiement. Le message concernant un paiement non finalisé s'affiche au-dessus de la page de paiement. OpenCart 4 garde une seule commande pour le paiement et la met à jour. Si la boutique a fermé cette commande entre-temps (par exemple parce que vous l'avez annulée), le client est renvoyé au paiement avec The payment was not completed. You can try again or choose another payment method., ou, si la commande avait été payée via Autopay, avec Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. Si cette commande est déjà payée pour un autre panier, le message est Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Le prochain Confirm Order paie une nouvelle commande. Une modification du panier, y compris une nouvelle quantité, compte comme un nouveau panier qui nécessite son propre paiement. L'ITN fonctionne aussi lorsque la boutique est en mode maintenance : sur OpenCart 4, l'extension ajoute une action de démarrage pour cela.

L'extension ne prend pas en charge les remboursements depuis OpenCart, ni les abonnements ou paiements récurrents, ni les cartes enregistrées, ni le code BLIK ou le formulaire de carte sur la page de paiement, ni le choix de la banque ou du canal de paiement sur la page de paiement, et elle utilise un Service ID par environnement.

Commandes

Order statuses

No status (missing order) : le client a été redirigé vers Autopay et n'a pas payé, le paiement a échoué, ou Autopay n'a pas encore confirmé le paiement. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status réglé sur Missing Orders.

Order Status After Payment (default Processing) : Autopay a confirmé le paiement et le montant et la devise correspondent. Une note affiche le montant, l'identifiant de transaction Autopay (remoteID) et la date du paiement.

On Hold Status (default Pending) : Autopay a signalé un montant ou une devise différents du total de la commande. La commande n'est pas marquée comme payée. Vérifiez la transaction dans le portail Autopay, puis finalisez-la ou remboursez-la manuellement. Une notification ultérieure correcte pour cette commande la marque comme payée. Le même statut est utilisé lorsqu'un paiement arrive pour une commande dont vous avez entre-temps modifié le statut, par exemple annulée : une note vous demande de vérifier le stock et de traiter la commande, ou de rembourser le paiement.

Une commande payée n'est jamais modifiée par une notification d'échec ultérieure. Si Autopay signale un autre paiement réussi pour une commande déjà payée, ou si une seconde commande du même panier est payée, une note avertit que le client a peut-être payé deux fois. Une notification concernant un paiement lancé avec un autre service Autopay n'est pas appliquée, et une note l'explique. Les notes sont des entrées de l'History de la commande que le client ne voit pas.

VibeFox Autopay Payment tab

Dans Sales > Orders, ouvrez une commande payée avec Autopay. En bas de la page de la commande, à côté de History et Additional, l'onglet VibeFox Autopay Payment affiche l'OrderID at Autopay, le Service ID et l'environnement avec une étiquette Test mode pour les paiements de test, le Amount, le statut de la Payment attempt, l'Autopay transaction ID et les Autopay notes de la commande. L'onglet est en lecture seule et il est affiché aux utilisateurs ayant accès à l'extension.

Refunds

Les remboursements via Autopay ne sont pas pris en charge. Remboursez le paiement dans le portail Autopay, puis mettez la commande à jour manuellement dans OpenCart.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Autopay Payment est le premier bloc de Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit, au-dessus des réglages. Collez 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: opencart-payment-autopay et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit Modify sur l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Autopay n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit encore le mode de paiement dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode de paiement est masqué pour tout le monde. Une fois la page Edit ouverte une fois, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : 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 de l'extension supprime toujours la clé de licence et le statut de licence.

Dépannage

Autopay n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'environnement sélectionné dispose d'un Service ID et d'une Shared key, et que la devise du paiement est sélectionnée dans Currencies. La page des réglages affiche un avertissement si l'un de ces éléments manque. Vérifiez également que l'adresse de paiement se trouve dans la Geo Zone sélectionnée et que la commande atteint le Total défini dans les réglages.

Le paiement a abouti, mais la commande reste sans statut : Autopay n'a pas envoyé l'ITN, ou la boutique l'a rejeté. Vérifiez que l'URL ITN affichée dans les réglages est bien configurée pour le service dans le portail Autopay (production ou test), que la fonction de hachage est SHA-256 et que la Shared key de l'extension correspond au service. Vérifiez que la boutique est accessible depuis Internet. Activez Logging et consultez le champ Log sur la page de l'extension.

Le journal affiche ITN rejected: invalid hash : la Shared key ne correspond pas au service, ou la fonction de hachage du service n'est pas SHA-256.

Le journal indique que le service ID n'est pas configuré : la notification provient d'un service dont le Service ID n'est pas saisi dans l'extension, ou dont la Shared key est vide.

Le journal affiche could not lock the order, Autopay will retry : la commande était en cours de traitement par une autre notification au même moment. La boutique répond afin qu'Autopay renvoie la notification.

L'URL ITN affiche METHOD_NOT_ALLOWED dans le navigateur : c'est normal. L'URL n'accepte que les requêtes POST d'Autopay.

La commande est dans le statut de mise en attente avec une note de non-concordance : Autopay a signalé un montant ou une devise différents du total de la commande. Vérifiez la transaction dans le portail Autopay, puis finalisez ou remboursez la commande manuellement.

Une note indique que la notification n'a PAS été appliquée : le paiement de cette commande n'a pas été lancé avec ce service Autopay, par exemple une notification de test pour une commande de production. Vérifiez la transaction dans le portail Autopay.

Après le paiement, le client arrive sur la page d'accueil : l'adresse de retour n'a pas pu être vérifiée, par exemple parce que le Service ID n'est pas saisi dans l'extension. La commande n'est pas affectée ; elle suit l'ITN.

Le client voit This payment method is not available. Please reload the checkout page. : la session de paiement ne correspond plus à la commande, ou le mode de paiement a été désactivé ou a perdu ses identifiants entre-temps. Le client recharge la page de paiement.

Pour les développeurs : avant la signature du formulaire de paiement, l'extension déclenche l'événement OpenCart wc_ap_payment_params avec les paramètres du formulaire et la commande ; le service, le numéro de commande, le montant et la devise ne peuvent pas être modifiés par celui-ci.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Autopay Payment. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart supprime ses propres réglages de l'extension : Enable/Disable, Sort Order, Geo Zone, Total et les statuts de commande de la section Orders. L'extension supprime toujours les autres réglages de la passerelle, y compris les Service ID et les Shared keys, ainsi que le journal. Elle ne propose aucune option pour conserver les réglages. Sur OpenCart 4, les événements de l'extension et son action de démarrage, qui laisse passer l'ITN en mode maintenance, sont également supprimés. Les enregistrements de paiements Autopay sont toujours conservés. Les commandes existantes conservent leurs notes de paiement.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Autopay Payment dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet téléchargé.

Autopay est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à Autopay ni approuvée par Autopay.