Stripe Metadata

Wenn Sie Stripe Checkout Sessions über die API erstellen, können Sie die click_id im Stripe-metadata-Feld unter dem Schlüssel aff_click_id übergeben. Selgeo liest diese Metadata aus Stripe-Webhooks und ordnet die Konversion dem empfehlenden Partner zu.

API-Version: v1

Wann diesen Ansatz verwenden

Verwenden Sie Stripe Metadata, wenn:

• Sie die click_id zusammen mit Ihrem eigenen client_reference_id-Wert übergeben möchten (was Checkout auch unterstützt, aber Metadata gibt Ihnen mehr Flexibilität).
• Sie Checkout Sessions erstellen, aber client_reference_id für eigene Zwecke verwenden möchten.

Direkte Payment Intents und Subscriptions werden nicht unterstützt

Selgeo verarbeitet Metadata bei checkout.session.completed- und invoice.paid-Webhook-Events. Wenn Sie Payment Intents direkt erstellen, ist deren Metadata für Selgeo nicht verfügbar. Wenn Sie Subscriptions direkt erstellen (ohne Checkout), speichert Stripe die Metadata unter invoice.subscription_details.metadata, nicht unter invoice.metadata, sodass Selgeo aff_click_id nicht lesen kann. Verwenden Sie stattdessen die Conversion API oder erstellen Sie Subscriptions über Stripe Checkout (das mode: 'subscription' unterstützt).

client_reference_id vs. Metadata

Für Stripe Checkout Sessions können Sie entweder client_reference_id (einfacher, behandelt in Stripe Checkout) oder metadata.aff_click_id (hier behandelt) verwenden. Beide funktionieren. Wenn Sie client_reference_id bereits für Ihr eigenes internes Tracking verwenden, verwenden Sie stattdessen Metadata.

Der Ablauf

┌────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│     Browser     │      │   Ihr Server     │      │    Selgeo API    │
│                 │      │                  │      │                  │
│ 1. Snippet      │      │                  │      │                  │
│    speichert    │      │                  │      │                  │
│    click_id     │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 2. Frontend     │─────>│ 3. Erstellt      │      │                  │
│    sendet       │      │    Stripe-Objekt │      │                  │
│    clickId ans  │      │    mit metadata: │      │                  │
│    Backend      │      │    aff_click_id  │      │                  │
│                 │      │                  │      │                  │
│                 │      │                  │      │ 4. Stripe-Webhook │
│                 │      │                  │      │    wird ausgelöst │
│                 │      │                  │      │    → Selgeo liest │
│                 │      │                  │      │    aff_click_id   │
│                 │      │                  │      │    aus Metadata   │
│                 │      │                  │      │    → attributiert │
│                 │      │                  │      │    Konversion     │
└────────────────┘      └──────────────────┘      └──────────────────┘

Der Metadata-Schlüssel

Selgeo sucht die click_id in Stripe-Metadata unter dem Schlüssel:

aff_click_id

Dieser Schlüssel wird auf Checkout Session-Objekten (via checkout.session.completed) und auf Invoice-Objekten (via invoice.paid) überprüft.

Implementierung

Schritt 1: Klick-ID im Frontend lesen

const clickId = __selgeo.getClickId();

Schritt 2: An Ihr Backend senden

Fügen Sie die clickId in Ihren API-Anfragekörper, Formulardaten oder wie auch immer Sie Daten an Ihren Server übergeben, ein:

const clickId = __selgeo.getClickId();

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

Schritt 3: In Stripe Metadata übergeben

Payment Intents

warnung

Direkte Payment Intents werden für die Stripe Metadata Attribution nicht unterstützt. Selgeo verarbeitet nur checkout.session.completed- und invoice.paid-Webhook-Events. Für benutzerdefinierte Zahlungsflows, die Payment Intents direkt verwenden, nutzen Sie die Conversion API, um Konversionen server-seitig zu melden.

Direkte Subscriptions

warnung

Das Setzen von metadata.aff_click_id auf stripe.subscriptions.create() funktioniert nicht. Stripe kopiert Subscription-Metadata nicht nach invoice.metadata – es speichert sie unter invoice.subscription_details.metadata, das Selgeo derzeit nicht liest. Für Abonnement-Billing verwenden Sie Stripe Checkout mit mode: 'subscription' (unten gezeigt) oder melden Sie Konversionen über die Conversion API.

Checkout Sessions (Metadata-Ansatz)

Wenn Sie Metadata statt client_reference_id bei Checkout Sessions bevorzugen:

JavaScript (Node.js)

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',
    // client_reference_id für eigenes Tracking verwenden
    client_reference_id: 'my_internal_ref_123',
    // Metadata für Selgeo-Attribution verwenden
    metadata: {
      aff_click_id: clickId || '',
    },
  });

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

Python

import stripe

stripe.api_key = "sk_test_YOUR_STRIPE_KEY"

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

    session = stripe.checkout.Session.create(
        mode="subscription",
        line_items=[{"price": data["priceId"], "quantity": 1}],
        success_url="https://ihre-website.com/success",
        cancel_url="https://ihre-website.com/cancel",
        # client_reference_id für eigenes Tracking verwenden
        client_reference_id="my_internal_ref_123",
        # Metadata für Selgeo-Attribution verwenden
        metadata={
            "aff_click_id": data.get("clickId", ""),
        },
    )

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

PHP

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

$data = json_decode(file_get_contents('php://input'), true);

$session = $stripe->checkout->sessions->create([
    'mode' => 'subscription',
    'line_items' => [['price' => $data['priceId'], 'quantity' => 1]],
    'success_url' => 'https://ihre-website.com/success',
    'cancel_url' => 'https://ihre-website.com/cancel',
    // client_reference_id für eigenes Tracking verwenden
    'client_reference_id' => 'my_internal_ref_123',
    // Metadata für Selgeo-Attribution verwenden
    'metadata' => [
        'aff_click_id' => $data['clickId'] ?? '',
    ],
]);

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

Wie Selgeo Metadata verarbeitet

Für checkout.session.completed-Events prüft Selgeo die click_id in dieser Reihenfolge:

1. client_reference_id auf der Checkout Session (wenn vorhanden und eine gültige UUID).
2. metadata.aff_click_id auf der Checkout Session.

Wenn beide vorhanden sind, hat client_reference_id Priorität. Das bedeutet, Sie können sicher beide setzen, ohne Konflikte – Selgeo verwendet das, was es zuerst findet.

Für invoice.paid-Events (initiale Rechnungen ohne vorherige Checkout Session) prüft Selgeo metadata.aff_click_id und metadata.aff_promo_code direkt am Invoice-Objekt.

Wiederkehrende Abonnements

Für über Checkout erstellte Abonnements (mode: 'subscription') müssen Sie aff_click_id nur beim Erstellen der Checkout Session übergeben. Selgeo attributiert die initiale Konversion aus dem checkout.session.completed-Event und ordnet automatisch nachfolgende Rechnungszahlungen (Verlängerungen) demselben Partner zu, indem es die Stripe Customer ID abgleicht. Sie müssen die click_id bei Verlängerungen nicht erneut übergeben.

Leere Werte

Wenn der Besucher nicht von einem Partner empfohlen wurde (clickId ist null), können Sie entweder:

• Den Schlüssel weglassen – fügen Sie aff_click_id nicht in die Metadata ein.
• Einen leeren String übergeben – aff_click_id: ''. Selgeo ignoriert leere Strings.

Beide Ansätze sind sicher. Das Stripe-Objekt wird normal erstellt, und Selgeo behandelt es als nicht empfohlene Konversion.

Testen

1. Erstellen Sie einen Tracking-Link und einen Testpartner im Selgeo-Dashboard.
2. Besuchen Sie Ihre Website über den Tracking-Link, um einen Klick zu registrieren.
3. Starten Sie Ihren Zahlungsflow – die click_id sollte an Ihr Backend übergeben und in Stripe Metadata als aff_click_id eingefügt werden.
4. Schließen Sie die Zahlung ab mit der Stripe-Testkarte 4242 4242 4242 4242.
5. Prüfen Sie das Selgeo-Dashboard – überprüfen Sie, ob die Konversion erscheint und dem Testpartner zugeordnet ist.

Metadata in Stripe überprüfen

Sie können bestätigen, dass die Metadata korrekt gesetzt wurde, im Stripe Dashboard:

1. Finden Sie die Checkout Session.
2. Scrollen Sie zum Abschnitt Metadata.
3. Überprüfen Sie, ob aff_click_id die erwartete UUID enthält.

Vergleich der Attributionsmethoden

Methode	Stripe-Objekt	Schlüssel	Am besten für
client_reference_id	Nur Checkout Session	client_reference_id	Einfache Checkout-Integrationen
metadata.aff_click_id	Checkout Session	metadata.aff_click_id	Wenn client_reference_id bereits für andere Zwecke verwendet wird
Payment Link Auto-Rewrite	Payment Link URL	client_reference_id (Query-Parameter)	Stripe Payment Links ohne Backend

Nächste Schritte

• Conversion API – für Nicht-Stripe-Konversionen
• Webhooks – Benachrichtigungen erhalten, wenn Konversionen attributiert werden
• Testmodus – detaillierter Testleitfaden