Shopify Stripe integration: Architektur-Guide für eine robuste Payment-Integration

Problem Statement

```mermaid graph LR A[Client] -->|HTTP POST| B[Webhook Gateway] B -->|Validate| C{Valid?} C -->|Yes| D[Event Queue] C -->|No| E[Error Response] D -->|Process| F[Worker] F -->|Success| G[Acknowledge] F -->|Failure| H[Retry Queue] ``` ```typescript // Configuration Example export const config = { environment: 'production', apiEndpoint: 'https://api.example.com', timeout: 5000, retries: 3 }; ```

Eine Shopify Stripe integration klingt trivial. In der Praxis ist sie es selten. Shopify hat ein eigenes Payment-Ökosystem. Stripe ist ein eigenes Payment-Ökosystem. Und dazwischen liegt Architektur. Wenn du Stripe „neben“ Shopify betreiben willst, musst du entscheiden, welches System am Ende Quelle der Wahrheit ist: Bestellung, Zahlung, Refund, Chargeback.

Ich sehe oft denselben Fehler: Man hängt Stripe-Checkout irgendwo dran, markiert die Shopify-Order „bezahlt“ und hofft, dass das schon passt. Das funktioniert bis zum ersten asynchronen Ereignis. Ein Payment wird „requires_action“. Ein 3DS-Flow läuft in einem anderen Tab. Ein Webhook kommt doppelt. Oder gar nicht. Und plötzlich stimmen Shopify-Financial-Status, Stripe-PaymentIntents und Fulfillment nicht mehr zusammen. Warum ist das wichtig? Weil du sonst reale Ware verschickst, ohne Geld zu haben. Oder du sperrst Kunden aus, die längst bezahlt haben.

Der Kern des Problems ist Konsistenz über Systemgrenzen. Shopify denkt in Orders und Transactions. Stripe denkt in PaymentIntents, Charges, Refunds, Disputes. Du brauchst eine Integrationsschicht, die sauber modelliert. Und du brauchst eine Strategie für Idempotenz, Retry und Observability. Sonst wird’s ein Dauerbrand.

Technical Background

Shopify bietet mehrere Wege, Zahlungen zu beeinflussen. Der „klassische“ Weg ist Shopify Payments. Für Stripe als eigenständigen Acquirer wird’s schnell „um die Ecke“: entweder als externes Payment-Gateway (je nach Region/Shopify-Plan) oder als offsite payment-Flow über App/Checkout-Extension-Muster, bei dem Shopify die Order erzeugt und du außerhalb kassierst. Ich halte mich hier bewusst an ein Shopify-zentriertes Integrationsmodell: Shopify bleibt führend für Order-Lifecycle, Stripe ist führend für Payment-Lifecycle.

Wichtig ist das Datenmodell. Du brauchst eine eindeutige Korrelation:

Shopify Order ⇄ Stripe PaymentIntent ⇄ Stripe Events

Das ist kein „nice to have“. Das ist dein Rettungsring bei Support-Fällen. Übrigens: Letztes Quartal hat ein Kunde zwei Wochen verloren, weil es keine saubere Referenz gab. Sie hatten nur „Order #10293“ in einem Freitextfeld. In Stripe war nichts auffindbar. Im Shopify-Admin stand „paid“. In der Buchhaltung fehlten 17 Zahlungen. Das war nicht mal ein Bug. Das war fehlende Architektur.

Ein robustes Setup hat typischerweise diese Komponenten:

Komponente	Rolle	Single Source of Truth
Shopify Store	Checkout/Order, Fulfillment, Customer	Order-Status, Fulfillment
Integration Service	Korrelation, Webhook-Handling, State Machine	Mapping & Verarbeitungshistorie
Stripe	PaymentIntents, Refunds, Disputes	Zahlungsstatus
Datenbank	Idempotenz, Audit, Reconciliation	Event-Log
Message Queue (optional)	Retry, Entkopplung	—

Der Datenfluss ist asynchron. Immer. Du kannst nicht „synchron“ sicherstellen, dass eine Zahlung final ist, bevor der Browser zurück zu Shopify kommt. Du musst Webhooks ernst nehmen. Und du musst akzeptieren, dass Webhooks doppelt kommen oder verspätet. Das ist kein Stripe-Problem. Das ist verteilte Systeme.

Ein Architekturdiagramm hilft, die Verantwortlichkeiten festzunageln:

flowchart LR
  U[Customer Browser] -->|Checkout in Shopify| S[Shopify Store]
  S -->|Create/Update Order| IS[Integration Service]
  IS -->|Create PaymentIntent| ST[Stripe API]
  ST -->|Client Secret| IS
  IS -->|Return redirect/hosted url| U

  ST -->|webhook events| WH[Webhook Endpoint]
  WH -->|verify + idempotent write| DB[(Event Store DB)]
  WH -->|state machine| IS
  IS -->|update order financial status / metafields| S

  IS -->|reconcile job| DB
  IS -->|reporting export| BI[Analytics/ERP]

Ich empfehle, die Integration als State Machine zu sehen. Nicht als „if paid then…“. Du modellierst Zustände: created → requires_action → processing → succeeded → refunded → disputed. Shopify hat eigene Status. Du mapst sie. Und du dokumentierst die Regeln.

Implementation Steps

Ich gehe von einer Architektur aus, die in der Praxis gut wartbar ist: ein kleiner Integration Service (TypeScript), ein Webhook-Verarbeiter (Python oder TypeScript), und eine Datenbank für Event-Audit und Idempotenz. „Warum zwei Sprachen?“ Muss nicht. Ich zeige bewusst heterogen, weil es in echten Teams oft so ist. Ein Data-Team schreibt Python. Ein Plattform-Team TypeScript. Das ist nicht hübsch, aber real.

Schritt 1: Identitäten und Korrelation definieren. Du brauchst mindestens:

Key	Beispiel	Warum
shopify_order_id	gid://shopify/Order/123456789	stabil, eindeutig
stripe_payment_intent_id	pi_3QXYZ...	Stripe Payment-Lifecycle
idempotency_key	order:123456789:create_pi	Duplikate verhindern

Schritt 2: Datenbanktabellen für Audit und Idempotenz. Ohne persistentes Event-Log debugst du im Nebel. Das folgende SQL demonstriert ein minimales Schema, das sich in mehreren Projekten bewährt hat. Ich halte es absichtlich schlank. Du kannst später normalisieren. Oder auch nicht.

-- Minimaler Event Store für Stripe-Webhooks.
-- Achtung: Häufiger Stolperstein ist fehlende Unique-Constraints für event_id.

CREATE TABLE stripe_events (
  id BIGSERIAL PRIMARY KEY,
  event_id TEXT NOT NULL UNIQUE,
  event_type TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  payload JSONB NOT NULL,
  processed_at TIMESTAMPTZ,
  processing_error TEXT
);

CREATE TABLE payment_mappings (
  id BIGSERIAL PRIMARY KEY,
  shopify_order_id TEXT NOT NULL,
  stripe_payment_intent_id TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL,
  amount_cents INTEGER NOT NULL,
  currency TEXT NOT NULL,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_payment_mappings_shopify_order_id
  ON payment_mappings(shopify_order_id);

Schritt 3: PaymentIntent-Erstellung über einen Integration Service. Der Service nimmt eine Shopify-Order (oder Cart/Checkout-Kontext) und erzeugt einen Stripe PaymentIntent. Wichtig: Idempotency-Key nutzen. Sonst erzeugst du bei Retries mehrere Intents. Das following TypeScript demonstrates einen simplen Endpoint, der genau das macht. In echten Projekten baue ich noch Signaturen, Rate-Limits und ein Permission-Modell ein.

import express from "express";
import Stripe from "stripe";

const app = express();
app.use(express.json());

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-06-20",
});

// Typisches Beispiel für einen "Create PaymentIntent"-Endpoint.
// TODO: Später auf eine Queue umstellen, wenn Last steigt.
app.post("/payments/create", async (req, res) => {
  const { shopifyOrderId, amountCents, currency, customerEmail } = req.body;

  if (!shopifyOrderId || !amountCents || !currency) {
    return res.status(400).json({ error: "missing fields" });
  }

  // Idempotenz schützt dich vor doppelten Intents bei Timeouts.
  const idempotencyKey = `order:${shopifyOrderId}:create_pi`;

  try {
    const pi = await stripe.paymentIntents.create(
      {
        amount: amountCents,
        currency,
        receipt_email: customerEmail,
        // Metadaten sind Gold wert. Später im Support unersetzlich.
        metadata: {
          shopify_order_id: shopifyOrderId,
        },
        automatic_payment_methods: { enabled: true },
      },
      { idempotencyKey }
    );

    // Achtung: Häufiger Stolperstein.
    // client_secret ist sensitiv. Nur an den Browser geben, wenn nötig.
    res.json({ paymentIntentId: pi.id, clientSecret: pi.client_secret });
  } catch (err: any) {
    // Früher haben wir hier alles geloggt. War ein Fehler. PII kann drin sein.
    res.status(500).json({ error: "stripe_error", detail: err.message });
  }
});

app.listen(3000, () => console.log("integration service listening"));

Schritt 4: Webhook-Verifikation und idempotente Verarbeitung. Hier trennt sich Hobby von Produktion. Stripe-Webhooks müssen signiert verifiziert werden. Danach wird das Event in den Event-Store geschrieben. Erst dann wird verarbeitet. Diese Reihenfolge ist nicht akademisch. Sie ist pragmatisch. Bei einem Kunden hatten wir einen 47-Minuten-Ausfall des Webhook-Workers. Ohne persistentes Event-Log waren 312 Events weg. Mit Event-Log war’s ein Reprocess.

Das folgende Python-Snippet demonstriert einen Webhook-Handler mit Verifikation und „insert-once“-Semantik. Es ist nicht das ganze System. Aber es zeigt den Kern.

import os
import json
import psycopg2
import stripe
from flask import Flask, request, abort

app = Flask(__name__)

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]
endpoint_secret = os.environ["STRIPE_WEBHOOK_SECRET"]

def get_conn():
    return psycopg2.connect(os.environ["DATABASE_URL"])

@app.post("/stripe/webhook")
def stripe_webhook():
    payload = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        event = stripe.Webhook.construct_event(
            payload=payload,
            sig_header=sig_header,
            secret=endpoint_secret,
        )
    except Exception:
        # Lieber hart abbrechen. Sonst akzeptierst du Spoofing.
        abort(400)

    event_id = event["id"]
    event_type = event["type"]

    # Idempotentes Persistieren.
    # Achtung: Wir speichern erst, dann verarbeiten. Sonst verlierst du Events bei Crash.
    conn = get_conn()
    conn.autocommit = True
    cur = conn.cursor()

    try:
        cur.execute(
            """
            INSERT INTO stripe_events(event_id, event_type, payload)
            VALUES (%s, %s, %s::jsonb)
            ON CONFLICT (event_id) DO NOTHING
            """,
            (event_id, event_type, json.dumps(event)),
        )
    except Exception as e:
        # Hier nicht zu viel loggen. Payload kann PII enthalten.
        abort(500)
    finally:
        cur.close()
        conn.close()

    # Processing kann asynchron sein (Queue). Hier direkt, der Einfachheit halber.
    # TODO: In echten Deployments Worker + Retry mit Backoff.
    return {"received": True}

if __name__ == "__main__":
    app.run(port=5000)

Schritt 5: Zustandsmaschine und Shopify-Update. Jetzt kommt der heikle Teil: Wie aktualisierst du Shopify? Je nach Setup machst du das über die Admin API. Meiner Meinung nach sollten Updates minimal sein: Metafields schreiben, Tags setzen, interne Notizen. Den „financial_status“ kannst du nicht beliebig setzen; Shopify kontrolliert das in vielen Flows. Darum ist das Ziel oft: Shopify informiert halten, nicht Shopify „übersteuern“.

Was sich bewährt hat: Ein eigenes Metafield-Set, z.B. stripe.payment_intent_id, stripe.status, stripe.last_event. Support schaut in Shopify. Engineering schaut in Stripe. Beide sehen denselben Key.

Schritt 6: Reconciliation-Job. Webhooks sind nicht garantiert. Dein System muss periodisch prüfen: „Welche Shopify-Orders sind offen, aber Stripe sagt succeeded?“ oder umgekehrt. Das ist kein Misstrauen, das ist Engineering-Hygiene. Ich plane solche Jobs gerne alle 10–15 Minuten, plus ein nächtlicher Full-Sweep. Nicht wegen Last. Wegen Schlaf.

Best Practices

Ein paar Dinge, die ich inzwischen fast dogmatisch sehe.

1) Event-First-Denken. Stripe ist event-getrieben. Shopify auch, aber anders. Wenn du versuchst, alles synchron zu machen, verlierst du. Baue um Events herum. Speichere Events. Verarbeite Events. Reprocess ist Pflicht.

2) Idempotenz ist nicht optional. Stripe schickt Events doppelt. Dein Netzwerk droppt Requests. Dein Load Balancer macht Retries. Wenn du kein exactly-once durchsetzen kannst, baue at-least-once mit Idempotenz. Das ist der Standard.

3) Zustände sauber mappen. Ich sehe oft „paid“ vs „succeeded“ als 1:1. Das stimmt nicht. Ein PaymentIntent kann „processing“ sein. Oder „requires_payment_method“. Oder „canceled“. Und Refunds sind eigene Objekte. Disputes sind nochmal anders. Schreib dir eine Mapping-Tabelle. Häng sie ins Repo. Diskutiere sie im Team.

Stripe	Interpretation	Shopify Aktion
payment_intent.succeeded	Zahlung final (meist)	Metafield setzen, Fulfillment freigeben
payment_intent.payment_failed	Keine Zahlung	Order blocken, Kunde informieren
charge.refunded	Refund (teilweise/komplett)	Shopify Notiz + ERP Trigger
charge.dispute.created	Chargeback-Workflow	Risk/Support Workflow starten

4) Security: Webhook-Signaturen und Secrets. Klingt banal. Wird aber oft falsch gemacht. Signature-Verification ist Pflicht. Secrets gehören in einen Secret Store. Nicht in .env auf einem Server, der noch 14 andere Services hostet. Übrigens: Ich habe einmal erlebt, dass ein Team Webhooks ohne Verifikation akzeptierte. Ergebnis: Fake „succeeded“-Events. Das war teuer. Sehr teuer.

5) Observability. Mindestens: Request-ID, Stripe-Event-ID, Shopify-Order-ID in jedem Log. Dazu Metriken: webhook_lag_seconds, events_processed_total, events_failed_total. Und Traces, wenn du es ernst meinst. Sonst suchst du nachts im Dunkeln.

6) Datenminimierung. Speichere nicht alles aus Stripe in Klartext, wenn du es nicht brauchst. Payloads sind praktisch, ja. Aber PII ist real. Tokenisiere, filtere, oder speichere nur Event-Header plus Referenzen. In manchen Branchen ist das kein Nice-to-have, sondern Compliance.

7) Failure-Playbooks. Schreibe auf, was passiert wenn:

• Stripe-Webhooks 30 Minuten nicht zugestellt werden.
• Shopify Admin API rate-limited.

Mehr Listen brauch ich nicht. Der Rest ist Detailarbeit.

Real-World Example

Bei einem Kunden hatten wir einen Shopify-Store mit hohem B2B-Anteil. Zahlung per Karte über Stripe. Fulfillment über ein externes Lager. Die Regel war klar: Kein Fulfillment ohne Stripe succeeded. Trotzdem wurden Bestellungen versendet, obwohl Zahlungen „processing“ waren. Warum? Weil das Lager nur auf Shopify-Tag „paid“ schaute, und dieses Tag wurde im Redirect-Callback gesetzt. Nicht per Webhook. Das ist so ein Klassiker, der auf dem Whiteboard harmlos aussieht.

Wir haben es umgebaut. Mit drei Bausteinen:

Event Store (Postgres), Worker (Queue-basiert), Shopify Metafields als sichtbare Brücke.

Der Worker machte dann:

1) Stripe Event kommt rein. Persistieren. 2) State Machine berechnet neuen Payment-Status. 3) Update in payment_mappings. 4) Shopify Metafield aktualisieren. 5) Wenn succeeded: „release_fulfillment“ an Lager-Connector.

Ein typisches Query, das wir für Reconciliation genutzt haben, sah so aus. Es ist unspektakulär. Aber es hat uns mehrfach gerettet, wenn Shopify-Updates rate-limited waren und der Worker nachziehen musste.

-- Finde Shopify Orders, die in unserem Mapping "succeeded" sind,
-- aber noch nicht als verarbeitet markiert wurden (vereinfachtes Beispiel).

SELECT
  shopify_order_id,
  stripe_payment_intent_id,
  status,
  updated_at
FROM payment_mappings
WHERE status = 'succeeded'
  AND updated_at < NOW() - INTERVAL '2 minutes'
ORDER BY updated_at ASC
LIMIT 200;

Was war das Ergebnis? Weniger „Ghost Shipments“. Weniger Support-Tickets. Und interessanterweise: weniger interne Diskussionen. Weil jeder auf dieselben IDs schauen konnte. Der größte Gewinn war nicht technisch. Es war organisatorisch.

Wenn du so etwas gerade aufbaust: Plane Zeit für Testfälle ein. Nicht Unit-Tests. Echte Zahlungsflüsse. 3DS. Abbruch. Retry. Refund. Dispute. Das kostet ein paar Stunden. Spart aber Wochen. Wenn du willst, kann man daraus auch ein kleines internes „Payment Testbook“ machen. Das wäre ein eigener Artikel.

Ganz am Ende, im letzten Projekt, haben wir noch einen simplen Self-Service-Screen im Admin gebaut: „Find Stripe Payment for this Order“. Kein Hexenwerk. Aber der Support hat’s geliebt. Wenn du sowas planst, mach es im letzten Sprint. Nicht am Anfang. Erst muss der Kern stabil sein.