Connectez SumUp à WebBlocks Commerce

Ce guide permet d'obtenir un premier paiement sandbox SumUp fonctionnant sans facturer d'argent réel. C'est écrit pour les propriétaires de magasins et les exploitants de sites. Vous n'avez pas besoin de créer un formulaire de paiement : les clients saisissent les détails de leur carte sur la page de paiement hébergée de SumUp.

Ce dont vous avez besoin

  • an installé et activé Plugin WebBlocks Commerce
  • accès au tableau de bord SumUp
  • permission de gérer les paramètres Commerce, ou un administrateur d'hébergement qui peut ajouter des remplacements de variables d'environnement
  • a adresse HTTPS publique pour la boutique
  • environ dix minutes pour la configuration initiale du bac à sable

Les paiements Sandbox sont des simulations. Ils ne déplacent pas d’argent réel.

Avant de commencer

WebBlocks Commerce accepte les informations de paiement via son formulaire protégé de paramètres Commerce. Le les valeurs sont chiffrées au repos, les champs sont en écriture seule et les secrets enregistrés ne sont plus jamais affichés. Ils ne doivent jamais être saisis dans un champ de page, de bloc, de produit ou de paramètres publics du CMS.

Hosting-les variables d'environnement gérées restent disponibles en tant que remplacements facultatifs. Ne pas envoyer l'API saisissez un e-mail normal, un chat, une capture d'écran ou un ticket d'assistance. Saisissez-le directement dans le champ protégé formulaire ou utilisez le gestionnaire secret de la plateforme d'hébergement ou un autre canal sécurisé agréé.

Étape 1 — Créer un marchand SumUp Sandbox

  1. Connectez-vous à SumUp Dashboard.
  2. Ouvrir Paramètres du développeur.
  3. Ouvrez l'onglet Sandboxes.
  4. Créez un marchand sandbox s'il n'en existe pas.
  5. Utilisez le sélecteur de compte pour sélectionner le marchand sandbox.

Le compte sélectionné doit être clairement marqué comme bac à sable. N'utilisez jamais de marchand en direct pour cela premier test.

Si votre compte SumUp ne dispose pas de paramètres de développeur ni d'option sandbox, créez un compte de développeur à partir de le lien dans le guide officiel de test de paiement en ligne de SumUp.

Étape 2 — Copiez le code marchand Sandbox

Une fois le marchand sandbox sélectionné, examinez la zone supérieure gauche du tableau de bord SumUp. Spectacles SumUp le nom du compte et Merchant ID. WebBlocks Commerce appelle cette valeur le code marchand. Il ressemble normalement à MXXXXXXX.

Copiez cette valeur pour l'étape 4. N'utilisez pas l'ID marchand de votre compte réel.

Étape 3 : Créer une clé API de test

Gardez le marchand sandbox sélectionné, puis :

  1. Développez votre profil et ouvrez Settings.
  2. Aller à Pour les développeurs → Boîte à outils.
  3. Ouvrir Clés API.
  4. Sélectionnez Créez et attribuez à la clé un nom reconnaissable, tel que WebBlocks Commerce sandbox.
  5. Copiez ou téléchargez la clé secrète lorsque SumUp l'affiche.

N'utilisez pas la clé publique SumUp. WebBlocks Commerce a besoin de la clé API secrète côté serveur. Un la clé secrète de test commence normalement par sk_test_. SumUp n'affiche plus le secret complet, donc stockez-le immédiatement dans un gestionnaire de secrets agréé.

L'intégration directe actuelle concerne un compte marchand contrôlé par le propriétaire du site. OAuth est non requis pour cette configuration.

Étape 4 — Configurer WebBlocks Commerce

  1. Connectez-vous à l'administrateur CMS.
  2. Ouvrir Commerce → Paramètres commerciaux.
  3. Sélectionnez la passerelle SumUp et le mode Sandbox.
  4. Entrez la clé API secrète et l'ID marchand, puis enregistrez.

Les champs d'informations d'identification sont en écriture seule. Laisser un champ vide préserve la valeur enregistrée ; utiliser le contrôle d'effacement explicite uniquement lorsque vous avez l'intention de le supprimer.

Les déploiements gérés par l'hébergement peuvent à la place ajouter ces remplacements d'environnement facultatifs :

Ajoutez ces valeurs aux paramètres de variable d'environnement ou secrets de la plateforme d'hébergement :

WEBBLOCKS_COMMERCE_GATEWAY=sumup
WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY=EUR
WEBBLOCKS_COMMERCE_SUMUP_MODE=sandbox
WEBBLOCKS_COMMERCE_SUMUP_API_KEY=replace-with-your-sk_test-key
WEBBLOCKS_COMMERCE_SUMUP_MERCHANT_CODE=replace-with-your-sandbox-merchant-id

Les valeurs d'environnement sont prioritaires et rendent les contrôles de formulaire correspondants en lecture seule. Si le l'installation utilise un fichier Laravel .env, ajoutez-y les valeurs. Puis effacez le cache configuration : 

php artisan config:clear

Si votre déploiement met normalement en cache la configuration, reconstruisez ce cache à l'aide de son déploiement normal. procédure. Redémarrez les travailleurs PHP de longue durée lorsque votre plate-forme d'hébergement l'exige.

L'étiquette de mode sandbox aide les opérateurs à voir quel environnement est prévu. SumUp utilise une seule API nom d'hôte, la clé API et le code marchand doivent donc eux-mêmes appartenir au compte sandbox.

Étape 5 — Confirmer que Commerce est prêt

  1. Connectez-vous à l'administrateur du CMS.
  2. Ouvrez Commerce → Paramètres commerciaux, ou visitez /webadmin/plugins/webblocks-commerce/settings.
  3. Confirmez tous les éléments suivants :
    • passerelle active : sumup
    • devise par défaut : EUR (ou une autre devise prise en charge par SumUp)
    • Mode SumUp : sandbox
    • Clé API : configurée
    • code commerçant : configuré
    • paiement : prêt
    • schéma du plugin : prêt

L'écran des paramètres indique délibérément uniquement « configuré » ou « manquant ». Il n'affiche jamais l'API clé elle-même, y compris après une sauvegarde réussie.

Si le schéma n'est pas prêt, ouvrez System → Plugins → WebBlocks Commerce et exécutez la configuration du plugin ou migrations en premier.

Étape 6 — Créer un produit de test

  1. Ouvrir Commerce → Produits.
  2. Créer ou modifier un produit.
  3. Définissez un titre, un slug, un prix, une devise et une classe de taxe.
  4. Choisissez EUR pour le premier test SumUp, sauf si le marchand sandbox utilise une autre option affichée dans le sélecteur de devise.
  5. Définir l'état du produit sur Active.
  6. Enregistrez le produit.

A Le brouillon ou le produit archivé ne peut pas être extrait. Si le stock suivi est activé, assurez-vous au moins une unité est disponible.

Étape 7 — Ajouter le bloc de commerce natif

  1. Ouvrez la page CMS souhaitée dans le générateur de pages.
  2. Ajoutez un bloc Commerce Buy Button à un emplacement de page normal.
  3. Sélectionnez le produit actif.
  4. Choisissez les options d'étiquette du bouton, d'alignement et d'affichage des prix.
  5. Prévisualisez et publiez la page via le flux de travail CMS normal.

N'utilisez pas de bloc Trusted HTML et ne collez pas d'URL de paiement SumUp dans le contenu. Une URL de paiement est créé pour chaque commande et expire après environ 30 minutes.

Étape 8 — Effectuer un paiement Sandbox réussi

  1. Ouvrez la page du produit public ou la page contenant le bouton Commerce.
  2. Ajouter le produit au panier.
  3. Vérifiez la quantité, la TVA, la devise et le montant final.
  4. Sélectionner Continuer pour sécuriser le paiement.
  5. Sur la page hébergée par SumUp, utilisez cette carte de test sandbox officielle :
Card number: 4200 0000 0000 0091
Expiry date: any future date, for example 12/30
CVV: any three digits, for example 123
Cardholder: any name
  1. Terminez le paiement et utilisez l'action de retour pour revenir à la boutique.
  2. Dans l'administrateur CMS, ouvrez Commerce → Commandes.
  3. Confirmez que la commande passe à paid et la tentative de paiement à succeeded.

La page de retour du navigateur ne constitue pas une preuve de paiement. La commande n'est payée qu'après WebBlocks Commerce reçoit la notification SumUp, récupère le paiement de SumUp et vérifie le commerçant, référence, montant, devise, statut final et transaction réussie.

Aucune configuration manuelle du webhook SumUp n'est nécessaire

Pour cette intégration, ne créez ni ne collez pas d'URL de webhook dans le tableau de bord SumUp. WebBlocks Commerce envoie automatiquement ce rappel en tant que paiement return_url:

https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup

La boutique publique doit utiliser HTTPS et SumUp doit pouvoir accéder à cette URL. Un pare-feu, une maintenance la page, l'authentification HTTP ou la règle de proxy ne doivent pas bloquer la requête POST de SumUp.

Test de défaillance facultatif

Le bac à sable de SumUp utilise certains totaux pour simuler un paiement refusé. Pour tester le chemin de l'échec, créez un produit temporaire dont le total final de paiement est exactement 11.00 EUR, puis utilisez un bac à sable carte de test. Confirmez que la commande n'est pas marquée comme payée et que le stock réservé est libéré après le l'échec est traité.

Ne modifiez pas le prix réel d'un produit pour ce test.

Passer aux paiements en direct

Basculez uniquement après la réussite du flux sandbox complet :

  1. Sélectionnez le compte marchand réel dans SumUp Dashboard.
  2. Terminez toute vérification commerciale et configuration de paiement requise par SumUp.
  3. Copiez l'ID du marchand en direct.
  4. Créez une clé API secrète en direct distincte. Une clé active commence normalement par sk_live_.
  5. Remplacez les valeurs sandbox enregistrées dans Commerce Settings, passez en mode Live et enregistrez. Les déploiements gérés par l'hébergement peuvent remplacer les remplacements de leur environnement :
WEBBLOCKS_COMMERCE_GATEWAY=sumup
WEBBLOCKS_COMMERCE_SUMUP_MODE=live
WEBBLOCKS_COMMERCE_SUMUP_API_KEY=replace-with-your-sk_live-key
WEBBLOCKS_COMMERCE_SUMUP_MERCHANT_CODE=replace-with-your-live-merchant-id
  1. Si des remplacements d'environnement sont utilisés, actualisez la configuration de l'application à l'aide de la procédure de déploiement normale.
  2. Revérifier Paramètres de commerce.
  3. Effectuez un achat réel acceptable de faible valeur et vérifiez la commande et le paiement dans les deux systèmes.

Ne combinez jamais une clé de test avec un identifiant de marchand actif et ne réutilisez jamais la clé sandbox en production.

Dépannage

Les paramètres commerciaux indiquent « Clé API manquante »

  • Entrez à nouveau la clé API dans le champ en écriture seule et enregistrez.
  • Si un remplacement d'environnement s'affiche, vérifiez son orthographe et confirmez que le processus de déploiement ou PHP a été actualisé.
  • Si la configuration est mise en cache, effacez-la et reconstruisez-la à l'aide de la procédure de déploiement normale.

Commerce Settings indique prêt, mais le paiement échoue

  • Confirmez que la clé et l'ID marchand appartiennent au même compte sandbox.
  • Confirmez que la clé est la clé API secrète et non la clé publique.
  • Confirmez que le produit est actif, a un prix positif et dispose d'un stock disponible.
  • Confirmez que la devise du produit correspond à la devise prise en charge par le commerçant.

Le client a payé, mais la commande reste en attente

  • Confirmer que https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup est accessible publiquement par POST sur HTTPS.
  • Vérifiez qu'un pare-feu, une page de maintenance ou un mot de passe HTTP ne bloque pas le rappel.
  • Confirmez que la clé API peut toujours récupérer le paiement et appartient au marchand configuré.
  • Confirm SumUp signale le paiement comme PAID avec une transaction réussie.

La caisse hébergée indique expirée ou introuvable

Recommencez le paiement à partir du panier. Les sessions de paiement hébergées expirent après environ 30 minutes. Ne ajouter ou réutiliser une ancienne URL de paiement hébergée dans vos favoris.

Règles de sécurité

  • Ne placez jamais la clé API dans un bloc CMS, une page, un produit, un script de navigateur, un référentiel, une capture d'écran ou journal de support.
  • Ne collez jamais une vraie clé API dans le chat.
  • Gardez le bac à sable et les informations d'identification en direct séparés.
  • Révoquer et remplacer immédiatement la clé si elle a pu être exposée.
  • Traitez l'état de la commande du CMS (et non l'écran de réussite du navigateur) comme signal d'exécution.

Pour l'architecture, la vérification des webhooks, les états de commande et le dépannage avancé, continuez avec le Guide de l'opérateur WebBlocks Commerce.

ORéférences officielles SumUp :