Building Integrations

    Learn how to build Stripe integrations. To see what others have built, check out the Works with Stripe gallery.

    Stripe’s products and features allow companies to accept online payments, but there are other reasons to integrate as well. Companies like Baremetrics and Zapier build on top of Stripe to provide their services. Integrations like these use a subset of Stripe Connect functionality to access Stripe data and connected accounts.

    There are three steps to building an integration:

    1. Register your platform.
    2. Connect accounts using OAuth.
    3. Use the API on behalf of connected accounts.

    Step 1: Register your platform

    To register your application, fill out the Standard account form in your Dashboard:

    Users see your logo when they link their Stripe accounts to your application. After the accounts are linked, your icon is displayed in their connected applications list.

    Stripe provides a unique identifier for your platform called a client_id. The redirect_uri is set by you and is the page users are directed to after connecting their accounts. The development and production versions of these values make testing easier. Take note of these values now so you can complete the next step.

    Step 2: Connect accounts using OAuth

    Stripe offers a standard OAuth 2.0 flow to connect to Stripe accounts. To complete the flow, you need a page that starts the connection process, and a page that users are directed to after connecting their accounts. The redirect page is the same as your redirect_uri.

    With these pages in place, you can use your client_id and redirect_url to create a Connect with Stripe button that sends users to our authorize_url endpoint:

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

    Here’s an example of what the button looks like:

    Connect with Stripe

    After clicking the button, users are taken to a page like the one below to review the requested permissions and link their account:

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

    {
      ...
      "stripe_user_id": "acct_JcjwALAXg1alBv",
      ...
    }

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

    Step 3: Use the API on behalf of connected 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 platform account secret key, and a Stripe-Account header that identifies the account the request is 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 (e.g., retrieve a charge) or a list of objects (e.g., list charges).

    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    Stripe::Charge.list(
      {
        :limit => 50,
        :created => {"lte": 1483228800}
      },
      {:stripe_account => CONNECTED_STRIPE_ACCOUNT_ID}
    )
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    stripe.Charge.list(
      limit=50,
      created={"lte": 1483228800},
      stripe_account=CONNECTED_STRIPE_ACCOUNT_ID
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    \Stripe\Charge::all(
      array(
        "limit" => 50,
        "created" => array("lte" => 1483228800)
      ),
      array("stripe_account" => CONNECTED_STRIPE_ACCOUNT_ID)
    );
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    RequestOptions requestOptions = RequestOptions.builder().setStripeAccount(CONNECTED_STRIPE_ACCOUNT_ID).build();
    
    Map<String, Object> chargeParams = new HashMap<String, Object>();
    chargeParams.put("limit", 50);
    chargeParams.put("created", {"lte": 1483228800});
    
    Charge.list(chargeParams, requestOptions);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    stripe.charges.list(
      {
        limit: 50,
        created: {lte: 1483228800}
      },
      {stripe_account: CONNECTED_STRIPE_ACCOUNT_ID}
    );
    

    The API is designed for performance, but repeatedly fetching large data sets will slow 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. Once you’ve defined a platform 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 the event occurred on.

    For example, the event below shows a customer was created in the acct_JcjwALAXg1alBv 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_iu1mxH8KQqwrwt",
      "livemode": true,
      "object": "event",
      "type": "customer.created",
      "account": "acct_JcjwALAXg1alBv",
      "pending_webhooks": 2,
      "created": 1349654313,
      "data": {...}
    }

    Charging for your application

    Your platform’s Stripe account can process its own charges, so you can still charge for your application with read_only access. After customers connect their Stripe accounts, ask for their payment details and then create a subscription for them in your Stripe account. Make sure to store the created customer ID with the associated Stripe account ID and you can track which users are paid and active, and which ones are not.

    If you create subscriptions, you can also specify an application_fee_percent as a fee for your application. This is charged on top of any Stripe fees. Read the subscriptions documentation to learn more.

    Disconnected accounts

    Users can disconnect their accounts from your integration at any time. When this happens, an account.application.deauthorized webhook event is sent. You can use this notification to trigger clean up on your end, such as disabling the user’s account on your site or removing their data.

    You can also disconnect accounts from your integration by making a request to the OAuth deauthorization endpoint.

    Submitting your integration to our gallery

    The Works with Stripe gallery showcases hundreds of applications and services already integrated with Stripe. To be included, contact us with some basic information about your integration.