Configure Stripe Checkout tracking for back-attribution

Why this matters

If you sell via Stripe Checkout (or Payment Links buy.stripe.com), your visitors pay before submitting a lead form. Without configuration, Metrikia cannot link the anonymous touchpoints (5 Meta ads viewed over 3 days for example) to the lead created at payment time.

The mechanism relies on the visitor id (mtk_vid) passed to Stripe, in the session metadata (mtk_vid key) or in client_reference_id. On a Stripe Payment Link, the Metrikia pixel adds it automatically; when your server creates the session, your server passes it. When Stripe confirms the payment, Metrikia receives this id and back-attributes every anonymous touchpoint of the visitor to the newly created lead.

Prerequisites

• Metrikia pixel v2.0+ deployed on all your public pages (back-attribution does not work on visitors who never saw the pixel).
• Stripe webhook configured on the Metrikia side (Integrations settings).

Your server creates the Stripe session (payment embedded in the page, server-side redirect)

If the Stripe payment form is displayed inside your page (embedded Checkout), or if your server creates the session and then redirects the buyer to Stripe, there is no Stripe link in the page for the pixel to complete. Your server passes the visitor id to Stripe when it creates the Checkout Session.

1. Get the visitor id. Server side, read the mtk_vid cookie from the request: it is set on your root domain (SameSite=Lax, kept 365 days), so your API on a subdomain receives it if the request that creates the session already sends cookies. Do not turn on sending cookies just for this: without a matching CORS answer from your API, the request would fail, and the payment with it. Otherwise, read it in the browser with window.MetrikiaPixel?.getVisitorId() and send the value with the payment request.
2. Add it to the session. When creating the Checkout Session, add the mtk_vid key to its metadata. Never put it in payment_intent_data.metadata: Metrikia reads only the session metadata. You can also pass the id as client_reference_id if you do not already use that field; Metrikia reads metadata.mtk_vid first.
3. If the id is empty, send nothing. No mtk_vid key, never the value "null" or "undefined", never another id in its place (customer id, email). Never block the payment to wait for the id.
4. Keep the return page. Leave ?session_id={CHECKOUT_SESSION_ID} in the return URL (return_url for the embedded payment, success_url for the hosted Stripe page), and keep the pixel loaded on that page. Stripe replaces the variable with the session id: when the visitor id is missing, this page still links the sale to the visit, even when the buyer reaches it several minutes after paying. It only covers the buyers who see it: the visitor id passed to the session remains the most complete way.

Server-side example:

/* Server side (Node.js example) */
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({
  /* your current parameters (line_items, mode, ui_mode...); add your other metadata to metadata */
  metadata,
  /* Embedded Checkout: return_url. Hosted Stripe page: success_url, same value */
  return_url: 'https://www.your-site.com/payment/thank-you?session_id={CHECKOUT_SESSION_ID}',
});

Consent. By default, the pixel measures as soon as it loads. It waits for the visitor's consent only if your site uses Google Consent Mode (analytics_storage or ad_storage denied) or calls mtk('consent', 'denied'): no cookie, no visit measured, and getVisitorId() returns null while the refusal holds. That is the case of step 3: send nothing. Without Consent Mode, your site declares the visitor's choice with mtk('consent', 'granted') or mtk('consent', 'denied'). If the pixel has not started yet, mtk('ready', function (visitorId) { ... }) gives you the id as soon as it is ready, and only once consent is granted: never delay the payment to wait for it.

Check. Make a purchase, then in the Stripe Dashboard, Developers menu, Workbench, Events tab, open the checkout.session.completed event of that purchase: its metadata object must contain mtk_vid with a 64-character value. The payment page shows the payment metadata, not the session metadata: mtk_vid does not appear there, which is normal.

Payment Element without a Checkout Session. Only the checkout.session.completed event links a sale to a visit. An integration with the Payment Element or a PaymentIntent used without a Checkout Session does not link the sale to the visit. If that is your case, contact support.

Method 1: Stripe Payment Link (buy.stripe.com), nothing to configure

If your checkout button is an <a> pointing to a Stripe Payment Link (https://buy.stripe.com/...), you have nothing to do: the Metrikia pixel adds the visitor id to the link (client_reference_id) before the click. A Checkout session (https://checkout.stripe.com/...) is created by your server: follow the section "Your server creates the Stripe session".

Verification:

1. Open your payment page in a browser.
2. Dev console (F12) → "Elements" tab.
3. Inspect the payment button.
4. You should see client_reference_id=<long-hex> in the href.

If the parameter does not appear, it means:

• The pixel is not loaded on this page (check <script src="metrikia-pixel.js"> in the HTML).
• The button is added dynamically after page load and the MutationObserver has not had time to tag it: manually call window.mtk('stripeify') after your render.

Method 2: Custom button with data-checkout

If your button is an <a> link to your own site (for example /start-checkout) that then creates the session and sends the buyer to Stripe, add the data-checkout attribute to it:

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

The pixel adds client_reference_id to every link marked data-checkout. The server behind this link must read client_reference_id from the URL and pass it to Stripe when it creates the session (as client_reference_id or in metadata.mtk_vid), and pass nothing when the parameter is absent.

The pixel does not complete a <button> without a link. If your button calls your server in JavaScript instead of following a link, read the id in the browser, send it with the request, then add it to the session as in the section "Your server creates the Stripe session":

/* Read the visitor id in the browser */
const mtkVid = window.MetrikiaPixel ? window.MetrikiaPixel.getVisitorId() : null;
fetch('/start-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(mtkVid ? { mtkVid } : {}),
});

/* Backend (PHP example) */
$params = [
    /* ... your parameters */
];
if (!empty($request->mtkVid)) {
    $params['metadata']['mtk_vid'] = $request->mtkVid;
}
$session = \Stripe\Checkout\Session::create($params);

Verify back-attribution works

1. Open your site in a private window (clean cookies), from a URL carrying test UTM parameters (for example ?utm_source=test&utm_campaign=stripe-check), and accept cookies if a banner appears.
2. Navigate 2-3 pages.
3. Click your payment button.
4. Complete a purchase. If your Stripe account is connected to Metrikia in live mode, a test mode payment does not reach it: make a small real purchase, which you can refund afterwards.
5. In the Stripe Dashboard, Developers menu, Workbench, Events tab, open the checkout.session.completed event of that purchase: metadata.mtk_vid or client_reference_id carries the visitor id.
6. In Metrikia, open CRM (/app/crm), Leads tab, then the lead created by the purchase: its Timeline tab shows Deal created.
7. Open MTA Attribution (/app/attribution), Customer Journeys table, and expand the journey of this sale.

You should see your test visit before the Purchase column.

Common issues

• "client_reference_id appears in the URL but the webhook receives null": check your Stripe integration does not reset parameters. On Stripe Payment Links the parameter is preserved. On a server-created session, you must pass it explicitly.
• "The visitor has an mtk_vid but no touchpoint appears before checkout": the pixel was probably not loaded on ad pages. Check the tag is deployed everywhere, not just on the payment page.
• "I changed domains between the pixel and Stripe": this is normal, client_reference_id crosses the domain. The mtk_vid cookie stays on your site, client_reference_id travels as a query string to Stripe then returns in the webhook.