Making API calls for connected accounts

Learn how to add the right information to your API calls so you can make calls for your connected accounts.

You can make API calls for your connected accounts:

Server-side with the Stripe-Account header and the connected account ID, per request
Client-side by passing the connected account ID as an argument to the client application
Server-side with the connected account API keys (legacy, not recommended)

The first two options required the ID of the connected account. Here’s how to get it:

For Standard accounts: when you complete the connection between your platform and the account
For Express accounts: when you complete the connection between your platform and the account
For Custom accounts: when you create the account with a call to the Accounts API

Adding the Stripe-Account header server-side

Server-side API calls should include the platform account secret key and pass a Stripe-Account header with the ID of the connected account the call is for. This curl request performs a refund of a charge on a connected account:

curl https://api.stripe.com/v1/charges/{{CHARGE_ID}}/refunds \
  -u {{PLATFORM_SECRET_KEY}}: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -d amount=1000
curl https://api.stripe.com/v1/charges/{{CHARGE_ID}}/refunds \
  -u {{PLATFORM_SECRET_KEY}}: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -d amount=1000

The Stripe-Account header approach is implied in any API request that includes the Stripe account ID in the URL:

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u {{PLATFORM_SECRET_KEY}}:
curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u {{PLATFORM_SECRET_KEY}}:

All of Stripe’s server-side libraries support this approach on a per-request basis:

Stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
Stripe::Customer.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
)

# Fetching an account just needs the ID as a parameter
Stripe::Account.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}')
Stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
Stripe::Customer.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
)

# Fetching an account just needs the ID as a parameter
Stripe::Account.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}')

stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
stripe.Customer.create(
  email="person@example.edu",
  stripe_account="{{CONNECTED_STRIPE_ACCOUNT_ID}}"
)

# Fetching an account just needs the ID as a parameter
stripe.Account.retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}")
stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
stripe.Customer.create(
  email="person@example.edu",
  stripe_account="{{CONNECTED_STRIPE_ACCOUNT_ID}}"
)

# Fetching an account just needs the ID as a parameter
stripe.Account.retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}")

\Stripe\Stripe::setApiKey("{{PLATFORM_SECRET_KEY}}");
\Stripe\Customer::create(
  ["email" => "person@example.edu"],
  ["stripe_account" => "{{CONNECTED_STRIPE_ACCOUNT_ID}}"]
);

// Fetching an account just needs the ID as a parameter
\Stripe\Account::retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}");
\Stripe\Stripe::setApiKey("{{PLATFORM_SECRET_KEY}}");
\Stripe\Customer::create(
  ["email" => "person@example.edu"],
  ["stripe_account" => "{{CONNECTED_STRIPE_ACCOUNT_ID}}"]
);

// Fetching an account just needs the ID as a parameter
\Stripe\Account::retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}");

Stripe.apiKey = "{{PLATFORM_SECRET_KEY}}";
RequestOptions requestOptions = RequestOptions.builder().setStripeAccount("{{CONNECTED_STRIPE_ACCOUNT_ID}}").build();

Map<String, Object> params = new HashMap<>();
params.put("email", "person@example.edu");

Customer.create(params, requestOptions);

// Fetching an account just needs the ID as a parameter
Account.retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}");
Stripe.apiKey = "{{PLATFORM_SECRET_KEY}}";
RequestOptions requestOptions = RequestOptions.builder().setStripeAccount("{{CONNECTED_STRIPE_ACCOUNT_ID}}").build();

Map<String, Object> params = new HashMap<>();
params.put("email", "person@example.edu");

Customer.create(params, requestOptions);

// Fetching an account just needs the ID as a parameter
Account.retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}");

const stripe = require('stripe')('{{PLATFORM_SECRET_KEY}}');
const customer = await stripe.customers.create(
  {email: 'person@example.edu'},
  {stripeAccount: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
);

// Fetching an account just needs the ID as a parameter
const account = await stripe.accounts.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}');
const stripe = require('stripe')('{{PLATFORM_SECRET_KEY}}');
const customer = await stripe.customers.create(
  {email: 'person@example.edu'},
  {stripeAccount: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
);

// Fetching an account just needs the ID as a parameter
const account = await stripe.accounts.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}');

stripe.Key = "{{PLATFORM_SECRET_KEY}}"
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
params.SetStripeAccount("{{CONNECTED_STRIPE_ACCOUNT_ID}}")
cus, _ := customer.New(params)

// Fetching an account just needs the ID as a parameter
acct, _ := account.GetByID("{{CONNECTED_STRIPE_ACCOUNT_ID}}", nil);
stripe.Key = "{{PLATFORM_SECRET_KEY}}"
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
params.SetStripeAccount("{{CONNECTED_STRIPE_ACCOUNT_ID}}")
cus, _ := customer.New(params)

// Fetching an account just needs the ID as a parameter
acct, _ := account.GetByID("{{CONNECTED_STRIPE_ACCOUNT_ID}}", nil);

StripeConfiguration.ApiKey = "{{PLATFORM_SECRET_KEY}}";
var customerOptions = new CustomerCreateOptions
{
  Email = "person@example.edu",
};
var requestOptions = new RequestOptions();
requestOptions.StripeAccount = "{{CONNECTED_ACCOUNT_ID}}";
var customerService = new CustomerService();
Customer customer = customerService.Create(customerOptions, requestOptions);

// Fetching an account just needs the ID as a parameter
var accountService = new AccountService();
Account account = accountService.Get("{{CONNECTED_STRIPE_ACCOUNT_ID}}");
StripeConfiguration.ApiKey = "{{PLATFORM_SECRET_KEY}}";
var customerOptions = new CustomerCreateOptions
{
  Email = "person@example.edu",
};
var requestOptions = new RequestOptions();
requestOptions.StripeAccount = "{{CONNECTED_ACCOUNT_ID}}";
var customerService = new CustomerService();
Customer customer = customerService.Create(customerOptions, requestOptions);

// Fetching an account just needs the ID as a parameter
var accountService = new AccountService();
Account account = accountService.Get("{{CONNECTED_STRIPE_ACCOUNT_ID}}");

Adding the connected account ID to a client-side application

Client-side libraries set the connected account ID as an argument to the client application:

The JavaScript code for passing the connected account ID client-side is the same for plain JS and for ESNext.

var stripe = Stripe("{{PLATFORM_PUBLISHABLE_KEY }}", { stripeAccount: "{{CONNECTED_STRIPE_ACCOUNT_ID}}"});
var stripe = Stripe("{{PLATFORM_PUBLISHABLE_KEY }}", { stripeAccount: "{{CONNECTED_STRIPE_ACCOUNT_ID}}"});

import UIKit
import Stripe

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        Stripe.setDefaultPublishableKey("{{PLATFORM_PUBLISHABLE_KEY}}")
        STPAPIClient.shared().stripeAccount = "{{CONNECTED_STRIPE_ACCOUNT_ID}}"

        // For SDK versions < v19.0.0, set this too:
        STPPaymentConfiguration.shared().stripeAccount = "{{CONNECTED_STRIPE_ACCOUNT_ID}}"
        return true
    }
}
import UIKit
import Stripe

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        Stripe.setDefaultPublishableKey("{{PLATFORM_PUBLISHABLE_KEY}}")
        STPAPIClient.shared().stripeAccount = "{{CONNECTED_STRIPE_ACCOUNT_ID}}"

        // For SDK versions < v19.0.0, set this too:
        STPPaymentConfiguration.shared().stripeAccount = "{{CONNECTED_STRIPE_ACCOUNT_ID}}"
        return true
    }
}

#import "AppDelegate.h"
#import <Stripe/Stripe.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Stripe setDefaultPublishableKey:@"{{PLATFORM_PUBLISHABLE_KEY}}"];
    [STPAPIClient sharedClient] setStripeAccount:@"{{CONNECTED_STRIPE_ACCOUNT_ID}}"];

    // For SDK versions < v19.0.0, set this too:
    [[STPPaymentConfiguration sharedConfiguration] setStripeAccount:@"{{CONNECTED_STRIPE_ACCOUNT_ID}}"];
    return YES;
}
@end
#import "AppDelegate.h"
#import <Stripe/Stripe.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Stripe setDefaultPublishableKey:@"{{PLATFORM_PUBLISHABLE_KEY}}"];
    [STPAPIClient sharedClient] setStripeAccount:@"{{CONNECTED_STRIPE_ACCOUNT_ID}}"];

    // For SDK versions < v19.0.0, set this too:
    [[STPPaymentConfiguration sharedConfiguration] setStripeAccount:@"{{CONNECTED_STRIPE_ACCOUNT_ID}}"];
    return YES;
}
@end

import com.stripe.android.PaymentConfiguration

class MyActivity: Activity() {
    private lateinit var stripe: Stripe

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        stripe = Stripe(
            this,
            PaymentConfiguration.getInstance(this).publishableKey,
            "{{CONNECTED_STRIPE_ACCOUNT_ID}}"
        )
    }
}
import com.stripe.android.PaymentConfiguration

class MyActivity: Activity() {
    private lateinit var stripe: Stripe

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        stripe = Stripe(
            this,
            PaymentConfiguration.getInstance(this).publishableKey,
            "{{CONNECTED_STRIPE_ACCOUNT_ID}}"
        )
    }
}

import com.stripe.android.PaymentConfiguration;

public class MyActivity extends Activity {
    private Stripe stripe;

    @Override
    public void onCreate(@Nullable Bundle savedInstancedState) {
        super.onCreate(savedInstancedState);
        stripe = new Stripe(
            this,
            PaymentConfiguration.getInstance(this).getPublishableKey(),
            "{{CONNECTED_STRIPE_ACCOUNT_ID}}"
        );
    }
}
import com.stripe.android.PaymentConfiguration;

public class MyActivity extends Activity {
    private Stripe stripe;

    @Override
    public void onCreate(@Nullable Bundle savedInstancedState) {
        super.onCreate(savedInstancedState);
        stripe = new Stripe(
            this,
            PaymentConfiguration.getInstance(this).getPublishableKey(),
            "{{CONNECTED_STRIPE_ACCOUNT_ID}}"
        );
    }
}

Using connected account API keys

This option makes API calls using the secret and publishable keys obtained during the OAuth flow for Standard and Express accounts. Those keys are specifically created for your platform to make API requests on this connected account. The secret key is returned in the access_token property and the publishable key in the stripe_publishable_key property provided in the response from the /oauth/token OAuth endpoint. API keys are provided only when the account is first connected. You cannot retrieve a connected account’s API keys after a connection has been established.

API keys grant broad permissions, including the ability to read and write sensitive data and move money. If your platform was compromised, leaked API keys could cause serious issues. For this reason, we strongly recommend using the Stripe-Account header as outlined above, which should work for most platforms. In general, API keys are only necessary when a central server is not used to make API requests. For example, if your platform operates as a plugin for WordPress or other self-hosted software, you can make API requests directly from the plugin where your platform’s API keys are not available.

This code performs the same refund request as the example that shows the Stripe-Account header:

curl https://api.stripe.com/v1/charges/{{CHARGE_ID}}/refunds \
  -u {{CONNECTED_ACCOUNT_SECRET_KEY}}: \
  -d amount=1000
curl https://api.stripe.com/v1/charges/{{CHARGE_ID}}/refunds \
  -u {{CONNECTED_ACCOUNT_SECRET_KEY}}: \
  -d amount=1000

If you are using this method, we recommend that you perform authentication with every request, instead of setting the API key globally. All of Stripe’s libraries support this style of authentication on a per-request basis:

# Not recommended: setting global API key state
Stripe.api_key = '{{CONNECTED_ACCOUNT_SECRET_KEY}}'
Stripe::Customer.create({
  email: 'person@example.edu'
})

# Recommended: sending API key with every request
Stripe::Customer.create({
  email: 'person@example.edu',
}, {
  api_key: '{{CONNECTED_ACCOUNT_SECRET_KEY}}', # account's access token from the Connect flow
})
# Not recommended: setting global API key state
Stripe.api_key = '{{CONNECTED_ACCOUNT_SECRET_KEY}}'
Stripe::Customer.create({
  email: 'person@example.edu'
})

# Recommended: sending API key with every request
Stripe::Customer.create({
  email: 'person@example.edu',
}, {
  api_key: '{{CONNECTED_ACCOUNT_SECRET_KEY}}', # account's access token from the Connect flow
})

# Not recommended: setting global API key state
stripe.api_key = '{{CONNECTED_ACCOUNT_SECRET_KEY}}'
stripe.Customer.create(
  email='person@example.edu'
)

# Recommended: sending API key with every request
stripe.Customer.create(
  email='person@example.edu',
  api_key='{{CONNECTED_ACCOUNT_SECRET_KEY}}' # account's access token from the Connect flow
)
# Not recommended: setting global API key state
stripe.api_key = '{{CONNECTED_ACCOUNT_SECRET_KEY}}'
stripe.Customer.create(
  email='person@example.edu'
)

# Recommended: sending API key with every request
stripe.Customer.create(
  email='person@example.edu',
  api_key='{{CONNECTED_ACCOUNT_SECRET_KEY}}' # account's access token from the Connect flow
)

// Not recommended: setting global API key state
\Stripe\Stripe::setApiKey('{{CONNECTED_ACCOUNT_SECRET_KEY}}');
\Stripe\Customer::create([
  'email' => 'person@example.edu',
]);

// Recommended: sending API key with every request
\Stripe\Customer::create([
  'email' => 'person@example.edu',
], [
  'api_key' => '{{CONNECTED_ACCOUNT_SECRET_KEY}}', // account's access token from the Connect flow
]);
// Not recommended: setting global API key state
\Stripe\Stripe::setApiKey('{{CONNECTED_ACCOUNT_SECRET_KEY}}');
\Stripe\Customer::create([
  'email' => 'person@example.edu',
]);

// Recommended: sending API key with every request
\Stripe\Customer::create([
  'email' => 'person@example.edu',
], [
  'api_key' => '{{CONNECTED_ACCOUNT_SECRET_KEY}}', // account's access token from the Connect flow
]);

// Not recommended: setting global API key state
Stripe.apiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";

CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("person@example.edu")
    .build();

Customer customer = Customer.create(params);

// Recommended: sending API key with every request
CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("person@example.edu")
    .build();

RequestOptions requestOptions =
  RequestOptions.builder()
    // Set account's access token from the Connect flow
    .setApiKey("{{CONNECTED_ACCOUNT_SECRET_KEY}}")
    .build();

Customer customer =  Customer.create(params, requestOptions);
// Not recommended: setting global API key state
Stripe.apiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";

CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("person@example.edu")
    .build();

Customer customer = Customer.create(params);

// Recommended: sending API key with every request
CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("person@example.edu")
    .build();

RequestOptions requestOptions =
  RequestOptions.builder()
    // Set account's access token from the Connect flow
    .setApiKey("{{CONNECTED_ACCOUNT_SECRET_KEY}}")
    .build();

Customer customer =  Customer.create(params, requestOptions);

// Not recommended: setting global API key state
const stripe = require('stripe')('{{CONNECTED_ACCOUNT_SECRET_KEY}}');
const customer = await stripe.customers.create({
  email: 'person@example.edu',
});

// Recommended: sending API key with every request
const secondCustomer = await stripe.customers.create({
  email: 'person@example.edu',
}, {
  api_key: '{{CONNECTED_ACCOUNT_SECRET_KEY}}', // account's access token from the Connect flow
});
// Not recommended: setting global API key state
const stripe = require('stripe')('{{CONNECTED_ACCOUNT_SECRET_KEY}}');
const customer = await stripe.customers.create({
  email: 'person@example.edu',
});

// Recommended: sending API key with every request
const secondCustomer = await stripe.customers.create({
  email: 'person@example.edu',
}, {
  api_key: '{{CONNECTED_ACCOUNT_SECRET_KEY}}', // account's access token from the Connect flow
});

// Not recommended: setting global API key state
stripe := &client.API{}
stripe.Init("access_token", "{{CONNECTED_ACCOUNT_SECRET_KEY}}")
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
cus, _ := customer.New(params)

// Recommended: custom client with the correct API key
sc := &client.API{}
// Set account's access token from the Connect flow
sc.Init("{{CONNECTED_ACCOUNT_SECRET_KEY}}", nil)

params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
cus, _ := sc.Customers.New(params)
// Not recommended: setting global API key state
stripe := &client.API{}
stripe.Init("access_token", "{{CONNECTED_ACCOUNT_SECRET_KEY}}")
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
cus, _ := customer.New(params)

// Recommended: custom client with the correct API key
sc := &client.API{}
// Set account's access token from the Connect flow
sc.Init("{{CONNECTED_ACCOUNT_SECRET_KEY}}", nil)

params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
cus, _ := sc.Customers.New(params)

// Not recommended: setting global API key state
StripeConfiguration.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";
var options = new CustomerCreateOptions
{
  Email = "person@example.edu",
};
var service = new CustomerService();
var customer = service.Create(options);

// Recommended: sending API key with every request
var options = new CustomerCreateOptions
{
  Email = "person@example.edu",
};
var requestOptions = new RequestOptions();
requestOptions.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";
var service = new CustomerService();
var customer = service.Create(options);
// Not recommended: setting global API key state
StripeConfiguration.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";
var options = new CustomerCreateOptions
{
  Email = "person@example.edu",
};
var service = new CustomerService();
var customer = service.Create(options);

// Recommended: sending API key with every request
var options = new CustomerCreateOptions
{
  Email = "person@example.edu",
};
var requestOptions = new RequestOptions();
requestOptions.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";
var service = new CustomerService();
var customer = service.Create(options);

Protect your API keys. They should remain internal to your systems and never be accessible in a browser. Don't expose connected account API keys through your own API endpoints.

Next steps

Learn about the API calls you can make for your connected accounts: