Using Connect with Express Accounts

With Connect, users of your platform can have one of three types of Stripe accounts:

• Standard
• Express
• Custom

With Express accounts, you can quickly onboard users so they are ready to get paid immediately. You can also customize the branding of the onboarding flow and dashboard.

Requirements for creating Express accounts

To use Express accounts, you must meet all of these requirements:

• Minimum API version: you must be using an API version at least as recent as 2017-05-25.
• Users based in the United States: Express accounts are only available to individuals and sole proprietors located in the United States. Contact us if you are interested in support for users outside the United States or support for businesses.
• SMS-enabled phone number: Express users must have a US phone number with SMS capabilities in order to authenticate with Express.
• Risk management: your platform is ultimately responsible for losses incurred by Express accounts. To protect against this, you need to scrutinize all accounts that sign up via your platform for potential fraud. Refer to our best practices guide for more information.

Startups in the Stripe Atlas network are eligible for a discount on Express pricing. Contact us for more information.

The OAuth connection flow

An Express account connects to your platform using OAuth, going through these steps:

1. Starting on a page at your site, the user clicks a link that takes them to Stripe, passing along your platform’s client_id.
2. On Stripe’s website, the user provides the necessary contact and payout information.
3. The user is then redirected back to your site, passing along an authorization code.
4. Your site then makes a request to our OAuth token endpoint to complete the connection and fetch the user’s account ID.

After completing Step 3, API requests can be made on behalf of the connected account using their account ID or authorization credentials.

Express demo

To see the complete Express onboarding flow in action, we recommend trying our sample end-to-end Express integration before you start building your own. The demo includes an example of a staged onboarding path for Rocket Rides, an on-demand marketplace. As you go through the demo application, you can use trigger cards to test the payment and verification flows.

You can find the demo’s complete source code on GitHub.

Step 1: Create the OAuth link

To get started with your integration, you need two pieces of information from your platform settings:

• Your client_id, a unique identifier for your platform, generated by Stripe
• Your redirect_uri, a URL-encoded address that points to the page on your website to which the user is redirected after connecting their account. If you do not include the redirect_uri parameter in your request, Stripe defaults to using the first address you have configured as the redirect destination in your Dashboard.

Stripe also provides a development client_id to make testing easier.

With these two pieces of information in hand, you’re ready to create the OAuth link. We recommend showing a Connect button that sends users to our Express OAuth endpoint:

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://stripe.com/connect/default/oauth/test&client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7&state={STATE_VALUE}

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

Here’s how the above URL can be presented to your user to begin the connection:

Connect with Stripe

Step 2: User creates or connects their account

After the user clicks the link on your site, they'll be taken to Stripe's website where they'll be prompted to provide contact and payout information.

To test the onboarding process, you can use (000) 000-0000 when it asks for a phone number. Instead of sending you an SMS message or e-mail, Stripe lets you complete verification by inputting the code 000-000.

Express displays your branding in the onboarding flow and the Express dashboard. You can provide a platform name, logo, and optional brand color in the Connect settings section of the Stripe Dashboard.

Step 3: User is redirected back to your site

After the user completes the onboarding process, they are redirected back to your site, to the URL established as your platform’s redirect_uri.

For successful connections, we’ll pass along in the URL:

• The state value, if provided
• An authorization code

https://stripe.com/connect/default/oauth/test?code={AUTHORIZATION_CODE}

Step 4: Finalize the connection

The last step is to use the provided code to make a POST request to our token endpoint to complete the connection and fetch the user’s account ID:

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

Stripe returns a response containing the account ID and authentication credentials for the user:

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

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

{
  "error": "invalid_grant",
  "error_description": "Authorization code does not exist: {AUTHORIZATION_CODE}"
}

The user is now connected to your platform. The stripe_user_id is the Stripe account ID for the newly-created account. Store this value in your database and use it to authenticate as the connected account by passing it into requests in the Stripe-Account header.

The refresh_token can be used to generate test access tokens for a production client_id or to roll your access token.

Webhooks

Once created, all account change notifications are delivered via webhooks as an account.updated event. Establish a Connect webhook URL in your account settings to watch for these. Tracking onboarding and verification status can be useful for providing user support and displaying relevant notices in your platform’s user interface, but it isn’t strictly necessary. Stripe communicates directly with your users, taking them through the steps of the onboarding and verification process and handling issues that arise, without requiring any intervention from your platform.

Next steps

• Integrating with the Express Dashboard
• Creating Charges
• OAuth Reference
• Scheduling Payouts