Account capabilities

Capabilities represent functionality that you can request for your connected accounts, such as accepting card payments or receiving transferred funds from your platform account. A capability must be active for a connected account to perform actions associated with that capability.

Most capabilities require verification of certain information about the connected account’s business before Stripe enables them for that account. The capabilities you request for a connected account determine the information you’re required to collect for that account. To reduce onboarding effort, only request the capabilities that your accounts need. Requesting more capabilities means the onboarding flow must verify more information.

You can start by completing the platform profile to understand which capabilities might be appropriate for your platform.

After creating an account, you can request additional capabilities and remove existing non-permanent capabilities. For connected accounts that other platforms control, you can’t unrequest capabilities.

Supported capabilities

Following is a list of available capabilities. Click an item to expand or collapse it.

Transfers

You can transfer funds to connected accounts that have the transfers capability. On-demand platforms often use it to pay their connected accounts. For example, a ride-hailing platform could use this capability so they can pay their drivers. The following diagram illustrates the flow of funds and the relationship between customers, the platform, and connected accounts.

Relationship between customers, the platform, and connected accounts.

When you use the transfers capability, your platform, not the connected account, processes charges. Therefore, a connected account’s customers’ bank statements display your platform’s statement descriptor, not the connected account’s.

Payments using the transfers capability include Destination charges and Separate charges and transfers.

Note

Before the 2019-08-14 API version, the transfers capability was referred to as platform_payments. If you’re using an API version older than 2019-08-14, use platform_payments.

Cross-border transfers

Moving money across country borders introduces additional requirements and is supported in the following scenarios only:

• European Union, United Kingdom, and Gibraltar platforms sending funds to SEPA countries.
• US platforms sending funds to cross-border payouts destinations using a recipient service agreement.

For other scenarios, create a platform account in the same region as your connected accounts. Depending on your business structure, that might require creating a legal entity in that region and additional work to onboard connected accounts.

Card payments

Connected accounts with the card_payments capability can receive payments from your platform and directly process card and ACH payments. An e-commerce storefront with this capability, for example, can collect its own payments. The following diagram illustrates the flow of funds and the relationship between customers, connected accounts, and the platform:

Relationship between customers, connected accounts, and the platform.

For an account to have the card_payments capability, you must request both card_payments and transfers.

When a connected account has this capability, its customers’ bank statements display the connected account’s statement descriptor, not the platform’s.

The card_payments capability applies to all charge types.

Multiple capabilities

Requesting multiple capabilities for a connected account is common, but involves the following considerations:

• Capabilities operate independently of each other.
• If a connected account has both card_payments and transfers, and the status of either one is inactive, then both capabilities are disabled.
• You can request or unrequest most capabilities for a connected account at any time during the account’s lifecycle.

Capabilities also allow you to collect information for multiple purposes at the same time. For example, you can collect both required tax information and the information required for a requested capability.

Request capabilities for an Account

Capabilities are set on the Account object. To get the list of available capabilities for an Account, use the list_capabilities endpoint.

Account creation and requesting capabilities differ for connected accounts in different configurations.

• For connected accounts with access to the full Stripe Dashboard, including Standard accounts, some capabilities are requested automatically, based on their country. You can also request other capabilities for them.
• For connected accounts with access to the Express Dashboard, including Express accounts, you can either request their capabilities or use the onboarding configuration settings to automate capability requests.
• For connected accounts without access to a Stripe-hosted Dashboard, including Custom accounts, you must request their capabilities.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[requirement_collection]"=application \
  -d country=US \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true

Information 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 retrieve a list of its requirements:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

In the response, the requirements hash specifies the required information. The values for payouts_enabled and charges_enabled indicate whether payouts and charges are enabled for the account.

Capabilities for existing connected accounts

The following sections describe how to preview information requirements or manage capabilities for existing connected accounts using the Capabilities API.

Preview information requirements

You can preview what information is needed from your connected account 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 can change. To enable a requirement faster and avoid disabling the account, preview the requirements and collect any required information before requesting the capability.

The following example lists the requirements for the card_payments capability for a specific account.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/capabilities/card_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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

{
  "id": "card_payments",
  "object": "capability",
  "account": 
"{{CONNECTED_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 the value is requested, the account’s requirements are active.

In addition to previewing a capability’s requirements before requesting it, you can use the same endpoint to view a capability’s current requirements. That can help you stay informed when requirements change.

Request and unrequest capabilities

To request a capability for an account, set the capability’s requested value to true by updating the account. If the request succeeds, the API returns requested: true in the response.

To unrequest a capability for an account, set the capability’s requested value to false by updating the account. If the capability can’t be removed, the call returns an error. If the call succeeds, the API returns requested: false in the response.

You can also request and remove an account’s capabilities from the Dashboard. If a capability can’t be removed, its Remove button is disabled.

The example below requests the transfers capability for a specific connected account:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/capabilities/transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d requested=true

The example below requests multiple capabilities for a specific connected account:

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "capabilities[bancontact_payments][requested]"=true \
  -d "capabilities[eps_payments][requested]"=true \
  -d "capabilities[ideal_payments][requested]"=true \
  -d "capabilities[p24_payments][requested]"=true \
  -d "capabilities[sepa_debit_payments][requested]"=true

Deprecated capabilities

Capabilities described in the following sections are deprecated. If possible, don’t request them for new accounts. If you have existing accounts that use deprecated capabilities, we recommend that you update them to use other capabilities instead.

legacy_payments

The legacy_payments capability enables charges, payouts, and transfers. Newer accounts enable those actions using the card_payments and transfers capabilities, which support more flexible configurations.

We recommend that you take the following steps:

1. Update your connected account onboarding process to request the appropriate combination of card_payments and transfers instead of legacy_payments.

2. Update your existing connected accounts to request the appropriate combination of card_payments and transfers.

3. Update any code that checks the status of legacy_payments to check the status of either legacy_payments or the appropriate new capability. For example, update code that relies on an account’s ability to make card payments to run when either legacy_payments or card_payments is active. Similarly, update code that relies on an account’s ability to accept transfers to run when either legacy_payments or transfers is active. The updated code works throughout the process of transitioning to the new capabilities, regardless of when the new capabilities become active.

4. After the new capabilities are active for all of your connected accounts, remove references to legacy_payments from your code.

If you do business in Canada, Stripe automatically requests card_payments and transfers for your accounts that use legacy_payments, to comply with updated requirements. During the process, you might see the following values in your connected accounts’ API responses.

capabilities: {
  legacy_payments: "active"
},
charges_enabled: true,
payouts_enabled: true

capabilities: {
  card_payments: "inactive",
  legacy_payments: "active",
  transfers: "inactive"
},
charges_enabled: true,
payouts_enabled: true

capabilities: {
  card_payments: "active",
  legacy_payments: "active",
  transfers: "active"
},
charges_enabled: true,
payouts_enabled: true