Public preview

Using install links Public preview

Allow users to install your app outside the Stripe App Marketplace.

Install links allow users to install public apps outside the Stripe App Marketplace. With one integrated flow, you can pass state from your application, complete the installation of the Stripe App, and redirect to your application or site.

The install link page

Overview

With the following steps, a user can install an app using an install link:

1. On your site, the user clicks a link that redirects them to Stripe, passing along the app _ id .
2. On Stripe, the user selects the appropriate account and accepts permissions for installing the app.
3. After installation, the user redirects to your site , along with the Stripe account for the given user.
4. Your app can now make authenticated account requests.

Create an install link

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.

stripe-app.json

Test your install link

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.

Using an install link

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. the relevant part of the product/{id}?redirect _ uri=https://example. com .
3. Recommended To prevent the related setting 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

Redirecting to your site

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:

An example of a test mode and sandbox environment redirect:

Installation failure

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

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 authorised 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 back end. Because of this, bad actors can’t replicate the hash if they try to 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. Set up an app back end to verify the install _ signature .

Sample back end 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 }.

Select a language

Ruby

Python

PHP

Node.js

No results

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

client = Stripe::StripeClient.new('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.

Make authenticated requests

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.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

See more examples of making an authenticated request here.

Customise links with URL parameters

You can change the behaviour of the app installation by including additional URL parameters in the install link.

Supported URL parameters

Prevent the related setting attacks with the state parameter

To prevent cross-site request forgery (the related setting) attacks, you can use the state parameter. This parameter accepts any string value and returns it unmodified upon redirecting the installer back to your application or platform. To use this parameter, pass a unique and non-guessable value when you initiate an install using an install link. Save the value to use it for verification later.

After the user installs and is redirected back to your application, verify whether the value of the state parameter provided matches the value present in the initial install link. This verification process provides a high-level of confidence to confirm that the account_id returned belongs to the user who initiated the install and safeguard against potential forgeries.

Revoking access

An account.application.deauthorized event occurs when a user disconnects your app from their account. You can perform any necessary clean-up on your servers by watching for this event with webhooks.

See also

• How Stripe Apps work
• Full API reference