Stripe Metadata

Si vous créez des Sessions de paiement Stripe via l'API, vous pouvez passer le click_id dans le champ metadata de Stripe en utilisant la clé aff_click_id. Selgeo lit ces métadonnées depuis les webhooks Stripe et attribue la conversion au partenaire référent.

Version API : v1

Quand utiliser cette approche

Utilisez les métadonnées Stripe lorsque :

• Vous voulez passer le click_id en même temps que votre propre valeur client_reference_id (que Checkout prend également en charge, mais les métadonnées vous donnent plus de flexibilité).
• Vous créez des Sessions de paiement mais voulez utiliser client_reference_id pour vos propres besoins.

Payment Intents directs et Abonnements non pris en charge

Selgeo traite les métadonnées sur les événements webhook checkout.session.completed et invoice.paid. Si vous créez des Payment Intents directement, leurs métadonnées ne sont pas disponibles pour Selgeo. Si vous créez des Abonnements directement (sans Checkout), Stripe stocke les métadonnées dans invoice.subscription_details.metadata, pas dans invoice.metadata, donc Selgeo ne peut pas lire aff_click_id. Utilisez plutôt l'API de conversion, ou créez des abonnements via Stripe Checkout (qui prend en charge mode: 'subscription').

client_reference_id vs métadonnées

Pour les Sessions de paiement Stripe, vous pouvez utiliser soit client_reference_id (plus simple, couvert dans Stripe Checkout) soit metadata.aff_click_id (couvert ici). Les deux fonctionnent. Si vous utilisez déjà client_reference_id pour votre propre suivi interne, utilisez les métadonnées à la place.

Le flux

┌────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│    Navigateur   │      │   Votre Serveur  │      │    Selgeo API    │
│                 │      │                  │      │                  │
│ 1. Snippet      │      │                  │      │                  │
│    stocke       │      │                  │      │                  │
│    click_id     │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 2. Frontend     │─────>│ 3. Crée objet    │      │                  │
│    envoie       │      │    Stripe avec   │      │                  │
│    clickId au   │      │    metadata:     │      │                  │
│    backend      │      │    aff_click_id  │      │                  │
│                 │      │                  │      │                  │
│                 │      │                  │      │ 4. Webhook Stripe │
│                 │      │                  │      │    se déclenche → │
│                 │      │                  │      │    Selgeo lit     │
│                 │      │                  │      │    aff_click_id   │
│                 │      │                  │      │    depuis metadata│
│                 │      │                  │      │    → attribue     │
│                 │      │                  │      │    conversion     │
└────────────────┘      └──────────────────┘      └──────────────────┘

La clé de métadonnées

Selgeo recherche le click_id dans les métadonnées Stripe sous la clé :

aff_click_id

Cette clé est vérifiée sur les objets Session de paiement (via checkout.session.completed) et sur les objets Facture (via invoice.paid).

Implémentation

Étape 1 : Lire l'ID de clic sur le frontend

const clickId = __selgeo.getClickId();

Étape 2 : L'envoyer à votre backend

Incluez le clickId dans le corps de votre requête API, vos données de formulaire, ou comment que vous passiez des données à votre serveur :

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,
  }),
});

Étape 3 : Le passer dans les métadonnées Stripe

Payment Intents

attention

Les Payment Intents directs ne sont pas pris en charge pour l'attribution via les métadonnées Stripe. Selgeo ne traite que les événements webhook checkout.session.completed et invoice.paid. Pour les flux de paiement personnalisés utilisant directement les Payment Intents, utilisez l'API de conversion pour signaler les conversions côté serveur.

Abonnements directs

attention

Définir metadata.aff_click_id sur stripe.subscriptions.create() ne fonctionne pas. Stripe ne copie pas les métadonnées d'abonnement dans invoice.metadata — il les stocke dans invoice.subscription_details.metadata, que Selgeo ne lit pas actuellement. Pour la facturation d'abonnements, utilisez Stripe Checkout avec mode: 'subscription' (montré ci-dessous), ou signalez les conversions via l'API de conversion.

Sessions de paiement (approche métadonnées)

Si vous préférez utiliser les métadonnées plutôt que client_reference_id sur les Sessions de paiement :

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://votre-site.com/success',
    cancel_url: 'https://votre-site.com/cancel',
    // Utiliser client_reference_id pour votre propre suivi
    client_reference_id: 'my_internal_ref_123',
    // Utiliser metadata pour l'attribution Selgeo
    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://votre-site.com/success",
        cancel_url="https://votre-site.com/cancel",
        # Utiliser client_reference_id pour votre propre suivi
        client_reference_id="my_internal_ref_123",
        # Utiliser metadata pour l'attribution Selgeo
        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://votre-site.com/success',
    'cancel_url' => 'https://votre-site.com/cancel',
    // Utiliser client_reference_id pour votre propre suivi
    'client_reference_id' => 'my_internal_ref_123',
    // Utiliser metadata pour l'attribution Selgeo
    'metadata' => [
        'aff_click_id' => $data['clickId'] ?? '',
    ],
]);

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

Comment Selgeo traite les métadonnées

Pour les événements checkout.session.completed, Selgeo vérifie le click_id dans cet ordre :

1. client_reference_id sur la Session de paiement (si présent et est un UUID valide).
2. metadata.aff_click_id sur la Session de paiement.

Si les deux sont présents, client_reference_id a la priorité. Cela signifie que vous pouvez définir les deux en toute sécurité sans conflit — Selgeo utilisera celui qu'il trouve en premier.

Pour les événements invoice.paid (factures initiales sans Session de paiement précédente), Selgeo vérifie metadata.aff_click_id et metadata.aff_promo_code directement sur l'objet Facture.

Abonnements récurrents

Pour les abonnements créés via Checkout (mode: 'subscription'), vous n'avez besoin de passer aff_click_id que lors de la création de la Session de paiement. Selgeo attribue la conversion initiale depuis l'événement checkout.session.completed et attribue automatiquement les paiements de factures ultérieurs (renouvellements) au même partenaire en faisant correspondre l'ID client Stripe. Vous n'avez pas besoin de passer à nouveau le click_id lors des renouvellements.

Valeurs vides

Si le visiteur n'a pas été référé par un partenaire (clickId est null), vous pouvez soit :

• Omettre la clé entièrement — ne pas inclure aff_click_id dans les métadonnées.
• Passer une chaîne vide — aff_click_id: ''. Selgeo ignore les chaînes vides.

Les deux approches sont sûres. L'objet Stripe est créé normalement, et Selgeo le traite comme une conversion non référée.

Tests

1. Créez un lien de suivi et un partenaire de test dans le tableau de bord Selgeo.
2. Visitez votre site via le lien de suivi pour enregistrer un clic.
3. Déclenchez votre flux de paiement — le click_id doit être passé à votre backend et inclus dans les métadonnées Stripe comme aff_click_id.
4. Complétez le paiement en utilisant la carte de test Stripe 4242 4242 4242 4242.
5. Vérifiez le tableau de bord Selgeo — vérifiez que la conversion apparaît et est attribuée au partenaire de test.

Vérifier les métadonnées dans Stripe

Vous pouvez confirmer que les métadonnées ont été correctement définies dans le Tableau de bord Stripe :

1. Trouvez la Session de paiement.
2. Faites défiler jusqu'à la section Métadonnées.
3. Vérifiez que aff_click_id contient l'UUID attendu.

Comparaison des méthodes d'attribution

Méthode	Objet Stripe	Clé	Idéal pour
client_reference_id	Session de paiement uniquement	client_reference_id	Intégrations Checkout simples
metadata.aff_click_id	Session de paiement	metadata.aff_click_id	Quand client_reference_id est déjà utilisé pour d'autres besoins
Réécriture automatique des Liens de paiement	URL du Lien de paiement	client_reference_id (paramètre de requête)	Liens de paiement Stripe sans backend

Prochaines étapes

• API de conversion — pour les conversions non-Stripe
• Webhooks — recevoir des notifications quand les conversions sont attribuées
• Mode test — guide de test détaillé