Account model

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

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. 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 INDIVIDUAL for a person, with an individual block, or ORGANIZATION 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 UBO_THROUGH_OWNERSHIP, DIRECTOR, or ULTIMATE_PARENT_COMPANY, 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 IDENTITY_REQUIREMENT_UNMET. Capabilities 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, 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 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: 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, filtered by accountId. You can create an address before the account’s capability is ACTIVE. 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 ACTIVE 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 ACTIVE capability granting SEND_PAYOUTS_TO_THIRD_PARTIES 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 ACTIVE lets you do. Only PENDING can move to ACTIVE, and an ACTIVE status never goes back to PENDING. Anything that isn’t REJECTED can move to REQUIRES_INFORMATION or REJECTED. 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 REJECTED. Capabilities and payout addresses always start PENDING. An account starts PENDING or ACTIVE. Two rules apply to all three:

1. Create responses show the current status. createAccount and createPayoutAddress 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 shows the starting status of the account and each capability, and payments.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 ACTIVE while a capability is still PENDING, or REJECTED while its capabilities are ACTIVE. OpenFX’s risk and compliance review sets it. Today that’s a manual decision, made outside the API. Each change sends common.account.activated, common.account.rejected, or common.account.requires_information, with the previousStatus. A REJECTED 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 PENDING and its checks begin straight away. Checks that finish during the call show up in the response, so a capability can already be ACTIVE there. The rest settle later, by webhook. PENDING 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, common.account.capability_rejected, or common.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. A REJECTED 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 PENDING 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, payments.payout_address.rejected, or payments.payout_address.requires_information. payments.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 ACTIVE 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 REJECTED 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 ACTIVE at once: the account, the capability the payout needs, and the payout address. REQUIRES_INFORMATION blocks a payout just like PENDING. createPayout 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 ACTIVE capability that covers the payout. See Capabilities. A missing capability fails the same way as one that isn’t ACTIVE.
• The address: the payout address’s own status.

Creating an address only needs a covering capability to exist, in any status. See Payouts.

​

Archiving

OpenFX sets status; you decide archiving. Accounts and payout addresses have an archivedAt that’s null until you call archiveAccount or archivePayoutAddress. 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. Archiving and status are separate. A REJECTED address stays live until you archive it, and an archived ACTIVE account is still ACTIVE. Archiving sends common.account.archived or payments.payout_address.archived.

​

What’s next