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.
Prefilling 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.
Sending 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 setting the redirect URI
For security purposes, Stripe only redirects a user 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:
- In your platform settings, add each redirect URI.
- 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.
Express account differences
The reference information below mostly applies to both Standard and Express accounts with the following differences for Express:
- The authorization URL is https://connect.stripe.com/express/oauth/authorize (it’s still a GET request, though).
- You don’t need to request a
scope
(we’ll always return express). - Only these fields can be prefilled:
stripe_user[business_name]
, assuming astripe_user[business_type]
ofcompany
stripe_user[business_type]
stripe_user[email]
stripe_user[first_name]
stripe_user[last_name]
stripe_user[phone_number]
- You can only set
stripe_user[business_type]
to eitherindividual
(the default) orcompany
. - You can only set
suggested_capabilities[]
to eithercard_payments
orplatform_payments
. - You can only set
assert_capabilities[]
to eithercard_payments
orplatform_payments
.
GET https://connect.stripe.com/oauth/authorize
This endpoint sends the user to Stripe to connect to your platform.
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_uri Optional |
The URL for the authorize response redirect. If provided, this must exactly match one of the comma-separated To protect yourself from certain forms of man-in-the-middle attacks, the live mode Defaults to the |
scope Optional |
read_write or read_only, depending on the level of access you need. Defaults to read_only. |
state Optional |
An arbitrary string value we will pass back to you, useful for CSRF protection. |
stripe_landing Optional |
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_prompt Optional |
Boolean to indicate that the user should always be asked to connect, even if they're already connected. Defaults to false. |
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.
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[business_name] |
The legal name of the business, also used for the statement descriptor. |
stripe_user[business_type] |
The type of the business. Must be one of sole_prop, corporation, non_profit, partnership, or llc. |
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. All three are required. |
stripe_user[street_address] |
Street address of the business. |
stripe_user[city] |
Address city of the business. We highly recommend that you also prefill |
stripe_user[state] |
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[zip] |
Address 郵便番号 of the business. Must be a string. We highly recommend that you also prefill |
stripe_user[physical_product] |
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] |
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[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[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[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[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[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[block_kana] |
The Kana variation of the address block. This parameter is only relevant for Japan. You must prefill |
stripe_user[block_kanji] |
The Kanji variation of the address block. This parameter is only relevant for Japan. You must prefill |
stripe_user[building_kana] |
The Kana variation of the address building. This parameter is only relevant for Japan. You must prefill |
stripe_user[building_kanji] |
The Kanji variation of the address building. This parameter is only relevant for Japan. You must prefill |
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 |
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 |
Error Codes
Parameter | Description |
---|---|
access_denied |
User denied authorization. |
invalid_scope |
Invalid |
invalid_redirect_uri |
Provided |
invalid_request |
Missing |
unsupported_response_type |
Unsupported |
POST https://connect.stripe.com/oauth/token
This endpoint is used both for turning an authorization_code
into an access_token
, 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 \
-d client_secret="{SECRET_API_KEY}"
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 |
scope Optional |
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. |
Response
Parameter | Description |
---|---|
access_token |
The access token you can use to make requests on behalf of this Stripe account. Use it as you would any Stripe secret API key. This key does not expire, but may be revoked by the user at any time (you'll get a |
scope |
The scope granted to the access token, depending on the scope of the authorization code and |
livemode |
The live mode indicator for the token. If true, the 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 |
invalid_grant |
A variety of things can prompt this error:
|
unsupported_grant_type |
Unsupported |
invalid_scope |
Invalid |
unsupported_response_type |
Unsupported |
POST https://connect.stripe.com/oauth/deauthorize
This endpoint is used for revoking access to an account.
Request
This call should be made using your secret API key as an Authorization header.
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 |
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 |
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 |
invalid_client |
A variety of things can prompt this error:
|