VibeFox Square for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : la devise de votre site Square : USD, CAD, AUD, JPY, GBP ou EUR. Pour les autres devises, le moyen 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 : l'extension obtient 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_square_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

5. Laissez Sandbox Mode activé et saisissez l'Application ID, l'Access Token et le Location ID du sandbox (voir Configuration). Enregistrez : l'extension vérifie les identifiants auprès de Square.

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

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Square. Au-dessus des champs, la page affiche Square Gateway est actuellement en mode SANDBOX. Aucun paiement réel ne sera effectué. tant que 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 moyen de paiement est alors masqué sur la page de paiement), ainsi que lorsque Square ne peut pas traiter la devise de la boutique. Dans la liste des moyens de paiement, Square affiche un badge « Test mode » tant que le mode sandbox est activé.

À l'enregistrement, l'extension vérifie les identifiants du mode sélectionné auprès de Square. Vous voyez une erreur 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 : l'extension mémorise la devise du site vérifié et masque le moyen de paiement sur la page de paiement pour toute autre devise, et la page de réglages continue d'afficher l'avertissement. Elle vous avertit également si un Application ID sandbox est utilisé en mode réel, ou inversement.

General

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

Title : le titre du moyen de paiement que le client voit lors du paiement. Par défaut : Credit / debit card.

Description : la description du moyen de paiement que le client voit lors du paiement. Par défaut : Pay securely with your credit or debit card via Square.

Square account

Ouvrez le Square Developer Dashboard, 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 production lorsqu'il est désactivé.

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

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

Sandbox Access Token : votre Access Token Square sandbox.

Sandbox Location ID : votre Location ID Square 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.

Advanced

Debug log : Log API requests and responses. Les erreurs sont toujours consignées. Activez cette option pour consigner aussi chaque requête, sans données de carte ni clés. Les journaux se trouvent dans WooCommerce > Status > Logs, source wcp_square_gateway. Par défaut : off.

Delete data on uninstall : Remove all plugin data when the plugin is deleted. Supprime les réglages de la passerelle et les fichiers journaux lorsque vous supprimez l'extension. Les données de paiement des commandes sont conservées. Par défaut : off.

Paiement

Le client choisit le moyen de paiement (par défaut Credit / debit card) et saisit sa carte dans le formulaire Square affiché sous la description. En mode sandbox, la page de paiement affiche un avertissement sandbox. Lorsque le client clique sur Place order, la carte est tokenisée dans le navigateur avec vérification de l'acheteur (3-D Secure / SCA) : le montant, la devise et le contact de facturation sont transmis à Square, et la banque du client peut demander une confirmation. Votre serveur ne reçoit qu'un jeton à usage unique.

L'extension débite ensuite le jeton via l'API Square Payments pour le total de la commande dans la devise de la commande, avec l'ID de commande comme référence, une note Order # avec le numéro de commande et le nom de votre site, ainsi que l'e-mail de facturation. Le paiement est capturé immédiatement. La commande n'est marquée payée qu'après confirmation de Square : la réponse de Square doit indiquer un paiement COMPLETED pour exactement le total de la commande, la devise, l'ID de commande et le site. Le client est ensuite redirigé vers la page de confirmation de commande. Si le paiement n'est pas COMPLETED ou si une valeur diffère, la commande est mise en attente avec une note, et le client est tout de même redirigé vers la page de confirmation de commande.

Une seule tentative de paiement par commande 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 vos e-mails avant de réessayer. Les requêtes sont idempotentes : la même commande, le même jeton et le même montant ne créent jamais un second paiement.

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. S'il n'y a toujours pas de réponse, le client voit 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 note de commande vous invite à consulter le Square Dashboard. Lors de la tentative suivante, l'extension recherche d'abord chez Square le paiement antérieur de cette commande et termine la commande avec celui-ci, au lieu de débiter à nouveau la carte.

Lorsque la banque refuse la carte, le client voit un court message selon le code d'erreur de Square, par exemple Votre carte a été refusée. Veuillez utiliser une autre carte ou un autre moyen 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 terminer la vérification. La raison technique est consignée dans les notes de commande et le journal. Le client peut réessayer avec une autre carte, y compris plus tard depuis la page Pay for order.

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

L'extension n'accepte que les paiements par carte, capturés immédiatement. Elle ne gère ni cartes enregistrées ni profils clients, ni WooCommerce Subscriptions ou précommandes, 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 se gèrent dans le Square Dashboard.

Commandes et remboursements

Statuts de commande

Pending payment : la commande a été créée et n'a pas encore été payée, par exemple après une carte refusée ou une réponse perdue de Square.

Processing : Square a confirmé un paiement COMPLETED du total de la commande. C'est le statut WooCommerce standard après paiement (les commandes ne contenant que des produits virtuels téléchargeables passent à Terminée). La note de commande affiche l'ID de paiement Square, la marque de la carte avec les 4 derniers chiffres et le mode (sandbox ou production). L'ID de transaction est l'ID de paiement Square ; sur l'écran de commande, il renvoie au paiement dans le Square Dashboard.

On hold : Square a répondu par un paiement qui n'est pas COMPLETED, ou dont le montant, la devise, la référence ou le site diffèrent. La note Square payment needs review affiche l'ID du paiement, le statut et les montants. Vérifiez la capture, le montant et la devise dans le Square Dashboard avant l'expédition.

L'extension enregistre sur la commande l'ID de paiement Square, la marque de la carte et les 4 derniers chiffres, l'environnement et le site. Les numéros de carte ne sont jamais stockés.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Credit / debit card (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé à l'environnement (sandbox ou production) et au site dans lesquels 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é aux notes de commande avec l'ID de remboursement Square. Si Square le rejette, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré.

Square finalise les remboursements de son côté. Un remboursement que Square rejette ultérieurement n'est pas signalé à WooCommerce, et les remboursements effectués dans le Square Dashboard n'apparaissent pas 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 > Square. 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, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau 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 seul 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, Square n'est pas affiché aux clients sur la page de paiement. Si un paiement est tout de même lancé, le client voit Ce moyen de paiement n'est pas disponible. Veuillez en choisir un autre. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les commandes payées restent payées, 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 à nouveau vérifié automatiquement en arrière-plan.

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 de la boutique (ou la devise de la commande sur la page Pay for order) est USD, CAD, AUD, JPY, GBP ou EUR et correspond à la devise de votre site Square. La page de réglages affiche un avertissement pour chacun de ces problèmes.

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 moyen de paiement. Vérifiez que l'Application ID et le Location ID correspondent au mode sélectionné (les ID sandbox commencent par sandbox-). Si le client clique trop tôt, s'affiche Le formulaire de carte est encore en cours de chargement. Veuillez patienter un instant et réessayer.

Les paiements sont refusés alors que la carte est valide : la devise du site doit être identique à la devise de la boutique. Enregistrez les réglages pour voir le résultat de la vérification des identifiants ; après une vérification réussie, le moyen de paiement est masqué pour les autres devises.

Square a rejeté l'Access Token du mode sélectionné : le jeton appartient à l'autre mode ou il 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. Lisez la note de commande et vérifiez les paiements de ce site dans le Square Dashboard (référence = ID de commande). Si le client réessaie, l'extension recherche d'abord le paiement antérieur et termine la commande avec lui, au lieu de débiter à nouveau.

La commande est On hold : lisez la note Square payment needs review. Le paiement n'était pas COMPLETED, ou son montant, sa devise ou son site différaient de la commande. Vérifiez-le dans le Square Dashboard, puis traitez la commande ou remboursez le paiement.

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

Autres erreurs : activez Debug log et consultez WooCommerce > Status > Logs, source wcp_square_gateway.

Le bloc de licence affiche une erreur : suivez le message affiché dans le 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 avec le dernier statut connu.

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 fichiers journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. 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. Cette extension n'est ni affiliée à Square ni approuvée par Square.