Stripe

Stripe sends payments, subscriptions, refunds, and disputes to Datalyr through the Stripe Connect webhook.

Connect

Open the source

Open Sources, find Stripe, and select connect.

Authorize the account

Complete the Stripe OAuth flow. Choose the Stripe account this workspace bills through.

Stamp the visitor ID

Follow the two sections below that match your checkout.

We own the endpoint https://webhooks.datalyr.com/stripe-connect and its signing secret, so you create no endpoint in Stripe.

Do not re-create the retired endpoint https://webhooks.datalyr.com/stripe/WORKSPACE_PUBLIC_ID. It returns HTTP 410, and the payments you send there are recorded nowhere.

Link payments to a web visitor

Pass the visitor ID whenever you create the Stripe object yourself. It’s the only deterministic link to the web visit. Without it, we fall back to email matching.

Checkout Sessions

const datalyrStripe = datalyr.getStripeMetadata()
// { client_reference_id: 'anon_…', metadata: { visitor_id: 'anon_…' } }

const session = await stripe.checkout.sessions.create({
  ...datalyrStripe,
  mode: 'subscription',
  line_items: [{ price: 'price_123', quantity: 1 }],
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/pricing'
})

The Checkout handler reads client_reference_id and nothing else, so metadata.visitor_id is ignored on a Checkout Session.

PaymentIntents, Subscriptions, and Customers

const visitorId = datalyr.getVisitorId()

await stripe.paymentIntents.create({
  amount: 9900,
  currency: 'usd',
  metadata: { visitor_id: visitorId }
})

await stripe.subscriptions.create({
  customer: 'cus_123',
  items: [{ price: 'price_123' }],
  metadata: { visitor_id: visitorId }
})

Each of these handlers reads metadata.visitor_id, then metadata.datalyr_id.

Payment Links and embeds

The Web SDK decorates these automatically. It never touches checkout.stripe.com Session URLs.

Target	What the SDK writes
`<a href>` to host `buy.stripe.com`	`client_reference_id` query parameter
`<a href>` to a host in `stripeLinkDomains`	`client_reference_id` query parameter
`<stripe-pricing-table>`	`client-reference-id` attribute
`<stripe-buy-button>`	`client-reference-id` attribute

The SDK also adds prefilled_email after identify(), unless privacyMode is strict. Your own value always wins. Set stripePaymentLinks: false to disable this. window.open(paymentLink) calls and links inside an iframe or shadow DOM are not decorated.

Identity resolution

We resolve the visitor in this order, per event.

Order	Source
1	The visitor ID field for that object type, listed above
2	A `/internal/attribution/lookup-visitor` call on that ID
3	The customer email, when step 2 returned no ad click ID
4	For `customer.subscription.created`, a cached customer-to-visitor entry

Term	Meaning
Ad click ID	`fbclid`, `gclid`, `ttclid`, `gbraid`, `wbraid`, `oppref`, `sclid`, `msclkid`, `twclid`, `li_fat_id`, `epik`, `dclid`, or `utm_source`

No match writes a synthetic visitor_id: stripe_<customer_id>, or stripe_guest_<hash> for a guest with an email, or stripe_<object_id>. Refund and dispute rows always use stripe_refund_<id> and stripe_dispute_<id>, with no lookup.

Event mapping

The Datalyr event name equals the Stripe event type, except where this table says otherwise.

Stripe event type	Datalyr event	`value`
`checkout.session.completed`	`checkout.session.completed`	`amount_total`; `0` when the session has an invoice
`checkout.session.async_payment_succeeded`	`checkout.session.completed`	Same as above
`payment_intent.succeeded`	`payment_intent.succeeded`	`amount_received`
`invoice_payment.paid`	`invoice.payment_succeeded`	`amount_paid`
`refund.created`, `refund.updated`	`charge.refunded`	Negative `refund.amount`
`refund.failed`	`charge.refunded` and `refund.failed`	Negative, then positive
`charge.dispute.funds_withdrawn`	`charge.disputed`	Negative dispute amount
`charge.dispute.funds_reinstated`	`charge.dispute_won`	Positive dispute amount
`customer.subscription.created`	`customer.subscription.created`	`0`
`customer.subscription.updated`	`customer.subscription.updated`	`0`
`customer.subscription.deleted`	`customer.subscription.deleted`	`0`
`customer.created`	`customer.created`	`0`
Any other type	The Stripe type string, unchanged	`0`

These six types return 200 and record nothing.

Ignored Stripe type	The money arrives as
`invoice.payment_succeeded`	`invoice_payment.paid`
`charge.refunded`	`refund.created`, `refund.updated`
`charge.dispute.created`	`charge.dispute.funds_withdrawn`
`charge.dispute.updated`	`charge.dispute.funds_withdrawn`
`charge.dispute.closed`	`charge.dispute.funds_reinstated`
`checkout.session.async_payment_failed`	Nothing. The payment failed

checkout.session.completed records nothing when payment_status is not paid.

Revenue

The event value is gross, before tax and processor fees. We divide the Stripe minor-unit amount by a per-currency divisor:

Currencies	Divisor
`BIF`, `CLP`, `DJF`, `GNF`, `JPY`, `KMF`, `KRW`, `MGA`, `PYG`, `RWF`, `VND`, `VUV`, `XAF`, `XOF`, `XPF`	1
`BHD`, `IQD`, `JOD`, `KWD`, `LYD`, `OMR`, `TND`	1000
Everything else, including `ISK`, `HUF`, `TWD`, `UGX`	100

Reported net revenue is cash, minus refunds, minus dispute withdrawals, plus reinstatements. Processor fees arrive as a separate non-cash row, stripe.balance_transaction.fee_fact, with value 0:

provider_net_minor = gross_amount_minor − fee_effect_minor

We serve net proceeds only when every cash movement has a matching fee fact. Otherwise the value is null.

USD conversion is all-or-nothing per hour. A missing FX rate for one event nulls revenue_usd, net_revenue_usd, refund_amount_usd, dispute_amount_usd, and mrr_usd for that hour. fx_coverage_ratio reports how much of the hour converted.

Top-level currency is the real Stripe currency, uppercased. We apply no conversion at write time.

Delivery behavior

Case	Response
Event `livemode` differs from the connected account	200, records nothing
Same event twice	200 `duplicate: true`, deduplicated on the Stripe event ID for 7 days
Over 1000 events per minute per workspace	429 with `Retry-After: 60`
Signature timestamp more than 300 seconds old or ahead	401

We accept multiple v1= signatures, so rotating your secret won’t break delivery.

Subscription state

We compute MRR from subscription items with exact decimal arithmetic. MRR is unavailable for a subscription that is paused, discounted, metered, tiered, on a schedule, priced with transformed_quantity, mixed-currency, or non-fixed. active_mrr_usd is served only when the baseline snapshot is complete and no subscription is incomplete.

Every HTTP status

Status	Cause
200	Processed, duplicate, livemode mismatch, unlinked account, or inactive connection
401	`Stripe-Signature` missing, malformed, stale, or not matching
405	The request method is not `POST`
429	Over 1000 events per minute for this workspace
500	The Connect signing secret is unset, or a handler threw
503	Workspace lookup, livemode authority, or Stripe credential unavailable

Every 503 carries Retry-After, so Stripe redelivers. We never answer 200 for an infrastructure failure, because that would drop the payment.

Verify

Open your pricing page in a private window with ?utm_source=doctest.
Open Events. Confirm a pageview row exists.
Complete one Stripe test payment through your production code path.
Open Events. Find the checkout.session.completed or payment_intent.succeeded row.
Confirm value, currency, and event_data.ledger_type.
Confirm visitor_id does not start with stripe_.

When it does not work

Symptom	Cause	Fix
No events at all	The Stripe account is linked to no active connection	Reconnect Stripe in Sources
HTTP 410 in Stripe’s webhook log	You created a `/stripe/…` endpoint	Delete it. Datalyr owns the endpoint
`visitor_id` starts with `stripe_`	The identity field never reached Stripe	Pass `client_reference_id` on Checkout, `metadata.visitor_id` elsewhere
Test payments missing	The connection is live-mode	Connect the test-mode Stripe account separately
Renewals counted twice	You read both `checkout.session.completed` and `invoice.payment_succeeded` as cash	Filter on `event_data.ledger_type`
`revenue_usd` is empty	One event in the hour had no FX rate	Check `fx_coverage_ratio` for that hour

Next, create a conversion rule so these payments reach your ad platforms.

Get started

Installation

Revenue

Using Datalyr

Advanced

Integrations

Account & billing

Troubleshooting

Connect

Link payments to a web visitor

Checkout Sessions

PaymentIntents, Subscriptions, and Customers

Payment Links and embeds

Identity resolution

Event mapping

Revenue

Delivery behavior

Subscription state

Every HTTP status

Verify

When it does not work

​Connect

​Link payments to a web visitor

​Checkout Sessions

​PaymentIntents, Subscriptions, and Customers

​Payment Links and embeds

​Identity resolution

​Event mapping

​Revenue

​Delivery behavior

​Subscription state

​Every HTTP status

​Verify

​When it does not work

Connect

Link payments to a web visitor

Checkout Sessions

PaymentIntents, Subscriptions, and Customers

Payment Links and embeds

Identity resolution

Event mapping

Revenue

Delivery behavior

Subscription state

Every HTTP status

Verify

When it does not work