Stripe Checkout

Si vous créez des Sessions de paiement Stripe sur votre serveur, vous devez passer le click_id du navigateur à votre backend et l'inclure comme client_reference_id lors de la création de la session. Selgeo lit cette valeur depuis le webhook Stripe et attribue la conversion au partenaire référent.

Version API : v1

Prérequis

• Le snippet Selgeo est installé sur votre site web (Configuration du snippet)
• Vous créez des Sessions de paiement Stripe sur votre backend
• Votre compte Stripe est connecté à Selgeo dans le tableau de bord (Paramètres > Stripe)

Fonctionnement

┌────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│    Navigateur   │      │   Votre Serveur  │      │    Selgeo API    │
│                 │      │                  │      │                  │
│ 1. Visiteur     │      │                  │      │                  │
│    arrive via   │      │                  │      │                  │
│    ?ref=abc123  │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 2. Snippet      │─────>│                  │─────>│ Enregistre clic  │
│    enregistre   │      │                  │      │ Retourne click_id│
│    clic         │<─────│                  │<─────│                  │
│                 │      │                  │      │                  │
│ 3. Utilisateur  │─────>│ 4. Crée Session  │      │                  │
│    clique       │      │    de paiement   │      │                  │
│    "S'abonner"  │      │    avec          │      │                  │
│    (envoie      │      │    client_ref_id │      │                  │
│     clickId)    │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 5. Redirection  │<─────│                  │      │                  │
│    vers Stripe  │      │                  │      │                  │
│    Checkout     │      │                  │      │                  │
│                 │      │                  │      │                  │
│ 6. Client paie  │      │                  │      │                  │
│                 │      │                  │      │                  │
│                 │      │                  │      │ 7. Webhook Stripe │
│                 │      │                  │      │    inclut         │
│                 │      │                  │      │    client_ref_id  │
│                 │      │                  │      │    → Selgeo       │
│                 │      │                  │      │    attribue       │
└────────────────┘      └──────────────────┘      └──────────────────┘

Implémentation

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

Après que le snippet ait chargé et capturé un clic de parrainage, le click_id est disponible via :

const clickId = __selgeo.getClickId();

Cela retourne une chaîne UUID (ex. "f47ac10b-58cc-4372-a567-0e02b2c3d479") ou null si aucun clic de parrainage n'a été enregistré.

Étape 2 : Envoyer l'ID de clic à votre backend

Incluez le click_id lorsque votre frontend demande une Session de paiement à votre serveur :

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;

Étape 3 : Le passer comme client_reference_id lors de la création de la Session 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',
    // Passer le click_id pour que Selgeo puisse attribuer cette conversion
    client_reference_id: clickId || undefined,
  });

  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()
    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://votre-site.com/success",
        cancel_url="https://votre-site.com/cancel",
        # Passer le click_id pour que Selgeo puisse attribuer cette conversion
        client_reference_id=click_id if click_id else None,
    )

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

PHP

$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://votre-site.com/success',
    'cancel_url' => 'https://votre-site.com/cancel',
    // Passer le click_id pour que Selgeo puisse attribuer cette conversion
    'client_reference_id' => $clickId,
]);

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

Passer undefined, pas une chaîne vide

S'il n'y a pas de click_id (le visiteur n'a pas été référé par un partenaire), passez undefined (JavaScript), None (Python), ou null (PHP) pour client_reference_id. Ne passez pas une chaîne vide — Stripe la stockera comme la valeur littérale "", que Selgeo ne peut pas associer à un clic.

Checkout intégré

Si vous utilisez Stripe Embedded Checkout plutôt que le Checkout par redirection, le flux est identique. Vous créez toujours une Session de paiement sur votre serveur avec client_reference_id et passez le client_secret au 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://votre-site.com/success?session_id={CHECKOUT_SESSION_ID}',
    // Comme pour le Checkout par redirection — passer le click_id ici
    client_reference_id: clickId || undefined,
  });

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

Selgeo lit client_reference_id depuis le webhook Stripe, que vous utilisiez le Checkout par redirection ou intégré.

Gérer le cas null

Quand __selgeo.getClickId() retourne null, cela signifie l'une des situations suivantes :

• Le visiteur n'est pas arrivé via un lien de parrainage partenaire.
• Le sessionStorage du visiteur a été effacé (ex. il a fermé et rouvert l'onglet).
• Le snippet n'a pas encore chargé (ex. le chargement asynchrone est encore en cours).

Dans tous les cas, vous devez quand même créer la Session de paiement normalement — omettez simplement client_reference_id. La conversion se déroulera comme une vente non référée :

const clickId = __selgeo.getClickId();

// Toujours créer le paiement, qu'il y ait ou non un clickId
const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_xxx',
    clickId: clickId, // null est acceptable — votre backend doit le gérer
  }),
});

Tests

1. Configurez un partenaire de test et un lien de suivi. Invitez un partenaire de test dans le tableau de bord marchand, puis connectez-vous au portail partenaire en tant que ce partenaire et créez un lien de parrainage (sous Liens). Les liens de suivi ne sont pas créés dans le tableau de bord marchand.
2. Visitez votre site via le lien de suivi : https://votre-site.com/?ref=VOTRE_REF_TEST
3. Vérifiez l'ID de clic dans la console du navigateur :

   __selgeo.getClickId() // Doit retourner un UUID

4. Déclenchez votre flux de paiement. Le click_id doit être passé à votre backend.
5. Complétez le paiement en utilisant la carte de test Stripe 4242 4242 4242 4242.
6. Vérifiez le tableau de bord Selgeo — la conversion doit apparaître attribuée au partenaire de test.

Comparaison avec les Liens de paiement

Fonctionnalité	Liens de paiement	Sessions de paiement
Code backend requis	Non	Oui (créer la session)
Code frontend requis	Non	Oui (lire click_id)
Prend en charge les abonnements	Oui	Oui
Prend en charge les paiements uniques	Oui	Oui
Prend en charge le checkout intégré	Non	Oui
Flux de paiement personnalisé	Non	Oui

Si vous avez seulement besoin d'un simple bouton d'achat et ne personnalisez pas le flux de paiement, les Liens de paiement Stripe sont l'option la plus simple.

Prochaines étapes

• Stripe Metadata — utiliser les métadonnées de Session de paiement plutôt que client_reference_id
• API de conversion — pour les conversions non-Stripe
• Mode test — guide détaillé pour les tests