Ce dont vous avez besoin
| Champ | Ce qu'il fait |
|---|---|
| Access token | Nous permet d'appeler Square pour créer le lien de paiement. Secret. |
| Webhook signature key | Confirme qu'un webhook vient vraiment de Square. Secrète. |
| Location ID | L'emplacement Square qui reçoit le paiement. Définit la devise. |
| URL de réussite / URL d'annulation | Où l'acheteur atterrit après avoir payé ou renoncé. |
Pourquoi nous demandons chaque champ
Access token
Autorise la création du lien de paiement, pour que le débit passe par votre compte.
Webhook signature key
Prouve qu'un webhook entrant provient bien de Square, pour que personne ne puisse falsifier un événement « payé ». C'est une valeur distincte de l'access token.
Location ID
Indique à Square quel emplacement reçoit l'argent, et définit la devise du paiement. Pas secret.
URL de réussite et d'annulation
Réglages simples : où l'acheteur atterrit après avoir payé ou renoncé. Pas secret.
Configuration
- Ouvrez le tableau de bord développeur Square
Connectez-vous sur developer.squareup.com. Chaque application a ses propres identifiants, et un Sandbox gratuit est créé à côté pour les tests. Ce guide parcourt le Sandbox ; le flux Live est identique, il suffit de basculer le bouton Sandbox / Production et d'utiliser vos identifiants de production. Pour créer une nouvelle application, cliquez sur la tuile + dans l'écran Applications.
Square Developer → Applications - Nommez votre application
Donnez à l'application un nom que vous reconnaîtrez (par exemple « Coin Moebius »), puis cliquez sur Next.
Square → Name your application - Copiez votre access token
Ouvrez l'application et allez dans Credentials. Vérifiez que le bouton Sandbox / Production en haut correspond à l'environnement que vous configurez. Cliquez sur l'icône de copie à côté de l'Access token et mettez-le de côté.
Square → Credentials L'access token est secret, traitez-le comme un mot de passe. Sandbox et Production ont des jetons distincts, ne les mélangez pas.
- Copiez votre Location ID
Dans le menu de gauche, ouvrez Locations. Copiez le Location ID de l'emplacement qui doit recevoir les paiements. Il définit la devise du paiement, choisissez donc celui dont vous souhaitez utiliser la devise.
Square → Locations - Ouvrez Webhooks → Subscriptions
Square appelle un endpoint de webhook une « subscription ». Dans le menu de gauche, développez Webhooks, ouvrez Subscriptions et cliquez sur Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Ajoutez la subscription et sélectionnez les événements
Donnez-lui un nom (par exemple « coin-moebius »). Dans Notification URL, collez l'adresse webhook Square de votre projet (ci-dessous). Ensuite, sous Events, recherchez et cochez les événements que Coin Moebius écoute, puis cliquez sur Save.
- Paiements uniques : payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Abonnements (uniquement si vous en vendez) : subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Si vous ne facturez pas de manière récurrente, ignorez-les.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription Votre identifiant de projet se trouve sous le nom du projet dans le tableau de bord Coin Moebius ; insérez-le dans l'adresse ci-dessus. Les événements supplémentaires sont inoffensifs, nous ignorons tout ce que nous n'utilisons pas. La carte du fournisseur connecté (dernière étape) affiche la même URL pour référence.
- Ouvrez la subscription que vous venez de créer
Square enregistre la subscription et la liste sous Webhooks avec le statut Enabled. Cliquez sur son nom pour ouvrir le panneau de détails où se trouve la clé de signature.
Square → Webhooks → votre subscription (Enabled) - Copiez la Signature key
Dans le panneau Properties de la subscription, cliquez sur l'icône de copie à côté de Signature key. C'est la valeur que Coin Moebius utilise pour confirmer que chaque webhook provient bien de Square. Elle n'existe qu'une fois la subscription créée, d'où l'importance d'avoir configuré le webhook avant l'étape de connexion.
Square → votre subscription → Signature key - Dans Coin Moebius : Add provider → Square
Dans votre projet, ouvrez l'onglet Providers, cliquez sur Add provider, choisissez Connect a service et sélectionnez Square. Définissez votre URL de réussite et votre URL d'annulation. Dans l'onglet Live, collez votre Access token, votre Webhook signature key et votre Location ID, puis cliquez sur Save. Vous configurez d'abord avec des identifiants sandbox ? Collez-les dans l'onglet Test à la place, puis ajoutez les identifiants live plus tard depuis Modifier.
Coin Moebius → Add provider → Square - Vous êtes connecté
Square apparaît désormais dans votre onglet Providers avec la date de connexion. La carte affiche la même URL de webhook que vous avez collée dans Square, ainsi que Modifier et Déconnecter. Utilisez le bouton Test mode pour faire passer une commande sandbox de bout en bout avant de passer en live.
Coin Moebius → Providers → Square (connecté) Les cartes sandbox ne débitent jamais une vraie carte. Utilisez la carte 4111 1111 1111 1111, CVV 111, n'importe quelle date d'expiration future, n'importe quel code postal valide (par exemple 94103).
Après la connexion
Faites un paiement de test avant de passer en live :
- Créez un produit et réglez son Environnement sur Testing. Cela fait tourner le produit sur vos identifiants sandbox, pour que vous puissiez passer une commande complète sans déplacer d'argent. (Si vous avez sauté le jeu sandbox, un produit Testing retombe sur le live, donc ajoutez-le d'abord.)
- Placez le bouton d'achat sur une page (un fichier HTML local convient) pointé vers votre projet.
- Finalisez le paiement avec la carte de test sandbox ci-dessus.
- Ouvrez l'onglet Transactions. Une nouvelle ligne apparaît, étiquetée Testing. Quand son statut atteint succeeded, vos identifiants et votre webhook fonctionnent tous deux de bout en bout.
Basculez l'Environnement du produit sur Live quand vous êtes prêt pour de vrais paiements.
Dépannage
Commencez par Vérifier. Dans le tableau de bord, cliquez sur Vérifier (ou Vérifier les identifiants de test) pour contrôler votre access token et votre emplacement.
La vérification échoue.
Recopiez l'access token et le Location ID. Production et Sandbox ont des jetons distincts, donc ne les mélangez pas.
La vérification de signature échoue, ou la commande reste en attente.
Square signe sur l'URL de notification exacte plus le corps. L'URL que vous enregistrez dans Square doit correspondre à votre URL de webhook caractère pour caractère, sans barre oblique finale ni paramètre de requête supplémentaire. Puis recopiez la signature key depuis ce même endpoint.
Confirmez de bout en bout.
Square Developer Console → Webhooks → votre subscription → Send Test Event, puis observez la commande se mettre à jour.
Bon à savoir
La devise suit l'emplacement. Le paiement débite dans la devise de l'emplacement dont vous fournissez l'id.
Rotation des secrets. Faites tourner l'access token ou la signature key à tout moment, puis collez la nouvelle valeur. Les champs secrets restent vides à la modification.
Des questions ? Join our Discord