Skip to Content
Connect Stripe

Connect Stripe

Unchurn talks to your Stripe account through Stripe Connect OAuth. You click one button, sign in to Stripe, and Unchurn receives a scoped access token. No API keys to copy. No webhook secrets to paste.

This page walks you through the connect flow, what happens on the Stripe side, and how to handle test mode and live mode separately.

Why OAuth, not API keys

Stripe Connect gives you three things that pasted API keys do not.

  • Revoke at any time. Open your Stripe dashboard, revoke Unchurn’s access, and the next API call from our backend fails. No support ticket, no key rotation on your end.
  • Mode is enforced by Stripe. A test-mode token cannot touch live data. Live and test live in separate columns on our merchant record and we never mix them.
  • Scoped permissions. Unchurn requests subscription read and write only. We do not see your charges, refunds, or card details.

Steps

  1. Sign up at the Unchurn dashboard with your work email.
  2. After confirming your email, you land on the Connect Stripe screen. The page lists exactly what Unchurn will read and write before you click anything.
  3. Click Connect Stripe. Your browser redirects to Stripe’s hosted OAuth consent page.
  4. Sign in to Stripe (or pick the right account if you have several). Stripe shows the scopes Unchurn is asking for and the connected account it will use.
  5. Click Authorize. Stripe redirects you back to Unchurn with a one-time code.
  6. Unchurn exchanges the code for an access token, stores it against your merchant record, and drops you on the onboarding reveal screen with your last 30 days of cancellations.

The whole round-trip takes about thirty seconds.

What gets stored on our side

After the callback succeeds, Unchurn stores three things:

  • The Stripe Connect access token for the mode you connected (test or live).
  • Your connected account ID — acct_… from Stripe.
  • A short-lived signed cookie that tells the dashboard which merchant you are.

Unchurn never sees and never stores your Stripe secret API key. The OAuth token is the only credential we hold, and Stripe lets you revoke it whenever you want.

Connecting test mode

Test mode is a separate connection. From the dashboard, switch the mode toggle to Test, then click Connect Stripe again. You will sign in to Stripe and authorize a test-mode connection on the same Stripe account. The two connections live side by side on your merchant record — neither overwrites the other.

Why connect both? Most teams build their cancel button against test data, validate the flow end to end, and then flip to live. The widget refuses to mix the two — a unch_live_… token cannot trigger a test-mode session, and a unch_test_… token cannot trigger a live-mode session.

See Test and live modes for how the widget picks a mode at runtime.

Switching modes after connect

Once both modes are connected, the dashboard shows a mode toggle in the top bar. The toggle controls which mode you are viewing — sessions, metrics, flow config — not which mode the widget runs in. The widget mode comes from the token your server mints.

Revoking access

Two options, both immediate.

  • From the Unchurn dashboard. Go to Account → Stripe connection and click Disconnect. Unchurn revokes the OAuth grant against Stripe and clears the stored token.
  • From your Stripe dashboard. Open Stripe → Settings → Connected apps and remove Unchurn. The next call from our backend returns a Stripe auth error and the dashboard shows a “reconnect required” banner.

Disconnecting test mode does not affect live mode and vice versa.

Common pitfalls

Test mode is connected but live is not. The dashboard renders test-mode metrics fine. The first live-mode showCancelFlow call returns stripe_not_connected. Connect live before going to production.

Revoking access mid-flow. A customer is in the middle of the cancel flow when you revoke the token in Stripe. The session that started before the revoke runs to completion if the Stripe call has already gone out. Anything that calls Stripe after the revoke fails with a Stripe auth error and the widget shows the “try again later” gate.

Multi-account Stripe organizations. If your Stripe login owns several accounts, the OAuth consent page asks which one to authorize. Pick the account that owns the subscriptions you want Unchurn to manage. To switch the connected account, disconnect and connect again — Unchurn binds to whichever account you authorized last.

Next steps

Last updated on
ArchitectureMerchant dashboard