Stripe Connect for SaaS Platforms: A Developer's Guide

TL;DR: Stripe Connect enables SaaS platforms to interact with their customers' Stripe accounts — reading subscription data, applying charges, and managing billing on their behalf. This guide covers the OAuth integration flow, webhook setup for connected accounts, common pitfalls, and best practices for building reliable Stripe Connect integrations.

What is Stripe Connect?

Stripe Connect is a set of APIs that allow platforms to connect to and interact with other Stripe accounts. There are three Connect account types: Standard, Express, and Custom. For SaaS platforms that need to interact with their customers' existing Stripe accounts, Standard Connect with OAuth is the most common approach.

The OAuth Flow

Standard Connect uses OAuth 2.0 to let your customers authorize your platform to access their Stripe account.

Step 1: Initiate the Connection

Redirect the user to Stripe's OAuth authorization URL with your platform's Client ID:

https://connect.stripe.com/oauth/authorize?
  response_type=code&
  client_id=ca_xxxxx&
  scope=read_write&
  state=your_state_parameter&
  redirect_uri=https://yourapp.com/api/stripe/connect/callback

Key parameters:

• client_id — Your platform's Connect Client ID (starts with ca_)
• scope — Use read_write for full access or read_only for limited access
• state — A unique value to prevent CSRF attacks (e.g., the user's account ID)

Step 2: Handle the Callback

When the user authorizes the connection, Stripe redirects to your redirect_uri with an authorization code. Exchange this code for the connected account ID:

const response = await stripe.oauth.token({
  grant_type: 'authorization_code',
  code: req.query.code,
});
const connectedAccountId = response.stripe_user_id;
// Store this in your database

Step 3: Make API Calls on Behalf of Connected Accounts

Once connected, you can make Stripe API calls on behalf of the connected account using the stripeAccount parameter:

const subscriptions = await stripe.subscriptions.list(
  { customer: 'cus_xxx' },
  { stripeAccount: connectedAccountId }
);

Webhook Setup for Connected Accounts

Connected account webhooks are essential for reacting to events on your customers' Stripe accounts (payment failures, subscription changes, etc.).

Platform-Level Webhook

Create a single webhook endpoint that receives events from all connected accounts. In your Stripe Dashboard (Connect section), add a webhook endpoint with "Events on Connected accounts" selected. The event object includes an account field identifying which connected account the event belongs to:

const event = stripe.webhooks.constructEvent(
  body,
  signature,
  webhookSecret
);
const connectedAccountId = event.account;
// Look up the tenant in your database by this account ID

Key Events to Listen For

| Event | Use Case | |---|---| | invoice.payment_failed | Trigger dunning workflow | | invoice.paid | Mark dunning case as recovered | | customer.subscription.updated | Track subscription changes | | customer.subscription.deleted | Detect churned customers |

Common Pitfalls

Pitfall 1: Using API keys instead of OAuth. Never ask customers for their Stripe secret key. OAuth is more secure and can be revoked by the customer at any time. Pitfall 2: Missing the stripeAccount parameter. Every API call to a connected account must include { stripeAccount: connectedAccountId }. Without it, you are operating on your own platform account. Pitfall 3: Not handling webhook signature verification. Always verify webhook signatures using your signing secret. Without verification, anyone can send fake events to your endpoint. Pitfall 4: Hardcoding return_url without HTTPS. Stripe requires HTTPS for billing portal and checkout URLs. Always use a full URL with https:// scheme. Pitfall 5: Not handling OAuth disconnection. Customers can disconnect your platform from their Stripe settings at any time. Handle the account.application.deauthorized event and update your database accordingly.

ChurnBack and Stripe Connect

ChurnBack uses Stripe Connect OAuth to integrate with your Stripe account. This architecture allows ChurnBack to read your subscription data, apply retention offers (discounts, pauses, plan changes), and monitor payment events for dunning — all without you sharing API keys. Get started →

FAQ

What is Stripe Connect?

Stripe Connect is a set of APIs that allow platforms to interact with other Stripe accounts. It enables SaaS platforms to read subscription data, apply charges, and manage billing on behalf of their connected accounts.

How do I integrate Stripe Connect?

Use the OAuth flow: redirect users to Stripe's authorization URL with your Client ID, handle the callback to receive the connected account ID, then use the stripeAccount parameter on all API calls to interact with that account.

What webhook events should I listen for with Stripe Connect?

The most important events are invoice.payment_failed (for dunning), invoice.paid (for recovery confirmation), customer.subscription.updated (for tracking changes), and customer.subscription.deleted (for detecting churn).

Is Stripe Connect OAuth more secure than sharing API keys?

Yes. OAuth grants limited, revocable access. The connected account owner can disconnect your platform at any time. API keys grant full, permanent access and are a security risk if exposed.