Skip to main content
A capability is permission for one account to do one thing with money. Each is requested, reviewed, and enabled separately.
The capabilities you request decide which requirements the account has to complete. Request only what it needs.

​
Two layers

A capability is not free-standing. Every capability in the registry belongs to at most one configuration, and a configuration is a persona: what kind of money mover the account is. An account can only hold a capability whose configuration it has applied. Applying merchant does not enable any payment method by itself, it only makes the merchant capabilities requestable; each still needs its own request and its own review before it is active. Naming a configuration authorizes nothing on its own. No configuration is ever applied automatically, recipient included. At creation and on update, you name every persona the account needs as a key in configuration; an account created with no configuration at all holds neither persona and cannot hold any capability.

​
Recipient-configuration capabilities

These three govern what an account can do with a balance it already holds, and all require the recipient configuration. A separate set gates what it can accept in the first place.

​
Merchant-configuration capabilities

Card acceptance is two separate capabilities, split by currency corridor. card_collection accepts Visa and Mastercard charged in USD (a global cardholder pays in dollars); ngn_card_collection accepts Nigerian-issued Visa and Mastercard charged in NGN (a local cardholder pays in naira). They are requested independently, so an account can hold either, both, or neither: a merchant selling to Nigerians locally can request only ngn_card_collection, one selling globally only card_collection, and one doing both requests both. Requesting card_collection alone does not enable naira cards, and vice versa. Each gates one payment method. An account needs the capability for a method active before a customer can pay it that way. The check runs when the payment method is resolved, on whichever party’s checkout it is, not at checkout creation, so a request without the capability can be accepted and only fail once the customer reaches the hosted page. See Direct charges and Destination charges for who is checked on each shape.

​
connect

connect belongs to neither configuration. It is not something an account requests; it is what your own platform holds so you can call the account endpoints at all. See Become a platform. Recipient- and merchant-configuration capabilities are requested and read the same way, described below.

​
Request a capability

At creation, on POST /v1/accounts, or afterwards on POST /v1/accounts/{account_id} · scope connected_accounts:write
Requesting does not authorize. The capability becomes requested and its requirements surface on the account.
In sandbox, a capability requested at creation is granted active immediately instead of landing restricted for review. This is scoped to the account’s applied personas: payouts, transfers, and conversions are granted only if recipient was named; merchant capabilities only if merchant was named. An account created with no configuration at all holds neither persona and cannot accept a payment, or hold any capability. See Testing.
Requesting payouts requests payouts alone, not the other capabilities in its group. On update, POST /v1/accounts/{account_id}, the same configuration shape applies a persona the account does not already have: naming merchant with card_collection nested under its capabilities, on a recipient-only account, applies merchant for it, in the same call, and then requests card_collection. An account can start recipient-only and become a merchant later this way; nothing about it is a hard stop. Unlike creation, an omitted capabilities on update never blanket-requests: naming a persona there with no capabilities just applies the persona and requests nothing. In sandbox, whatever is named under capabilities grants active immediately, the same as at creation, but scoped to only what was named. See Testing.
"requested": false returns 400 capability_unrequest_unsupported on update, POST /v1/accounts/{account_id}. There is no revocation path for an active capability. On create, POST /v1/accounts, {"recipient": {"capabilities": {"payouts": {"requested": false}}}} is accepted and means “request nothing”: it is equivalent to omitting payouts from the map.

​
Read the status

GET /v1/accounts/{account_id}/capabilities · scope connected_accounts:read · full field reference → Returns every capability applicable to the account, including ones it has never requested. Gate on status == "active". Every other value denies the action.
unrequested is not stored. It is returned when no record exists, so you get a status rather than a null. It differs from restricted, which means requested and not enabled.
requested is a separate boolean saying whether the account ever asked. A restricted capability that was requested is in progress; one that was never requested is outside this account’s setup.

​
status_details

status_details carries the machine-readable reason a capability is not active, and is null when the capability is active. Branch on code or resolution; show message to a human.
When a capability is not active because information is outstanding, the fields are in the account’s requirements. See Requirements.

​
Enabling

Completing every requirement makes an account eligible. A capability is enabled on review, not automatically, and a requirement falling due on an active capability does not disable it.
  • Subscribe to capability.updated rather than polling. See capability.updated.
  • An account with an empty requirements, or an account.updated event with an empty outstanding, has nothing left to provide. That is not the same as a capability being active. Check the capability’s status.