Sign in
Support
Sign in
Sign up

Connect OAuth reference

This reference lists available public methods for our OAuth endpoints for Connect.

The OAuth Connect flow allows you to customize the user’s experience by passing additional parameters to Stripe. Some common examples are explained below, and the rest of the reference lists every possible option.

Common examples

Prefill fields

Provide the best possible user experience for users needing to create a new Stripe account by prefilling the account form fields with information you already have, like the user’s email and name. Prefilling has no effect if your user already has an existing Stripe account. Certain fields cannot be prefilled, including terms of service acceptance and RISA acceptance in Japan.

Send to the login page

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

Dynamically set the redirect URI

For security purposes, Stripe redirects a user only to a predefined URI. 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.

To dynamically set the redirect URI:

  1. In your platform settings, add each redirect URI.
  2. Add a redirect_uri parameter to your authorization request and set the value to one of your redirect URIs.
https://connect.stripe.com/oauth/authorize?response_type=code&client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7&scope=read_write&redirect_uri=https://sub2.example.com

If no redirect_uri is set, the first URI in the list is used.

Authorize the account

For Standard accounts: GET https://connect.stripe.com/oauth/authorize

For Express accounts: GET https://connect.stripe.com/express/oauth/authorize

Sends the user to Stripe to connect to your platform. Note that one parameter applies only to Express accounts.

Request

Parameter Description
client_id

The unique identifier provided to your application, found in your application settings.
response_type

The only option at the moment is code.
redirect_uriOptional

The URL for the authorize response redirect. If provided, this must exactly match one of the comma-separated redirect_uri values in your application settings.

To protect yourself from certain forms of man-in-the-middle attacks, the live mode redirect_uri must use a secure HTTPS connection.

Defaults to the redirect_uri in your application settings if not provided.
scopeOptional

read_write or read_only, depending on the level of access you need.

Defaults to read_only.
stateOptional

An arbitrary string value we will pass back to you, useful for CSRF protection.
stripe_landingOptional

login or register, depending on what type of screen you want your users to see. Only override this to be login if you expect all your users to have Stripe accounts already (e.g., most read-only applications, like analytics dashboards or accounting software).

Defaults to login for scope read_only and register for scope read_write.
always_promptOptional

Boolean to indicate that the user should always be asked to connect, even if they're already connected.

Defaults to false.
suggested_capabilitiesOptionalExpress only

An array of capabilities to apply to the connected account.

The following query string parameters are all optional; we will use them to prefill details in the account form for new users. Some prefilled fields (e.g., URL or product category) may be automatically hidden from the user's view. Any parameters with invalid values will be silently ignored.

Note that some of these parameters apply only to Standard accounts (indicated).

Parameter Description
stripe_user[email]Recommended

The user's email address. Must be a valid email format.
stripe_user[url]Recommended

The URL for the user's business. This may be the user's website, a profile page within your application, or another publicly available profile for the business, such as a LinkedIn or Facebook profile.

Must be URL-encoded and include a scheme (http or https).

If you will be prefilling this field, we highly recommend that the linked page contain a description of the user's products or services and their contact information. If we don't have enough information, we'll have to reach out to the user directly before initiating payouts.
stripe_user[country]

Two-letter country code (e.g., US or CA).

Must be a country that Stripe currently supports.
stripe_user[phone_number]

The business phone number. Must be 10 digits only.

Must also prefill stripe_user[country] with the corresponding country.
stripe_user[business_name]

The legal name of the business, also used for the statement descriptor.
stripe_user[business_type]

The type of the business.

For Standard accounts the value must be one of sole_prop, corporation, non_profit, partnership, or llc.

For Express accounts the value must be one of company or individual.
stripe_user[first_name]

First name of the person who will be filling out a Stripe application.
stripe_user[last_name]

Last name of the person who will be filling out a Stripe application.
stripe_user[dob_day] stripe_user[dob_month] stripe_user[dob_year]

Day (0-31), month (1-12), and year (YYYY, greater than 1900) for the birth date of the person who will be filling out a Stripe application.

If you choose to pass these parameters, you must pass all three.
stripe_user[street_address]Standard only

Street address of the business.
stripe_user[city]Standard only

Address city of the business.

We highly recommend that you also prefill stripe_user[country] with the corresponding country.
stripe_user[state]Standard only

Address state of the business. Must be the two-letter state or province code (e.g., NY for a U.S. business or AB for a Canadian one).

Must also prefill stripe_user[country] with the corresponding country.
stripe_user[zip]Standard only

Address ZIP code of the business. Must be a string.

We highly recommend that you also prefill stripe_user[country] with the corresponding country.
stripe_user[physical_product]Standard only

A string: true if the user sells a physical product, false otherwise.
stripe_user[product_description]

A description of what the business is accepting payments for.
stripe_user[currency]Standard only

Three-letter ISO code representing currency, in lowercase (e.g., usd or cad).

Must be a valid country and currency combination that Stripe supports.

Must prefill stripe_user[country] with the corresponding country.
stripe_user[first_name_kana]

The Kana variation of the first name of the person who will be filling out a Stripe application.

Must prefill stripe_user[country] with JP, as this parameter is only relevant for Japan.
stripe_user[first_name_kanji]

The Kanji variation of the first name of the person who will be filling out a Stripe application.

Must prefill stripe_user[country] with JP, as this parameter is only relevant for Japan.
stripe_user[last_name_kana]

The Kana variation of the last name of the person who will be filling out a Stripe application.

Must prefill stripe_user[country] with JP, as this parameter is only relevant for Japan.
stripe_user[last_name_kanji]

The Kanji variation of the last name of the person who will be filling out a Stripe application.

Must prefill stripe_user[country] with JP, as this parameter is only relevant for Japan.
stripe_user[gender]

The gender of the person who will be filling out a Stripe application. (International regulations require either male or female.)

Must prefill stripe_user[country] with JP, as this parameter is only relevant for Japan.
stripe_user[block_kana]Standard only

The Kana variation of the address block.

This parameter is only relevant for Japan. You must prefill stripe_user[country] with JP and stripe_user[zip] with a valid Japanese postal code to use this parameter.
stripe_user[block_kanji]Standard only

The Kanji variation of the address block.

This parameter is only relevant for Japan. You must prefill stripe_user[country] with JP and stripe_user[zip] with a valid Japanese postal code to use this parameter.
stripe_user[building_kana]Standard only

The Kana variation of the address building.

This parameter is only relevant for Japan. You must prefill stripe_user[country] with JP and stripe_user[zip] with a valid Japanese postal code to use this parameter.
stripe_user[building_kanji]Standard only

The Kanji variation of the address building.

This parameter is only relevant for Japan. You must prefill stripe_user[country] with JP and stripe_user[zip] with a valid Japanese postal code to use this parameter.

Response

The user's browser is redirected back to your configured redirect URI or the value you passed in the redirect_uri parameter. When successful, you should receive the following query parameters:

Parameter Description
code

An authorization code you can use in the next call to get an access token for your user. This can only be used once and expires in 5 minutes.
scope

read_write or read_only, depending what you passed on the initial GET request.
state

The value of the state parameter you provided on the initial GET request.

Error Response

In case of an error, the user's browser will not be redirected except in the case of access_denied. Instead, errors will be returned in a JSON dictionary with the following fields:

Parameter Description
error

A unique error code per error type.
error_description

A human readable description of the error.
state

The value of the state parameter you provided on the initial GET request.

Error Codes

Parameter Description
access_denied

User denied authorization.
invalid_scope

Invalid scope parameter provided.
invalid_redirect_uri

Provided redirect_uri parameter is either an invalid URL or is not allowed by your application settings.
invalid_request

Missing response_type parameter.
unsupported_response_type

Unsupported response_type parameter. Currently the only supported response_type is code.

Complete the connection and get the account ID

POST https://connect.stripe.com/oauth/token

Used both for turning an authorization_code into an account connection, and for getting a new access token using a refresh_token.

Request

This call should be made using your secret API key as a client_secret POST parameter:

curl https://connect.stripe.com/oauth/token \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d code=ac_123456789 \
  -d grant_type=authorization_code

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

response = Stripe::OAuth.token({
  grant_type: 'authorization_code',
  code: 'ac_123456789',
})

# Access the connected account id in the response
connected_account_id = response.stripe_user_id

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

response = stripe.OAuth.token(
  grant_type='authorization_code',
  code='ac_123456789',
)

# Access the connected account id in the response
connected_account_id = response['stripe_user_id']

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$response = \Stripe\OAuth::token([
  'grant_type' => 'authorization_code',
  'code' => 'ac_123456789',
]);

// Access the connected account id in the response
$connected_account_id = $response->stripe_user_id;

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Map<String, Object> params = new HashMap<>();
params.put("grant_type", "authorization_code");
params.put("code", "ac_123456789");

TokenResponse response = OAuth.token(params, null);

// Access the connected account ID in the response
String accountId = response.getStripeUserId();

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const response = await stripe.oauth.token({
  grant_type: 'authorization_code',
  code: 'ac_123456789',
});

var connected_account_id = response.stripe_user_id;

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.OAuthTokenParams{
  GrantType: stripe.String("authorization_code"),
  Code:      stripe.String("ac_123456789"),
}
token, _ := oauth.New(params)

// Access the connected account id in the response
connected_account_id = token.StripeUserID

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new OAuthTokenCreateOptions
{
  GrantType = "authorization_code",
  Code = "ac_123456789",
};

var service = new OAuthTokenService();
var response = service.Create(options);

// Access the connected account id in the response
connected_account_id = response.StripeUserId

When converting an authorization code to an access token, you must use an API key that matches the mode—live or test—of the authorization code (which depends on whether the client_id used was production or development).

When using a refresh token to request an access token, you may use either a test or live API key to obtain a test or live access token respectively. Any existing access token with the same scope and mode—live or test—will be revoked.

Parameter Description
grant_type

authorization_code when turning an authorization code into an access token, or refresh_token when using a refresh token to get a new access token.
code or refresh_token

The value of the code or refresh_token, depending on the grant_type.
scopeOptional

When requesting a new access token from a refresh token, any scope that has an equal or lesser scope as the refresh token. Has no effect when requesting an access token from an authorization code.

Defaults to the scope of the refresh token.
assert_capabilitiesOptionalExpress only

Check whether the suggested_capabilities were applied to the connected account.

Response

Parameter Description
access_token

The access token you can use to make requests on behalf of this Stripe account. You can use it as you would any Stripe secret API key, though we suggest using the Stripe-Account header.

This key does not expire, but may be revoked by the user at any time (you'll get a account.application.deauthorized webhook event when this happens).

As per our API Guidelines for object IDs, this key can be up to 255 characters in length.
scope

The scope granted to the access token, depending on the scope of the authorization code and scope parameter.
livemode

The live mode indicator for the token. If true, the access_token can be used as a live secret key. If false, the access_token can be used as a test secret key.

Depends on the mode of the secret API key used to make the request.
token_type

Will always have a value of bearer.
refresh_token

Can be used to get a new access token of an equal or lesser scope, or of a different live mode (where applicable).
stripe_user_id

The unique id of the account you have been granted access to, as a string.
stripe_publishable_key

A publishable key that can be used with this account. Matches the mode—live or test—of the token.

Error Response

Parameter Description
error

A unique error code per error type.
error_description

A human readable description of the error.

Error Codes

Parameter Description
invalid_request

No code, refresh_token, or grant_type parameter provided (where required).

invalid_grant

A variety of things can prompt this error:

  • code does not exist, is expired, has been used, or does not belong to you
  • refresh_token does not exist or does not belong to you
  • API key mode (live or test mode) does not match the code or refresh_token mode
unsupported_grant_type

Unsupported grant_type parameter specified. The only currently supported types are authorization_code and refresh_token.

invalid_scope

Invalid scope parameter provided.
unsupported_response_type

Unsupported response_type parameter. Currently the only supported response_type is code.

Revoke the account's access

POST https://connect.stripe.com/oauth/deauthorize

Used for revoking access to an account.

Request

This call should be made using your secret API key as an Authorization header.

curl https://connect.stripe.com/oauth/deauthorize \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7 \
  -d stripe_user_id=acct_OWImCCguekHiKF

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::OAuth.deauthorize({
  client_id: 'ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7',
  stripe_user_id: 'acct_DdxD0G6Q7cFGpg',
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.OAuth.deauthorize(
  client_id='ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7',
  stripe_user_id='acct_iTFOzQ6LV4PlYG'
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\OAuth::deauthorize([
  'client_id' => 'ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7',
  'stripe_user_id' => 'acct_3gTjwFMI66J5Io',
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Map<String, Object> params = new HashMap<>();
params.put("client_id", "ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7");
params.put("stripe_user_id", "acct_FmPh5lmSuzrTWy");

OAuth.deauthorize(params, null);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const response = await stripe.oauth.deauthorize({
  client_id: 'ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7',
  stripe_user_id: 'acct_30uApTd0cgKw3j',
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.DeauthorizeParams{
  ClientID:     stripe.String("ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7"),
  StripeUserID: stripe.String("acct_RPvUWOS676kCeo"),
}
oauth.Del(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new OAuthDeauthorizeOptions
{
    ClientId = "ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7",
    StripeUserId = "acct_ozt4R3708NwCUC",
};

var service = new OAuthTokenService();
service.Deauthorize(options);

When revoking access to an account, you must use an API key that matches the mode—live or test—of the authorization code (which depends on whether the client_id used was production or development).

Parameter Description
client_id

The client_id of the application that you'd like to disconnect the account from. The account must be connected to this application.
stripe_user_id

The account you'd like to disconnect from.

Response

Parameter Description
stripe_user_id

The unique id of the account you have revoked access to, as a string. This is the same as the stripe_user_id you passed in. If this is returned, the revocation was successful.

Error Response

Parameter Description
error

A unique error code per error type.
error_description

A human readable description of the error.

Error Codes

Parameter Description
invalid_request

No client_id or stripe_user_id parameter provided (where required).

invalid_client

A variety of things can prompt this error:

  • client_id does not belong to you
  • stripe_user_id does not exist or is not connect to your application
  • API key mode (live or test mode) does not match the client_id mode
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Common examples
Authorize the account
Complete the connection and get the account ID
Revoke the account's access