Stripe Account Capability

The four statuses, and which one is lying to you

The Capability object carries a `status` field with exactly four values, and Stripe defines each of them tersely enough to quote in full: `active` means "the capability is active", `inactive` means "the capability is inactive", `pending` means "the capability is inactive with requirements pending verification", and `unrequested` means "the capability is unrequested".

Read the `pending` definition twice. Pending is a flavour of inactive. An account sitting in `pending` cannot do the thing, and a dashboard that shows "pending" reads to most people as "nearly working". It is not. It is off, with a reason attached.

The useful pair of booleans sits one level up on the Account rather than on the capability. Stripe documents `payouts_enabled` and `charges_enabled` as the values that "indicate whether payouts and charges are enabled for the account". When you want a yes-or-no answer for a single account, read those. When you want to know why the answer is no, read the capability.

Independent, except for the pair that is not

Stripe says plainly that "capabilities operate independently of each other", and then documents the exception that catches every new platform: "If a connected account has both `card_payments` and `transfers`, and the `status` of either one is `inactive`, then both capabilities are disabled."

So the two most common capabilities fail together. An account that cannot receive a transfer also cannot take a card payment, even though only one of them had a verification problem. Chasing the symptom on the charge side while the requirement sits on the transfers side is a genuinely common way to lose an afternoon.

They are also coupled at request time. For an Account to have `card_payments`, Stripe requires that "you must request both `card_payments` and `transfers`". Requesting one is not a subset of requesting the other.

A historical note that still shows up in older integrations: before the 2019-08-14 API version the `transfers` capability "was referred to as `platform_payments`". And the deprecated `legacy_payments` capability "enables charges, payouts, and transfers" all at once. Stripe notes you "can’t unrequest the `legacy_payments` capability", so an old account can carry it indefinitely.

What each of the two main capabilities decides about your books

The two capabilities are not interchangeable, and the difference is visible on a customer’s bank statement.

With `transfers`, Stripe says "your platform, not the connected account, processes charges", and therefore "a connected account’s customers’ bank statements display your platform’s statement descriptor, not the connected account’s". Payments using it "include Destination charges and Separate charges and transfers".

With `card_payments`, connected accounts "can receive payments from your platform and directly process card and ACH payments", and "its customers’ bank statements display the connected account’s statement descriptor, not the platform’s". Stripe scopes it to "all charge types where the connected account is the merchant of record for the payment".

That merchant-of-record clause is the accounting fact hiding inside a permissions field. Which capability your platform runs on decides whose revenue the sale is, whose name the cardholder sees, and therefore which entity’s books the gross amount belongs in. It is worth knowing before an auditor asks, because the capability is a durable statement about who sold what.

Requirements, deadlines, and the hash worth reading

When a capability is not active, the answer is in its `requirements` hash. Stripe reports "both risk and compliance requirements" there, and the hash separates them by urgency: `currently_due`, `eventually_due`, `past_due`, `pending_verification`, plus `current_deadline`, `disabled_reason`, `errors` and `alternatives`.

The deadline field is the one to monitor. Requirements that move from `eventually_due` to `currently_due` to `past_due` end with a capability switching off, which means an account that has been charging happily for months can stop. A separate `future_requirements` hash carries "the upcoming new requirements for the capability, including what information needs to be collected, and by when", so the warning is available before the break rather than after.

Risk requirements are labelled. Stripe documents the format as `<id>.<requirement_description>.<resolution_path>`, "where `id` is prefixed with `interv_` to indicate a risk verification requirement". An `interv_` prefix means a human review, not a missing field, and it is not something more API calls will clear.

One order-of-operations warning from Stripe: requesting a capability "triggers an `account.updated` event and the `Account`’s requirements can change", so Stripe advises previewing requirements and collecting the information before requesting, rather than requesting first and surprising the account holder with a form.

Ask for less than you think you need

Capabilities have an onboarding cost, and Stripe is direct about the tradeoff: "To reduce onboarding effort, only request the capabilities that your accounts need. Requesting more capabilities means the onboarding flow must verify more information."

There is a second reason to be conservative, and it is not reversible. "For some capabilities, requesting them enables them permanently. Attempting to remove or unrequest a permanent capability returns an error." For accounts that other platforms control, Stripe says "you can’t unrequest capabilities" at all.

So the speculative request, the one made because a feature might ship next quarter, is a decision you may not be able to take back. Request narrow, and add later.

Beyond the two main ones, capabilities also cover tax reporting. Platforms with US filing obligations can use `tax_reporting_us_1099_misc` and `tax_reporting_us_1099_k` to collect the information those forms require from connected accounts, which is a capability requested for a paperwork reason rather than a payments one.

Payment methods have their own capabilities, and their own entry

Most individual payment methods sit behind a capability of their own, named after the method: `ideal_payments`, `klarna_payments`, `sepa_debit_payments`, `us_bank_account_ach_payments`. Stripe puts it as "some payment methods are enabled by the `card_payments` capability, while others are enabled by their own capability", and Apple Pay and Google Pay fall in the first group, available with `card_payments` rather than carrying their own.

Who has to request them depends on the dashboard the account holder sees. For connected accounts with the full Stripe Dashboard, including Standard accounts, "most payment method capabilities are enabled by default" and "those accounts can manage their own payment method capabilities". For Express and Custom accounts, which lack full Dashboard access, "you must request payment method capabilities for them".

The rule for offering a method on someone else’s behalf is narrower than people expect: "to enable connected accounts to accept a payment method for direct charges or charges with `on_behalf_of`, you must request that payment method’s capability for those accounts".

The interaction between these capabilities and the sets that decide what a customer actually sees at checkout is a separate subject with its own mechanics, covered on the [payment method configuration](/glossary/stripe-payment-method-configuration) entry. Read that one for what gets offered. Read this one for what is permitted.

Why sandbox testing will not catch this

Stripe includes a warning that deserves more attention than its placement suggests: "Sandboxes might not enforce some capabilities. In certain cases, they can allow an `Account` to perform capability-dependent actions even when the associated capability’s `status` isn’t `active`."

That is a class of bug that passes every test you write. A flow that works end to end against a sandbox account can fail on the first live connected account, not because the code differs but because the sandbox never enforced the gate. If you are building Connect onboarding, assert on capability status explicitly rather than inferring it from whether a test charge succeeded.

The practical version for a finance team: when a connected account reports that payments stopped, the first thing to read is the capability status and its `requirements` hash, not the charge logs. The charge logs will only tell you the charge did not happen.