Configurer le tracking Stripe Checkout pour la rétro-attribution

Pourquoi c'est important

Si vous vendez via Stripe Checkout (ou Payment Links buy.stripe.com), vos visiteurs achètent avant d'avoir soumis un formulaire de lead. Sans configuration, Metrikia ne peut pas relier les touchpoints anonymes (les 5 pubs Meta vues sur 3 jours par exemple) au lead créé au moment du paiement.

Le mécanisme s'appuie sur l'identifiant du visiteur (mtk_vid) transmis à Stripe, dans les métadonnées de la session (clé mtk_vid) ou dans client_reference_id. Sur un lien de paiement Stripe, le pixel Metrikia l'ajoute automatiquement ; quand votre serveur crée la session, c'est lui qui le transmet. Quand Stripe confirme le paiement, Metrikia reçoit cet identifiant et rétro-attribue tous les touchpoints anonymes du visiteur au lead nouvellement créé.

Prérequis

• Pixel Metrikia v2.0+ posé sur toutes vos pages publiques (la rétro-attribution ne fonctionne pas sur les visiteurs qui n'ont jamais vu le pixel).
• Webhook Stripe configuré côté Metrikia (réglage Intégrations).

Votre serveur crée la session Stripe (paiement intégré à la page, redirection côté serveur)

Si le formulaire de paiement Stripe s'affiche directement dans votre page (Checkout intégré), ou si votre serveur crée la session puis redirige l'acheteur vers Stripe, il n'y a aucun lien Stripe dans la page que le pixel puisse compléter. C'est votre serveur qui transmet l'identifiant du visiteur à Stripe, au moment où il crée la Checkout Session.

1. Récupérez l'identifiant du visiteur. Côté serveur, lisez le cookie mtk_vid de la requête : il est posé sur votre domaine principal (SameSite=Lax, conservé 365 jours), donc votre API sur un sous-domaine le reçoit si la requête qui crée la session envoie déjà les cookies. N'activez pas l'envoi des cookies uniquement pour cela : sans réponse CORS adaptée de votre API, la requête échouerait, et le paiement avec. Sinon, lisez-le dans le navigateur avec window.MetrikiaPixel?.getVisitorId() et envoyez la valeur avec la demande de paiement.
2. Ajoutez-le à la session. À la création de la Checkout Session, ajoutez la clé mtk_vid dans son metadata. Ne la mettez jamais dans payment_intent_data.metadata : Metrikia ne lit que les métadonnées de la session. Vous pouvez aussi passer l'identifiant en client_reference_id si vous n'utilisez pas déjà ce champ ; Metrikia lit metadata.mtk_vid en premier.
3. Si l'identifiant est vide, n'envoyez rien. Pas de clé mtk_vid, jamais la valeur "null" ou "undefined", jamais un autre identifiant à la place (identifiant client, e-mail). Ne bloquez jamais le paiement pour attendre l'identifiant.
4. Gardez la page de retour. Laissez ?session_id={CHECKOUT_SESSION_ID} dans l'URL de retour (return_url pour le paiement intégré, success_url pour la page Stripe hébergée), et gardez le pixel chargé sur cette page. Stripe remplace la variable par l'identifiant de la session : si l'identifiant du visiteur manque, cette page relie quand même la vente à la visite, même quand l'acheteur y arrive plusieurs minutes après son paiement. Elle ne couvre que les acheteurs qui la voient : l'identifiant du visiteur transmis à la session reste le moyen le plus complet.

Exemple côté serveur :

/* Côté serveur (exemple Node.js) */
const fromCookie = req.cookies ? req.cookies.mtk_vid : undefined;
const fromBody = req.body ? req.body.mtkVid : undefined;
const visitorId = fromCookie || fromBody;
const metadata = {};
if (typeof visitorId === 'string' && visitorId !== '') {
  metadata.mtk_vid = visitorId;
}
const session = await stripe.checkout.sessions.create({
  /* vos paramètres actuels (line_items, mode, ui_mode...) ; ajoutez vos autres métadonnées à metadata */
  metadata,
  /* Checkout intégré : return_url. Page Stripe hébergée : success_url, avec la même valeur */
  return_url: 'https://www.votre-site.com/paiement/merci?session_id={CHECKOUT_SESSION_ID}',
});

Consentement. Par défaut, le pixel mesure dès son chargement. Il attend l'accord du visiteur seulement si votre site utilise Google Consent Mode (analytics_storage ou ad_storage refusé) ou appelle mtk('consent', 'denied') : pas de cookie, pas de visite mesurée, et getVisitorId() renvoie null tant que le refus tient. C'est le cas de l'étape 3 : n'envoyez rien. Sans Consent Mode, votre site déclare le choix du visiteur avec mtk('consent', 'granted') ou mtk('consent', 'denied'). Si le pixel n'a pas encore démarré, mtk('ready', function (visitorId) { ... }) vous donne l'identifiant dès qu'il est prêt, et seulement une fois le consentement accordé : ne retardez jamais le paiement pour l'attendre.

Vérifier. Faites un achat, puis dans le Dashboard Stripe, menu Développeurs, Workbench, onglet Événements, ouvrez l'événement checkout.session.completed de cet achat : son objet metadata doit contenir mtk_vid avec une valeur de 64 caractères. La page du paiement affiche les métadonnées du paiement, pas celles de la session : mtk_vid n'y apparaît pas, c'est normal.

Payment Element sans Checkout Session. Seul l'événement checkout.session.completed relie une vente à une visite. Une intégration par Payment Element ou par PaymentIntent utilisée sans Checkout Session ne relie pas la vente à la visite. Si c'est votre cas, contactez le support.

Méthode 1 : lien de paiement Stripe (buy.stripe.com), rien à configurer

Si votre bouton de paiement est un <a> qui pointe vers un lien de paiement Stripe (https://buy.stripe.com/...), vous n'avez rien à faire : le pixel Metrikia ajoute l'identifiant du visiteur au lien (client_reference_id) avant le clic. Une session Checkout (https://checkout.stripe.com/...) est créée par votre serveur : suivez la section « Votre serveur crée la session Stripe ».

Vérification :

1. Ouvrez votre page de paiement dans un navigateur.
2. Console développeur (F12) → onglet "Eléments".
3. Inspectez le bouton de paiement.
4. Vous devez voir client_reference_id=<long-hex> dans le href.

Si le paramètre n'apparaît pas, c'est que :

• Le pixel n'est pas chargé sur cette page (vérifiez le <script src="metrikia-pixel.js"> dans le HTML).
• Le bouton est ajouté dynamiquement après le chargement et le MutationObserver n'a pas eu le temps de le tagger : appelez manuellement window.mtk('stripeify') après votre rendu.

Méthode 2: Bouton custom avec data-checkout

Si votre bouton est un lien <a> vers votre propre site (par exemple /start-checkout) qui crée ensuite la session et envoie l'acheteur vers Stripe, ajoutez-lui l'attribut data-checkout :

<a data-checkout href="https://votre-app.com/start-checkout">Acheter</a>

Le pixel ajoute client_reference_id à tout lien marqué data-checkout. Le serveur derrière ce lien doit relire client_reference_id dans l'URL et le passer à Stripe à la création de la session (en client_reference_id ou dans metadata.mtk_vid), et ne rien passer quand le paramètre est absent.

Un <button> sans lien n'est pas complété par le pixel. Si votre bouton appelle votre serveur en JavaScript plutôt que de suivre un lien, lisez l'identifiant dans le navigateur, envoyez-le avec la requête, puis ajoutez-le à la session comme dans la section « Votre serveur crée la session Stripe » :

/* Lire l'identifiant du visiteur côté navigateur */
const mtkVid = window.MetrikiaPixel ? window.MetrikiaPixel.getVisitorId() : null;
fetch('/start-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(mtkVid ? { mtkVid } : {}),
});

/* Côté backend (exemple PHP) */
$params = [
    /* ... vos paramètres */
];
if (!empty($request->mtkVid)) {
    $params['metadata']['mtk_vid'] = $request->mtkVid;
}
$session = \Stripe\Checkout\Session::create($params);

Vérifier que la rétro-attribution fonctionne

1. Ouvrez votre site en navigation privée (cookies vierges), depuis une URL qui porte des paramètres UTM de test (par exemple ?utm_source=test&utm_campaign=verification-stripe), et acceptez les cookies si une bannière s'affiche.
2. Naviguez sur 2-3 pages.
3. Cliquez sur votre bouton de paiement.
4. Terminez un achat. Si votre compte Stripe est relié à Metrikia en mode réel, un paiement en mode test ne lui parvient pas : faites un petit achat réel, que vous pourrez rembourser ensuite.
5. Dans le Dashboard Stripe, menu Développeurs, Workbench, onglet Événements, ouvrez l'événement checkout.session.completed de cet achat : metadata.mtk_vid ou client_reference_id porte l'identifiant du visiteur.
6. Dans Metrikia, ouvrez CRM (/app/crm), onglet Leads, puis le lead créé par l'achat : son onglet Historique affiche Vente créée.
7. Ouvrez Attribution MTA (/app/attribution), tableau Parcours client, et dépliez le parcours de cette vente.

Vous devez y voir votre visite de test avant la colonne Achat.

Problèmes fréquents

• "Le client_reference_id apparaît dans l'URL mais le webhook reçoit null" : vérifiez que votre intégration Stripe ne réinitialise pas les paramètres. Sur Stripe Payment Links, le paramètre est conservé. Sur une session créée côté serveur, vous devez le passer explicitement.
• "Le visiteur a un mtk_vid mais aucun touchpoint apparaît avant le checkout" : le pixel n'a probablement pas été chargé sur les pages de pub. Vérifiez que le tag est posé partout, pas seulement sur la page de paiement.
• "J'ai changé de domaine entre le pixel et Stripe" : c'est normal, client_reference_id traverse le domaine. Le cookie mtk_vid reste sur votre site, le client_reference_id voyage en query string vers Stripe puis revient en webhook.