Stripe Connect for the Kustiq churn engine.

Overview

The Stripe Connect integration is the input source for Kustiq’s churn engine. It listens to subscription, invoice, and dispute events on your Stripe account and turns them into a live churn-risk score on every paying customer. It does not run Kustiq’s own billing, and it does not run your reporting.

One direction, Stripe to Kustiq. We never call POST, PATCH, or DELETE against your Stripe account. The OAuth token is requested with the read-only Connect role, and the dashboard reflects that scope. 11 event types feed the engine: 5 churn signals, 3 recovery signals, 3 context events. The full list is in the Event reference below.

With the integration on, a customer who hits invoice.payment_failed twice inside 14 days appears at the top of the at-risk segment within 90 seconds. With Stripe alone, the same signal stays in the dashboard event log nobody scrolls.

Setup, in 4 minutes

Five steps. Stripe-side OAuth, no API key paste, no restricted-key creation. The grant is scoped read_only from the consent screen and you can downgrade or revoke it from your Stripe dashboard at any time.

Event reference

11 event types in total. The engine ignores everything else Stripe sends, so an extra event in your account does not cost you anything and does not affect the score.

Permissions and scopes

Kustiq requests one Stripe Connect role and five read resources, no more. Every grant is read-only and revocable from Stripe → Settings → Connected apps without contacting support.

• read_only · the Connect role. Cannot create, update, or delete anything in your Stripe account.
• customer_read · read customer name, email, metadata. Used for matching and tenure features.
• subscription_read · read subscription state, plan, cancellation reason, pause schedule.
• invoice_read · read invoice status, attempt count, amount, currency. Drives the dunning signal.
• charge_read + dispute_read · read dispute reason and outcome on a charge. Drives the dispute signal.

Kustiq does not request balance_read, transfer_read, payout_read, tax_read, or any write role. If your IT review asks for a written list of what we touch, the six lines above are the answer.

Webhook verification

Kustiq registers one webhook endpoint on your account at connect time. We verify Stripe’s signature on every inbound request before the event hits the engine. The snippet below mirrors how we verify on our side, so you can audit the exact code path.

// Express handler. Use express.raw({ type: "application/json" }).
const stripe = require("stripe")(process.env.STRIPE_SECRET);
const SECRET = process.env.STRIPE_WEBHOOK_SECRET;

function verify(req) {
  const sig = req.headers["stripe-signature"];
  try {
    const event = stripe.webhooks.constructEvent(
      req.body,    // raw bytes, not parsed JSON
      sig,
      SECRET,
    );
    return event;
  } catch (err) {
    // invalid signature, replay, or stale timestamp (> 5 min)
    return null;
  }
}

Retry policy mirrors Stripe. A 5xx response or no response inside 10s triggers exponential backoff (1m, 5m, 30m, 2h, 12h) for up to 24 hours, then the event is marked failed in /dashboard/integrations with the underlying Stripe event ID.

Sync rules

• Cadence. Real-time via webhook. The backfill runs once on connect; after that, no polling.
• Direction. One way, Stripe to Kustiq. The integration cannot write, update, refund, or cancel anything on your account.
• Mode. Live and test grants are separate OAuth connections. Re-run the connect flow on the matching mode if you switch.
• Match key. Stripe customer email first, customer- metadata kustiq_profile_id override second, domain fallback third. Confidence below 90% never feeds the score.
• Latency. Median 90 seconds from Stripe webhook to dashboard score change. p95 under 4 minutes.
• Backfill. 30 / 90 / all-time. Picked once at setup, replayable from /dashboard/integrations.
• Rate limit.Stripe’s read API limits apply during backfill; live mode caps at 100 req / sec, test mode at 25.

Trust and data handling

This section is the answer to your IT review. What we store, what we never touch, where it lives.

Region pinning matches the rest of the platform. EU workspaces route Stripe events through Frankfurt; US workspaces route through Virginia. Cross-region routing is opt-in per workspace and visible from Settings → Region. Full DPA at /dpa, security posture at /trust.

Disconnect

Two paths. From Stripe: Stripe → Settings → Connected apps → Kustiq → Revoke access. From Kustiq: Settings → Integrations → Stripe → Disconnect. Either revokes the OAuth grant within 5 minutes; live webhook delivery stops immediately.

Troubleshooting

Ten known states. Each has a stable anchor so you can link a teammate to the exact row.

FAQ

Changelog

• 2026-05-16 · v1.1 Pair-lock production-ready audit. BreadcrumbList position-1 fixed to “Home”. SoftwareApplication JSON-LD @id-graph linked to root #org and #site. New per-page OG image at /docs/stripe/opengraph-image. FAQ trust-card reference converted to anchor link. Free-tier copy unified to 3 profiles a week. Eleven → 11 numeric consistency.
• 2026-05-08 · v1.0 Initial release. Disambiguation banner against billing-docs collision. Pro-plan link on the lede. Trust section above Disconnect. Footer cross-link row. Last-verified badge.
• 2026-04-24 · v0.9 Backfill window picker added (30 / 90 / all-time). Customer match confidence raised from 80% to 90%.
• 2026-03-11 · v0.7 11th event added: charge.dispute.created. Dispute signal feeds the score with a 7-day decay.
• 2026-01-29 · v0.5 Test-mode wiring split out from live mode. Test events no longer affect live scores.
• 2025-12-04 · v0.1 Closed beta with three design partners.