Guides

Stripe Billing Instrumentation

This guide maps each RecurCite evidence event to the exact location in your Stripe Billing flow where you should add it. Follow this decision map for complete evidence coverage.

Evidence event decision map

Each event type maps to a specific touchpoint in your billing lifecycle. The table below shows where to add each event and why it matters for dispute defense:

Event type	Trigger point	Why it wins disputes	Priority
`terms.accepted`	ToS checkbox click / acceptance modal	Proves customer agreed to refund policy, cancellation terms, and service agreement before purchase	P0 — Critical
`user.login`	Successful authentication callback	Proves customer had account access; IP + user agent strengthen CE3 eligibility	P0 — Critical
`product.used`	Key feature usage (API calls, exports, page views)	Quantifies value delivery — "customer used 150 API calls this month"	P1 — High
`transaction.completed`	`invoice.paid` webhook	CE3 signal collection — IP + email + device matching for Visa liability shift	P1 — High (CE3)
`cancellation.requested`	Cancel button click / cancellation form submission	Proves you offered an accessible cancellation path	P1 — High
`cancellation.confirmed`	`customer.subscription.deleted` webhook	Proves cancellation was processed as promised	P1 — High
`support.ticket.created`	Ticketing system webhook (Zendesk, Intercom, etc.)	Proves customer support was available and accessed	P2 — Medium
`support.ticket.resolved`	Ticket closed/resolved webhook	Proves you addressed the customer's concerns	P2 — Medium

Start with P0

If you only integrate two events, make them terms.accepted and user.login. These alone can dramatically improve your win rate.

Stripe webhook → RecurCite event mapping

If you already handle Stripe webhooks, add RecurCite events alongside your existing handlers:

Stripe webhook	RecurCite event	Key fields to include
`invoice.paid`	`transaction.completed`	charge_id, amount, currency, customer IP, email
`customer.subscription.deleted`	`cancellation.confirmed`	subscription_id, occurred_at
`customer.subscription.updated`	`cancellation.requested` (if cancel_at_period_end changed)	subscription_id, occurred_at

Complete webhook handler example

Stripe webhook handler (any framework)

import { recurcite } from "./lib/recurcite";

// Inside your Stripe webhook handler switch:
switch (event.type) {
  case "invoice.paid":
  case "invoice.payment_succeeded": {
    const invoice = event.data.object;

    // Track for CE3 evidence
    await recurcite.track({
      type: "transaction.completed",
      payload: {
        charge_id: invoice.charge as string,
        amount: invoice.amount_paid,
        currency: invoice.currency,
        occurred_at: new Date(invoice.created * 1000).toISOString(),
        // Include CE3 signals if available:
        // ip: customerIp,
        // email_sha256: customerEmailSha256,
      },
      stripe_refs: {
        stripe_customer_id: invoice.customer as string,
        stripe_subscription_id: invoice.subscription as string,
        stripe_invoice_id: invoice.id,
      },
    });
    break;
  }

  case "customer.subscription.deleted": {
    const sub = event.data.object;

    await recurcite.track({
      type: "cancellation.confirmed",
      payload: {
        occurred_at: new Date().toISOString(),
        receipt_id: sub.id,
      },
      stripe_refs: {
        stripe_customer_id: sub.customer as string,
        stripe_subscription_id: sub.id,
      },
    });
    break;
  }
}

Maximizing Evidence Health

Your Evidence Health score determines how strong your dispute defense is. Here's how each event type contributes:

terms.acceptedHigh — Single strongest signal — proves customer agreement

user.login (×3+)High — Multiple logins prove sustained access and engagement

product.used (×5+)Medium-High — Multiple usage events quantify value delivery

transaction.completedMedium — Enables CE3; also proves payment history

cancellation.*Medium — Proves cancellation flow existed and was accessible

support.ticket.*Low-Medium — Shows customer support was provided

Proof Discount

Maintain Evidence Health grade A (80+) on 80% of disputes to earn reduced success fees. See Pricing → Proof Discount.

Next steps

Next.js Integration — full code examples for Next.js App Router
Express Integration — middleware and route handler patterns
CE3 Explained — deep dive into Visa Compelling Evidence 3.0

Express Integration

Security & Data