VibeFox PayU LATAM for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Devise : le panier doit être en 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 moyen de paiement n'est pas proposé à l'étape de paiement.

Compte PayU Latam : il vous faut trois valeurs de votre compte commerçant PayU : l'identifiant marchand, l'identifiant de compte du pays dans lequel vous vendez et la clé API. Elles se trouvent dans le module PayU (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 développeur. L'API Login et les autres identifiants d'API ne sont pas nécessaires, car le paiement s'effectue sur la page hébergée de PayU et le module n'appelle jamais l'API de PayU.

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

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

Installation

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

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

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, 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'à avoir effectué un paiement test, puis désactivez-le pour accepter de vrais paiements avec les identifiants de production.

À l'installation, le module crée deux statuts de commande : Awaiting PayU LATAM payment et PayU LATAM payment on hold. PrestaShop propose un nouveau moyen de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez le limiter dans Payment > Preferences. Un pays activé plus tard doit aussi y être coché pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, 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 si l'identifiant marchand, l'identifiant de compte ou la clé API de l'environnement actif est absent ; et un avertissement si PayU LATAM ne traite pas la devise par défaut de la boutique. Tant que des identifiants manquent, PayU LATAM n'apparaît pas à l'étape de paiement. Les espaces au début ou à la fin d'un identifiant sont ignorés. La page n'enregistre pas un Title vide et affiche Enter a title for the payment method.

PayU LATAM

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

Title : le titre du moyen de paiement affiché au client à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : PayU LATAM. Obligatoire.

Description : la description du moyen de paiement affichée au client à l'étape de paiement. 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.

Environnement

Sandbox : les paiements sont envoyés au sandbox PayU avec les identifiants sandbox ci-dessous, et aucun argent réel n'est débité. Lorsqu'il est désactivé, les identifiants de production et la page de paiement de production de PayU sont utilisés. Par défaut : activé. Tant qu'il est activé, les clients voient Sandbox mode: no real money is charged. sous le moyen de paiement.

Identifiants de production

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

Merchant ID : l'identifiant numérique de votre compte commerçant 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 vers la page « Test your solution » de la documentation PayU.

Sandbox merchant ID : l'identifiant marchand du sandbox PayU.

Sandbox account ID : l'identifiant de compte du sandbox PayU.

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

Les clés API enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved secrets : cochez API Key ou Sandbox API key et cliquez sur Save pour supprimer la clé enregistrée. Un champ vide conserve la valeur enregistrée.

Chaque tentative de paiement mémorise son environnement. La confirmation d'un paiement sandbox est vérifiée avec la clé API et l'identifiant marchand du sandbox, et celle d'un paiement réel avec les valeurs de production ; les paiements en attente continuent donc de fonctionner après le changement. Un paiement sandbox confirmé après le changement est marqué [sandbox] dans les notes de la commande.

URL de confirmation

Cette section affiche l'URL à laquelle PayU transmet chaque résultat de paiement. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_payu_latam_payment/confirmation, éventuellement avec un code de langue comme /en/. Le module l'envoie à PayU avec 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 et n'est pas bloquée par la restriction par pays de votre boutique. La confirmation est signée par PayU avec votre clé API. Les confirmations sans signature valide, avec un autre identifiant marchand ou avec une référence de paiement que cette boutique n'a pas émise sont rejetées. Le module gère ces états de transaction PayU :

Les autres états sont seulement ajoutés en note. Sans la confirmation, aucune commande n'est créée.

Avancé

Debug log : enregistre les requêtes de paiement et les notifications PayU dans logs/payu_lp_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données personnelles ne sont pas journalisées. Les erreurs et les notifications rejetées sont toujours journalisées, même si 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 : supprime les réglages et les journaux à la désinstallation du module. Les données PayU des commandes (tentatives de paiement) et les statuts de commande sont conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut PayU LATAM) et valide. Une page de votre boutique affiche You are being redirected to PayU LATAM to complete the payment... et envoie automatiquement un formulaire signé vers la page WebCheckout de PayU. Si cela ne se produit pas, le client clique sur Pay with PayU LATAM, ou sur Back to checkout pour revenir. Aucune commande n'existe encore à ce stade.

Le formulaire contient le total et la devise du panier, la taxe et la base d'imposition du panier (toutes deux à 0 pour les paniers sans taxe, afin que PayU n'ajoute pas de TVA par défaut), la description Cart # avec le numéro du panier et le nom de votre boutique, ainsi que l'adresse 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 panier. Sur la page PayU, le client paie avec n'importe quel moyen activé dans votre compte PayU.

Chaque visite de la page de paiement démarre une nouvelle tentative de paiement avec sa propre référence (PS, le numéro du panier et un horodatage). 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 accepté.

La commande n'est marquée payée qu'après la confirmation signée de PayU. Le client qui revient de PayU ne marque jamais une commande comme payée. Lorsque le client revient :

Si les identifiants de l'environnement actif sont absents, le client voit PayU LATAM is not available right now. Please choose another payment method. Pour une devise de panier non prise en charge, le message est PayU LATAM does not accept payments in, suivi de la devise. Un panier qui a déjà une commande n'est pas payé une seconde fois : le client est redirigé vers la page de confirmation de sa commande.

Le module ne propose pas de formulaire de paiement dans votre boutique, ni de remboursements depuis PrestaShop, ni de cartes enregistrées, ni d'abonnements, ni de réglages de paiements échelonnés (PayU affiche les paiements échelonnés sur sa page). Il n'interroge pas l'API PayU pour connaître le statut du paiement : seule la confirmation signée met à jour la commande.

Commandes

Statuts de commande

Aucune commande pour l'instant : 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. Seul le panier existe.

Payment accepted : PayU a confirmé le paiement, et le montant et la devise correspondent. Le paiement est enregistré avec l'identifiant de transaction PayU, et une note indique la transaction, le montant, le moyen de paiement et [sandbox] pour les paiements sandbox.

Awaiting PayU LATAM payment : PayU signale le paiement comme en attente (paiement en espèces ou par virement). La commande passe en Payment accepted lorsque PayU confirme le paiement.

PayU LATAM payment on hold : le montant ou la devise payé ne correspond pas au total du panier, ou un paiement a été approuvé pour une commande annulée. Le paiement est enregistré s'il est dans la devise de la commande. La note indique le cas : vérifiez le paiement dans le module PayU, puis traitez la commande, rétablissez-la ou remboursez le paiement.

Payment error : un paiement en attente de la dernière tentative a ensuite été refusé, expiré ou s'est terminé par une erreur. La note affiche le message PayU. Ce panier ne peut plus être payé : le client passe une nouvelle commande. 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 créent pas de deuxième commande et n'ajoutent pas de notes en double. Une commande payée n'est jamais rouverte ni rétrogradée. Si un autre paiement approuvé arrive pour une commande déjà payée, une note le signale : si le client a payé deux fois, remboursez le doublon dans le module PayU.

Bloc de paiement PayU LATAM

La page de la commande affiche un bloc PayU LATAM payment avec la référence, l'identifiant de transaction, la référence PayU, le statut et l'état PayU, le montant demandé, le montant indiqué par PayU, le moyen de paiement, le message PayU, un badge SANDBOX pour les paiements sandbox, la liste de toutes les tentatives de paiement du panier et les PayU LATAM notes de la commande.

Remboursements

Les remboursements ne se font pas depuis PrestaShop. Remboursez la transaction dans le module PayU, puis enregistrez manuellement le remboursement dans PrestaShop.

Clé de licence

Le module 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 Modules > Module Manager > VibeFox PayU LATAM Payment > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) 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: presta-payment-payu-latam et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).

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

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

Sans clé active, 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. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office ; le moyen de paiement est donc masqué pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à l'étape de paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés par la confirmation PayU et par le retour du client.

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

Dépannage

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 actif 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 panier est ARS, BRL, CLP, COP, MXN, PEN ou USD. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : 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 (pas de site local, de pare-feu ou de protection par mot de passe). Consultez le champ Log de la page du module pour voir 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 : l'identifiant marchand de la confirmation diffère de Merchant ID ou de Sandbox merchant ID de l'environnement du paiement. Saisissez l'identifiant marchand du compte PayU qui traite les paiements.

La confirmation répond Gateway not configured : la clé API ou l'identifiant marchand de l'environnement du paiement est absent, par exemple si les identifiants sandbox ont été supprimés pendant qu'un paiement sandbox était en attente. Saisissez-les à nouveau ; PayU renouvellera la confirmation.

La confirmation répond Retry : le panier était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Rien n'a été modifié, et PayU renvoie la confirmation. Consultez le Log pour en connaître la raison.

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 de PayU.

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

La commande est en PayU LATAM payment on hold : lisez les notes du bloc PayU LATAM payment. Le montant ou la devise payé était différent du panier, ou le paiement est arrivé après l'annulation de la commande. Vérifiez la transaction dans le module PayU.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayU LATAM Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data est activé, les réglages et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les tentatives de paiement et les statuts de commande Awaiting PayU LATAM payment et PayU LATAM payment on hold sont toujours conservés, afin qu'une confirmation PayU tardive d'une ancienne tentative soit reconnue après une réinstallation. Les commandes existantes conservent leurs notes de paiement, références PayU et identifiants de transaction.

PayU est une marque de son titulaire respectif. Ce module n'est ni affilié à PayU ni approuvé par PayU.