VibeFox CorvusPay for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Devise : AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK ou USD. Pour toute autre devise du paiement, la méthode de paiement est masquée au moment du paiement. Les montants sont envoyés avec 2 décimales ; un total avec davantage de décimales (par exemple dans une devise à 3 décimales comme BHD) est refusé au lieu d'être arrondi.

Compte CorvusPay : vous avez besoin d'un compte marchand CorvusPay. CorvusPay délivre un Store ID et une Secret Key pour chaque boutique, séparément pour la boutique de test et pour la boutique de production ; ils sont affichés dans le CorvusPay Merchant Center. L'URL de succès (Success URL) et l'URL d'annulation (Cancel URL) de l'extension doivent y être saisies (voir Configuration).

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

Installation

Le téléchargement est un fichier ZIP unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_corvuspay_gateway-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_corvuspay_gateway.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_corvuspay_gateway-oc3-(version).ocmod.zip. L'extension ne comporte aucune modification OCMOD, donc Extensions > Modifications n'a pas besoin d'être actualisé. Au lieu de l'installateur, vous pouvez aussi 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 CorvusPay Gateway 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 crayon) pour ouvrir la page de configuration. 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 Store ID et la Secret Key de votre boutique de test CorvusPay (et celles de la boutique de production pour les paiements réels). Copiez la Success URL et la Cancel URL affichées sur la page de configuration dans le CorvusPay Merchant Center, pour la boutique de test comme pour la boutique de production.

5. Activez Enable/Disable et cliquez sur Save. Passez une commande de test, puis désactivez Test Mode pour passer en production.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_corvuspay_gateway.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 CorvusPay Gateway, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence, les boutiques CorvusPay et les URL du Merchant Center comme aux étapes 3 à 5 pour OpenCart 3. La page de configuration et ses champs sont identiques dans les deux versions. Seules la Success URL et la Cancel URL diffèrent (voir URL de succès et d'annulation).

Une nouvelle installation démarre avec la méthode de paiement désactivée et le mode test activé.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > 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 Test mode is on. Payments go to the CorvusPay test environment — no real money is taken. tant que le mode test est activé, vous avertit lorsque la passerelle est activée mais que le Store ID ou la Secret Key du mode actuel est vide (la méthode est alors masquée au paiement tant qu'ils ne sont pas renseignés) et lorsque la devise par défaut de votre boutique n'est pas prise en charge par CorvusPay. Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

Lors de l'enregistrement, Title ne doit pas dépasser 128 caractères, Sort Order doit être un nombre entier, Minimum Total doit être un nombre non négatif, et la zone géographique et les statuts de commande sélectionnés doivent exister ; sinon, rien n'est enregistré et la page affiche les erreurs.

CorvusPay

Enable/Disable : Enable CorvusPay Gateway. active ou désactive la méthode de paiement. Default : off.

Title : le nom de la méthode de paiement que le client voit au moment du paiement. C'est aussi le nom de la méthode de paiement enregistré dans la commande. Default : Credit/Debit Card (CorvusPay). Jusqu'à 128 caractères ; si vous le laissez vide, le nom par défaut est affiché.

Description : le texte affiché au client à l'étape Confirm Order, au-dessus du bouton de confirmation. Default : Pay securely with your credit or debit card via CorvusPay. En mode test, (Test mode — no real payment is taken.) y est ajouté.

Sort Order : la position de CorvusPay parmi les méthodes de paiement au moment du paiement. Laissez le champ vide ou saisissez un nombre entier.

Geo Zone : proposer CorvusPay uniquement pour les adresses de facturation situées dans la zone géographique sélectionnée. Default : All zones. Les zones géographiques se configurent dans System > Localisation > Geo Zones.

Minimum Total : le montant total de la commande, dans la devise par défaut de la boutique, que la commande doit atteindre avant que CorvusPay soit proposé. Laissez le champ vide s'il n'y a pas de minimum.

Identifiants de la boutique

Le Store ID et la Secret Key sont délivrés par CorvusPay pour chaque boutique (test et production séparément) et sont affichés dans le CorvusPay Merchant Center.

Test Mode : utilise l'environnement de test de CorvusPay (wallet.test.corvuspay.com) ainsi que le Store ID et la Secret Key de test. Default : on. Désactivez-le pour accepter de vrais paiements sur wallet.corvuspay.com.

Test Store ID : le Store ID numérique de votre boutique de test CorvusPay.

Test Secret Key : la Secret Key de votre boutique de test CorvusPay, utilisée pour les signatures HMAC-SHA256.

Live Store ID : le Store ID numérique de votre boutique de production CorvusPay.

Live Secret Key : la Secret Key de votre boutique de production CorvusPay, utilisée pour les signatures HMAC-SHA256.

Un Store ID ne doit contenir que des chiffres. Si vous saisissez autre chose, la page affiche … must contain digits only — the previous value was kept. et les autres champs sont tout de même enregistrés. Les Secret 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 value on save sous le champ puis cliquez sur Save. Un paiement est toujours vérifié avec la Secret Key de la boutique dans laquelle il a été lancé ; gardez donc la clé de test renseignée tant que des paiements de test peuvent encore revenir.

URL de succès et d'annulation

Copiez les deux adresses affichées sous Merchant Center URLs dans le CorvusPay Merchant Center, pour la boutique de test comme pour la boutique de production. CorvusPay y renvoie le client après le paiement. Elles sont construites à partir de l'adresse de la vitrine de votre installation OpenCart ; copiez-les exactement comme la page les affiche.

Paiement

Transaction Type : la manière dont la carte est débitée.

Payment Page Language : la langue de la page de paiement CorvusPay. Site language (par défaut) utilise la langue actuelle de votre boutique lorsque CorvusPay la prend en charge, sinon l'anglais. Vous pouvez aussi choisir Hrvatski, English, Deutsch, Italiano, Srpski ou Slovenščina.

Order Status After Payment : le statut de la commande après un paiement Sale réussi. Les options renvoient aux statuts OpenCart choisis dans la section Order statuses.

Statuts de commande

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). Ce sont les statuts OpenCart que la passerelle attribue ; chaque champ liste vos statuts de commande OpenCart. OpenCart n'a pas de statut On hold ; le statut de vérification est donc utilisé pour Authorize only, pour les écarts de montant ou de devise et pour les paiements effectués après une annulation. Une note de commande explique la raison.

Processing status : utilisé lorsque Order Status After Payment est Processing. Default : Processing.

Completed status : utilisé lorsque Order Status After Payment est Completed. Default : Complete.

On hold (review) status : Authorize only, écart de montant ou de devise, paiement après une annulation, ou Order Status After Payment réglé sur On hold. Default : Pending. Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

Avancé

Logging : écrit des informations de débogage dans corvuspay_p_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque cette option est désactivée ; les secrets, les signatures et les données clients ne le sont jamais. Default : off.

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

Delete Data : lorsqu'il est activé, la désinstallation de l'extension supprime les réglages de la passerelle et les fichiers journaux. Les commandes et les données de transaction CorvusPay sont toujours conservées. Default : off.

Importer / Exporter

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

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

Paiement

À l'étape Payment Method, le client choisit la méthode de paiement (par défaut Credit/Debit Card (CorvusPay)). À l'étape Confirm Order, le client voit votre description ; OpenCart crée la commande à cette étape, toujours sans statut. Lorsque le client clique sur Confirm Order, la page affiche Redirecting to CorvusPay for payment. Please wait... et envoie le formulaire signé à la page de paiement CorvusPay. Si la redirection ne démarre pas, le client clique sur Pay via CorvusPay. Sont envoyés le total de la commande dans la devise de la commande, une courte description (Order, le numéro de commande et le nom de la boutique), ainsi que les coordonnées et l'adresse e-mail du client (pour préremplir la page de paiement). Le même numéro de commande CorvusPay est réutilisé tant que le montant, la devise, le mode et le type de transaction ne changent pas, et CorvusPay n'accepte pas un second paiement pour cette commande. Sur OpenCart 4, le client choisit la méthode de paiement avec le bouton Choose du bloc de méthode de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order en bas de la page de paiement. Si la boutique ne demande pas d'adresse de facturation (valeur par défaut d'OpenCart 4), les coordonnées du titulaire de la carte sont reprises du nom du client et de l'adresse de livraison.

Après le paiement, CorvusPay renvoie le client vers la Success URL. La commande n'est marquée payée qu'après confirmation par CorvusPay : le numéro de commande CorvusPay doit avoir été émis par cette boutique, la signature doit correspondre à la Secret Key de la boutique dans laquelle le paiement a été lancé, et le montant et la devise doivent correspondre à la commande. La commande reçoit ensuite son statut de la manière standard d'OpenCart, avec les e-mails habituels de commande et la mise à jour des stocks, et le client voit la page de succès de commande d'OpenCart avec Your CorvusPay payment has been received. Pour Authorize only, la page affiche Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order., et pour une commande au statut de vérification, Your payment was received and is being reviewed by the shop.

Si le paiement ne peut pas être pris en compte à ce moment (par exemple parce qu'une autre requête est en train de confirmer la même commande), le client voit Your payment is being confirmed avec un bouton Check again, qui mène à la page de succès dès que la commande a un statut. Si la requête vers la Success URL ne peut pas être vérifiée, le client voit Payment not confirmed et We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. Rien n'est modifié. La Success URL fonctionne aussi lorsque la boutique est en mode maintenance : OpenCart 3 laisse passer les requêtes des extensions de paiement, et sur OpenCart 4 l'extension ajoute une action de démarrage pour les URL de succès et d'annulation. Sur OpenCart 4, le navigateur n'envoie pas la session de la boutique lorsque CorvusPay renvoie le client ; l'extension affiche donc d'abord une courte page qui rouvre la même adresse depuis votre boutique : le client conserve son panier et sa connexion.

Si le client annule sur la page CorvusPay, la commande reste sans statut et le client revient au paiement avec son panier intact et le message The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. Sur OpenCart 4, ce message est affiché au-dessus de la page de paiement. OpenCart 3 crée une nouvelle commande chaque fois que l'étape Confirm Order est affichée ; OpenCart 4 conserve une commande pour le paiement et la met à jour, et une nouvelle tentative reçoit un nouveau numéro de commande CorvusPay ; si une autre commande du même panier est déjà payée, le client est dirigé vers la page de succès au lieu de payer à nouveau.

OpenCart 4 conserve la commande dans le paiement jusqu'à l'affichage de la page de succès. Si cette commande a été fermée sans paiement entre-temps (par exemple, vous l'avez annulée), Confirm Order ou le retour depuis CorvusPay renvoie le client au paiement avec Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Si la commande a déjà un statut et que le panier a changé depuis (autres produits ou quantités), le message est Your previous order is already placed. The cart has changed since then: please confirm the new order to pay for it. Dans les deux cas, le Confirm Order suivant paie une nouvelle commande du panier.

Si le paiement ne peut pas démarrer, le client reste à l'étape Confirm Order avec un bref message au-dessus du bouton : CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … ou This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

La commande n'est confirmée que lorsque CorvusPay renvoie le client vers la Success URL ; il n'existe pas de notifications serveur à serveur. Si le client ferme le navigateur juste après avoir payé, la commande reste sans statut. L'extension ne prend en charge ni remboursements, ni captures, ni annulations depuis OpenCart (l'API serveur de CorvusPay exige un certificat client), ni cartes enregistrées, abonnements, paiements échelonnés ou formulaire de carte sur le site.

Commandes

Statuts de commande

Aucun statut (commande manquante) : le client a été envoyé vers CorvusPay et n'est pas revenu avec un paiement confirmé, ou a annulé le paiement. Dans Sales > Orders, ces commandes ne sont affichées qu'avec le filtre Order Status réglé sur Missing Orders. Si le client a payé sans revenir, vérifiez le paiement dans le CorvusPay Merchant Center et réglez manuellement le statut de la commande.

Processing, Completed ou statut de vérification : le paiement Sale a été confirmé. Le statut suit Order Status After Payment. Une note indique le numéro de commande CorvusPay, le code d'autorisation et le type de carte.

Statut de vérification, autorisé : Authorize only est sélectionné. Capturez le paiement dans le CorvusPay Merchant Center, puis modifiez le statut de la commande.

Statut de vérification, écart de montant ou de devise : le montant ou la devise payés ne correspondent pas à la commande. N'expédiez pas avant d'avoir vérifié le paiement dans le CorvusPay Merchant Center.

Statut de vérification, paiement après annulation : un paiement réussi est arrivé pour une tentative de paiement que le client avait annulée. Traitez la commande ou remboursez le paiement dans le CorvusPay Merchant Center.

Si un autre paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de vérifier le CorvusPay Merchant Center et de rembourser le paiement en double si nécessaire. Si un paiement arrive pour une autre commande du même panier alors qu'une commande est déjà payée, cette commande reste sans statut et la note est ajoutée à la commande payée.

Les notes sont des entrées de l'History de la commande que le client ne voit pas.

Onglet VibeFox CorvusPay Gateway

Dans Sales > Orders, ouvrez une commande payée avec CorvusPay. En bas de la page de la commande, à côté de History et Additional, l'onglet VibeFox CorvusPay Gateway affiche le CorvusPay order number, le Status de la tentative de paiement, le Transaction type, le Amount (et le montant reçu, si CorvusPay l'a signalé), le Approval code, la Transaction, le type de Card et les CorvusPay notes. Les paiements de test sont marqués Test. L'onglet est en lecture seule et est affiché aux utilisateurs qui ont accès à l'extension.

Remboursements : les remboursements, captures et annulations depuis OpenCart ne sont pas pris en charge. Effectuez-les dans le CorvusPay Merchant Center et enregistrez le résultat manuellement dans OpenCart. Les retours de produits dans Sales > Returns ne renvoient pas d'argent via CorvusPay.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox CorvusPay Gateway est le premier bloc de Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > Edit, au-dessus des réglages. Collez la clé dans License key puis 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-corvuspay et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit Modify pour l'extension peuvent changer 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 pour un seul domaine : l'adresse de la boutique de la configuration OpenCart. 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, CorvusPay n'est pas affiché aux clients au moment 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 toujours la méthode de paiement dans la boutique, marquée (unlicensed — visible to admins only), afin que vous puissiez installer 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 la méthode de paiement est masquée 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 lorsque le client revient de CorvusPay.

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

CorvusPay n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le Store ID et la Secret Key du mode actuel sont renseignés (Test Store ID et Test Secret Key en mode test, Live Store ID et Live Secret Key en mode production) et que la devise du paiement est prise en charge par CorvusPay. Vérifiez également que l'adresse de paiement se trouve dans la Geo Zone sélectionnée et que la commande atteint le Minimum Total.

Le paiement a abouti, mais la commande reste sans statut : la Success URL n'est probablement pas saisie dans le CorvusPay Merchant Center, ou la Secret Key d'OpenCart ne correspond pas à la boutique. Recherchez INVALID signature dans le champ Log de la page de l'extension (les erreurs sont toujours journalisées). La commande reste aussi sans statut si le client a fermé le navigateur avant de revenir ; vérifiez alors le paiement dans le Merchant Center et réglez manuellement le statut de la commande.

Le client voit Payment not confirmed : la requête vers la Success URL a été rejetée : des champs obligatoires manquaient, le numéro de commande CorvusPay n'a pas été émis par cette boutique, la Secret Key de cette boutique est vide ou la signature ne correspondait pas. Rien n'est modifié. Le journal indique la raison.

Le client voit Your payment is being confirmed pendant longtemps : le statut de la commande n'a pas pu être attribué. Le journal indique la raison ; vérifiez le paiement dans le Merchant Center.

Le client voit This order total cannot be paid via CorvusPay : le total est nul ou comporte plus de 2 décimales.

Le client voit CorvusPay is not configured ou CorvusPay does not accept payments in … : le Store ID ou la Secret Key du mode actuel est absent, ou la devise du paiement n'est pas prise en charge.

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

La commande est au statut de vérification : lisez les notes dans l'onglet VibeFox CorvusPay Gateway. Authorize only est sélectionné, le montant ou la devise payés ne correspondaient pas à la commande, le paiement est arrivé après que le client a annulé, ou Order Status After Payment est réglé sur On hold.

Pour les développeurs : avant la signature du formulaire, l'extension déclenche l'événement OpenCart corvuspay_p_form_params avec les champs du formulaire et la commande.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox CorvusPay Gateway. 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, Minimum Total et les statuts de la section Order statuses, qui reviennent à leurs valeurs par défaut lors d'une réinstallation. L'événement OpenCart de l'extension est également supprimé (sur OpenCart 4, ses événements et son action de démarrage, qui laisse passer CorvusPay en mode maintenance). Si Delete Data est activé, les autres réglages de la passerelle (titre, description, Store ID, Secret Keys, mode test, réglages de paiement, journalisation) ainsi que les fichiers journaux sont supprimés. S'il est désactivé, ils sont conservés pour une réinstallation ultérieure. Les données de transaction CorvusPay sont toujours conservées, de sorte que l'onglet CorvusPay des anciennes commandes réapparaît après une réinstallation. 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 CorvusPay Gateway dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléchargé.

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