VibeFox PayU LATAM for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Devise : la devise de paiement du client doit être ARS, BRL, CLP, COP, MXN, PEN ou USD, les devises traitées par PayU Latam en Argentine, au Brésil, au Chili, en Colombie, au Mexique, au Panama et au Pérou. Pour les autres devises, le mode de paiement est masqué à l'étape de paiement.

Compte PayU Latam : vous avez besoin de trois valeurs de votre compte marchand PayU : le Merchant ID, l'Account ID du pays dans lequel vous vendez et la clé API. Elles se trouvent dans le panneau marchand PayU, sous Settings > Technical configuration (merchant ID, API key) et Accounts (account ID). Pour les tests, PayU publie des identifiants sandbox publics et des cartes de test sur la page « Test your solution » de sa documentation pour développeurs. Les identifiants API Login et les autres identifiants API ne sont pas nécessaires, car le paiement s'effectue sur la page hébergée de PayU et l'extension n'appelle jamais l'API de PayU.

Accès à Internet pour votre boutique : PayU envoie le résultat du paiement à votre boutique depuis ses serveurs ; la boutique doit donc être accessible depuis Internet (ni site local, ni protection par mot de passe).

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur 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_payu_latam_payment-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_payu_latam_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_payu_latam_payment-oc3-(version).ocmod.zip. L'extension n'apporte aucune modification OCMOD ; il n'est donc pas nécessaire d'actualiser Extensions > Modifications. Au lieu de passer par 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 PayU LATAM 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 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 les identifiants sandbox et vos identifiants de production (voir Configuration). Aucune URL de confirmation n'est à configurer dans PayU.

5. Activez Enable/Disable et cliquez sur Save. Gardez Sandbox activé jusqu'à ce que vous ayez effectué un paiement test, puis désactivez-le pour accepter de vrais paiements avec les identifiants de production.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_payu_latam_payment.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension à partir 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 PayU LATAM Payment, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence et les identifiants PayU comme aux étapes 3 à 5 pour OpenCart 3. La page des réglages et ses champs sont les mêmes dans les deux versions. Seule l'URL de confirmation diffère (voir URL de confirmation).

Une nouvelle installation démarre avec le mode de paiement désactivé et le sandbox activé.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox PayU LATAM 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 Sandbox mode. Payments go to the PayU sandbox and no real money is charged. tant que le sandbox est activé ; une erreur lorsque l'identifiant marchand, l'identifiant de compte ou la clé API de l'environnement actuel est manquant (PayU Latam n'est alors pas proposé à l'étape de paiement) ; et un avertissement lorsque PayU Latam ne traite pas la devise par défaut de la boutique. 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 être vide ni dépasser 128 caractères (la page affiche Enter a title for the payment method (at most 128 characters).), Sort Order doit être un nombre entier (les nombres négatifs sont acceptés), Total doit être un nombre égal ou supérieur à 0, et la zone géographique et les statuts de commande doivent exister. Sinon, rien n'est enregistré. Les espaces en début ou en fin d'identifiant sont ignorés.

PayU LATAM

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

Title : le nom du mode de paiement que le client voit à l'étape de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : PayU LATAM. Obligatoire, 128 caractères maximum.

Description : le texte affiché au client à l'étape Confirm Order, au-dessus du bouton de confirmation. Par défaut : Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Sort Order : la position de PayU LATAM parmi les modes de paiement à l'étape de paiement. Laissez ce champ vide ou saisissez un nombre entier.

Geo Zone : proposer PayU LATAM uniquement pour les adresses de facturation de 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 panier, dans la devise par défaut de la boutique, que la commande doit atteindre pour que PayU LATAM soit proposé. Laissez ce champ vide pour proposer PayU LATAM quel que soit le montant.

Environnement

Sandbox : les paiements sont envoyés au sandbox de PayU avec les identifiants sandbox, et aucun argent réel n'est débité. Lorsque l'option est désactivée, les identifiants de production et la page de paiement de production de PayU sont utilisés. Par défaut : activé. Tant qu'elle est activée, le client voit Sandbox mode: no real money is charged. à l'étape Confirm Order.

Identifiants de production

Retrouvez-les dans le panneau marchand PayU : Settings > Technical configuration (merchant ID, API key) et Accounts (account ID du pays dans lequel vous vendez). La section renvoie au panneau marchand PayU.

Merchant ID : l'identifiant numérique de votre compte marchand PayU.

Account ID : l'identifiant du compte PayU. Il existe un compte par pays.

API Key : la clé secrète utilisée pour signer les paiements et vérifier les notifications PayU.

Identifiants sandbox

PayU publie des identifiants de test publics et des cartes de test pour son sandbox. La section renvoie à la page « Test your solution » de la documentation PayU.

Sandbox merchant ID : le Merchant ID du sandbox PayU.

Sandbox account ID : l'Account ID du sandbox PayU.

Sandbox API key : la clé API du sandbox PayU.

Les clés API enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. Pour supprimer une clé enregistrée, cochez Clear saved secret on save sous le champ, puis cliquez sur Save.

Chaque tentative de paiement mémorise son environnement. La confirmation d'un paiement sandbox est vérifiée avec la clé API et le Merchant ID sandbox, et celle d'un paiement réel avec les identifiants de production ; ainsi, les paiements en attente continuent de fonctionner après un changement d'environnement. Les paiements sandbox sont signalés comme tels dans les notes de commande.

URL de confirmation

Cette section affiche l'URL à laquelle PayU transmet chaque résultat de paiement. Sur OpenCart 3, elle se présente sous la forme https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation, sur OpenCart 4 sous la forme https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation. Elle est construite à partir de l'adresse de la vitrine de votre installation OpenCart. L'extension la transmet à PayU à chaque paiement ; il n'y a donc rien à configurer dans PayU. L'URL doit être accessible depuis Internet. Elle fonctionne aussi lorsque la boutique est en mode maintenance (sur OpenCart 4 grâce à l'action de démarrage de l'extension, qui permet aussi au client de revenir depuis PayU). La confirmation est signée par PayU avec votre clé API. Les confirmations sans signature valide, avec un autre Merchant ID ou avec une référence de paiement que cette boutique n'a pas émise, sont rejetées. L'extension gère les états de transaction PayU suivants :

Les autres états sont seulement ajoutés en note. Sans la confirmation, la commande ne reçoit aucun statut.

Commandes

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). La commande ne reçoit un statut qu'après la confirmation signée de PayU. Chaque champ ci-dessous liste vos statuts de commande OpenCart.

Order Status After Payment : un paiement approuvé (état PayU 4) dont le montant et la devise correspondent. Par défaut : En traitement.

Awaiting Payment Status : un paiement en attente (états 7, 10, 12, 14, 15, 18 ; par exemple un paiement en espèces ou par virement non encore finalisé). La commande reçoit Order Status After Payment lorsque PayU la confirme. Par défaut : En attente.

On Hold (Review) Status : PayU a approuvé un paiement, mais avec un montant ou une devise différent de la commande, ou pour une commande qui avait été annulée. Une note indique les détails ; la commande n'est pas marquée comme payée. Par défaut : En attente, 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.

Failed Payment Status : un paiement en attente de la dernière tentative que PayU a ensuite signalé comme refusé, expiré ou échoué. Par défaut : Échec.

Cancelled Order Status : le statut utilisé par votre boutique pour les commandes annulées. Un paiement approuvé pour une telle commande la place en On Hold (Review) Status au lieu de la marquer comme payée. L'extension ne définit jamais ce statut. Par défaut : Annulé.

Avancé

Debug log : enregistre les demandes de paiement et les notifications PayU dans payu_lp_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web et, à 5 Mo, il est déplacé vers payu_lp_debug.old.log.php. Les clés et les données personnelles ne sont pas journalisées. Les erreurs et les notifications rejetées sont toujours enregistrées, même lorsque ce commutateur est désactivé. 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 : lorsqu'elle est activée, la désinstallation de l'extension supprime les réglages de la passerelle et le journal. Les commandes et les enregistrements de paiement PayU (tentatives de paiement) ne sont jamais supprimés. Par défaut : désactivé.

Importer / Exporter

Export : Download JSON enregistre les réglages dans un fichier JSON. Les clés API ne sont pas exportées.

Import : collez le JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. Les clés API enregistrées sont conservées.

Paiement

À l'étape Payment Method, le client choisit le mode de paiement (par défaut PayU LATAM). À l'étape Confirm Order, le client voit votre description ; OpenCart crée la commande à cette étape, toujours sans statut. Sur 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 du tunnel de commande. Lorsque le client clique sur Confirm Order, l'extension prépare un formulaire de paiement signé, la page affiche You are being redirected to PayU LATAM to complete the payment... et envoie automatiquement le formulaire à la page WebCheckout de PayU. Si cela ne se produit pas, le client clique sur Pay with PayU LATAM.

Le formulaire contient le montant total de la commande dans la devise de la commande, la taxe et la base d'imposition de la commande (toutes deux à 0 pour les commandes sans taxe, afin que PayU n'ajoute pas de TVA par défaut), la description Order # avec le numéro de commande et le nom de votre boutique, ainsi que l'e-mail, le nom, le téléphone et l'adresse de facturation du client. La page PayU s'ouvre en espagnol, en portugais ou en anglais, selon la langue du client. Sur la page PayU, le client paie avec n'importe quel mode activé dans votre compte PayU.

Chaque clic sur Confirm Order lance une nouvelle tentative de paiement avec sa propre référence (OC, le numéro de commande et un horodatage). Sur OpenCart 4, une nouvelle tentative paie la même commande du tunnel de commande. Les tentatives précédentes sont mémorisées : si le client paie depuis un ancien onglet PayU, le paiement est tout de même reconnu.

La commande n'est marquée comme payée qu'après la confirmation signée de PayU. Elle reçoit ensuite son statut de la manière habituelle d'OpenCart, avec les e-mails de commande habituels et la mise à jour du stock. Le client qui revient de PayU ne marque jamais une commande comme payée. Lorsque le client revient :

Sur OpenCart 4, les messages du tunnel de commande 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 du tunnel de commande, mais un panier n'est payé qu'une seule fois : si une autre commande de ce même panier est déjà payée, en attente de paiement ou en vérification, Confirm Order mène directement à la page de succès. Si les identifiants de l'environnement actuel sont manquants, le client voit PayU LATAM is not available right now. Please choose another payment method.

Sur OpenCart 4, la commande est conservée jusqu'à l'affichage de la page de succès. Si cette commande a été fermée entre-temps sans paiement (par exemple si son paiement en espèces a échoué ou si vous l'avez annulée), le client revient au tunnel de commande avec Your PayU LATAM payment was not approved et le motif de PayU, s'il existe. Si elle avait été payée puis fermée par la boutique, ou payée pour un panier antérieur dont le contenu a changé, le message est Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. Le prochain Confirm Order paie une nouvelle commande. Une commande fermée n'est jamais affichée comme payée.

L'extension ne propose ni formulaire de paiement sur votre site, ni remboursement depuis OpenCart, ni cartes enregistrées, ni abonnements, ni paramètres de paiement en plusieurs fois (PayU affiche les mensualités sur sa page). Elle n'interroge pas l'API PayU pour connaître l'état du paiement : seule la confirmation signée met à jour la commande.

Commandes

Statuts de commande

Aucun statut (commande manquante) : le client a été envoyé vers PayU et n'a pas payé, le paiement a été refusé, ou PayU n'a pas encore envoyé la confirmation. 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) : PayU a confirmé le paiement, et le montant et la devise correspondent. Une note indique la transaction, le montant, le mode de paiement et s'il s'agissait d'un paiement sandbox.

Awaiting Payment Status (default Pending) : PayU signale le paiement comme en attente (paiement en espèces ou par virement). La commande passe à Order Status After Payment lorsque PayU confirme le paiement, ou à Failed Payment Status en cas d'échec. OpenCart informe le client de ces changements.

On Hold (Review) Status (default Pending) : le montant ou la devise payé ne correspond pas au total de la commande, ou un paiement a été approuvé pour une commande annulée. La note indique le cas concerné : vérifiez le paiement dans le panneau marchand PayU, puis traitez la commande, rétablissez-la ou remboursez le paiement.

Failed Payment Status (default Failed) : un paiement en attente de la dernière tentative a ensuite été refusé, expiré ou a échoué. La note affiche le message de PayU. Un refus d'une tentative plus ancienne, ou d'une commande qui a déjà un paiement approuvé, est seulement ajouté en note.

Chaque notification est traitée une seule fois, sous un verrou par panier : les notifications PayU répétées ne modifient pas la commande deux fois et n'ajoutent pas de notes en double. Une commande payée n'est jamais rétrogradée. Si un autre paiement approuvé arrive pour une commande déjà payée, ou pour une autre commande du même panier, une note sur la commande payée le signale : si le client a payé deux fois, remboursez le doublon dans le panneau marchand PayU.

Les notes sont des entrées de l'History de la commande, invisibles pour le client.

Onglet VibeFox PayU LATAM Payment

Dans Sales > Orders, ouvrez une commande payée avec PayU LATAM. En bas de la page de commande, à côté de History et Additional, l'onglet VibeFox PayU LATAM Payment affiche la Reference, le Transaction ID, la PayU reference, le Status et l'état PayU, le montant Requested, le Amount reported by PayU, le Payment method, le PayU message, un badge SANDBOX pour les paiements sandbox, la liste de toutes les Payment attempts du panier et les PayU LATAM notes de la commande. L'onglet est affiché aux utilisateurs qui ont accès à l'extension.

Remboursements

Les remboursements ne se font pas depuis OpenCart. Remboursez la transaction dans le panneau marchand PayU, puis enregistrez le remboursement 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 PayU LATAM Payment est le premier bloc de Extensions > Extensions > Payments > VibeFox PayU LATAM 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, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine), ainsi que les boutons Check now pour vérifier à nouveau l'état, 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-payu-latam et le lien Gérer les licences et les domaines dans votre compte, 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 le motif, 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 état 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, PayU LATAM n'est pas proposé aux clients à l'étape de 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 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. 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 affectées : les paiements déjà lancés sont toujours confirmés par la confirmation PayU et par le retour du client.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié automatiquement à l'ouverture du Dashboard ou de 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 l'état de la licence.

Dépannage

PayU LATAM n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé, et que l'identifiant marchand, l'identifiant de compte et la clé API de l'environnement actuel sont renseignés : les identifiants sandbox lorsque Sandbox est activé, les identifiants de production lorsqu'il est désactivé. Vérifiez que la devise du client est ARS, BRL, CLP, COP, MXN, PEN ou USD, 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 abouti, mais la commande reste sans statut : la confirmation PayU n'a pas atteint votre boutique ou a été rejetée. Vérifiez que l'URL de confirmation affichée dans les réglages est accessible depuis Internet (ni site local, ni pare-feu, ni protection par mot de passe). Consultez le champ Log de la page de l'extension pour repérer les confirmations rejetées. PayU renvoie la confirmation après toute réponse d'erreur.

La confirmation répond Invalid signature : la confirmation n'a pas été signée avec la clé API de l'environnement du paiement. Vérifiez API Key pour les paiements réels et Sandbox API key pour les paiements sandbox.

La confirmation répond Merchant mismatch : le Merchant ID de la confirmation ne correspond pas à Merchant ID ou à Sandbox merchant ID de l'environnement du paiement. Saisissez le Merchant ID du compte PayU qui traite les paiements.

La confirmation répond Gateway not configured : la clé API ou le Merchant ID de l'environnement du paiement est manquant, par exemple parce que les identifiants sandbox ont été supprimés pendant qu'un paiement sandbox était en attente. Saisissez-les à nouveau ; PayU relancera la confirmation.

La confirmation répond Retry : le panier était en cours de traitement par une autre requête au même moment, ou le statut de la commande n'a pas pu être défini. PayU renverra la confirmation. Consultez le Log pour en connaître le motif.

La confirmation répond Unknown reference : la référence de paiement n'a pas été émise par cette boutique.

L'URL de confirmation affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de PayU.

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

La commande est au statut de vérification : consultez les notes dans l'onglet VibeFox PayU LATAM Payment. Le montant ou la devise payé différait de la commande, ou le paiement est arrivé après l'annulation de la commande. Vérifiez la transaction dans le panneau marchand PayU.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox PayU LATAM Payment. La clé de licence et l'état de la 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é (sur OpenCart 4, ses événements et son action de démarrage sont supprimés, ce qui permet de laisser passer la confirmation et le retour du client en mode maintenance). Si Delete data est activé, les autres réglages de la passerelle (titre, description, sandbox, identifiants, commutateur du journal de débogage) et le journal sont supprimés. Dans le cas contraire, ils sont conservés pour une future réinstallation. Les tentatives de paiement sont toujours conservées, de sorte qu'une confirmation PayU tardive d'une ancienne tentative reste reconnue 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 PayU LATAM Payment dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

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