Was Sie brauchen
| Feld | Was es tut |
|---|---|
| Access Token | Lässt uns Square aufrufen, um den Checkout-Link zu erstellen. Geheim. |
| Webhook Signature Key | Bestätigt, dass ein Webhook wirklich von Square kam. Geheim. |
| Location ID | Der Square-Standort, der die Zahlung erhält. Legt die Währung fest. |
| Erfolgs-URL / Abbruch-URL | Wohin der Käufer nach dem Zahlen oder Abbrechen landet. |
Warum wir nach jedem Feld fragen
Access Token
Autorisiert das Erstellen des Checkout-Links, sodass die Belastung über Ihr Konto läuft.
Webhook Signature Key
Beweist, dass ein eingehender Webhook echt von Square stammt, sodass niemand ein "bezahlt"-Ereignis fälschen kann. Es ist ein vom Access Token getrennter Wert.
Location ID
Sagt Square, welcher Standort das Geld erhält, und legt die Checkout-Währung fest. Nicht geheim.
Erfolgs- und Abbruch-URL
Schlichte Einstellungen: wohin der Käufer nach dem Zahlen oder Abbrechen landet. Nicht geheim.
Einrichten
- Square-Entwickler-Dashboard öffnen
Melden Sie sich bei developer.squareup.com an. Jede Anwendung hat eigene Zugangsdaten, und ein kostenloser Sandbox wird beim Erstellen automatisch mitangelegt. Diese Anleitung führt durch den Sandbox; der Live-Ablauf ist identisch, drehen Sie einfach den Sandbox/Production-Schalter um und verwenden Sie Ihre Produktionszugangsdaten. Um eine neue App zu erstellen, klicken Sie auf die +-Kachel im Anwendungsbildschirm.
Square Developer → Applications - Anwendung benennen
Geben Sie der Anwendung einen Namen, den Sie wiedererkennen (zum Beispiel „Coin Moebius"), und klicken Sie dann auf Next.
Square → Name your application - Access Token kopieren
Öffnen Sie die App und gehen Sie zu Credentials. Vergewissern Sie sich, dass der Sandbox/Production-Schalter oben der Umgebung entspricht, die Sie einrichten. Klicken Sie auf das Kopiersymbol neben dem Access token und legen Sie ihn beiseite.
Square → Credentials Der Access token ist geheim, behandeln Sie ihn wie ein Passwort. Sandbox und Production haben getrennte Token, mischen Sie sie also nicht.
- Location ID kopieren
Öffnen Sie im linken Menü Locations. Kopieren Sie die Location ID des Standorts, der Zahlungen erhalten soll. Sie legt die Checkout-Währung fest, wählen Sie also den Standort mit der gewünschten Abrechnungswährung.
Square → Locations - Webhooks → Subscriptions öffnen
Square nennt einen Webhook-Endpunkt „Subscription". Erweitern Sie im linken Menü Webhooks, öffnen Sie Subscriptions und klicken Sie Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Subscription hinzufügen und Ereignisse auswählen
Geben Sie einen Namen ein (z. B. „coin-moebius"). Fügen Sie im Feld Notification URL die Square-Webhook-Adresse Ihres Projekts ein (unten). Suchen und aktivieren Sie dann unter Events die Ereignisse, auf die Coin Moebius hört, und klicken Sie Speichern.
- Einmalzahlungen: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Abos (nur wenn Sie diese verkaufen): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Wenn Sie nicht auf Abonnementbasis abrechnen, lassen Sie diese weg.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription Ihre Projekt-ID steht im Coin Moebius Dashboard unter dem Projektnamen; tragen Sie sie in die obige Adresse ein. Zusätzliche Ereignisse sind harmlos, wir ignorieren alles, was wir nicht verwenden. Die verbundene Anbieterkarte (letzter Schritt) zeigt dieselbe URL als Referenz.
- Die gerade erstellte Subscription öffnen
Square speichert die Subscription und listet sie unter Webhooks mit dem Status Enabled auf. Klicken Sie auf ihren Namen, um den Detailbereich zu öffnen, in dem der Signing Key hinterlegt ist.
Square → Webhooks → Ihre Subscription (Enabled) - Signature Key kopieren
Klicken Sie im Properties-Bereich der Subscription auf das Kopiersymbol neben Signature key. Diesen Wert verwendet Coin Moebius, um zu bestätigen, dass jeder Webhook wirklich von Square stammt. Er existiert erst, nachdem die Subscription erstellt wurde, weshalb der Webhook-Schritt vor dem Verbindungsschritt kommt.
Square → Ihre Subscription → Signature key - Zurück in Coin Moebius: Anbieter hinzufügen → Square
Öffnen Sie in Ihrem Projekt den Reiter Anbieter, klicken Sie Anbieter hinzufügen, wählen Sie Dienst verbinden und dann Square. Legen Sie Ihre Erfolgs-URL und Abbruch-URL fest. Fügen Sie auf dem Live-Reiter Ihren Access token, Webhook signature key und die Location ID ein, und klicken Sie dann auf Speichern. Möchten Sie zunächst mit Sandbox-Zugangsdaten arbeiten? Fügen Sie diese stattdessen auf dem Test-Reiter ein und ergänzen Sie die Live-Zugangsdaten später über Bearbeiten.
Coin Moebius → Anbieter hinzufügen → Square - Sie sind verbunden
Square erscheint jetzt im Reiter Anbieter mit dem Verbindungsdatum. Die Karte zeigt dieselbe Webhook-URL, die Sie in Square eingefügt haben, sowie Bearbeiten und Trennen. Nutzen Sie den Testmodus-Schalter, um eine Sandbox-Bestellung von Ende zu Ende durchzugehen, bevor Sie live gehen.
Coin Moebius → Anbieter → Square (verbunden) Sandbox-Karten belasten nie eine echte Karte. Verwenden Sie Karte 4111 1111 1111 1111, CVV 111, ein beliebiges zukünftiges Ablaufdatum und eine beliebige gültige Postleitzahl (zum Beispiel 94103).
Nachdem Sie verbunden haben
Führen Sie vor dem Live-Gang eine Testzahlung durch:
- Erstellen Sie ein Produkt und setzen Sie seine Umgebung auf Testing. Das betreibt das Produkt mit Ihren Sandbox-Zugangsdaten, sodass Sie eine volle Bestellung aufgeben können, ohne Geld zu bewegen. (Wenn Sie den Sandbox-Satz übersprungen haben, fällt ein Testing-Produkt auf Live zurück, fügen Sie ihn also zuerst hinzu.)
- Setzen Sie den Buy-Button auf eine Seite (eine lokale HTML-Datei reicht), die auf Ihr Projekt zeigt.
- Schließen Sie den Checkout mit der Sandbox-Testkarte von oben ab.
- Öffnen Sie den Reiter Transaktionen. Eine neue Zeile erscheint, mit Testing markiert. Wenn ihr Status succeeded erreicht, funktionieren Ihre Zugangsdaten und der Webhook beide von Ende zu Ende.
Schalten Sie die Umgebung des Produkts auf Live, wenn Sie für echte Zahlungen bereit sind.
Fehlerbehebung
Beginnen Sie mit Verifizieren. Klicken Sie im Dashboard Verifizieren (oder Testdaten verifizieren), um Ihren Access Token und Ihren Standort zu prüfen.
Verifizieren schlägt fehl.
Kopieren Sie den Access Token und die Location ID erneut. Production und Sandbox haben getrennte Token, mischen Sie sie also nicht.
Signaturprüfung schlägt fehl, oder die Bestellung bleibt ausstehend.
Square signiert über die genaue Notification-URL plus den Body. Die URL, die Sie in Square registrieren, muss zeichengenau mit Ihrer Webhook-URL übereinstimmen, ohne abschließenden Schrägstrich und ohne zusätzlichen Query-String. Kopieren Sie dann den Signature Key von demselben Endpunkt erneut.
Bestätigen Sie es von Ende zu Ende.
Square Developer Console → Webhooks → Ihre Subscription → Send Test Event, dann beobachten Sie, wie die Bestellung sich aktualisiert.
Gut zu wissen
Währung folgt dem Standort. Der Checkout belastet in der Währung des Standorts, dessen ID Sie angeben.
Secrets rotieren. Rollen Sie den Access Token oder den Signature Key jederzeit, fügen Sie dann den neuen Wert ein. Geheime Felder bleiben beim Bearbeiten leer.
Fragen? Join our Discord