SumUp mit WebBlocks Commerce verbinden

Mit diesem Leitfaden erhalten Sie eine erste SumUp-Sandbox-Zahlung, die funktioniert, ohne echtes Geld zu verlangen. Es steht geschrieben für Ladenbesitzer und Seitenbetreiber. Sie müssen kein Zahlungsformular erstellen: Kunden geben es ein ihre Kartendetails auf der gehosteten Checkout-Seite von SumUp.

Was Sie brauchen

  • ein installiertes und aktiviertes WebBlocks Commerce-Plugin
  • Zugriff auf das SumUp-Dashboard
  • Berechtigung zum Verwalten der Commerce-Einstellungen oder ein Hosting-Administrator, der geschützt hinzufügen kann Umgebungsvariablenüberschreibungen
  • eine öffentliche HTTPS-Adresse für den Shop
  • etwa zehn Minuten für die Ersteinrichtung der Sandbox

Sandbox-Zahlungen sind Simulationen. Sie bewegen kein echtes Geld.

Bevor Sie beginnen

WebBlocks Commerce akzeptiert Zahlungsanmeldeinformationen über sein geschütztes Commerce-Einstellungsformular. Die Werte werden im Ruhezustand verschlüsselt, Felder sind schreibgeschützt und gespeicherte Geheimnisse werden nie wieder angezeigt. Sie dürfen niemals in ein CMS-Seiten-, Block-, Produkt- oder öffentliches Einstellungsfeld eingegeben werden.

Hosting-verwaltete Umgebungsvariablen bleiben als optionale Außerkraftsetzungen verfügbar. Senden Sie die API nicht Geben Sie eine normale E-Mail, einen Chat, einen Screenshot oder ein Support-Ticket ein. Geben Sie es direkt in das geschützte Feld ein Formular oder verwenden Sie den Secret Manager der Hosting-Plattform oder einen anderen zugelassenen sicheren Kanal.

Schritt 1 – Erstellen Sie einen SumUp Sandbox-Händler

  1. Anmelden bei SumUp Dashboard.
  2. Öffnen Sie die Entwicklereinstellungen.
  3. Öffnen Sie die Registerkarte Sandboxes.
  4. Erstellen Sie einen Sandbox-Händler, falls keiner vorhanden ist.
  5. Verwenden Sie den Kontowechsel, um den Sandbox-Händler auszuwählen.

Das ausgewählte Konto sollte deutlich als Sandbox gekennzeichnet sein. Nutzen Sie hierfür niemals einen Live-Händler Erster Test.

Wenn Ihr SumUp-Konto keine Entwicklereinstellungen oder Sandbox-Option hat, erstellen Sie ein Entwicklerkonto unter der Link im offiziellen Online-Zahlungstestleitfaden von SumUp.

Schritt 2 – Kopieren Sie den Sandbox-Händlercode

Sehen Sie sich bei ausgewähltem Sandbox-Händler den oberen linken Bereich des SumUp-Dashboards an. SumUp zeigt dort den Kontonamen und Merchant ID. WebBlocks Commerce nennt diesen Wert den Händlercode. Normalerweise sieht es ähnlich aus wie MXXXXXXX.

Kopieren Sie diesen Wert für Schritt 4. Verwenden Sie nicht die Händler-ID Ihres Live-Kontos.

Schritt 3 – Erstellen Sie einen Test-API-Schlüssel

Lassen Sie den Sandbox-Händler ausgewählt, dann:

  1. Erweitern Sie Ihr Profil und öffnen Sie Einstellungen.
  2. Gehen Sie zu Für Entwickler → Toolkit.
  3. Open API-Schlüssel.
  4. Wählen Sie Erstellen aus und geben Sie dem Schlüssel einen erkennbaren Namen, z WebBlocks Commerce sandbox.
  5. Kopieren oder laden Sie den geheimen Schlüssel herunter, wenn SumUp ihn anzeigt.

Verwenden Sie nicht den öffentlichen Schlüssel SumUp. WebBlocks Commerce benötigt den geheimen serverseitigen API-Schlüssel. A Der geheime Testschlüssel beginnt normalerweise mit sk_test_. SumUp verrät also nicht noch einmal das komplette Geheimnis Bewahren Sie es sofort in einem zugelassenen Secret Manager auf.

Die aktuelle direkte Integration gilt für ein Händlerkonto, das vom Websitebesitzer kontrolliert wird. OAuth ist Für dieses Setup nicht erforderlich.

Schritt 4 – Konfigurieren Sie WebBlocks Commerce

  1. Melden Sie sich beim CMS-Administrator an.
  2. Öffnen Sie Commerce → Commerce-Einstellungen.
  3. Wählen Sie Gateway SumUp und Modus Sandbox.
  4. Geben Sie den geheimen API-Schlüssel und die Händler-ID ein und speichern Sie.

Die Anmeldeinformationsfelder sind schreibgeschützt. Wenn Sie ein Feld leer lassen, bleibt der gespeicherte Wert erhalten. Benutze die explizite Löschkontrolle nur, wenn Sie beabsichtigen, sie zu entfernen.

Hosting-verwaltete Bereitstellungen können stattdessen diese optionalen Umgebungsüberschreibungen hinzufügen:

Fügen Sie diese Werte zu den Umgebungsvariablen- oder Geheimeinstellungen der Hosting-Plattform hinzu:

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

EUmgebungswerte haben Vorrang und machen die entsprechenden Formularsteuerelemente schreibgeschützt. Wenn die Wenn die Installation eine Laravel .env-Datei verwendet, fügen Sie dort die Werte hinzu. Anschließend den Cache löschen Konfiguration:

php artisan config:clear

Wenn Ihre Bereitstellung die Konfiguration normalerweise zwischenspeichert, erstellen Sie diesen Cache mit der normalen Bereitstellung neu Verfahren. Starten Sie lang laufende PHP-Worker neu, wenn Ihre Hosting-Plattform dies erfordert.

Die Modusbezeichnung sandbox hilft Bedienern zu erkennen, welche Umgebung vorgesehen ist. SumUp verwendet eine API Hostname, daher müssen der API-Schlüssel und der Händlercode selbst zum Sandbox-Konto gehören.

Schritt 5 – Bestätigen Sie, dass Commerce bereit ist

  1. Melden Sie sich beim CMS-Administrator an.
  2. Öffnen Sie Commerce → Commerce-Einstellungen, oder besuchen Sie /webadmin/plugins/webblocks-commerce/settings.
  3. Bestätigen Sie alle folgenden Punkte:
    • aktives Gateway: sumup
    • Standardwährung: EUR (oder eine andere von SumUp unterstützte Währung)
    • SumUp-Modus: sandbox
    • API-Schlüssel: konfiguriert
    • Händlercode: konfiguriert
    • Kaufabwicklung: bereit
    • plugin-Schema: ready

Auf dem Einstellungsbildschirm steht bewusst nur „konfiguriert“ oder „fehlt“. Die API wird nie angezeigt Schlüssel selbst, auch nach erfolgreichem Speichern.

Wenn das Schema nicht bereit ist, öffnen Sie System → Plugins → WebBlocks Commerce und führen Sie das Plugin-Setup aus oder Migrationen zuerst.

Schritt 6 – Erstellen Sie ein Testprodukt

  1. Öffnen Commerce → Produkte.
  2. Erstellen oder bearbeiten Sie ein Produkt.
  3. Legen Sie einen Titel, einen Artikel, einen Preis, eine Währung und eine Steuerklasse fest.
  4. Wählen Sie EUR für den ersten SumUp-Test, es sei denn, der Sandbox-Händler verwendet eine andere Option, die in der Währungsauswahl angezeigt wird.
  5. Setzen Sie den Produktstatus auf Active.
  6. Speichern Sie das Produkt.

A Entwurf oder archiviertes Produkt kann nicht ausgecheckt werden. Wenn die Nachverfolgung des Bestands aktiviert ist, stellen Sie zumindest sicher, dass dies der Fall ist Eine Einheit ist verfügbar.

Schritt 7 – Fügen Sie den Native Commerce-Block hinzu

  1. Öffnen Sie die gewünschte CMS-Seite im Page Builder.
  2. Fügen Sie einen Commerce Buy Button Block zu einem normalen Seitenslot hinzu.
  3. Wählen Sie das aktive Produkt aus.
  4. Wählen Sie die Schaltflächenbeschriftung, Ausrichtung und Preisanzeigeoptionen.
  5. Zeigen Sie eine Vorschau der Seite an und veröffentlichen Sie sie über den normalen CMS-Workflow.

Verwenden Sie keinen vertrauenswürdigen HTML-Block und fügen Sie keine SumUp-Checkout-URL in den Inhalt ein. Eine Checkout-URL wird für jede Bestellung erstellt und läuft nach ca. 30 Minuten ab.

Schritt 8 – Führen Sie eine erfolgreiche Sandbox-Zahlung durch

  1. Öffnen Sie die öffentliche Produktseite oder die Seite mit der Schaltfläche „Commerce“.
  2. Fügen Sie das Produkt dem Warenkorb hinzu.
  3. Überprüfen Sie die Menge, die Mehrwertsteuer, die Währung und den Endbetrag.
  4. Wählen Sie Weiter zur sicheren Zahlung.
  5. Verwenden Sie auf der von SumUp gehosteten Seite diese offizielle Sandbox-Testkarte:
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. Schließen Sie die Zahlung ab und nutzen Sie die Retourenaktion, um zum Shop zurückzukehren.
  2. Öffnen Sie im CMS-Administrator Commerce → Orders.
  3. Bestätigen Sie, dass sich die Bestellung in paid und der Zahlungsversuch in succeeded ändert.

Die Browser-Rückseite ist kein Zahlungsnachweis. Die Bestellung wird erst nach WebBlocks bezahlt Commerce empfängt die SumUp-Benachrichtigung, ruft den Checkout von SumUp ab und überprüft den Händler, Referenz, Betrag, Währung, Endstatus und erfolgreiche Transaktion.

Es ist keine manuelle Einrichtung des SumUp-Webhooks erforderlich

Für diese Integration dürfen Sie keine Webhook-URL im SumUp-Dashboard erstellen oder einfügen. WebBlocks Commerce sendet diesen Rückruf automatisch als Checkout return_url:

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

Der öffentliche Shop muss HTTPS verwenden und SumUp muss diese URL erreichen können. Eine Firewall, Wartung Seite, HTTP-Authentifizierung oder Proxy-Regel dürfen die POST-Anfrage von SumUp nicht blockieren.

Optionaler Fehlertest

SumUps Sandbox verwendet bestimmte Summen, um eine abgelehnte Zahlung zu simulieren. Um den Fehlerpfad zu testen, Erstellen Sie ein temporäres Produkt, dessen endgültige Kaufsumme genau 11.00 EUR beträgt, und verwenden Sie dann eine Sandbox Testkarte. Bestätigen Sie, dass die Bestellung nicht als bezahlt markiert ist und dass der reservierte Lagerbestand nach dem freigegeben wird Fehler wird verarbeitet.

Ändern Sie für diesen Test nicht den Preis eines echten Produkts.

Wechseln Sie zu Live Payments

Wechseln Sie erst, nachdem der vollständige Sandbox-Flow erfolgreich war:

  1. Wählen Sie das echte Händlerkonto im SumUp Dashboard aus.
  2. Schließen Sie alle von SumUp geforderten geschäftlichen Verifizierungs- und Auszahlungseinstellungen ab.
  3. Kopieren Sie die Live-Händler-ID.
  4. Erstellen Sie einen separaten Live-Secret-API-Schlüssel. Ein Live-Schlüssel beginnt normalerweise mit sk_live_.
  5. Ersetzen Sie die gespeicherten Sandbox-Werte in Commerce-Einstellungen, wechseln Sie den Modus zu Live und speichern Sie. Durch Hosting verwaltete Bereitstellungen können stattdessen ihre Umgebungsüberschreibungen ersetzen:
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. Wenn Umgebungsüberschreibungen verwendet werden, aktualisieren Sie die Anwendungskonfiguration mit dem normalen Bereitstellungsverfahren.
  2. Recheck Commerce-Einstellungen.
  3. Machen Sie einen akzeptablen, echten Kauf mit geringem Wert durch und überprüfen Sie die Bestellung und Auszahlung in beiden Systemen.

Kombinieren Sie niemals einen Testschlüssel mit einer Live-Händler-ID und verwenden Sie den Sandbox-Schlüssel niemals in der Produktion.

Fehlerbehebung

In den Commerce-Einstellungen steht „API-Schlüssel fehlt“

  • Geben Sie den API-Schlüssel erneut in das schreibgeschützte Feld ein und speichern Sie.
  • Wenn eine Umgebungsüberschreibung angezeigt wird, überprüfen Sie deren Schreibweise und bestätigen Sie, dass die Bereitstellung oder der PHP-Prozess aktualisiert wurde.
  • Wenn die Konfiguration zwischengespeichert ist, löschen Sie sie und erstellen Sie sie mit dem normalen Bereitstellungsverfahren neu.

In den Commerce-Einstellungen wird „Bereit“ angezeigt, aber der Checkout schlägt fehl

  • Bestätigen Sie, dass der Schlüssel und die Händler-ID zum selben Sandbox-Konto gehören.
  • Bestätigen Sie, dass es sich bei dem Schlüssel um den geheimen API-Schlüssel und nicht um den öffentlichen Schlüssel handelt.
  • Bestätigen Sie, dass das Produkt aktiv ist, einen positiven Preis hat und Lagerbestände verfügbar sind.
  • Bestätigen Sie, dass die Produktwährung mit der vom Händler unterstützten Währung übereinstimmt.

Der Kunde hat bezahlt, aber die Bestellung bleibt ausstehend

  • Bestätigen Sie, dass https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup öffentlich per POST erreichbar ist HTTPS.
  • Überprüfen Sie, ob eine Firewall, eine Wartungsseite oder ein HTTP-Passwort den Rückruf nicht blockiert.
  • Bestätigen Sie, dass der API-Schlüssel weiterhin beim Bezahlvorgang abgerufen werden kann und zum konfigurierten Händler gehört.
  • Confirm SumUp meldet den Checkout als PAID mit einer erfolgreichen Transaktion.

Der gehostete Checkout meldet, dass er abgelaufen ist oder nicht gefunden wurde

Starten Sie den Checkout erneut über den Warenkorb. Gehostete Checkout-Sitzungen laufen nach etwa 30 Minuten ab. Nicht Setzen Sie ein Lesezeichen oder verwenden Sie eine alte gehostete Checkout-URL.

Sicherheitsregeln

  • Fügen Sie den API-Schlüssel niemals in einen CMS-Block, eine Seite, ein Produkt, ein Browserskript, ein Repository, einen Screenshot usw. ein Support-Protokoll.
  • Fügen Sie niemals einen echten API-Schlüssel in den Chat ein.
  • Halten Sie Sandbox- und Live-Anmeldeinformationen getrennt.
  • Ziehen Sie den Schlüssel sofort zurück und ersetzen Sie ihn, wenn er möglicherweise offengelegt wurde.
  • Behandeln Sie den CMS-Bestellstatus – nicht den Browser-Erfolgsbildschirm – als Erfüllungssignal.

Für Informationen zur Architektur, Webhook-Überprüfung, Auftragsstatus und erweiterte Fehlerbehebung fahren Sie mit fort das WebBlocks Commerce Operator Guide.

Offizielle SumUp-Referenzen: