Skip to main content
A capability is permission for one account to do one thing with money. Read each capability’s status to decide whether the account can use it. In the sandbox, capabilities are granted at once. In live mode, a capability goes live when its checks pass. See How a capability goes live.
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. In live mode, applying a configuration makes its capabilities requestable; use each returned capability’s status to determine what is active. Sandbox creation grants the operational set allowed by the applied personas. See Testing Connect. 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 through the API with no configuration at all holds neither persona and cannot hold any capability. The defaults in your Connect setup apply only to accounts you create from the dashboard.

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. The collection capabilities gate payment methods. For virtual-account activation, requirements and number creation, see Accept bank transfers with a virtual account. 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 The update endpoint accepts your own account as well as a connected account you own. Requesting a capability for your own account does not require creating a connected account first.
A live request does not establish approval. Read the capability’s status and the account’s returned requirements; requested is a boolean recording the request, not an enabled status.
In sandbox, account creation grants the operational capability set allowed by its applied personas as active, which can include capabilities you did not explicitly name. 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.
An explicit live request for payouts requests that capability alone. Sandbox creation can grant a wider operational set, and recipient-capable accounts receive conversions automatically. See Testing Connect. 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. On create, POST /v1/accounts, {"recipient": {"capabilities": {"payouts": {"requested": false}}}} is accepted and means “request nothing”: it is the same as leaving payouts out.

Withdraw a capability

Asked for a capability by mistake? Send "requested": false on POST /v1/accounts/{account_id}, as long as it has not gone live.
  • The capability goes back to not requested, and requested reads false.
  • What it asked for leaves the account’s requirements, unless another capability still needs it.
  • Anything the person already gave stays on file. If you ask again later, they are not asked twice.
  • We send capability.updated.
Withdrawing a capability that was never requested does nothing, and is not an error. Only a platform can withdraw a capability, for an account it owns. Anyone else gets 400 capability_unrequest_unsupported.

International payouts

An account with payouts can always be paid out to a bank in Nigeria. To pay it out to a mobile money wallet, or to a bank outside Nigeria, turn on international under payouts:
  • Send it on create, POST /v1/accounts, or on update, POST /v1/accounts/{account_id}.
  • international: true requests payouts too, so you can leave requested out. requested: false with international: true is refused with 422 VALIDATION_ERROR.
  • international: false turns it off. It does not withdraw payouts.
  • Leave international out and nothing about it changes.
  • Only payouts takes it. On any other capability the call fails with 400 capability_option_not_supported.
  • Only your platform can set it. The account cannot turn it on for itself (400 capability_option_platform_only).
What it asks for. Basic payouts asks for a name and a payout account. With international on, an individual is also asked for their email and address, and a company for its own address. They show in the account’s requirements and in the hosted onboarding checklist. If payouts is already active, it stays active, and payouts in Nigeria carry on. See Payouts abroad. Reading it back. capabilities.payouts on the account, and the payouts entry from GET /v1/accounts/{account_id}/capabilities, carry "international": true or false. No other capability has the field. A change sends capability.updated with the same field. A default for new accounts. In your Connect setup in the dashboard, turn on international payouts for new accounts. Every account you create that requests payouts then starts with it on, unless the create call sends international itself. This one setting applies to accounts you create through the API too. The other Connect setup defaults apply only to accounts created from the dashboard. Accounts you already have. An account that already had payouts before this option existed has it on, so it keeps paying out as it did. An older account that asks for payouts for the first time starts with it off, like a new one.
In sandbox, the option is on as soon as you send it, and payouts abroad work straight away. The payout still checks that a name, email and address are on file.

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 asked. A restricted capability that was requested is in progress; one that was never requested is outside this account’s setup. international appears on payouts only. It says whether the account can be paid out to mobile money and to banks outside Nigeria. See International payouts. goes_live_automatically says whether the capability will switch on by itself once its checks pass (true), or waits for our team first (false). See How a capability goes live.

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.

How a capability goes live

A capability switches on as soon as its automatic checks pass. Whether our team also reviews it, and when, depends on the capability. Outside Nigeria, the selfie video check also checks the person’s ID. A requirement falling due on a live capability does not switch it off.
  • 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.