Skip to main content
Sent when a capability is enabled or turned off. This is the event to gate features on: an account can perform an action once its capability reaches active, and not before. Delivered to endpoints with event_source set to connect or all. The default for a new endpoint is account, its own events only, so a platform that never sets event_source receives nothing about the accounts it owns. See Connect events.

Event fields

string
The event’s unique identifier, prefixed evt_. Use it to deduplicate deliveries.
string
Always capability.updated.
string
When the event occurred, in UTC.
string
The account the capability change happened on. On an event from an account you own, this is that account, not your platform.
string
The origin account’s id, repeated at the top level. Present only when the origin has a parent; absent on your platform’s own events. This is how a platform tells which of its accounts the event concerns.
string
The account’s id. Matches organization_id.
string
The capability that changed, for example payouts, transfers, conversions, or a payment method capability such as card_collection. See Capabilities for the full list.
string
The capability’s new status. In this event, always one of active (enabled, the account can perform the action) or restricted (not enabled). The status read API also defines pending and unsupported, but nothing in this codebase writes either today, so this event never carries them; do not build handling for them.
boolean
Whether the account ever requested this capability. A restricted capability that was requested is in progress; one that was never requested is outside the account’s setup.
boolean
Only on payouts, and left out for every other capability. Whether the account can be paid out to mobile money and to banks outside Nigeria. See International payouts.
The payload does not carry status_details. When data.status is restricted and you need the reason, read status_details from GET /v1/accounts/{account_id}/capabilities.
A capability can reach the same status more than once over its life, for example restricted to active to restricted to active. Each transition is delivered as its own event, so treat a repeat of the same status as a real change rather than a duplicate.

When it fires

capability.updated fires whenever a capability’s stored status is written: a capability being requested (which lands it restricted, with requested now true), a capability going live when its checks pass or our team approves it (active), our team restricting one, or you withdrawing one (requested now false). It also fires when international payouts are turned on or off for an account’s payouts, with the status unchanged. It does not fire when only the account’s requirements change with no capability write behind it; that is account.updated.

What to do on receipt

Read data.capability and data.status for the account named in account (or organization_id if account is absent), and update whatever in your system depends on that capability being enabled. Only active means the account can perform the action; treat every other status as not enabled and fall back to your existing state until you receive active.