A standalone Stripe account is a normal Stripe account that is controlled by the account holder: your platform’s user. (By contrast, managed accounts are fully controlled by the platform.)

To connect to standalone accounts—either if your users already have accounts or if you’d like them to create accounts—you’ll want to integrate with our standard OAuth flow. With this flow, there’s minimal integration work to do in terms of onboarding, communicating with users, ongoing maintenance, and so on since Stripe handles all of it for you and your users will have access to the Dashboard. (Of course, this also means that there’s not as much user experience customizability.)

Unless you’re looking to fully control the user experience from the beginning, we recommend starting off with an OAuth integration.

What does the flow look like?

OAuth 2.0

When a user wants to connect to your platform, they’ll go through these steps:

Starting on a page at your site, the user will click a link that takes them to Stripe, passing along your platform’s client_id.

On Stripe’s website, the user will be prompted to connect their Stripe account, or create a new account if they don’t already have one.

The user will then be redirected back to your site (specifically to your redirect_uri), passing along either an authorization code or an error (if the connection request was denied).

Your site then makes a request to our OAuth token endpoint to fetch the user’s authorization credentials, storing them on your site.

Subsquent API requests can be made on behalf of the connected account using the authorization credentials.

Unlike most OAuth implementations (like Facebook Connect or Sign In with Twitter), we’ve seamlessly added the process of creating a Stripe account right into our authorization flow. You don’t have to worry about whether or not your users already have Stripe accounts.

The user is logged in, and can connect directly.

The user needs to create an account.

When your users land back on your site, their account is ready to accept credit card payments. You can also retrieve their account status at any time.

Keep reading for a step-by-step guide to integrating the flow. You can also check out the OAuth reference for additional details on the request and response parameters.

Integrating OAuth

To get started with your integration, you’ll first need to know two key pieces of information from in your platform settings:

CSRF Protection

To prevent CSRF attacks, use the state parameter, passing along a unique token as the value. We’ll include the state you gave us when we redirect back.

The Stripe endpoint needs to at least receive two parameters:

response_type, with a value of code.

Your client_id.

You’ll likely also want to provide the scope. This parameter dictates what your platform will be able to do on behalf of the connected account. The options are read_write and read_only, with read_only being the default.

For an analytics platform, read_only is appropriate; if you need to perform charges on behalf of the connected user, you will need to request read_write scope instead. See the OAuth reference for more.

After the user has connected

When the user arrives at Stripe, they’ll be prompted to allow or deny the connection to your platform, and will then be sent to your redirect_uri page. In the URL, we’ll pass along an authorization code:

You’re done! The user is now connected to your platform. You’ll want to store all of the returned information in your database for later use.

You’ll notice that the response also includes a refresh_token. This can be used to generate test access tokens for a production client_id or to roll your access token. You should hold on to this, as you’re only able to get it after this initial POST request.

Customizing the user experience

Through additional parameters you can supply Stripe, you can easily customize the user’s experience. Below are a few example uses of those parameters, but see the OAuth reference for the full list.

Pre-filling fields

If your user needs to set up a new account with Stripe, you can provide the best possible user experience by pre-filling the account form fields with information you already have, like the user’s email and name. Pre-filling has no effect if your user already has an existing Stripe account.

Alternatively, if you know your user has a Stripe account already, you can use the stripe_landing parameter, with a value of login, to have Stripe show a login screen instead of the default account application.

Dynamically setting the redirect URI

For security purposes, Stripe will only redirect a user to a pre-defined url. However, Connect allows you to define more than one redirect URI, which can be used to further customize the user’s experience. For example, you could have some of your users redirected back to https://sub1.example.com and others sent to https://sub2.example.com, each with custom behavior.

First, in your platform settings, set the redirect URIs to a comma-separated list of allowed URIs. Second, add a redirect_uri parameter to your authorization request with a value found in your comma-separated list.

Revoked Access

An account.application.deauthorizedwebhook
event is sent when a user disconnects your platform from
their account. By watching for this event, you can perform any necessary credential cleanup on your
servers. (Note that a managed account cannot be disconnected by the account’s beneficiary.)

Additionally, if you want to disconnect access to a standalone account (for
example, to stop getting webhooks for an account you no longer work
with), you can POST your client_id and the connected account’s ID to
https://connect.stripe.com/oauth/deauthorize: