Payment analytics integrations for Stripe, Dodo, Lemon Squeezy, Paddle and Polar

Payment analytics becomes useful when it answers more than “someone opened checkout.” A trustworthy integration connects an acquisition visit and the product actions that followed it to provider-verified commercial outcomes: first payment, renewal, expansion, refund, dispute, cancellation, failed payment and recovery. The browser can describe intent. It cannot establish money truth or change an entitlement.

MetricFold supports Dodo Payments, Stripe, Lemon Squeezy, Paddle, Polar and a signed generic webhook through one normalized revenue contract. Provider differences remain at the adapter boundary, while reports use stable definitions. This guide explains the shared installation model and the provider-specific metadata handoff. Read revenue attribution for the reporting model and SaaS analytics for the wider subscription lifecycle.

Use the same five-stage contract for every gateway

1. Collect the landing page, allowed campaign parameters and referrer as first-party analytics.
2. Request a short-lived attribution token from MetricFold for the current analytics site and visit.
3. Add only that opaque token to the provider checkout metadata or custom-data field.
4. Receive the payment provider webhook on your server and verify its signature against the raw body.
5. Let the MetricFold provider adapter redeem the token and record the normalized event once.

The token is correlation data, not a bearer credential. It must not contain an email address, payment details or a permanent cross-site profile. It expires, is scoped to one analytics site and can be redeemed only through the trusted server path.

Stripe attribution handoff

Stripe Checkout supports metadata on a Checkout Session, and Stripe documents how that metadata appears in webhook objects. The official Stripe metadata guide explains how Checkout Session metadata is included in the completion webhook. Put the MetricFold attribution token in a dedicated metadata key when the server creates the session. Do not accept a price, product id or paid state from browser JavaScript.

Subscribe only to the events needed for your billing state machine. Verify Stripe's signature with the unmodified request body, scope the object to this product and deduplicate by Stripe event id. A checkout.session.completed event may describe initial success, while subscription, invoice, refund and dispute events carry later lifecycle truth. Preserve the original acquisition context for renewals instead of presenting each renewal as a new acquisition conversion.

Dodo Payments attribution handoff

Dodo webhooks cover payments, subscriptions and abandoned checkout signals. MetricFold's Dodo adapter requires the configured product identifiers because multiple products can share one merchant account. A correctly signed event for a foreign product is acknowledged and ignored. This prevents one SaaS from receiving another product's revenue or entitlement event.

Add the opaque attribution token to the checkout metadata supported by the current Dodo API. The webhook still owns payment state. Process it idempotently and refuse to let a delayed failure overwrite an already paid or delivered terminal state.

Lemon Squeezy attribution handoff

Lemon Squeezy supports checkout custom data both in checkout links and API-created checkouts. Its custom-data documentation shows that custom data is returned under webhook metadata for order, subscription and license-key events. Add a single MetricFold token rather than copying the full UTM set, customer identity or browser fingerprint into the payment provider.

Verify the Lemon Squeezy signing secret on every request. Map order, subscription, renewal, expiry and refund facts to normalized events, then preserve the provider object id for reconciliation. A checkout success callback in the browser remains a UX signal; the signed webhook establishes revenue.

Paddle attribution handoff

Paddle custom data can be attached to a checkout transaction and carried into a recurring subscription and later transactions. That propagation is useful for durable attribution, but it also makes data minimization important. Use an opaque, expiring correlation value rather than a bundle of personal or campaign fields.

Paddle documents at-least-once webhook delivery and recommends idempotency by event id. It also notes that delivery order can differ from occurrence order. Store the provider occurrence time, converge duplicates and apply explicit state transitions so an older event cannot regress a later state.

Polar attribution handoff

Polar checkout-link metadata can propagate to the generated checkout, order and subscription. Put the site-scoped attribution token in that metadata, verify webhook authenticity and normalize the resulting order or subscription event. Treat the success URL as navigation, not settlement evidence.

Normalize provider events without erasing evidence

The normalized record should keep:

• provider and unique provider event id;
• scoped product or price id;
• stable event type;
• amount in integer minor units and explicit currency;
• provider occurrence time;
• hashed product-owned customer or subscription reference where permitted;
• attribution-token status;
• processing and reconciliation status.

Never add unlike currencies into one unlabeled total. Distinguish gross payment, refund, dispute and net revenue. Keep unattributed revenue visible: an expired token, another device, an old checkout link or an installation failure should not make a verified payment disappear.

Test the lifecycle, not only the happy path

A production acceptance suite replays the exact raw provider payload and checks:

Run these cases in each provider's test mode, then inspect MetricFold's revenue, source conversion, time-to-purchase, failed-payment and recovery reports. Confirm secrets and raw payloads do not appear in logs or client responses.

Read acquisition and lifecycle separately

First-touch attribution explains where demand began. Last non-direct touch explains the interaction nearest conversion. The product journey explains which meaningful actions occurred in between. Renewal, expansion, downgrade, failed payment and recovery explain continuing value and payment health. A single “revenue by source” chart cannot replace all four views.

MetricFold keeps those definitions explicit and exposes the same bounded evidence through the dashboard, REST API and MCP. Your AI analyst can compare segments and propose an experiment, but it must not claim a source or feature caused the payment without controlled evidence.

Operate and reconcile the integration

Monitor delivery and freshness

Track the latest provider occurrence time, receipt time, processing time and reconciliation time separately. A green endpoint that has received no events for a week may be misconfigured, while a retrying event can be healthy provider behaviour. Alert on sustained signature failures, foreign product spikes, growing processing lag, reconciliation mismatches and an unexpected rise in unattributed payments. Do not include raw bodies or secrets in those alerts.

Maintain a provider-side test product and a documented smoke sequence. After credential rotation, send one signed test event, confirm the normalized record, then confirm the expected dashboard total. Keep provider API versions and accepted event types explicit so an upstream version change cannot silently alter amount or subscription-state interpretation.

Handle account and product boundaries

A merchant account may contain many products, stores or workspaces. Store the permitted external product identifiers on the site-specific connection and fail closed when a signed event is outside that set. An administrator who can configure the connection does not thereby gain access to another workspace's events. Property-test the adapter with arbitrary foreign identifiers and confirm that acknowledgement never creates money, attribution or entitlement data.

Use a signed generic webhook only when no native adapter exists. Give it the same guarantees: timestamped signature, replay window, idempotency key, explicit currency, integer amount, allowlisted event names and site scope. A generic endpoint is not permission to accept an arbitrary browser JSON shape.

Frequently asked questions

Can I attribute a payment without storing a permanent visitor id?

Yes. A short-lived, site-scoped token can carry the permitted first- and last-touch context from a visit into provider metadata. The verified webhook redeems it once. Payments that occur after expiry or on another device remain trusted revenue but may be unattributed. MetricFold does not invent a fingerprint to fill that gap. The cookieless analytics guide explains the identity boundary.

Should a renewal keep the original source?

Keep the original acquisition context as historical evidence, but label the event as renewal revenue. Do not count it as a second newly acquired customer. Product adoption, customer success and payment recovery may be more useful explanations for retained revenue than the original campaign, so lifecycle reports should remain available beside source reports.

What should an AI analyst receive?

Expose normalized totals, definitions, windows, freshness, unattributed share, sample limits and relevant journey aggregates. Do not provide provider secrets, raw payment payloads or customer payment details. The analyst may identify a segment difference or instrumentation gap and propose a test; it cannot authorize refunds, change access or declare causation.