VibeFox Square 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 : la devise du panier doit être celle de votre site Square : USD, CAD, AUD, JPY, GBP ou EUR. Pour les autres devises, le mode de paiement est masqué sur la page de paiement. Square accepte les vendeurs aux États-Unis, au Canada, en Australie, au Japon, au Royaume-Uni, en Irlande, en France et en Espagne.

Compte Square : vous avez besoin d'une application dans le Square Developer Dashboard. Vous y copiez l'Application ID et l'Access Token (page Credentials) ainsi que le Location ID (page Locations). Sandbox et Production ont des valeurs distinctes. Aucun webhook n'est nécessaire : le module reçoit le résultat du paiement directement dans la réponse de Square.

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 Square Gateway 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. Laissez Sandbox Mode activé et saisissez l'Application ID, l'Access Token et le Location ID du sandbox (voir Configuration). Cliquez sur Save : le module vérifie les identifiants auprès de Square.

5. Activez Enable/Disable, enregistrez et testez un paiement avec les cartes de test du guide de test du sandbox de Square. Désactivez ensuite Sandbox Mode, saisissez les identifiants de production et enregistrez à nouveau.

À l'installation, le module crée le statut de commande Square payment on hold. PrestaShop autorise un nouveau module de paiement pour les devises, les pays actifs au moment de l'installation et les groupes de clients. Vérifiez-les, et cochez les pays ajoutés plus tard, dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Square Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Square Gateway est actuellement en mode SANDBOX. Aucun débit réel ne sera effectué. lorsque le mode sandbox est activé. Elle vous avertit lorsque Square est activé mais que l'Application ID, l'Access Token ou le Location ID du mode sélectionné est manquant (le mode de paiement est alors masqué sur la page de paiement), lorsque Square ne peut pas traiter la devise par défaut de votre boutique, et lorsque la devise de votre site Square diffère de celle-ci.

À l'enregistrement, le module vérifie auprès de Square les identifiants du mode sélectionné. Les réglages sont enregistrés dans tous les cas. Un avertissement s'affiche si Square rejette l'Access Token, si le Location ID est introuvable pour ce jeton, si les identifiants n'ont pas pu être vérifiés, ou si la devise du site diffère de la devise de la boutique. Square ne peut débiter que dans la devise du site : le module mémorise la devise du site vérifié et masque le mode de paiement pour les paniers dans toute autre devise. Il avertit également si un Application ID sandbox est utilisé en mode live, ou inversement.

Square

Enable/Disable : Enable Square Payment Gateway active ou désactive le mode de paiement. Par défaut : off.

Title : le titre du mode de paiement que le client voit lors du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit / debit card. Obligatoire.

Description : la description du mode de paiement que le client voit lors du paiement. Par défaut : Pay securely with your credit or debit card via Square. En mode sandbox, (SANDBOX MODE) est ajouté.

Compte Square

Ouvrez le Square Developer Dashboard (la section contient un lien), choisissez votre application et copiez l'Application ID et l'Access token depuis la page Credentials (Sandbox et Production ont des valeurs distinctes), ainsi que le Location ID depuis la page Locations. La devise du site doit correspondre à la devise de votre boutique. La page n'affiche que les champs d'identifiants du mode sélectionné : les champs sandbox tant que Sandbox Mode est activé, les champs live lorsqu'il est désactivé. Les deux jeux restent enregistrés.

Sandbox Mode : les paiements sont envoyés au sandbox de Square et aucun argent réel n'est débité. Utilisez les cartes de test de Square. Par défaut : on.

Sandbox Application ID : votre Application ID Square de sandbox (commence par sandbox-sq0idb-).

Sandbox Access Token : votre Access Token Square de sandbox.

Sandbox Location ID : votre Location ID Square de sandbox.

Live Application ID : votre Application ID Square de production (commence par sq0idp-).

Live Access Token : votre Access Token Square de production.

Live Location ID : votre Location ID Square de production.

Les access tokens enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Enregistré — laissez vide pour le conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved secrets : cochez un access token et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Avancé

Debug log : les erreurs et avertissements sont toujours consignés. Activez-le pour consigner aussi chaque requête et réponse, sans données de carte ni clés, dans logs/wc_sqg_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Par défaut : off.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : si cette option est activée, la désinstallation du module supprime les réglages de la passerelle et les fichiers journaux. Les paiements et remboursements Square des commandes ainsi que le statut de commande Square payment on hold sont toujours conservés. Par défaut : off.

Page de paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit / debit card) et saisit sa carte dans le formulaire Square affiché sous la description. Lorsque le client passe commande, la carte est tokenisée dans le navigateur avec vérification de l'acheteur (3-D Secure / SCA) : le total du panier, la devise et l'adresse de facturation sont transmis à Square, et la banque du client peut demander une confirmation. Votre boutique ne reçoit qu'un jeton à usage unique.

Le module débite ensuite le jeton via l'API Square Payments pour le total du panier dans la devise du panier, avec l'ID du panier comme référence, une note Cart # indiquant le numéro de panier et le nom de votre boutique, ainsi que l'adresse e-mail du client. Le paiement est capturé immédiatement. La commande n'est marquée payée qu'après confirmation par Square : la réponse de Square doit indiquer un paiement COMPLETED d'un montant exactement égal au total du panier, dans la même devise, avec le même ID de panier et le même site. La commande est alors créée avec Payment accepted, et le client voit la page de confirmation de commande standard avec Votre paiement par carte a bien été reçu. et un lien vers le reçu Square. Si le paiement n'est pas COMPLETED ou si une valeur diffère, la commande est créée en Square payment on hold et la page affiche Votre paiement par carte a bien été reçu et est en cours de vérification. Nous mettrons votre commande à jour dès la fin de la vérification.

Une seule tentative de paiement par panier s'exécute à la fois. Si le client clique deux fois ou paie dans deux onglets, la seconde tentative affiche Cette commande est déjà en cours de paiement. Veuillez patienter un instant et vérifier votre e-mail avant de réessayer. Les requêtes sont idempotentes : le même panier, le même jeton de carte et le même montant ne créent jamais un second paiement, et un panier qui a déjà une commande n'est jamais débité à nouveau.

Si Square ne répond pas (problème réseau, délai dépassé, erreur serveur), la requête est relancée une fois avec la même clé d'idempotence. Si la réponse manque toujours, le module recherche immédiatement le paiement de ce panier chez Square. S'il le trouve, la commande est créée avec ce paiement. Si aucun paiement n'est trouvé, le client reste sur la page de paiement avec Nous n'avons pas pu obtenir de confirmation de la part du prestataire de paiement. Veuillez patienter une minute et réessayer — si votre carte a déjà été débitée, le paiement sera reconnu et vous ne serez pas débité deux fois. La tentative suivante recherche d'abord à nouveau le paiement précédent. Si Square ne peut pas non plus être joint pour cette recherche, la commande est créée en Square payment on hold sans paiement, avec une note indiquant que la carte a peut-être été débitée, et la page de confirmation affiche Nous n'avons pas pu obtenir de confirmation de votre paiement par carte auprès de Square. Veuillez vérifier votre e-mail et le relevé de votre carte avant de payer à nouveau, ou contactez-nous.

Lorsque la banque refuse la carte, aucune commande n'est créée et le client reste sur la page de paiement avec un bref message selon le code d'erreur de Square, par exemple Votre carte a été refusée. Veuillez utiliser une autre carte ou un autre mode de paiement., Le code de sécurité de la carte (CVV) est incorrect. Veuillez le vérifier et réessayer. ou Votre banque exige une vérification supplémentaire (3-D Secure). Veuillez saisir à nouveau votre carte et effectuer la vérification. Le panier est conservé, et le client peut réessayer avec une autre carte. La raison technique est consignée dans le journal.

Le module n'accepte que les paiements par carte, capturés immédiatement. Il ne gère ni cartes enregistrées ni profils clients, ni abonnements, ni Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ou cartes cadeaux Square, ni paiements en autorisation seule, ni webhooks Square, ni synchronisation des produits ou des stocks avec Square. Les litiges sont gérés dans le Square Dashboard.

Commandes et remboursements

Statuts de commande

No order yet : la carte a été refusée, ou la réponse de Square s'est perdue et aucun paiement n'a été trouvé. Seul le panier existe.

Payment accepted : Square a confirmé un paiement COMPLETED du total du panier. Le paiement est enregistré avec l'ID de paiement Square comme ID de transaction, et une note indique l'ID de paiement, la marque de la carte avec les 4 derniers chiffres et le mode (sandbox ou live).

Square payment on hold : Square a répondu par un paiement qui n'est pas COMPLETED (par exemple APPROVED), ou par un montant, une devise, une référence ou un site différents. La note Le paiement Square doit être vérifié indique l'ID de paiement, le statut et les montants. Un paiement COMPLETED est enregistré sur la commande avec le montant débité par Square. Ce statut est aussi utilisé lorsque le panier a changé pendant le paiement, et lorsque la réponse de Square s'est perdue et n'a pas pu être vérifiée (aucun paiement n'est alors enregistré). Vérifiez le paiement dans le Square Dashboard avant l'expédition.

Refunded : le paiement a été intégralement remboursé via le module.

Si un second paiement arrive pour un panier qui a déjà une commande, la commande n'est pas modifiée. Une note vous demande de le vérifier et de rembourser le doublon dans le Square Dashboard.

Bloc Square

La page de commande affiche un bloc Square avec l'ID de paiement Square (lié au paiement dans le Square Dashboard), le statut Square, la marque de la carte et les 4 derniers chiffres, les montants Paid / order / refunded, l'environnement et le site, un lien vers le reçu Square, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les Square notes de la commande. Les numéros de carte ne sont jamais stockés.

Remboursements

Dans le bloc Square, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Square. Confirmez la question Rembourser ce montant via Square ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont effectués dans le montant et la devise débités par Square : après un écart de montant, vous pouvez donc rembourser jusqu'au montant réellement payé par le client, et non le total de la commande. Le remboursement est envoyé à l'environnement (sandbox ou production) et au site où le paiement a été effectué ; l'Access Token de ce mode doit donc être renseigné. Les demandes de remboursement sont idempotentes et sont relancées une fois si Square ne répond pas. Un remboursement accepté par Square (statut PENDING ou COMPLETED) est ajouté à l'historique des remboursements et aux notes, avec l'ID de remboursement Square. Si Square le rejette, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

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 Square. Square finalise les remboursements de son côté : un remboursement que Square rejette plus tard n'est pas signalé, et les remboursements effectués dans le Square Dashboard n'apparaissent pas dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Square Gateway est le premier bloc de Modules > Module Manager > VibeFox Square Gateway > 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-square 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 : 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-le dans votre compte vibefox.net.

Sans clé active, Square n'est pas affiché aux 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. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le mode de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais vous ne pouvez pas le tester sur la page de paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les commandes payées restent payées, 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 suivant 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

Square n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé et que l'Application ID, l'Access Token et le Location ID du mode actuel sont renseignés. Vérifiez que la devise du panier est USD, CAD, AUD, JPY, GBP ou EUR et qu'elle correspond à la devise de votre site Square. La page de réglages affiche un avertissement pour chacun de ces problèmes. 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 formulaire de carte ne se charge pas : le client voit Le formulaire de carte n'a pas pu être chargé. Veuillez recharger la page ou choisir un autre mode de paiement. Vérifiez que l'Application ID et le Location ID appartiennent au mode sélectionné (les ID sandbox commencent par sandbox-). Si le client clique trop tôt, Le formulaire de carte est encore en cours de chargement. Veuillez patienter un instant et réessayer. s'affiche.

Le mode de paiement a disparu après l'enregistrement : la devise du site Square diffère de la devise du panier. Saisissez le Location ID d'un site Square dans la devise de votre boutique et enregistrez à nouveau : le mode est de nouveau affiché après une vérification réussie.

Square a rejeté l'Access Token du mode sélectionné : le jeton appartient à l'autre mode ou est incorrect. Copiez-le à nouveau depuis la page Credentials de votre application et vérifiez Sandbox Mode.

Le Location ID est introuvable pour cet Access Token : copiez le Location ID depuis la page Locations de la même application et du même mode.

Le client a vu Nous n'avons pas pu obtenir de confirmation de la part du prestataire de paiement : Square n'a pas répondu et aucun paiement n'a encore été trouvé. Vérifiez les paiements de ce site dans le Square Dashboard (référence = ID du panier). Si le client réessaie, le module recherche d'abord le paiement précédent et crée la commande avec lui au lieu de débiter à nouveau.

Le client a vu Votre paiement a bien été reçu, mais la commande n'a pas pu être finalisée automatiquement : la carte a été débitée, mais PrestaShop n'a pas pu créer la commande (par exemple parce que le module était désactivé à ce moment-là). Consultez le journal, puis créez la commande manuellement ou remboursez le paiement dans le Square Dashboard.

La commande est en Square payment on hold : lisez les notes du bloc Square (voir Statuts de commande). Vérifiez le paiement dans le Square Dashboard, puis préparez la commande ou remboursez le paiement.

Le remboursement échoue avec un message sur le mode : le paiement a été effectué en mode sandbox ou live, et l'Access Token de ce mode n'est pas renseigné. Saisissez-le et réessayez.

Autres erreurs : activez Debug log et consultez le champ Log sur la page du module.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Square Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages de la passerelle et les fichiers journaux sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une future réinstallation. Les paiements et remboursements Square des commandes ainsi que le statut de commande Square 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, leurs ID de paiement Square et leurs ID de transaction.

Square est une marque commerciale de son propriétaire respectif. Ce module n'est ni affilié à Square ni approuvé par Square.