VibeFox dLocal for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

WooCommerce: 7.0 ou ultérieur, installé et actif.

PHP: 8.0 ou ultérieur. L'extension refuse de s'activer avec une version plus ancienne de PHP ou de WordPress.

Accès au site : votre site doit être accessible depuis Internet et utiliser HTTPS en production, pour que dLocal Go puisse livrer les notifications de paiement. Un pare-feu, le mode maintenance ou une authentification basique peuvent les bloquer.

Compte dLocal Go : il vous faut la clé API et le secret API du tableau de bord dLocal Go, section Payment integration : dashboard-sbx.dlocalgo.com pour la sandbox, dashboard.dlocalgo.com pour la production. La sandbox et la production utilisent des identifiants différents. L'API entreprise dLocal Payments (identifiants X-Login / X-Trans-Key) est un produit différent et n'est pas prise en charge.

Pays et devises : l'extension ne les limite pas. dLocal Go décide quels moyens de paiement sont proposés pour le pays du client et la devise de la boutique.

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

Installation

1. Dans WordPress, allez dans 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_dlocal_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate. WooCommerce doit être actif.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > dLocal Go > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.

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

5. Choisissez l'Environment et collez la clé API et le secret API de cet environnement (voir Configuration).

6. Activez Enable/Disable et enregistrez. Testez un paiement en sandbox, puis passez Environment sur Production.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > dLocal Go. Le titre de la page affiche SANDBOX ou PRODUCTION. Tant que la clé API et le secret de l'environnement sélectionné ne sont pas saisis, la page vous avertit que le moyen de paiement est masqué sur la page de paiement. Tant que la sandbox est sélectionnée et que la passerelle est activée, elle affiche Sandbox mode is active: payments are simulated, no money is charged. Dans la liste des moyens de paiement, dLocal Go est signalé comme à configurer tant que les identifiants ne sont pas renseignés, et affiche Test mode en sandbox.

Général

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

Title: le nom du moyen de paiement que les clients voient sur la page de paiement. Par défaut : dLocal Go.

Description: le texte affiché sous le moyen de paiement sur la page de paiement. Par défaut : Pay with local cards, bank transfer or cash via dLocal Go.

Identifiants API

Copiez la clé API et le secret API depuis le tableau de bord dLocal Go, Payment integration : dashboard-sbx.dlocalgo.com (sandbox) ou dashboard.dlocalgo.com (production). Tous les champs d'identifiants sont des champs de mot de passe.

Environment: les identifiants et les serveurs dLocal Go utilisés.

Sandbox API Key: votre clé API sandbox dLocal Go.

Sandbox API Secret: votre secret API sandbox dLocal Go.

Production API Key: votre clé API de production dLocal Go.

Production API Secret: votre secret API de production dLocal Go.

Paiement

Default country: dLocal Go affiche les moyens de paiement du pays du client, pris dans l'adresse de facturation, puis dans l'adresse de livraison. Ce pays est utilisé lorsque la commande n'a ni l'une ni l'autre. Par défaut : Uruguay.

Auto-complete orders: Set paid orders to "Completed" instead of "Processing". L'état est défini en une seule fois, avec un seul jeu d'e-mails. Par défaut : désactivé.

Notifications (IPN)

Les notifications informent votre boutique qu'un paiement ou un remboursement a changé. L'extension envoie les URL de notification à dLocal Go avec chaque paiement et chaque remboursement, il n'y a donc rien à configurer dans le tableau de bord dLocal Go. Cette section des réglages affiche les deux URL :

Les notifications sont vérifiées avec votre secret API (HMAC-SHA256). Les notifications sans signature valide sont rejetées. Ensuite, le statut, le montant et la devise du paiement sont toujours relus depuis l'API dLocal Go ; le contenu de la notification n'est pas considéré comme fiable. Sans notifications, une commande n'est mise à jour que lorsque le client revient sur la boutique.

Avancé

Debug log: Log API requests and notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_dlocal_payment, sans identifiants API ni données personnelles. Les erreurs sont toujours journalisées. Par défaut : désactivé.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Par défaut : désactivé.

Page de paiement

Le client choisit le moyen de paiement (par défaut dLocal Go) et passe la commande. L'extension crée un paiement dLocal Go pour le total de la commande dans la devise de la commande, avec le pays, le nom, l'e-mail et le téléphone du client, et redirige le client vers la page de paiement dLocal Go. Le client y paie avec un moyen de son pays. Le paiement apparaît sur la page dLocal Go sous la forme Order # suivi du numéro de commande. En mode sandbox, la page de paiement affiche Sandbox mode: no real payment is made. sous le moyen de paiement.

Après le paiement, le client revient sur la page de commande reçue de votre boutique. La commande n'est marquée payée qu'après confirmation de dLocal Go : par la notification signée ou par une requête côté serveur à l'API dLocal Go lorsque le client arrive sur cette page.

Si le client quitte la page dLocal Go sans payer, il revient sur la page de paiement (ou sur la page Pay for order) et voit The payment at dLocal Go was not completed. You can try again or choose another payment method. Si le paiement a été refusé ou a expiré, le message est Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. S'il s'avère que le paiement a bien été effectué, le client est redirigé vers la page de commande reçue. Un ancien lien de paiement de la même commande peut encore être payé après une nouvelle tentative.

Si dLocal Go ne peut pas démarrer le paiement, le client voit un court message sans détails techniques, par exemple dLocal could not start the payment: suivi du motif indiqué par dLocal, et peut choisir un autre moyen. Cela se produit aussi lorsque le pays du client et la devise de la boutique ne sont pas activés dans votre compte dLocal Go. Le motif technique est écrit dans le journal.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage des commandes haute performance (HPOS) de WooCommerce.

L'extension ne prend que les paiements ponctuels sur la page dLocal Go. Elle n'a ni formulaire de carte sur votre site, ni cartes enregistrées, ni abonnements, ni autorisation et capture séparées.

Commandes et remboursements

États de commande

Pending payment: le client a été redirigé vers dLocal Go et n'a pas encore payé, ou le paiement est en attente chez dLocal Go (par exemple un bon de paiement en espèces pas encore réglé). Chaque nouvelle tentative de paiement est notée dans la commande avec son identifiant de paiement dLocal, le montant et l'environnement.

Processing or Completed: le paiement a été confirmé. La commande est En cours (par défaut dans WooCommerce), ou Terminée lorsque Auto-complete orders est activé. L'identifiant de transaction est l'identifiant de paiement dLocal.

On hold: dLocal Go a indiqué un montant ou une devise différents du total de la commande, ou le paiement est arrivé après l'annulation de la commande. La note de commande l'explique. Comparez avec le tableau de bord dLocal Go et traitez la commande ou remboursez le paiement.

Failed: la dernière tentative de paiement a été refusée ou a expiré. Le client peut réessayer.

Cancelled: dLocal Go a signalé la dernière tentative de paiement comme annulée.

Seule la dernière tentative de paiement peut faire échouer ou annuler une commande non payée. Une commande payée n'est jamais rouverte par une ancienne notification. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double dans le tableau de bord dLocal Go.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via dLocal Go. Les remboursements totaux et partiels sont pris en charge pour les commandes payées via dLocal Go. Le remboursement est envoyé à l'environnement dans lequel le paiement a été effectué, avec les identifiants de cet environnement. Si dLocal Go n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement accepté est ajouté aux notes de commande avec son identifiant et son statut.

dLocal Go communique ensuite le statut final du remboursement par la notification de remboursement, et il est ajouté aux notes de commande. Si dLocal Go rejette ou annule plus tard un remboursement qu'il avait accepté, la note avertit que l'argent n'a pas été rendu au client. Vérifiez le remboursement WooCommerce enregistré pour celui-ci : supprimez-le et remboursez à nouveau, ou remboursez le client autrement.

Les remboursements effectués dans le tableau de bord dLocal Go ne sont pas enregistrés comme remboursements WooCommerce et n'ajoutent généralement pas de note de commande. Si nécessaire, créez un remboursement manuel dans WooCommerce sans Refund via dLocal Go.

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 > dLocal Go. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour revérifier le statut, 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 l'emplacement de son domaine. Libérez l'emplacement dans votre compte vibefox.net.

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

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

Dépannage

dLocal Go n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la clé API et le secret API de l'Environment sélectionné sont renseignés. La page des réglages affiche un avertissement lorsqu'ils manquent.

Le paiement est passé, mais la commande reste En attente de paiement : dLocal Go n'a pas pu joindre l'URL de notification (pare-feu, mode maintenance, authentification basique) et le client n'est pas revenu sur la page de commande reçue. Consultez WooCommerce > Status > Logs, source wcp_dlocal_payment, et le paiement dans le tableau de bord dLocal Go. Dès qu'une notification arrive ou que le client ouvre la page de commande reçue, la commande est mise à jour.

La notification répond Missing signature ou Invalid signature : la clé API et le secret des réglages n'appartiennent pas au compte qui a envoyé la notification. Les notifications sont vérifiées avec les identifiants des deux environnements, donc les paiements lancés avant que vous changiez Environment sont toujours confirmés, tant que les identifiants de leur environnement restent dans les réglages.

La notification répond Gateway not configured : les identifiants de l'environnement sélectionné manquent. dLocal Go renvoie la notification.

La notification répond API verification failed : l'API dLocal Go n'a pas pu être jointe pour lire le paiement. dLocal Go renvoie la notification.

La notification répond Order not found : le paiement n'appartient pas à une commande de cette boutique ; par exemple, il a été créé par un autre site avec le même compte dLocal Go.

Le client voit This payment method is temporarily unavailable : dLocal Go a rejeté la clé API ou le secret. Vérifiez les identifiants de l'environnement sélectionné.

La commande est En attente après le paiement : lisez la note de commande. Le montant ou la devise payés différaient de la commande, ou le paiement est arrivé après l'annulation de la commande. Traitez la commande ou remboursez le paiement.

Le remboursement échoue avec un message sur des identifiants manquants : le paiement a été effectué dans l'autre environnement, et ses identifiants ne sont pas renseignés. Saisissez-les et réessayez.

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 injoignable, l'extension continue de fonctionner sur le dernier statut connu.

Pour les développeurs, la documentation de l'extension liste les filtres dlocal_p_payment_data, dlocal_p_currency_decimals et dlocal_p_icon.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils restent pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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