VibeFox PayU LATAM for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

WooCommerce: 7.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui ; si WooCommerce est ensuite désactivé, elle ne fait rien et affiche un avis dans l'administration.

PHP: 8.0 ou ultérieur.

Currency: la commande 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 est masqué sur la page de paiement.

PayU Latam account: vous avez besoin de trois valeurs de votre commerce PayU : l'identifiant marchand, l'identifiant du compte du pays où vous vendez et la clé API. Elles se trouvent dans le module PayU (le panneau marchand PayU), sous Settings > Technical configuration (identifiant marchand, clé API) et Accounts (identifiant de compte). 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. API Login et les autres identifiants API ne sont pas nécessaires, car le paiement se fait sur la page hébergée par PayU.

Internet access to your site: PayU envoie le résultat du paiement à votre boutique depuis ses serveurs ; le site doit donc être accessible depuis Internet (ni site local, ni protection par mot de passe, ni page de maintenance).

VibeFox license key: achetée sur vibefox.net. Une clé fonctionne sur un domaine.

Installation

1. Dans WordPress, ouvrez Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier wcp_payu_latam_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > PayU LATAM > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page des extensions.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez les identifiants sandbox et vos identifiants de production (voir Configuration). Aucune URL de confirmation n'est à configurer dans PayU.

6. Activez Enable/Disable et enregistrez. Laissez Sandbox activé jusqu'à la réalisation d'un paiement de test, puis décochez-le pour accepter les paiements réels avec les identifiants de production.

Configuration

Tous les réglages sont sur une page : WooCommerce > Settings > Payments > PayU LATAM. Au-dessus des champs, la page vous avertit lorsque le mode sandbox est activé (Sandbox mode. Les paiements sont envoyés au sandbox PayU et aucun argent réel n'est débité.), lorsqu'il manque l'identifiant marchand, l'identifiant de compte ou la clé API de l'environnement actuel, et lorsque PayU LATAM ne traite pas la devise de la boutique. Dans les deux derniers cas, PayU LATAM n'apparaît pas sur la page de paiement. Dans la liste des moyens de paiement, PayU LATAM est indiqué comme nécessitant une configuration tant que les trois identifiants de l'environnement actuel ne sont pas renseignés. Les espaces au début ou à la fin d'un identifiant sont ignorés.

Général

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

Title: le titre du moyen de paiement affiché au client sur la page de paiement. Par défaut : PayU LATAM.

Description: la description du moyen de paiement affichée au client sur la page 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: Enable the PayU sandbox (test mode). Les paiements sont envoyés au sandbox PayU avec les identifiants sandbox ci-dessous, sans débiter d'argent réel. Si l'option est désactivée, les identifiants et la page de paiement PayU de production sont utilisés. Par défaut : on.

Identifiants de production

Retrouvez-les dans le module PayU : Settings > Technical configuration (identifiant marchand, clé API) et Accounts (identifiant du compte du pays où vous vendez). La section propose un lien vers le panneau marchand PayU.

Merchant ID: l'identifiant numérique de votre commerce 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 propose un lien 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.

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 sandbox, et celle d'un paiement de production avec les valeurs de production. Les paiements en attente continuent donc de fonctionner après un changement d'environnement. Lors d'une mise à jour depuis la version 1.0, qui ne disposait que d'un jeu d'identifiants, les anciennes valeurs sont copiées dans les champs sandbox si celui-ci était activé. Vérifiez les réglages après la mise à jour.

URL de confirmation

Cette section affiche l'URL à laquelle PayU communique chaque résultat de paiement. Elle ressemble à https://your-site/wc-api/payu_lp/. L'extension l'envoie à PayU avec chaque paiement ; il n'y a donc rien à configurer dans PayU. La page doit être accessible depuis Internet. PayU signe la confirmation 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 pour la commande sont rejetées. L'extension gère ces états de transaction PayU :

4 (approved): le paiement a été effectué. La commande est marquée payée lorsque le montant et la devise correspondent.

6 (declined), 5 (expired), 104 (error): le paiement a échoué. Une commande impayée correspondant à la dernière tentative passe à Échouée.

7 and other pending states: le paiement est en attente, par exemple un paiement en espèces ou bancaire que le client n'a pas encore finalisé. La commande est mise en attente.

Les autres états sont uniquement ajoutés comme note de commande. Sans confirmation, une commande n'est jamais marquée payée : elle reste En attente de paiement.

Avancé

Debug log: Log payment requests and PayU notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_payu_latam_payment, sans clés ni données personnelles. Les erreurs et les notifications rejetées sont toujours journalisées. Par défaut : off.

Delete data: Delete the settings and logs when the plugin is deleted. Désactiver l'extension ne supprime jamais rien. Les données PayU enregistrées dans les commandes sont conservées. Par défaut : off.

Paiement

Le client choisit le moyen de paiement (par défaut PayU LATAM) et passe commande. Dans le bloc Paiement en mode sandbox, il voit Sandbox mode: no real payment is made. La commande reste En attente de paiement, et le client accède à une page de paiement de votre boutique avec le texte Thank you for your order. You are being redirected to PayU LATAM to complete the payment… La page envoie automatiquement un formulaire signé à la page PayU WebCheckout. Si cela ne se produit pas, le client clique sur Pay with PayU LATAM, ou sur Cancel order pour annuler la commande.

Le formulaire contient le total et la devise de la commande, la taxe et la base imposable 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, portugais ou anglais selon la langue de la boutique. Le client y paie avec l'un des moyens activés dans votre compte PayU.

Chaque visite de la page de paiement lance une nouvelle tentative avec sa propre référence (numéro de commande et horodatage). Les 30 dernières tentatives de la commande sont mémorisées : si le client paie dans un ancien onglet PayU, le paiement est toujours accepté.

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

Après un refus, une expiration ou une erreur signés : la commande passe immédiatement à Échouée, et WooCommerce affiche sa page standard d'échec du paiement avec la possibilité de réessayer.

Sans transaction PayU (le client a quitté la page PayU) : le client accède à la page Pay for order avec le message Your PayU LATAM payment was not completed. You can try again or choose another payment method.

Sinon : le client voit la page de commande reçue. Tant que la commande est En attente de paiement, elle indique We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. Pour une commande en attente, elle indique Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment.

Si les identifiants de l'environnement actuel manquent, le client voit PayU LATAM is not available right now. Please choose another payment method. Si la devise de la commande n'est pas prise en charge, le message est PayU LATAM does not accept payments in suivi de la devise. Une commande déjà payée n'est pas payée à nouveau : la page de paiement affiche This order has already been paid.

Le moyen de paiement fonctionne sur le paiement classique, le bloc Paiement et la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne propose ni formulaire de paiement dans votre boutique, ni remboursements depuis WooCommerce, ni cartes enregistrées, ni abonnements, ni réglages des paiements échelonnés (PayU les affiche 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

États des commandes

Pending payment: le client a été envoyé sur PayU et n'a pas encore payé, ou PayU n'a pas encore envoyé la confirmation.

Processing: PayU a confirmé le paiement et le montant et la devise correspondent. La note de commande indique la transaction PayU, le montant, le moyen de paiement et [sandbox] pour les paiements sandbox. L'identifiant de transaction de la commande est celui de PayU. Les commandes contenant uniquement des produits virtuels téléchargeables passent à Terminée, conformément au comportement par défaut de WooCommerce.

On hold: PayU signale le paiement comme en attente (espèces ou paiement bancaire), le montant payé ou la devise ne correspond pas au total de la commande, ou un paiement a été approuvé pour une commande annulée. La note de commande précise le cas : vérifiez le paiement dans le module PayU, puis traitez la commande, rétablissez-la ou remboursez le paiement.

Failed: la dernière tentative de paiement a été refusée, a expiré ou s'est terminée par une erreur. La note affiche le message PayU. Le client peut réessayer. Le refus d'une ancienne tentative, ou d'une commande ayant déjà un paiement approuvé, est seulement ajouté comme note.

Chaque notification est traitée une fois, sous un verrou par commande : les notifications répétées de PayU ne dupliquent ni notes, ni réductions de stock, ni e-mails. Si une autre requête met trop longtemps à actualiser la commande, la confirmation reçoit une réponse d'erreur et PayU la renvoie plus tard. Une commande payée, terminée ou remboursée n'est jamais rouverte. 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.

Remboursements

Les remboursements ne se font pas depuis WooCommerce. Remboursez la transaction dans le module PayU et, si nécessaire, enregistrez manuellement le remboursement dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > PayU LATAM. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date de validité de la licence et votre domaine. Utilisez Check now pour revérifier l'état, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez cet emplacement dans votre compte vibefox.net.

Sans clé active, PayU LATAM n'apparaît pas pour les clients sur la page de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), pour vous permettre de configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page des extensions et les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. L'état est revérifié automatiquement en arrière-plan.

Dépannage

PayU LATAM n'apparaît pas sur la page 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é, ceux de production lorsqu'il est désactivé. Vérifiez que la devise de la boutique (ou de la commande sur la page de paiement de la commande) est ARS, BRL, CLP, COP, MXN, PEN ou USD. La page de réglages affiche un avertissement pour chacun de ces problèmes.

Le paiement a abouti, mais la commande reste Pending payment : la confirmation PayU n'a pas atteint votre boutique ou a été rejetée. Vérifiez que l'URL de confirmation des réglages est accessible depuis Internet (ni site local, ni mode maintenance, ni pare-feu, ni protection par mot de passe). Consultez WooCommerce > Status > Logs, source wcp_payu_latam_payment, pour les confirmations rejetées. PayU renvoie la confirmation après toute réponse d'erreur.

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

La confirmation répond Merchant mismatch : son identifiant marchand diffère de Merchant ID ou 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 manque ; par exemple les identifiants sandbox ont été retirés alors qu'un paiement sandbox était en attente. Saisissez-les à nouveau ; PayU réessaie la confirmation.

La confirmation répond Busy, retry later : une autre requête actualisait la commande simultanément. Rien n'a été modifié et PayU renvoie la confirmation.

La confirmation répond Unknown reference : la référence de paiement n'appartient à aucune commande PayU LATAM de cette boutique ; par exemple la commande a été supprimée ou son moyen de paiement a été changé.

La commande est On hold : lisez la note de commande. Le paiement est encore en attente chez PayU (espèces ou paiement bancaire), le montant payé ou la devise différait de la commande, ou le paiement est arrivé après son annulation. Vérifiez la transaction dans le module PayU.

Autres devises ou champs du formulaire : les développeurs peuvent modifier la liste des devises avec le filtre payu_lp_supported_currencies, l'icône du paiement avec le filtre payu_lp_icon et les champs du formulaire WebCheckout avec le filtre payu_lp_payment_fields.

Le bloc de licence affiche une erreur : suivez le message du bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est inaccessible, l'extension continue avec le dernier état connu.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la retirer, désactivez-la puis supprimez-la sur la page Plugins. Sa clé de licence et son état de licence sont toujours supprimés. Ses réglages de passerelle et journaux ne sont supprimés que si Delete data était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, références PayU et identifiants de transaction.

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