Managing Capabilities

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

    The capabilities framework lets you specify which functionalities to enable on your platform’s connected accounts. Each capability has specific onboarding requirements associated with it. You can request capabilities 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.

    If you prefer, you can request and unrequest an account’s capabilities from the Dashboard instead of using the API.

    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 affect a 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. A capability’s status can become inactive if requirements are not satisfied for the account’s processing volume.

    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" \
      -d "requested_capabilities[]=transfers"
    
    # 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', 'transfers'],
    })
    
    # 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', 'transfers']
    )
    
    // 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", "transfers"],
    ]);
    
    // 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", "transfers"));
    
    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', 'transfers']
    }, function(err, account) {
      // asynchronously called
    });
    

    Requirements vary depending on the capability, but they often relate to identity verification 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 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. If you preview the requirements first, collect what’s required for the account, and then request the capability, you can assist in enabling charges and payouts for the account more quickly. You also avoid the possibility of the account getting disabled since the requirements have already been collected in advance.

    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": ["company.tax_id", ...],
        "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.

    While these steps demonstrate how to preview a capability’s requirements before requesting it, you can use the same endpoint to view what the current requirements are for a capability. This can help you stay informed of what a capability’s requirements are and also of any requirement changes.

    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 transfers capability request for a specific connected account:

    curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}}/capabilities/transfers \
      -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.

    Was this page helpful?

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

    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.

    On this page