Capabilities

Capabilities define what a connected account is allowed to do.

They control whether an account can accept payments, receive payouts, and access other platform features.

Capability model

Each capability has a lifecycle and is evaluated based on the account’s data and verification status.

{
  "capabilities": {
    "payments": "inactive",
    "payouts": "inactive"
  }
}

Capability lifecycle

Capabilities transition through the following states:

inactive

The capability has been requested but is not yet enabled.

This typically means that required information is missing or verification is incomplete.

pending

The required data has been submitted and is under review.

No further action is required until verification completes.

active

The capability is fully enabled.

The account can use the corresponding functionality.

disabled

The capability has been disabled.

This may occur due to:

• Failed verification
• Regulatory restrictions
• Missing or outdated information

Requesting capabilities

Capabilities are requested when creating or updating an account.

POST /v1/accounts

{
  "capabilities": {
    "payments": { "requested": true },
    "payouts": { "requested": true }
  }
}

Relationship to requirements

Each capability introduces its own set of requirements.

Example:

{
  "capabilities": {
    "payments": "inactive"
  },
  "requirements": {
    "currently_due": [
      "company.tax_id"
    ]
  }
}

A capability cannot become active until all associated requirements are satisfied and verified.

Operational flags

Capabilities are complemented by operational flags on the account:

{
  "charges_enabled": false,
  "payouts_enabled": false
}

charges_enabled

Indicates whether the account can accept payments.

payouts_enabled

Indicates whether the account can receive payouts.

Capability vs operational readiness

Capabilities represent permission. Operational flags represent readiness.

An account is considered operational only when:

• Required capabilities are active
• charges_enabled or payouts_enabled are true

Dynamic behavior

Capabilities are continuously evaluated.

They may change when:

• Account data is updated
• Requirements are satisfied or become past due
• Verification results are returned
• Regulations change

Monitoring changes

Capability changes are communicated via webhooks.

Event:

account.updated

Your platform should:

• Re-fetch the account
• Evaluate capabilities and requirements
• Update user-facing state if needed

Best practices

• Request only the capabilities you need
• Use requirements to guide data collection
• Do not assume capabilities are immediately active
• Always check operational flags before enabling functionality

Summary

Capabilities define what an account is allowed to do.

They are:

• Requested explicitly
• Activated after verification
• Continuously evaluated over time