VibeFox dLocal 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 de PHP plus anciennes.
Accès à la boutique : votre boutique doit être accessible depuis Internet, et utiliser HTTPS en production, pour que dLocal Go puisse envoyer les notifications de paiement.
Compte dLocal Go : vous avez besoin de la clé API et du secret API du tableau de bord dLocal Go, section Payment integration : dashboard-sbx.dlocalgo.com pour le sandbox, dashboard.dlocalgo.com pour la production. Le sandbox et la production utilisent des identifiants différents. L'API entreprise dLocal Payments (identifiants X-Login / X-Trans-Key) est un produit distinct et n'est pas prise en charge.
Pays et devises : le module ne les limite pas. dLocal Go décide quels moyens de paiement sont proposés pour le pays du client et la devise du panier. Seules les restrictions de paiement de PrestaShop s'appliquent.
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éversement terminé, cliquez sur Configure, ou retrouvez VibeFox dLocal Payment plus tard dans la liste des modules et cliquez sur Configure.
3. Collez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, et cliquez sur Activate (voir Clé de licence).
4. Choisissez l'Environment et collez la clé API et le secret API de cet environnement (voir Configuration).
5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en sandbox, puis passez l'Environment sur Production.
À l'installation, le module crée le statut de commande dLocal payment on hold. PrestaShop propose le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox dLocal Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Le titre de la première section 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é à l'étape de paiement, par exemple Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Lorsque le sandbox est sélectionné et que le moyen de paiement est activé, la page affiche Sandbox mode is active: payments are simulated, no money is charged.
dLocal Go
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 voient les clients lors du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : dLocal Go. Obligatoire.
Description: le texte affiché sous le moyen de paiement lors du 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). La section contient des liens vers les deux tableaux de bord.
Environment: les identifiants et les serveurs dLocal Go utilisés pour les nouveaux paiements.
Les remboursements et les notifications d'un paiement utilisent toujours les identifiants de l'environnement dans lequel il a été effectué. Conservez donc les identifiants de l'autre environnement tant que ses paiements sont encore ouverts ou susceptibles d'être remboursé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.
Les clés et secrets enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.
Clear saved credentials: cochez une clé ou un secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.
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 le panier n'en a aucune des deux. Par défaut : Uruguay.
Auto-complete orders: passe les commandes payées à Delivered au lieu de Payment accepted. Le statut est défini immédiatement, en un seul changement de statut. Par défaut : désactivé.
Notifications (IPN): les notifications informent votre boutique qu'un paiement ou un remboursement a changé. Le module envoie les URL de notification à dLocal Go avec chaque paiement et chaque remboursement, de sorte qu'il n'y a rien à configurer dans le tableau de bord dLocal Go. Ce champ affiche les deux URL :
Les notifications sont vérifiées avec votre secret API (HMAC-SHA256). Les notifications sans signature valide sont rejetées. Une notification doit être signée avec les identifiants de l'environnement dans lequel le paiement a été effectué. 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 créée que lorsque le client revient sur la boutique.
Avancé
Debug log: écrit les requêtes et notifications dLocal Go dans logs/dlocal_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les identifiants API et les données personnelles ne sont pas journalisés. Les erreurs et avertissements sont toujours écrits ; les autres entrées uniquement tant que cette option est activée. 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 on uninstall: lorsqu'elle est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les données de paiement des commandes (paiements et remboursements dLocal) et le statut de commande dLocal payment on hold sont toujours conservés, pour que les commandes existantes continuent de fonctionner. Par défaut : désactivé.
Paiement
À l'étape de paiement, le client choisit le moyen de paiement (par défaut dLocal Go). En mode sandbox, la page de paiement affiche Sandbox mode: no real payment is made. sous le moyen de paiement. Après confirmation, le module crée un paiement dLocal Go pour le total du panier dans la devise du panier, avec le pays, le nom, l'e-mail et le téléphone du client, puis envoie le client sur 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 du panier. À ce stade, aucune commande n'existe encore.
Après le paiement, le client revient sur 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 vers l'API dLocal Go lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with dLocal Go has been received. Si la commande a été mise en attente, la page affiche Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Si dLocal Go n'a pas encore confirmé le paiement (par exemple un bon en espèces non encore payé, ou si dLocal Go était injoignable), une page Payment confirmation demande au client de ne pas payer à nouveau et propose Check again et Back to checkout. La commande est créée dès que dLocal Go confirme le paiement.
Si le client quitte la page dLocal Go sans payer, il revient au paiement 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. Le panier est conservé. Chaque nouvelle tentative crée un nouveau paiement dLocal Go ; un ancien lien de paiement du même panier peut encore être payé, et crée alors la commande.
Si dLocal Go ne peut pas démarrer le paiement, le client reste sur la page de paiement avec un bref message, par exemple dLocal could not start the payment: suivi du motif indiqué par dLocal. Cela arrive aussi lorsque le pays du client et la devise du panier ne sont pas activés dans votre compte dLocal Go. Si dLocal Go rejette vos identifiants, le client voit This payment method is temporarily unavailable. Please choose another payment method or contact us. Le motif technique est écrit dans le journal.
Les notifications fonctionnent pendant que la boutique est en mode maintenance et ne sont pas bloquées par la restriction de pays de votre boutique.
Le module n'accepte que les paiements ponctuels sur la page dLocal Go. Il 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
Statuts de commande
Pas encore de commande : le client a été envoyé vers dLocal Go et n'a pas payé, ou le paiement est toujours en attente chez dLocal Go. Seul le panier existe.
Payment accepted or Delivered : le paiement a été confirmé. La commande passe en « Paiement accepté », ou en « Livré » si Auto-complete orders est activé. Le paiement est enregistré avec l'ID du paiement dLocal comme ID de transaction, et une note indique l'environnement et l'ID du paiement.
dLocal payment on hold : dLocal Go a signalé un montant ou une devise différent du total du panier (par exemple, le panier a été modifié dans un autre onglet après le début du paiement), ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Comparez avec le tableau de bord dLocal Go, puis traitez la commande ou remboursez le paiement.
Refunded : le paiement a été entièrement remboursé via le module.
Un paiement refusé, expiré ou annulé ne modifie jamais une commande existante. 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.
Bloc de paiement dLocal Go
La page de commande affiche un bloc dLocal Go payment avec l'ID du paiement dLocal, l'environnement (avec un badge Sandbox pour les paiements de test), le statut du paiement, le montant encaissé par dLocal Go et le montant remboursé, le formulaire de remboursement, l'historique des remboursements et les dLocal Go notes de la commande.
Remboursements
Dans le bloc dLocal Go payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via dLocal Go. Confirmez la question Refund this amount through dLocal Go? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements se font dans le montant et la devise facturés par dLocal Go. Après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'à ce que le client a réellement payé, et non le total de la commande. 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, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement accepté est ajouté à l'historique des remboursements et aux notes, avec l'ID, le statut et le motif du remboursement. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.
dLocal Go communique ensuite le statut final du remboursement par la notification de remboursement, et il est ajouté aux notes. Si dLocal Go rejette ou annule plus tard un remboursement qu'il avait accepté, la note avertit que l'argent n'a pas été restitué au client. Remboursez à nouveau le client ou par un autre moyen.
Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via dLocal Go. Les remboursements effectués dans le tableau de bord dLocal Go ne sont pas enregistrés comme remboursements dans PrestaShop et n'ajoutent généralement aucune note. Mettez la commande à jour manuellement si nécessaire.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox dLocal Payment est le premier bloc de Modules > Module Manager > VibeFox dLocal Payment > Configure, au-dessus des réglages. Collez 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-dlocal et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation 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 : le domaine 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, dLocal Go n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back office, donc le moyen de paiement est aussi masqué pour vous : 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 touchées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.
Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant que vous travaillez 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 la licence.
Dépannage
dLocal Go n'apparaît pas au 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 de réglages affiche un avertissement s'ils manquent. 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 : dLocal Go n'a pas pu joindre l'URL de notification (pare-feu, authentification de base, pas d'adresse publique) et le client n'est pas revenu sur la boutique. Activez Debug log, consultez le champ Log et vérifiez le paiement dans le tableau de bord dLocal Go. Dès qu'une notification arrive ou que le client ouvre Check again, la commande est créée.
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 de l'environnement du paiement ; les paiements commencés avant que vous changiez l'Environment sont donc 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 du paiement sont absents. Saisissez-les ; dLocal Go relancera 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 relancera la notification.
La notification répond Temporarily unavailable : la commande était en cours de confirmation 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é). dLocal Go relancera la notification. Le motif figure dans le journal.
La notification répond Order not found : le paiement n'appartient à aucun panier de cette boutique, par exemple parce qu'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é.
Le client voit Payment gateway is not properly configured : les identifiants de l'environnement sélectionné sont absents.
La commande est en dLocal payment on hold après le paiement : lisez les notes du bloc dLocal Go payment. Le montant ou la devise payés ne correspondaient pas au panier, 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 d'identifiants manquants : le paiement a été effectué dans l'autre environnement, et ses identifiants ne sont pas renseignés. Saisissez-les et réessayez.
Pour les développeurs, la documentation du module répertorie les hooks actionWcpDlocalPaymentData et actionWcpDlocalCurrencyDecimals.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox dLocal Payment et choisissez Uninstall. La clé de licence et le statut de la licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages de la passerelle 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 paiements et remboursements dLocal des commandes ainsi que le statut de commande dLocal payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
dLocal est une marque de son propriétaire respectif. Ce module n'est ni affilié à dLocal ni approuvé par dLocal.