Stripe Checkout

Wenn Sie Stripe Checkout Sessions auf Ihrem Server erstellen, müssen Sie die click_id vom Browser an Ihr Backend übergeben und sie als client_reference_id beim Erstellen der Session einschließen. Selgeo liest diesen Wert aus dem Stripe-Webhook und ordnet die Konversion dem empfehlenden Partner zu.

API-Version: v1

Voraussetzungen

Das Selgeo-Snippet ist auf Ihrer Website installiert (Snippet-Setup)
Sie erstellen Stripe Checkout Sessions auf Ihrem Backend
Ihr Stripe-Konto ist im Dashboard mit Selgeo verbunden (Einstellungen > Stripe)

Funktionsweise

┌────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│     Browser     │      │   Ihr Server     │      │    Selgeo API    │
│                 │      │                  │      │                  │
│ 1. Besucher     │      │                  │      │                  │
│    kommt via    │      │                  │      │                  │
│    ?ref=abc123  │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 2. Snippet      │─────>│                  │─────>│ Registriert Klick│
│    registriert  │      │                  │      │ Gibt click_id    │
│    Klick        │<─────│                  │<─────│ zurück           │
│                 │      │                  │      │                  │
│ 3. Nutzer       │─────>│ 4. Erstellt      │      │                  │
│    klickt       │      │    Checkout       │      │                  │
│    "Abonnieren" │      │    Session mit   │      │                  │
│    (sendet      │      │    client_ref_id  │      │                  │
│     clickId)    │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 5. Weiterleitung│<─────│                  │      │                  │
│    zu Stripe    │      │                  │      │                  │
│    Checkout     │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 6. Kunde zahlt  │      │                  │      │                  │
│                 │      │                  │      │                  │
│                 │      │                  │      │ 7. Stripe-Webhook │
│                 │      │                  │      │    enthält        │
│                 │      │                  │      │    client_ref_id  │
│                 │      │                  │      │    → Selgeo       │
│                 │      │                  │      │    attributiert   │
└────────────────┘      └──────────────────┘      └──────────────────┘

Implementierung

Schritt 1: Klick-ID im Frontend lesen

Nachdem das Snippet geladen und einen Empfehlungsklick erfasst hat, ist die click_id verfügbar über:

const clickId = __selgeo.getClickId();

Dies gibt einen UUID-String zurück (z. B. "f47ac10b-58cc-4372-a567-0e02b2c3d479") oder null, wenn kein Empfehlungsklick aufgezeichnet wurde.

Schritt 2: Klick-ID an Ihr Backend senden

Fügen Sie die click_id ein, wenn Ihr Frontend eine Checkout Session von Ihrem Server anfordert:

const clickId = __selgeo.getClickId();

const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_xxx',
    clickId: clickId,
  }),
});

const { url } = await response.json();
window.location.href = url;

Schritt 3: Als `client_reference_id` beim Erstellen der Checkout Session übergeben

JavaScript (Node.js)
Python
PHP

const stripe = require('stripe')('sk_test_YOUR_STRIPE_KEY');

app.post('/api/create-checkout', async (req, res) => {
  const { priceId, clickId } = req.body;

  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: 'https://ihre-website.com/success',
    cancel_url: 'https://ihre-website.com/cancel',
    // click_id übergeben, damit Selgeo diese Konversion attributieren kann
    client_reference_id: clickId || undefined,
  });

  res.json({ url: session.url });
});

import stripe

stripe.api_key = "sk_test_YOUR_STRIPE_KEY"

@app.route("/api/create-checkout", methods=["POST"])
def create_checkout():
    data = request.get_json()
    price_id = data["priceId"]
    click_id = data.get("clickId")

    session = stripe.checkout.Session.create(
        mode="subscription",
        line_items=[{"price": price_id, "quantity": 1}],
        success_url="https://ihre-website.com/success",
        cancel_url="https://ihre-website.com/cancel",
        # click_id übergeben, damit Selgeo diese Konversion attributieren kann
        client_reference_id=click_id if click_id else None,
    )

    return jsonify({"url": session.url})

$stripe = new \Stripe\StripeClient('sk_test_YOUR_STRIPE_KEY');

$data = json_decode(file_get_contents('php://input'), true);
$priceId = $data['priceId'];
$clickId = $data['clickId'] ?? null;

$session = $stripe->checkout->sessions->create([
    'mode' => 'subscription',
    'line_items' => [['price' => $priceId, 'quantity' => 1]],
    'success_url' => 'https://ihre-website.com/success',
    'cancel_url' => 'https://ihre-website.com/cancel',
    // click_id übergeben, damit Selgeo diese Konversion attributieren kann
    'client_reference_id' => $clickId,
]);

echo json_encode(['url' => $session->url]);

undefined übergeben, nicht einen leeren String

Wenn keine click_id vorhanden ist (der Besucher wurde nicht von einem Partner empfohlen), übergeben Sie undefined (JavaScript), None (Python) oder null (PHP) für client_reference_id. Übergeben Sie keinen leeren String – Stripe speichert ihn als den Literalwert "", den Selgeo keinem Klick zuordnen kann.

Eingebetteter Checkout

Wenn Sie Stripe Embedded Checkout statt Redirect-basiertem Checkout verwenden, ist der Ablauf identisch. Sie erstellen weiterhin eine Checkout Session auf Ihrem Server mit client_reference_id und übergeben das client_secret an das Frontend:

JavaScript (Node.js)

app.post('/api/create-checkout', async (req, res) => {
  const { priceId, clickId } = req.body;

  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    ui_mode: 'embedded',
    return_url: 'https://ihre-website.com/success?session_id={CHECKOUT_SESSION_ID}',
    // Wie bei Redirect Checkout – click_id hier übergeben
    client_reference_id: clickId || undefined,
  });

  res.json({ clientSecret: session.client_secret });
});

Selgeo liest client_reference_id aus dem Stripe-Webhook, unabhängig davon, ob Sie Redirect- oder Embedded Checkout verwenden.

Den `null`-Fall behandeln

Wenn __selgeo.getClickId() null zurückgibt, bedeutet das eine der folgenden Situationen:

Der Besucher ist nicht über einen Partner-Empfehlungslink gekommen.
Der sessionStorage des Besuchers wurde geleert (z. B. weil er den Tab geschlossen und wieder geöffnet hat).
Das Snippet hat noch nicht geladen (z. B. ist das asynchrone Laden noch im Gange).

In allen Fällen sollten Sie die Checkout Session trotzdem normal erstellen – lassen Sie einfach client_reference_id weg. Die Konversion wird als nicht empfohlener Verkauf weiterverarbeitet:

const clickId = __selgeo.getClickId();

// Checkout immer erstellen, unabhängig davon, ob clickId vorhanden ist
const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_xxx',
    clickId: clickId, // null ist in Ordnung – Ihr Backend sollte damit umgehen
  }),
});

Testen

Erstellen Sie einen Tracking-Link und einen Testpartner im Selgeo-Dashboard.
Besuchen Sie Ihre Website über den Tracking-Link: https://ihre-website.com/?ref=IHR_TEST_REF

Überprüfen Sie die Klick-ID in der Browser-Konsole:

__selgeo.getClickId() // Sollte eine UUID zurückgeben

Starten Sie Ihren Checkout-Flow. Die click_id sollte an Ihr Backend übergeben werden.
Schließen Sie die Zahlung ab mit der Stripe-Testkarte 4242 4242 4242 4242.
Prüfen Sie das Selgeo-Dashboard – die Konversion sollte dem Testpartner zugeordnet erscheinen.

Vergleich mit Payment Links

Funktion	Payment Links	Checkout Sessions
Backend-Code erforderlich	Nein	Ja (Session erstellen)
Frontend-Code erforderlich	Nein	Ja (`click_id` lesen)
Unterstützt Abonnements	Ja	Ja
Unterstützt Einmalzahlungen	Ja	Ja
Unterstützt eingebetteten Checkout	Nein	Ja
Benutzerdefinierter Checkout-Flow	Nein	Ja

Wenn Sie nur einen einfachen Kauf-Button benötigen und den Checkout-Flow nicht anpassen, ist Stripe Payment Links die einfachere Option.

Nächste Schritte

Stripe Metadata – Checkout Session Metadata statt client_reference_id verwenden
Conversion API – für Nicht-Stripe-Konversionen
Testmodus – detaillierter Leitfaden zum Testen

Voraussetzungen​

Funktionsweise​

Implementierung​

Schritt 1: Klick-ID im Frontend lesen​

Schritt 2: Klick-ID an Ihr Backend senden​

Schritt 3: Als client_reference_id beim Erstellen der Checkout Session übergeben​

Eingebetteter Checkout​

Den null-Fall behandeln​

Testen​

Vergleich mit Payment Links​

Nächste Schritte​