Integrations
Stripe Checkout
Count purchases paid through Stripe Checkout, tied to the visit they came from, so purchases agents made and purchases people made report separately. Works for one-off payments and subscriptions, and for payment methods that settle later.
How the purchase finds its visit
Stripe doesn't tell anyone the shopper's address, so your server seals the visit into the Checkout Session when it creates it: a visit token in the session's metadata. It holds the visitor's address and user agent, as your install reports them for page views, encrypted with a key from your site's secret. Stripe stores it as an opaque string; only Punchline can open it, and only for 24 hours.
When Stripe reports the payment, Punchline opens the token, finds the visit, and records a purchase with the amount and currency. A purchase an agent made counts as the agent's. Without a token (a Payment Link, say) the purchase is still counted, not tied to a visit.
1. Add the token when you create the session
With the Next.js package 0.6.0 or later, in the route that creates the session:
import { visitToken } from "@punchline-analytics/next";
export async function POST(request: Request) {
const session = await stripe.checkout.sessions.create({
// … your line items, mode, success_url …
metadata: { pl_visit: (await visitToken(request)) ?? "" },
});
return Response.redirect(session.url!, 303);
}
In a Cloudflare Worker, visitToken(request, env) from @punchline-analytics/cloudflare does the same.
2. Add the webhook in Stripe
- In Punchline: Site settings → Install → Stripe Checkout. Copy the webhook address. Keep it private: anyone with it can add purchases to the site.
- In Stripe: Developers → Webhooks → Add endpoint. Paste the address. Events:
checkout.session.completedandcheckout.session.async_payment_succeeded. Save. - Make a purchase. It appears under Events as
purchasewithin a minute.
Test-mode payments are ignored, so they never mix with real ones. To check the setup in test mode, add a test-mode endpoint with &test=1 at the end of the address.
What's kept
The amount and currency, whether it was a one-off payment or a subscription, and stripe_checkout as the channel. Never the customer's name, email, address or card details, and never what was bought. The visitor's address and user agent from the token are used in memory to find the visit, then discarded, as for page views.
- Each Checkout Session counts once, however often Stripe retries.
- Unpaid sessions (a bank debit still settling) wait for
checkout.session.async_payment_succeeded. - Paid more than half an hour after the token was made? Still counted. It's tied to the visit when the visit happened within half an hour before the session was created.
Ask the docs
Answers come from these docs only, written by Claude (Anthropic). Your question is sent to answer it, and isn't stored.