Managing Capabilities

    Learn how to request, unrequest, and enable capabilities for your connected accounts.

    Capabilities enable specific functionality on your platform’s connected accounts as well as directly impacting the overall onboarding requirements for those accounts. You can request them at account creation by using the create an account method. If you need to change capabilities after an account is created, use the Capabilities API. You can also preview what the requirements are for a capability before or after it is requested.

    By default, capabilities are unrequested. Requesting a capability transitions its status from being unrequested to any of these: pending, active, or inactive. When you request a capability, it activates the requirements for the account but does not necessarily enable the capability immediately. You can view these requirements from the requirements hash. When capabilities are unrequested, their status is changed to unrequested and the requirements are deactivated. Time, processing volume, information collection, and asynchronous verification processes can and do affect the capability’s status. For example, a capability on an account can have a pending status which means it is not enabled while verification is being reviewed. When requirements are successfully collected and verified, the capability becomes active for the account.

    Creating accounts with capabilities

    Capabilities are set on the Account object. When creating accounts, use the requested_capabilities argument to assign capabilities. To find the list of available capabilities, use the list_capabilities endpoint. You can read more about creating Standard, Express, and Custom accounts in their respective sections.

    curl https://api.stripe.com/v1/accounts \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d type=custom \
      -d country=US \
      -d business_type=company \
      -d requested_capabilities[]=card_payments
    
    # 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_4eC39HqLyjWDarjtT1zdp7dc'
    
    Stripe::Account.create({
      type: 'custom',
      country: 'US',
      business_type: 'company',
      requested_capabilities: ['card_payments'],
    })
    
    # 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_4eC39HqLyjWDarjtT1zdp7dc'
    
    stripe.Account.create(
      type='custom',
      country='US',
      business_type='company',
      requested_capabilities=['card_payments']
    )
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc');
    
    \Stripe\Account::create([
      "type" => "custom",
      "country" => "US",
      "business_type" => "company",
      "requested_capabilities" => ["card_payments"],
    ]);
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc";
    
    Map<String, Object> accountParams = new HashMap<String, Object>();
    accountParams.put("type", "custom");
    accountParams.put("country", "US");
    accountParams.put("business_type", "company");
    accountParams.put("requested_capabilities", Arrays.asList("card_payments"));
    
    Account.create(accountParams);
    
    // 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
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    stripe.accounts.create({
      type: 'custom',
      country: 'US',
      business_type: 'company',
      requested_capabilities: ['card_payments']
    }, function(err, account) {
      // asynchronously called
    });
    

    Requirements vary depending on the capability, but they often relate to identity verification, accepting Stripe’s terms of service, or other information specific to a payment type.

    When your connected account is successfully created, you can view what its requirements are:

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

    In the response, check the requirements hash to see what onboarding information is needed. The values for payouts_enabled and charges_enabled indicate whether payouts and charges can be made for the account.

    Previewing requirements

    You can preview (fetch) what requirements are needed from your user for a particular capability either before or after that capability has been requested.

    When you request capabilities, account.updated webhooks fire and the account’s requirements may change. You can avoid this by checking the requirements prior to requesting a capability.

    Below is an example that lists the requirements for the card_payments capability for a specific account:

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

    In the response, check the requirements hash to see what onboarding information is needed:

    {
      "id": "card_payments",
      "object": "capability",
      "account": "{{CONNECTED_STRIPE_ACCOUNT_ID}}",
      "requested": false,
      "requested_at": null,
      "requirements": {
        "past_due": [],
        "currently_due": ["representative.email", ...],
        "eventually_due": [...],
        "disabled_reason": ...,
        "current_deadline": ...,
      },
      "status": "unrequested"
    }
    

    The value for status identifies whether the capability has been requested. When it is requested, requirements are activated for the account.

    Requesting and unrequesting capabilities

    After account creation, you can request additional capabilities. Do this by using the Capabilities API to set requested to true, specify which capability you want, and which connected account you are requesting for. If the capability request is successful, the API returns requested: true in the response.

    As an example, below is a platform_payments capability request for a specific connected account:

    curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}}/capabilities/platform_payments \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d requested=true
    

    You can also unrequest capabilities for an account, just use the same API call but set requested to false instead.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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

    On this page