VibeFox Paysera 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.

Projet Paysera : vous avez besoin de l'identifiant de projet et du mot de passe de projet (clé de signature) de votre projet Paysera. Les moyens de paiement que voit le client sont ceux activés dans ce projet. Rien n'a besoin d'être configuré dans Paysera pour le rappel : son URL est envoyée avec chaque demande de paiement.

Boutique accessible : les commandes reçoivent leur statut du rappel de Paysera ; votre boutique doit donc être accessible depuis Internet, sans connexion, authentification de base ni pare-feu qui la bloque. Le rappel fonctionne aussi lorsque la boutique est en mode maintenance.

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

Installation

Il s'agit d'un seul 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_paysera_payment-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_paysera_payment.ocmod.zip. N'installez que 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_paysera_payment-oc3-(version).ocmod.zip. L'extension ne contient aucune modification OCMOD, donc Extensions > Modifications n'a pas besoin d'être actualisé. Au lieu de l'installateur, vous pouvez copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox Paysera 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 Project ID et le Project password de votre compte Paysera (voir Configuration).

5. Facultatif : activez Allow test payments dans le projet Paysera et Test payments dans l'extension pour essayer le parcours sans débiter d'argent. Désactivez-le avant de commencer à vendre.

6. Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_paysera_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 dans la liste des extensions installées sur la même page. Cliquez sur Install (le bouton vert +) à côté.

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

4. Saisissez la clé de licence, l'identifiant et le mot de passe du projet ainsi que les réglages de test comme aux étapes 3 à 6 pour OpenCart 3. La page des réglages et ses champs sont les mêmes dans les deux versions. Seule l'URL de rappel diffère (voir Projet Paysera).

Une nouvelle installation démarre avec le mode de paiement désactivé, les paiements test désactivés et l'environnement Production.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox Paysera 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 affiche Paysera is hidden at checkout until the project ID and the project password are entered. tant que l'un des deux manque, et Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. tant que les paiements test ou le bac à sable sont activés. Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

À l'enregistrement, Title doit comporter de 1 à 128 caractères, Project ID ne doit contenir que des chiffres, Sort Order doit être un nombre entier, Total doit être un nombre égal ou supérieur à 0 et les statuts de commande doivent exister. Si une vérification échoue, rien n'est enregistré et la page liste les erreurs.

Paysera

Enable/Disable : Enable Paysera Payment active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voient les clients au moment de la commande. Il est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Paysera. 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 securely via Paysera.

Sort Order : la position de Paysera parmi les modes de paiement de la commande. Laissez ce champ vide ou saisissez un nombre entier.

Geo Zone : proposer Paysera 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 total de la commande, dans la devise par défaut de la boutique, que la commande doit atteindre pour que Paysera soit proposé. Laissez ce champ vide pour proposer Paysera quel que soit le total.

Projet Paysera

Retrouvez l'identifiant de projet et le mot de passe de projet dans votre compte Paysera, sous Projects and activities, votre projet, General project settings. La section contient un lien vers le compte Paysera.

Callback URL : l'adresse que Paysera utilise pour confirmer chaque paiement. Sous OpenCart 3, elle ressemble à https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback, et sous OpenCart 4 à https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback. Elle est construite à partir de l'adresse de la boutique de votre installation OpenCart. Elle est envoyée automatiquement avec chaque paiement : rien n'est à configurer dans Paysera, mais elle doit être accessible depuis Internet. Les commandes ne reçoivent leur statut que par ces rappels signés ou chiffrés.

Project ID : l'identifiant numérique de votre projet Paysera. Seuls les chiffres sont acceptés : toute autre valeur donne l'erreur Project ID must contain digits only: the numeric ID of your Paysera project. et rien n'est enregistré.

Project password : le mot de passe de projet (clé de signature). Il signe les demandes de paiement et vérifie les rappels de Paysera. Le mot de passe enregistré n'est jamais réaffiché. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une valeur que si vous voulez la modifier. Pour supprimer le mot de passe enregistré, cochez Clear saved password (tick and save; an empty field keeps the saved value) sous le champ, puis cliquez sur Save.

Tests

Test payments : envoie les paiements en mode test, donc aucun argent n'est débité. Paysera renvoie un paiement test réussi sans débiter le client. Activez d'abord Allow test payments dans les réglages du projet Paysera. Tant que cette option est activée, les paiements test marquent les commandes comme payées ; lorsqu'elle est désactivée, un paiement test met la commande en attente. Par défaut : désactivé. Tant qu'elle est activée, le client voit TEST MODE — no money will be charged. à l'étape Confirm Order.

Environment : l'endroit vers lequel le client est envoyé. Gardez Production pour un projet Paysera normal, y compris pour les paiements test. Par défaut : Production.

Commandes

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). La commande ne reçoit un statut que par le rappel de Paysera. Un paiement annulé ou non exécuté laisse la commande sans statut, et le client peut payer à nouveau. Chaque champ ci-dessous liste vos statuts de commande OpenCart.

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

Awaiting Payment Status : la banque a accepté l'ordre de paiement, mais ne l'a pas encore exécuté. La commande est marquée comme payée lorsque Paysera confirme le paiement. Par défaut : Pending.

On Hold Status : un paiement TEST alors que Test payments est désactivé, un montant ou une devise différent, ou un paiement effectué après l'annulation par le client. 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.

Cancelled Order Status : l'extension ne définit jamais ce statut ; elle le lit seulement : un paiement arrivant pour une commande dans ce statut ne rouvre pas la commande, il ajoute seulement une note. Par défaut : Canceled.

Avancé

Debug log : écrit les événements de paiement dans wc_psr_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours écrits ; les autres étapes seulement lorsque cette option est activée. Les mots de passe et les données client ne sont jamais écrits. Par défaut : désactivé.

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

Delete data : lorsque l'option est activée, la désinstallation de l'extension supprime ses réglages et son journal. Les données de commande (commandes, enregistrements de paiement Paysera) sont toujours conservées. Par défaut : désactivé.

Import / Export

Export : Download JSON enregistre les réglages dans un fichier JSON. Le mot de passe de projet n'est pas exporté.

Import : collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. Le mot de passe de projet enregistré est conservé.

Commande

À l'étape Payment Method, le client choisit le mode de paiement (par défaut Paysera). À l'étape Confirm Order, le client voit votre description et la mention You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. OpenCart crée la commande à cette étape, toujours sans statut. Sous OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc du mode de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order en bas de la page de commande. Lorsque le client clique sur Confirm Order, l'extension crée une demande de paiement signée contenant le numéro de commande, le total de la commande dans l'unité monétaire la plus petite de la devise, le nom, l'e-mail et l'adresse de facturation du client, ainsi que la langue de la page de la boutique (lituanien, letton, estonien, russe, allemand, polonais ; sinon anglais). Le client est envoyé vers la fenêtre de paiement Paysera et y choisit une banque, une carte ou un autre moyen.

Paysera confirme le paiement par un rappel de serveur à serveur. La commande n'est marquée comme payée qu'après une confirmation signée de Paysera ; le retour du client dans la boutique ne paie jamais une commande. La commande reçoit ensuite son statut de la manière standard d'OpenCart, avec les e-mails de commande habituels et la mise à jour des stocks. Lorsque le client revient après le rappel, la page de confirmation de commande d'OpenCart s'affiche. Si la banque a accepté l'ordre de paiement sans l'avoir encore exécuté, la commande reçoit le Awaiting Payment Status et la page affiche Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Pour une commande en attente, la page affiche Your payment is being reviewed. We will contact you if anything else is needed.

Si le client revient avant le rappel, une page Payment confirmation explique que la commande sera confirmée dès que Paysera aura confirmé le paiement, et propose Check again et Back to checkout.

Si le client annule dans la fenêtre Paysera, il revient à la commande avec le message The Paysera payment was cancelled. You can try again or choose another payment method. Si Paysera indique que le paiement n'a pas été exécuté, le message est The payment was not completed. You can try again or choose another payment method. Le panier est conservé dans les deux cas. Sous OpenCart 4, ces messages s'affichent au-dessus de la page de commande. OpenCart 3 crée une nouvelle commande à chaque affichage de l'étape Confirm Order, et OpenCart 4 met à jour la commande de la caisse (une nouvelle tentative paie la même commande) ; si une autre commande du même panier est déjà payée, en attente de paiement ou en attente de vérification, une nouvelle tentative mène directement à la page de confirmation au lieu d'un second paiement. Une modification du panier, y compris une nouvelle quantité, compte comme un nouveau panier qui a besoin de son propre paiement.

OpenCart 4 garde la commande dans la caisse jusqu'à l'affichage de la page de confirmation. Si cette commande a été fermée entre-temps (par exemple si vous avez annulé une commande qui attendait le paiement bancaire), le client est renvoyé vers la caisse avec le message Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. Le Confirm Order suivant paie une nouvelle commande. Si cette commande avait déjà été payée pour un panier précédent et que le panier a changé depuis, le client est renvoyé vers la caisse, et le Confirm Order suivant paie une nouvelle commande du panier actuel. Une commande fermée n'est jamais affichée comme payée.

Si le paiement ne peut pas être démarré, le client reste à l'étape Confirm Order avec Paysera payments are temporarily unavailable. Please choose another payment method. ou, pour un montant de commande non valide, avec This order cannot be paid via Paysera. La raison est écrite dans le journal.

Le rappel fonctionne aussi lorsque la boutique est en mode maintenance, car OpenCart laisse passer les requêtes des extensions de paiement (sous OpenCart 4, l'extension ajoute sa propre action de démarrage à cet effet, qui permet aussi au client de revenir depuis Paysera).

L'extension ne prend pas en charge les remboursements depuis l'administration, ni le choix de la banque ou du moyen de paiement sur la page de commande, ni les abonnements, ni les cartes enregistrées, ni les services de livraison ou de coursier de Paysera.

Commandes

Statuts de commande

Aucun statut (commande manquante) : le client a été envoyé vers Paysera et le rappel n'est pas encore arrivé, ou le client a annulé, ou le paiement n'a pas été exécuté. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status réglé sur Missing Orders.

Order Status After Payment (par défaut Processing) : Paysera a confirmé le paiement avec le montant et la devise correspondants. Une note affiche la demande et le moyen de paiement, marqués (TEST — no money charged) pour les paiements test.

Awaiting Payment Status (par défaut Pending) : Paysera a accepté l'ordre de paiement, mais la banque ne l'a pas encore exécuté. La commande passe à Order Status After Payment lorsque Paysera confirme le paiement.

On Hold Status (par défaut Pending) : le paiement nécessite un examen manuel. Le montant ou la devise payés diffèrent du total de la commande, un paiement TEST est arrivé alors que Test payments est désactivé (aucun argent n'a été débité), ou le paiement a été confirmé après l'annulation du client. La note l'explique, et l'onglet de la commande vous demande de vérifier le paiement dans votre compte Paysera, puis de passer la commande au statut payé ou de l'annuler et de rembourser le paiement dans Paysera. Un paiement correct ultérieur pour la même commande la marque comme payée.

Cancelled Order Status (par défaut Canceled) : un paiement confirmé plus tard pour une commande annulée ne modifie pas son statut. Une note vous demande de rétablir la commande (la passer au statut payé) ou de rembourser le paiement dans Paysera. Si le moyen de paiement de la commande n'est plus Paysera, un paiement confirmé ajoute seulement une note.

Si un autre paiement réussi arrive pour une commande déjà payée, ou pour une autre commande d'un panier déjà payé, la commande payée n'est pas modifiée, et une note vous demande de rembourser le doublon dans votre compte Paysera. Les autres statuts Paysera (paiement non exécuté, informations complémentaires) ajoutent seulement une note. Les notes sont des entrées de l'History de la commande, que le client ne voit pas.

Onglet VibeFox Paysera Payment

Dans Sales > Orders, ouvrez une commande payée avec Paysera. En bas de la page de commande, à côté de History et Additional, l'onglet VibeFox Paysera Payment affiche le Paysera order ID (le numéro de commande et la tentative), le Paysera request ID, l'Environment et une mention TEST payment, le Status du paiement, les montants Requested / paid, le Payment method et les Notes de l'extension. Pour une commande en attente, il indique quoi vérifier. L'onglet ne fait qu'afficher des informations et est visible des utilisateurs ayant accès à l'extension.

Remboursements

Les remboursements depuis l'administration ne sont pas pris en charge : le protocole de la fenêtre de paiement Paysera n'a pas d'API de remboursement. Effectuez les remboursements dans votre compte Paysera. Lorsque Paysera signale un remboursement, une note indiquant le montant remboursé est ajoutée à la commande, et le statut de la commande ne change pas. Enregistrez le remboursement dans OpenCart manuellement si nécessaire. Les retours de produits dans Sales > Returns ne renvoient pas d'argent via Paysera.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Paysera Payment est le premier bloc de Extensions > Extensions > Payments > VibeFox Paysera 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) et 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-paysera 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é une place 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 sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, Paysera n'est pas affiché aux clients au moment 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. 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é. Sous 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. Après avoir ouvert une fois la page Edit, 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 touchées : les paiements déjà lancés sont toujours confirmés par le rappel.

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 de l'administration ou la page Edit : 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

Paysera n'apparaît pas à la commande : vérifiez que la licence est active, que Enable/Disable est activé, et que Project ID et Project password sont tous deux saisis. La page des réglages affiche un avertissement tant que l'un des deux manque. Vérifiez aussi que l'adresse de facturation 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 été effectué, mais la commande reste sans statut : la commande reçoit son statut du rappel de Paysera, et non du retour du client. Vérifiez que votre boutique est accessible depuis Internet à la Callback URL affichée dans les réglages (pas derrière une connexion, une authentification de base ou un pare-feu), et consultez le champ Log sur la page de l'extension.

Le rappel répond Invalid signature : le Project password ne correspond pas au projet, ou le rappel ne vient pas de Paysera. Recopiez le mot de passe de projet. Si vous avez changé de projet ou de mot de passe, les paiements commencés avant ce changement ne peuvent plus être vérifiés.

Le rappel répond Project ID mismatch : le Project ID des réglages diffère du projet qui a effectué le paiement.

Le rappel répond Order not found : la commande du rappel n'a pas de paiement Paysera dans cette boutique, par exemple parce que le paiement a été lancé dans une autre boutique avec le même projet.

Le rappel répond Gateway not configured, Busy ou Temporary error : l'identifiant ou le mot de passe du projet est vide, un autre rappel pour le même panier est encore en cours, ou le statut de la commande n'a pas pu être défini. Paysera renouvelle le rappel. Activez Debug log pour voir la raison.

Paysera refuse la fenêtre de paiement ou indique que le projet n'existe pas : vérifiez Environment. Un projet Paysera normal ne fonctionne qu'avec Production ; Sandbox nécessite un projet créé dans l'environnement bac à sable de Paysera.

Le paiement test ne paie pas la commande : un paiement TEST ne paie une commande que tant que Test payments est activé. Sinon, la commande est mise en attente avec une note indiquant qu'aucun argent n'a été débité. Activez aussi Allow test payments dans le projet Paysera.

Une commande est en attente avec une note sur un écart de montant ou de devise : Paysera a confirmé un paiement dont le montant ou la devise diffère du total de la commande. Comparez le paiement dans votre compte Paysera et acceptez la commande ou remboursez le paiement manuellement.

Le client voit Paysera payments are temporarily unavailable : consultez le champ Log. L'identifiant ou le mot de passe du projet peuvent être vides, ou l'une des adresses de la boutique envoyées à Paysera dépasse 255 caractères.

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Paysera Payment. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart supprime toujours ses propres réglages de l'extension : Enable/Disable, Sort Order, Geo Zone, Total et les statuts de commande de la section Orders, qui reviennent à leurs valeurs par défaut lors d'une réinstallation. L'événement OpenCart de l'extension est également supprimé (sous OpenCart 4, ses événements et son action de démarrage, qui laissent passer le rappel et le retour du client en mode maintenance). Si Delete data est activé, les autres réglages (titre, description, identifiant et mot de passe du projet, tests, journalisation) et le journal sont supprimés. S'il est désactivé, ils sont conservés pour une réinstallation ultérieure. Les enregistrements de paiement Paysera sont toujours conservés. Les commandes existantes conservent leurs notes de paiement.

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

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