Billing providers

A session token authenticates the cancel flow against a specific customer. Connecting a billing provider lets Churnkey apply discount, pause, plan change, and cancel actions against that customer's subscription.

Token mode works without a connected provider, but every action becomes your responsibility — keep the handle<Type> callbacks in code and use the token only for session recording and dashboard-driven flow config. Most teams connect a provider so Churnkey handles the apply step.

Supported providers

Connect Stripe

In the Churnkey dashboard, open Settings → Billing → Connect Stripe. The OAuth flow grants Churnkey read access to your customers, subscriptions, coupons, and prices, plus write access for the actions it applies. The grant is scoped — Churnkey can't create new prices or modify the account itself.

Once connected, the dashboard mirrors your customer and subscription records, so opening a customer in Churnkey shows their Stripe subscription state. The IDs you sign into tokens (customerId) must match Stripe's cus_xxx IDs. Mismatched IDs are the most common source of "token mode shows no flow" errors during setup.

Connect Braintree, Chargebee, Paddle, or Maxio

The flow is the same: enter the keys in the dashboard, Churnkey verifies them by listing one customer, the connection saves. Keys live in Churnkey's encrypted credential store and aren't visible to anyone in your team after entry.

Provider          Required credentials
---------------   ----------------------------------------
Braintree         merchant_id, public_key, private_key, environment (sandbox | production)
Chargebee         site, api_key, environment (test | live)
Paddle Billing    api_key, environment (sandbox | production)
Paddle Classic    vendor_id, vendor_auth_code
Maxio             subdomain, api_key

What Churnkey can do per provider

Not every provider exposes every action. Discount and cancel are universal; pause, plan change, trial extension, and prorated refunds depend on the provider's API.

"Partial" means the provider exposes the action with caveats — Braintree's trial extension works only when the subscription is in its first billing period; Maxio's prorated refunds support some plans but not others. When the provider can't do the action cleanly, keep that offer type client-side with handle<Type>:

<CancelFlow
  session={token}
  // Discount, pause: Churnkey handles them.
  // Trial extension: our Braintree integration needs custom logic.
  handleTrialExtension={async (offer) => myBraintree.extendTrial(offer.days)}
/>

Mix freely — each offer type decides independently.

Customer-ID resolution

The customerId in the token is what Churnkey looks up in your provider. The lookup ID is the provider's customer identifier, unless you're in Direct mode (no connected provider), in which case it's your internal ID.

Store the provider ID on your user record when you create the subscription, then read it directly when you mint a token. Looking it up at token-mint time by querying the provider works but adds latency.

Switching providers

The dashboard supports connecting a second provider and routing specific customer cohorts to it via metadata. Migration patterns vary by which providers are involved — reach out to support before you start so the cutover doesn't drop any in-flight sessions.

Next steps

• Server-side tokens — token minting and Direct mode.
• Callbacks — handler/listener contracts for per-offer opt-out.