With Express accounts, you can quickly onboard users so they can be paid immediately. You can customize the branding of the Express onboarding flow and dashboard. Stripe hosts the dashboard; you can grant access through your platform so your users can access it.

Express demo

To see the complete Express onboarding flow in action, Stripe recommends trying our sample end-to-end Express integration before you start building your own. This demo includes an example of a user onboarding experience and account management for Rocket Rides, an on-demand marketplace.

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

Prerequisites for using Express

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

• Minimum API version: Express requires the API version 2017-05-25 or later. Capabilities in Express require the API version 2019-02-19 or later.
• Users based in the United States: Express accounts are available only to individuals and businesses located in the United States. Contact us if you are interested in support for users outside the U.S.
• SMS-enabled phone number: Express users must have a U.S. 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.
• Platform profile: you need to complete your platform’s profile.

Note there’s an additional cost for active Express accounts. An Express account is considered active if it has received at least one successful payout in a given month. 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 an OAuth flow:

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

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

Step 1: Create the OAuth link

To start your integration, you need two pieces of information from your platform settings:

• Your client_id, a unique identifier for your platform that is generated by Stripe.
• Your redirect_uri, the URL which your user will be redirected to 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

Customize Express with OAuth parameters

You can change the behavior of the Express onboarding flow by including additional URL parameters in your OAuth link, which are detailed below. You can see a complete list in the OAuth Reference Guide.

Individual or company accounts

You can specify whether Stripe should present an Express onboarding form for individuals or companies by setting the stripe_user[business_type] parameter to either individual or company.

Stripe will collect the right information for each account type. For example, to onboard a company:

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

Prefill form fields

You can prefill some form fields on the user’s Stripe application by including the relevant URL parameters in your OAuth link.

This example prefills the user’s email address with stripe_user[email]:

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://stripe.com/connect/default/oauth/test&client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7&state={STATE_VALUE}&stripe_user[email]=user@example.com

Specify Capabilities for an account

If your platform is designated for one Capability (either card_payments or platform_payments), you won’t need to specify additional Capabilities. However, if your platform supports both, you can add a Capability to an individual Express account by including the suggested_capabilities[] parameter in your OAuth link.

We can designate this account’s Capability as platform_payments:

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

Stripe will attempt to add the suggested Capability to this Express account:

• If the user is in a country that doesn’t support platform_payments, Stripe attempts to designate the account as card_payments.
• If platform_payments and card_payments are both not supported for the user, then the connected account is marked as having no Capabilities.

You can verify that Stripe added your suggested Capability in Step 4 when you complete the Express flow by using the assert_capabilities[] parameter.

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 your 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 using the URL defined 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: Complete the Express account connection

The last step is to use the provided authorization code to make a POST request to Stripe’s 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_4eC39HqLyjWDarjtT1zdp7dc \
  -d code="{AUTHORIZATION_CODE}" \
  -d grant_type=authorization_code

Stripe returns a response containing the account ID (stripe_user_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.

Verify the account's Capability

If you specified a Capability using the suggested_capabilities[] parameter, you can verify that Stripe applied the suggested Capability in this POST request by including assert_capabilities[] and identifying that card_payments or platform_payments match. A request error will be returned if the suggested Capability doesn’t match the assertion: in this case, it’s recommended to end the onboarding flow with a failure.

Since the OAuth link is publicly accessible and can be changed by the user, this is a useful check to perform. However, recall that Stripe attempts to make the account have the Capability you designated; there are situations when it’s not possible.

If you get a request error, review your user’s details and check whether card_payments or platform_payments is supported in their country. That could be the limiting factor, rather than a bad actor changing the URL.

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