Using install linksPublic preview

Set your allowed_redirect_uris in your app manifest. These are the URLs that users are redirected to after installing your app. You must specify all redirect URLs in your app settings.

After you’ve set allowed_redirect_uris, upload a new version of your app.

{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "app_backend": {},
  "ui_extension": {},
  "allowed_redirect_uris": [
    "https://example.com/callback/stripe"
  ]
}

You can use external testing with the following steps to test the install link before submitting it for review:

1. Create an external test for your app using the version with allowed_redirect_uris defined in the app manifest. You can update the testing version to the desired one if a test already exists.
2. The External test tab shows a test install link and displays the allowed redirects in a table.
3. When you’re ready to publish, make sure that you upload a new version with any testing URIs and values replaced with the values you intend to use in production.

When you’ve finished testing, you can make it available for all users with the following steps:

1. Publish a new version of your app that defines allowed_redirect_uris.
2. Click the Settings tab. The install link is shown here, and you can copy it. The link looks like this: https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com.
3. Recommended To prevent CSRF attacks, you can add the recommended state parameter and pass along a unique token as the value. We’ll include the state you provided when redirecting users to your site. Your site can confirm that the state parameter hasn’t been modified.
4. After a user clicks the install link, Stripe opens the following page where they can select an account, review app details, and proceed with the installation.

Install link account selection

After the user installs your app, they’re redirected to the redirect_uri URL parameter that matches a defined redirect in allowed_redirect_uris in your app manifest.

Successful installation

For successful installations, the URL includes:

• The user_id value. The ID of the Stripe user that initiated the install.
• The account_id value. The ID of the Stripe account that installed your app.
• The state value, if provided
• The install_signature value. This a hash of the above values that’s generated using your app’s signing secret.
• If the app is installed into test mode or a sandbox environment, a livemode=false value is appended to the redirect URL.

An example of a live mode redirect:

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}

An example of a test mode and sandbox environment redirect:

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false

Installation failure

If the user cancels the installation, they will still be redirected to your site, but the URL includes an error instead:

https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request

The user is now connected to your app. Store the account_id in your database—this is the user’s Stripe account ID. You’ll use this value to authenticate as the connected account by passing it into requests in the Stripe-Account header.

Verify app installs with install_signature Recommended

It’s important to verify that your app’s user was authorized to install the app for the account provided in the redirect URL. An install_signature is included for this reason. This signature is generated from your app’s signing secret and the user_id and account_id that completed the install. The signature also includes the passed state, if provided. The signature can’t be replicated without access to the signing secret, which is only available internally to Stripe and to your app’s backend. Because of this, bad actors can’t replicate the hash if they were to try and spoof the redirect URL. By verifying the app signature, you can trust that the account is associated with your app user.

To verify the signature, follow these steps:

1. Create your app’s signing secret if you haven’t done so already.
2. Setup an app backend to verify the install_signature.

Sample backend verifying the install:

The order and naming of the payload fields matter when performing signature verification. The state precedes the user_id, which precedes the account_id. The resulting object should be { state, user_id, account_id }.

require 'stripe'
require 'sinatra'
require 'json'

Stripe.api_key = 'API_KEY'

get '/' do
  'Install Links verification example'
end

get '/verify' do
  user_id = params[:user_id]
  account_id = params[:account_id]
  state = params[:state]
  install_signature = params[:install_signature]

  payload = JSON.dump({
    state: state,
    user_id: user_id,
    account_id: account_id
  })

  begin
    Stripe::Webhook::Signature.verify_header(
      payload,
      install_signature,
      'STRIPE_APP_SECRET'
    )
  rescue Stripe::SignatureVerificationError => e
    return e.message, 400
  end

  { success: true }.to_json
end

set :port, 3000

After it’s verified, you can make API calls on behalf of the installed account.

For server-side API calls, you can make requests as connected accounts using the special header Stripe-Account with the Stripe account identifier (it starts with the prefix acct_) of your platform user. Here’s an example that shows how to Create a PaymentIntent with your platform’s API secret key and your user’s Account identifier.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card

The Stripe-Account header approach is implied in any API request that includes the Stripe account ID in the URL. Here’s an example that shows how to Retrieve an account with your user’s Account identifier in the URL.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

See more examples of making an authenticated request here.