Build a Stripe extension

You can configure this setting in the Integration section of the Extensions Settings page.

Start your integration by toggling the button to enable onboarding Standard accounts with OAuth. Extensions shouldn’t use OAuth with Express accounts.

Stripe provides a unique identifier for your extension called a client_id. You set the redirect_uri and users are directed to that page after they connect their accounts. You must specify all redirect URIs in your extension settings. The development and production versions of these two values make testing easier. Take note of these values so you can create an OAuth link in the third step.

You can customize how your business appears to your users in the Branding section of the Extensions Settings page.

Users see your logo when they link their Stripe accounts to your application. After they link their accounts, your icon displays in their connected applications list.

Stripe offers a standard OAuth 2.0 flow to connect to Stripe accounts. Using the client_id and redirect_uri values from step one, you can create an OAuth link for your users to onboard with. We recommend showing this link with a Connect button that sends users to our authorize_url endpoint:

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

Here’s an example of how you can display the above link to your user, along with the Connect with Stripe button:

After the user clicks the link on your site, we redirect them to a page to allow or deny the connection to your extension. Stripe’s authorization flow prompts them to either choose an existing account to connect with your extension, or create a new one.

After the user connects their existing or newly created account to your extension, we redirect them back to the URL you set as your extension’s redirect_uri .

At the end of the OAuth workflow, you’re provided with authorization credentials for the user’s account:

{
  ...
  "stripe_user_id": "acct_0123456789",
  ...
}

You need to store the stripe_user_id so you can identify user accounts.

After users link their Stripe accounts to your application, you can make API requests on their behalf. To perform API requests, you need your extension account’s secret key, and a Stripe-Account header that identifies the account that you’re making the request for. All Stripe libraries support this style of authentication on a per-request basis.

Fetching stored data

Stored data includes information like charges and customer details. With read_only access, you can make most GET requests in Stripe’s API. You can retrieve a single object (for example, retrieve a Payment Intent) or a list of objects (for example, list all Payment Intents).

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "created[lte]"=1612048287 \
  -d "limit"=50 \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

While the API performs at a high level, repeatedly fetching large data sets slows your application’s responsiveness. We recommended storing fetched data on your side for analysis and reporting.

Listening for real-time data

In addition to stored data, you can access real-time data via webhooks. After you define an extension webhook endpoint in your account, Stripe sends event notifications to your endpoint for every connected account. The event object’s account property identifies the account where the event occurred.

For example, the event below shows that a customer was created in the acct_0123456789 account. Again, we recommend storing this data on your side for analysis and reporting. By watching events as they occur, your application can respond faster, and you won’t need to make as many API calls.

{
  "id": "evt_SkLUhegNFdwLxb",
  "livemode": true,
  "object": "event",
  "type": "customer.created",
  "account": "acct_0123456789",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}