Account lifecycle

Connected accounts move through a lifecycle as information is collected, verified, and re-evaluated.

This lifecycle determines whether an account can accept payments, receive payouts, or requires additional action.

Lifecycle model

An account lifecycle is driven by:

submitted account data
verification status
requirements
requested capabilities
operational flags

The lifecycle is not controlled by a single status field. Your platform should determine the account state by evaluating requirements, capabilities, and operational readiness.

Typical lifecycle

Created

The account has been created, but required information is still missing.

Onboarding in progress

Your platform is collecting and submitting business, person, and payout information.

Pending verification

Required information has been submitted and is under review.

Operational

The account has the required capabilities and can perform the intended actions.

Restricted

Previously submitted information is no longer sufficient or valid, and additional action is required.

Lifecycle stages

Created

The account exists, but onboarding has not been completed.

Typical characteristics:

required fields are missing
capabilities are not yet active
operational flags are disabled

Example:

{
  "capabilities": {
    "payments": "inactive",
    "payouts": "inactive"
  },
  "requirements": {
    "currently_due": [
      "business_profile.name",
      "company.tax_id"
    ]
  },
  "charges_enabled": false,
  "payouts_enabled": false
}

Onboarding in progress

Your platform is actively collecting and submitting data.

Typical characteristics:

requirements are still present
some data may already be submitted
related resources such as persons and external accounts may already exist

At this stage, your platform should continue to drive the flow from the requirements field.

Pending verification

Required information has been submitted, but verification has not completed yet.

Typical characteristics:

currently due requirements may be empty
pending verification fields are present
capabilities may still be inactive or pending
operational flags may still be disabled

Example:

{
  "requirements": {
    "currently_due": [],
    "pending_verification": [
      "company.verification.document"
    ]
  },
  "capabilities": {
    "payments": "pending",
    "payouts": "pending"
  },
  "charges_enabled": false,
  "payouts_enabled": false
}

Operational

The account is ready to use the requested functionality.

Typical characteristics:

blocking requirements are resolved
required capabilities are active
operational flags are enabled

Example:

{
  "requirements": {
    "currently_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "capabilities": {
    "payments": "active",
    "payouts": "active"
  },
  "charges_enabled": true,
  "payouts_enabled": true
}

Restricted

An account that was previously operational may become restricted.

This can happen when:

information becomes outdated
verification fails
new regulatory requirements apply
previously acceptable data must be corrected or resubmitted

Typical characteristics:

new currently due or past due requirements appear
a capability may become disabled or inactive
one or more operational flags may become false

Do not assume that an operational account will remain operational permanently. Account state must be monitored continuously.

Signals to monitor

When determining the lifecycle state of an account, monitor:

requirements.currently_due
requirements.past_due
requirements.pending_verification
capabilities
charges_enabled
payouts_enabled

These fields should drive your platform logic and user-facing status.

Recommended lifecycle logic

A practical way to model account state in your platform is:

Created — account exists and required information is missing
Onboarding in progress — requirements are being addressed
Pending verification — information is submitted and under review
Operational — required capabilities are active and operational flags are enabled
Restricted — new or overdue requirements block operation

These lifecycle labels are a platform-facing interpretation of account state. The source of truth remains the underlying account fields.

Tasks and lifecycle

Tasks can influence the lifecycle of an account.

For example:

A blocking task may move an account into a restricted state
Completing a task may allow the account to become operational

Tasks provide actionable steps that drive lifecycle transitions.

Best practices

Build your lifecycle state from account data instead of storing it as a manually managed field
Re-fetch the account after updates
React to webhook events to detect lifecycle changes
Treat restrictions as part of the normal lifecycle, not as exceptional edge cases

Summary

An account lifecycle reflects the current operational state of a connected account.

It is determined by:

what information is missing
what is under review
what capabilities are active
whether payments and payouts are enabled

Overview

Update accounts