Make API calls for your 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:

    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

    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}}:

    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\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<String, Object>(); 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}}'); stripe.customers.create( {email: 'person@example.edu'}, {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'} ); // Fetching an account just needs the ID as a parameter 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, err := customer.New(params) // Fetching an account just needs the ID as a parameter acct, err := 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}}");

    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}}"});
    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}}" 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}}"]; [[STPPaymentConfiguration sharedConfiguration] setStripeAccount:@"{{CONNECTED_STRIPE_ACCOUNT_ID}}"]; return YES; } @end
    import com.stripe.android.PaymentConfiguration; public class MyActivity extends Activity { private Stripe stripe; @Override public void onCreate(@Nullable Bundle savedInstancedState) { super.onCreate(savedInstancedState); PaymentConfiguration.init(this, "{{PLATFORM_PUBLISHABLE_KEY }}", "{{CONNECTED_STRIPE_ACCOUNT_ID}}"); stripe = new Stripe(getApplicationContext(), 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) PaymentConfiguration.init(this, "{{PLATFORM_PUBLISHABLE_KEY }}", "{{CONNECTED_STRIPE_ACCOUNT_ID}}") stripe = Stripe(applicationContext, PaymentConfiguration.getInstance(this).publishableKey, "{{CONNECTED_STRIPE_ACCOUNT_ID}}") } }

    Adding API keys

    This option makes API calls using the connected account’s secret and publishable keys. How a platform receives a connected account’s secret key depends upon the connection method:

    • For Standard and Express accounts, it’s the access_token, provided by the OAuth flow
    • For Custom accounts, it’s in the keys[secret] property returned by the create account API call

    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

    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\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}}"; Map<String, Object> params = new HashMap<String, Object>(); params.put("email", "person@example.edu"); Customer.create(params); // Recommended: sending API key with every request RequestOptions requestOptions = RequestOptions.builder().setApiKey("{{CONNECTED_ACCOUNT_SECRET_KEY}}").build(); Map<String, Object> params = new HashMap<String, Object>(); params.put("email", "person@example.edu"); Customer.create(params, requestOptions);
    // Not recommended: setting global API key state const stripe = require('stripe')('{{CONNECTED_ACCOUNT_SECRET_KEY}}'); stripe.customers.create({ email: 'person@example.edu' }); // Recommended: sending API key with every request 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, err := customer.New(params) // Recommended: sending API key with every request params := &stripe.CustomerParams{ Email: stripe.String("person@example.edu"), Key: "{{CONNECTED_ACCOUNT_SECRET_KEY}}", } cus, err := customer.New(params)
    // Not recommended: setting global API key state StripeConfiguration.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}"; var customerOptions = new CustomerCreateOptions { Email = "person@example.edu", }; var customerService = new CustomerService(); Customer customer = customerService.Create(customerOptions); // Recommended: sending API key with every request var customerOptions = new CustomerCreateOptions { Email = "person@example.edu", }; var customerService = new CustomerService(); var requestOptions = new RequestOptions(); requestOptions.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}"; Customer customer = customerService.Create(customerOptions);

    Next steps

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

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page