Documentation

Stripe guide

Create a snapshot endpoint for payment_intent.succeeded, invoice.paid, refund.created, and refund.updated. Store the endpoint's whsec_ secret, not an account API key. Thin events require API retrieval and are unsupported. Official webhook setup.

Verify Stripe-Signature using the literal endpoint secret and HMAC-SHA256 over timestamp.rawBody; accept v1 signatures with a five-minute freshness bound. Multiple rotation signatures are supported, ambiguous duplicate timestamps are rejected. Official SDK implementation.

Only payment_intent.succeeded creates financial revenue, keyed by its PaymentIntent ID, using amount_received and currency. Successful refund.created/refund.updated resources reverse amount against their payment_intent. Pending/failed refunds do not count. PaymentIntent fields, refund fields.

Invoices enrich attribution and renewal classification; invoice allocations never create additional money. Current snapshots use payments.data[].payment.payment_intent and parent.subscription_details; older pinned snapshots with a direct payment_intent are also accepted. An invoice without a PaymentIntent reference is ignored. billing_reason=subscription_cycle supplies renewal classification. Invoice metadata can arrive before or after the financial event. Invoice, Invoice Payment allocations.

On server-created Checkout set payment_intent_data.metadata.ml_visitor_id and ml_session_id; for subscriptions set subscription_data.metadata as well. Optional custom ml_product_id supports product filters on PaymentIntents without expanded product data. Invoice product context can release an earlier payment waiting for its product match. Metadata propagation rules.

A PaymentIntent may pay multiple invoices. Product evidence is combined atomically across all authenticated invoice allocations, and unmatched filtered payments remain pending for later context. If any product matches the filter, the entire PaymentIntent amount is included once; invoice allocations never add revenue. This is transaction-level filtering, with no per-product allocation of money. Invoice Payment allocation semantics.

Hosted links are not auto-tagged. Stripe supports client_reference_id, but that application reference is not arbitrary per-visitor PaymentIntent metadata and is not overwritten. Payment-link URL parameters.

Boundaries: no account OAuth/Connect or API enrichment; no credit-only/out-of-band invoice revenue without a successful PaymentIntent; no automatic allocation of a multi-product transaction among products. Configure the canonical PaymentIntent event alongside invoices.