Connecting to Standalone Accounts

Integrating with standalone Stripe accounts is the fastest and easiest way to get started, since you’ll be offloading the majority of the user experience and user communication to Stripe.

This tutorial assumes you have already registered your platform

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?

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

  1. 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.
  2. 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.
  3. 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).
  4. Your site then makes a request to our OAuth token endpoint to fetch the user’s authorization credentials, storing them on your site.
  5. 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:

  • Your client_id, a unique identifier for your platform, generated by Stripe.
  • Your redirect_uri, a page on your website to which the user will be redirected after connecting their account (or failing to, should that be the case), set by you.

Stripe also provides a development client_id, to make testing easier.

Connecting users

With these two pieces of information in hand, you’re ready to have your users connect with your platform. We recommend showing a Connect button that sends them to our authorize_url endpoint:

https://connect.stripe.com/oauth/authorize?response_type=code&client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7&scope=read_write

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.

Here is how this may look (the href value matches that above):

Connect with Stripe

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:

https://stripe.com/connect/default/oauth/test?scope=read_write&code=AUTHORIZATION_CODE

If the authorization was denied by the user, we’ll include an error instead:

https://stripe.com/connect/default/oauth/test?error=access_denied&error_description=The%20user%20denied%20your%20request

Using the code parameter, you should make a POST request to our access_token_url endpoint (also see the sample-code below for non-cURL examples):

curl https://connect.stripe.com/oauth/token \
   -d client_secret=sk_test_BQokikJOvBiI2HlWgH4olfQ2 \
   -d code=AUTHORIZATION_CODE \
   -d grant_type=authorization_code

Note that you’ll make the request with your live secret API key or test secret API key, depending on whether you want to get a live or test access token back.

Stripe will return a response containing the authentication credentials for the user:

{
  "token_type": "bearer",
  "stripe_publishable_key": PUBLISHABLE_KEY,
  "scope": "read_write",
  "livemode": false,
  "stripe_user_id": USER_ID,
  "refresh_token": REFRESH_TOKEN,
  "access_token": ACCESS_TOKEN
}

If there was a problem, we’ll instead return an error:

{
  "error": "invalid_grant",
  "error_description": "Authorization code does not exist: 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.

https://connect.stripe.com/oauth/authorize?response_type=code&client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7&scope=read_write&redirect_uri=https://sub2.example.com

The first URI in your comma-separated list will always be treated as the default.

Deferred account activation

In some cases, you may want to defer account activation until later—that is, let your user start accepting payments without completely setting up their account.

To do this, you can spin up a standalone account with just a country and email address.

Revoked Access

An account.application.deauthorized webhook 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:

curl https://connect.stripe.com/oauth/deauthorize \
   -u {YOUR_SECRET_KEY}: \
   -d client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7 \
   -d stripe_user_id=acct_muEnSzfNnWznGV

Sample OAuth Applications

Here’s some sample code for performing the OAuth flow, but we recommend that you use a client library instead of handling the implementation yourself.


You’re connected!

Now you can use the API on your user’s behalf to accept payments, set up recurring billing, fetch account data, and more.