> ## Documentation Index
> Fetch the complete documentation index at: https://public-openfx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Account model

> The resources behind a payout, how they relate, and the statuses they share.

An `Account` is someone you send money to or on behalf of: who they are, and what they're set up
to do. It holds no money. This page covers the resources a payout uses, how they fit together, and
the statuses they share.

## The four resources

| Resource | Who it belongs to | What it is |
| - | - | - |
| `FinancialAccount` | You | A balance in one currency that funds your payouts. OpenFX creates these for you. |
| `Account` | The person or company you pay | Who they are, plus the capabilities (`AccountCapability`) they hold. You create it. |
| `PayoutAddress` | The person or company you pay | A bank account the money lands in. It belongs to one `Account`, through `accountId`, and an account can have several. You create it. |
| `Payout` | You | Money sent from one of your financial accounts to a payout address. |

**A payout links your side to theirs.** It debits `financialAccountId` and credits
`receiver.payoutAddressId`. You don't name the receiving account, because the address already
belongs to it. Your credentials show which accounts are yours; no field links them to your
organization.

To find which balances can fund a payout in a given `receiveCurrency`, call
[`listFinancialAccounts`](/v3/api-reference/payments/accounts/list-financial-accounts). Each entry
has a `currency`, a `label` to tell same-currency balances apart, an `availableBalance`, and a
`totalBalance`. The difference between the two balances is the amount on hold.

## Identity

`identity` describes who the account is. Set `identityType` to <span class="ofx-enum">INDIVIDUAL</span> for a person, with an
`individual` block, or <span class="ofx-enum">ORGANIZATION</span> for a company, with an `organization` block. You can't
change the type later.

An individual's block holds their name, date of birth, nationality, contact details, address, tax
numbers, and identity documents. An organization's block holds its registration details (legal
name, registration number, date of incorporation, legal structure, registered address) and
`associations`: the people and companies that own or control it. Each association has a `role`,
such as <span class="ofx-enum">UBO\_THROUGH\_OWNERSHIP</span>, <span class="ofx-enum">DIRECTOR</span>, or <span class="ofx-enum">ULTIMATE\_PARENT\_COMPANY</span>, and an
`ownershipPercent` where they hold shares.

Most identity fields are optional in the schema. The capabilities you request decide which ones you
must send. If a required field is missing, the request fails with `422`
<span class="ofx-enum">IDENTITY\_REQUIREMENT\_UNMET</span>. [Capabilities](/v3/capabilities#identity-requirements) lists the
fields for each one.

Two fields are just for you: `label`, a name to help you recognize the account, and `metadata`, for
a reference back to a record in your own system.

## Capabilities

A capability lets an account be paid in a currency, or be named as the sender of a payout. Request
them by id in `capabilities` when you
[create the account](/v3/api-reference/payments/accounts/create-account), along with the identity
they need. You can only add capabilities at creation. An account created without any is just an
identity.

Each capability comes back as an `AccountCapability` with its `id`, its own `status`, and `details`
describing what it covers. [Capabilities](/v3/capabilities) lists every capability and explains how
they control payouts.

## Payout addresses

A `PayoutAddress` is a bank account an account can be paid at. Its `bankAccount` holds the bank
details, and `routingFamily` decides which ones:

| `routingFamily` | Bank details |
| - | - |
| <span class="ofx-enum">SEPA</span> | An IBAN, as `accountNumber` |
| <span class="ofx-enum">SWIFT</span> | `accountNumber`, `bic`, and the holder's address |
| <span class="ofx-enum">IN\_LOCAL</span> | `ifsc`, `accountNumber`, and `isNre`, which says whether the account is repatriable |
| <span class="ofx-enum">MX\_LOCAL</span> | A CLABE, as `accountNumber` |
| <span class="ofx-enum">CO\_LOCAL</span> | `bankCode`, `accountNumber`, and `bankAccountType` |
| <span class="ofx-enum">CO\_BREB</span> | A Bre-B key, as `brebKey` |
| <span class="ofx-enum">AE\_LOCAL</span> | A UAE IBAN, as `accountNumber` |

The address also shows the currencies and rails it can be paid in (`supportedCurrencies`,
`supportedRails`) and the checks run on it (`verifications[]`).

An address belongs to one account, set by `accountId`, and you can't edit it. To correct anything,
create a new address and archive the old one. Addresses aren't included in the account; list them
with [`listPayoutAddresses`](/v3/api-reference/payments/addresses/list-payout-addresses), filtered
by `accountId`.

You can create an address before the account's capability is <span class="ofx-enum">ACTIVE</span>. The account only needs
to hold a capability that can receive at that address, in any status. So you can set up the address
and the capability at the same time.

## Roles on a payout

An account plays one of two roles on a payout, and each needs a capability.

* **The receiver** is the account being paid: the owner of `receiver.payoutAddressId`. It needs an
  <span class="ofx-enum">ACTIVE</span> capability that covers that address.
* **The sender** is optional: another account, named as `sender` on the quote or inline payout. The
  payout is made in their name, but the money still comes from your financial account. The sender
  needs an <span class="ofx-enum">ACTIVE</span> capability granting <span class="ofx-enum">SEND\_PAYOUTS\_TO\_THIRD\_PARTIES</span> for the destination.
  Today that exists only for INR.

## The shared state machine

Three statuses decide whether you can pay:

* The account's own status (`AccountStatus`): OpenFX's view of the account as a whole.
* Each capability's status (`CapabilityStatus`).
* Each payout address's status (`PayoutAddressStatus`).

All three use the same four values and the same transitions, so you only need to learn them once.
They differ in what changes them and what <span class="ofx-enum">ACTIVE</span> lets you do.

```mermaid theme={"theme":{"light":"poimandres","dark":"poimandres"}}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Inter, system-ui, sans-serif','fontSize':'13px'}}}%%
stateDiagram-v2
  direction TB
  [*] --> PENDING: created
  [*] --> ACTIVE: created
  PENDING --> ACTIVE: settled, nothing blocking
  PENDING --> REQUIRES_INFORMATION: needs information
  PENDING --> REJECTED: outcome went against it
  ACTIVE --> REQUIRES_INFORMATION: needs information
  ACTIVE --> REJECTED: later outcome turned
  REQUIRES_INFORMATION --> PENDING: information provided
  REQUIRES_INFORMATION --> REJECTED: outcome went against it
  ACTIVE --> [*]
  REJECTED --> [*]

  classDef ok stroke-width:1px
  classDef bad stroke-width:1px
  classDef pending stroke-width:1px
  classDef hold stroke-width:1px
  classDef returned stroke-width:1px
  classDef neutral stroke-width:1px
  class PENDING pending
  class ACTIVE ok
  class REQUIRES_INFORMATION hold
  class REJECTED bad
```

| Status | Meaning |
| - | - |
| <span class="ofx-status-pill ofx-status-pill--purple">PENDING</span> | Created and not settled yet |
| <span class="ofx-status-pill ofx-status-pill--green">ACTIVE</span> | Settled, with nothing blocking |
| <span class="ofx-status-pill ofx-status-pill--yellow">REQUIRES\_INFORMATION</span> | OpenFX has asked you for something. The status returns to <span class="ofx-enum">PENDING</span> once you provide it |
| <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> | An outcome went against it. Final |

Only <span class="ofx-enum">PENDING</span> can move to <span class="ofx-enum">ACTIVE</span>, and an <span class="ofx-enum">ACTIVE</span> status never goes back to
<span class="ofx-enum">PENDING</span>. Anything that isn't <span class="ofx-enum">REJECTED</span> can move to <span class="ofx-enum">REQUIRES\_INFORMATION</span> or
<span class="ofx-enum">REJECTED</span>.

OpenFX's request for information and your answer go through your usual support channel, not the API. Each section below says what to do after <span class="ofx-enum">REJECTED</span>.

Capabilities and payout addresses always start <span class="ofx-enum">PENDING</span>. An account starts <span class="ofx-enum">PENDING</span> or
<span class="ofx-enum">ACTIVE</span>.

Two rules apply to all three:

1. **Create responses show the current status.**
   [`createAccount`](/v3/api-reference/payments/accounts/create-account) and
   [`createPayoutAddress`](/v3/api-reference/payments/addresses/create-payout-address) show each
   status at the moment of the response, including checks that finished during the call. Read the
   response instead of assuming a starting value.
2. **Every status change sends exactly one webhook**, however quickly it happened. Creation has its
   own webhook:
   [`common.account.created`](/v3/webhooks/payments/accounts-webhooks/account-created) shows the
   starting status of the account and each capability, and
   [`payments.payout_address.created`](/v3/webhooks/payments/addresses-webhooks/payout-address-created)
   shows an address's.

### The account's own status

`AccountStatus` is OpenFX's decision on whether to do business with the account at all. **It
doesn't summarize the capabilities.** An account can be <span class="ofx-enum">ACTIVE</span> while a capability is still
<span class="ofx-enum">PENDING</span>, or <span class="ofx-enum">REJECTED</span> while its capabilities are <span class="ofx-enum">ACTIVE</span>.

OpenFX's risk and compliance review sets it. Today that's a manual decision, made outside the API.

Each change sends
[`common.account.activated`](/v3/webhooks/payments/accounts-webhooks/account-activated),
[`common.account.rejected`](/v3/webhooks/payments/accounts-webhooks/account-rejected), or
[`common.account.requires_information`](/v3/webhooks/payments/accounts-webhooks/account-requires-information),
with the `previousStatus`.

A <span class="ofx-enum">REJECTED</span> account can't be named on any payout, as receiver or sender. Create a new account
instead. Sending more identity details won't reverse a rejection.

### Capability status

`createAccount` succeeds once the request is valid and the identity requirements are met. Each
capability starts <span class="ofx-enum">PENDING</span> and its checks begin straight away. Checks that finish during the
call show up in the response, so a capability can already be <span class="ofx-enum">ACTIVE</span> there. The rest settle
later, by webhook.

<span class="ofx-enum">PENDING</span> means the capability's checks haven't finished. The API doesn't show which checks run
or in what order, only the result. A minute is typical but not guaranteed, so don't build a flow
that assumes a time limit. Wait for the webhook instead.

Each change sends its own webhook:
[`common.account.capability_activated`](/v3/webhooks/payments/accounts-webhooks/account-capability-activated),
[`common.account.capability_rejected`](/v3/webhooks/payments/accounts-webhooks/account-capability-rejected), or
[`common.account.capability_requires_information`](/v3/webhooks/payments/accounts-webhooks/account-capability-requires-information).
`data.capability` says which capability changed, and `data.capabilities[]` has the current status of
every capability.

A fast check still sends its webhook, so it can arrive before your system has handled the create
response, or before `common.account.created`. Each webhook carries the resource as it was when the
event fired, minus a few fields webhooks never include. See
[Webhook authentication](/v3/webhooks/authentication).

A <span class="ofx-enum">REJECTED</span> capability can't be used or revived. The account and its other capabilities aren't
affected. The replacement is a different capability, never the same one, and capabilities can only
be requested when an account is created.

### Payout address status

An address usually starts <span class="ofx-enum">PENDING</span> and its checks begin straight away. Some are listed in
`verifications[]`; others OpenFX runs without listing. `status` reflects all of them. There's no
time guarantee here either, and OpenFX retries temporary problems itself.

Each change sends one webhook:
[`payments.payout_address.activated`](/v3/webhooks/payments/addresses-webhooks/payout-address-activated),
[`payments.payout_address.rejected`](/v3/webhooks/payments/addresses-webhooks/payout-address-rejected), or
[`payments.payout_address.requires_information`](/v3/webhooks/payments/addresses-webhooks/payout-address-requires-information).
[`payments.payout_address.verification_resolved`](/v3/webhooks/payments/addresses-webhooks/payout-address-verification-resolved)
also fires whenever a listed check resolves, even if the status doesn't change.

**Checks continue for as long as the address exists**, so an <span class="ofx-enum">ACTIVE</span> address can later be
rejected or need more information. A rejection after activation arrives as
`payments.payout_address.rejected` with `previousStatus: "ACTIVE"`. If every entry in
`verifications[]` looks fine, the failure came from an unlisted check. A <span class="ofx-enum">REJECTED</span> address
can't receive payouts. Since you can't edit it, create a new one.

## How a payout reads the model

A payout needs all three <span class="ofx-enum">ACTIVE</span> at once: the account, the capability the payout needs, and the
payout address. <span class="ofx-enum">REQUIRES\_INFORMATION</span> blocks a payout just like <span class="ofx-enum">PENDING</span>.
[`createPayout`](/v3/api-reference/payments/payouts/create-payout) checks all three, and its 409
errors say which one failed.

* **The account**: the status of the receiving account, and of the sender if there is one.
* **The capability**: the receiver and any sender each need an <span class="ofx-enum">ACTIVE</span> capability that covers
  the payout. See [Capabilities](/v3/capabilities#the-coverage-gate). A missing capability fails the
  same way as one that isn't <span class="ofx-enum">ACTIVE</span>.
* **The address**: the payout address's own status.

Creating an address only needs a covering capability to exist, in any status. See
[Payouts](/v3/payouts).

## Archiving

OpenFX sets status; you decide archiving. Accounts and payout addresses have an `archivedAt` that's
null until you call [`archiveAccount`](/v3/api-reference/payments/accounts/archive-account) or
[`archivePayoutAddress`](/v3/api-reference/payments/addresses/archive-payout-address). Archiving is
permanent. Both calls take no body and are safe to repeat: archiving again returns the record with
its original `archivedAt`.

Archived records are hidden from list calls by default, can still be fetched by id, and are kept in
full for regulatory and audit purposes. Nothing is deleted. You can't pay an archived account or
create addresses for it, and you can't pay an archived address. Payouts already under way carry on,
as described in
[Payouts](/v3/payouts#archiving-does-not-stop-a-payout-in-flight).

Archiving and status are separate. A <span class="ofx-enum">REJECTED</span> address stays live until you archive it, and an
archived <span class="ofx-enum">ACTIVE</span> account is still <span class="ofx-enum">ACTIVE</span>. Archiving sends
[`common.account.archived`](/v3/webhooks/payments/accounts-webhooks/account-archived) or
[`payments.payout_address.archived`](/v3/webhooks/payments/addresses-webhooks/payout-address-archived).

## What's next

<CardGroup cols={2}>
  <Card title="Payouts" icon="https://public-assets.openfx.com/docs/icons/withdrawals.svg" href="/v3/payouts">
    Set up a recipient and send a payout.
  </Card>

  <Card title="Capabilities" icon="https://public-assets.openfx.com/docs/icons/capabilities.svg" href="/v3/capabilities">
    Every capability and the identity it requires.
  </Card>

  <Card title="Payment Webhooks" icon="https://public-assets.openfx.com/docs/icons/webhooks-setup.svg" href="/v3/webhooks/payments/accounts-webhooks/account-created">
    Every event these resources emit.
  </Card>
</CardGroup>