---
title: "Financial accounts"
description: "Register external accounts, manage payout eligibility, and record pull authorization."
canonical: "https://studio.inttegro.com/api/financial-accounts"
format: inttegro-machine-docs/v1
language: "Java"
sdk_version: "v8.3.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/java/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 479
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: []
estimated_tokens: 14252
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Register external accounts, manage payout eligibility, and record pull authorization. This Java representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. Is Financial accounts the right source for this task?

Use this reference for register external accounts, manage payout eligibility, and record pull authorization. For the complete outcome or lifecycle, start with [Set up financial accounts](https://studio.inttegro.com/machine/java/guides/set-up-financial-account.md); return here for exact operations and fields.

#### Q2. What is the first decision rule for separate connection, capability, and payout-destination state?

Connecting an account registers its identity; it does not by itself make the
account a payout destination. Verify an active lifecycle, supported account
type, matching currency, and enabled push capability, then configure the
destination through [Payouts](https://studio.inttegro.com/machine/java/api/payouts.md#set-payout-destinations).

#### Q3. What is the second decision rule for separate connection, capability, and payout-destination state?

Enabling pull is a distinct authorization step when authorization context is
required. A boolean supplied during connection does not replace the dedicated
enable-pull operation.

#### Q4. What is the third decision rule for separate connection, capability, and payout-destination state?

Before disconnecting, remove the account from payout destinations or
deliberately request that the disconnect operation does so. This avoids
silently breaking payout routing.

#### Q5. What is the fourth decision rule for separate connection, capability, and payout-destination state?

Reconnect preserves the account ID and history. Follow it with lookup because
mutation responses are compact and do not contain the complete readable
account state.

## Document content

# Financial accounts

Use this reference to connect financial accounts, manage their capabilities, and
choose where payouts are sent. For an end-to-end setup flow, start with [Set up
financial accounts](https://studio.inttegro.com/machine/java/guides/set-up-financial-account.md).

## Separate connection, capability, and payout-destination state

The four decision rules are in the machine preamble above.

## The financial account object

The response shape varies slightly by operation. Lookup and page return the complete readable state; disconnect and reconnect return a compact account summary. Optional fields are omitted when no value is stored.

### Properties

- [`archivedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `timestamp`

  Historical archive time when present. New integrations cannot archive a
  financial account through the public API.

- [`bankAccount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html)

  Present when account.type is "bank\_account" .

  - [`bankAccount(…).ghanaBankAccount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

    Ghana bank-account details.

    - [`bankAccount(…).ghanaBankAccount(…).branch(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Bank branch name when enrichment is available.

    - [`bankAccount(…).ghanaBankAccount(…).holder(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

      Account holder name and address.

    - [`bankAccount(…).ghanaBankAccount(…).name(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Bank name when enrichment is available.

    - [`bankAccount(…).ghanaBankAccount(…).number(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Bank account number.

    - [`bankAccount(…).ghanaBankAccount(…).sortCode(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Bank sort code when supplied.

    - [`bankAccount(…).ghanaBankAccount(…).swiftCode(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      SWIFT or BIC code when supplied.

  - [`bankAccount(…).id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

    Bank-account identifier on responses that include it.

  - [`bankAccount(…).type(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `enum`

    [`BankAccountType.GHANA_BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/bankaccounts/BankAccountType.html#GHANA_BANK_ACCOUNT).

- [`createdAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `timestamp`

  When the financial account was created.

- [`currency(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

  Lowercase ISO 4217 currency code. Connect and create currently accept
  `"ghs"`.

- [`customData(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

  Your string key-value metadata. Omitted when empty.

- [`description(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

  Optional description. Connect and create accept up to 200 characters.

- [`disconnectedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `timestamp`

  When the account was disconnected. Omitted for connected accounts.

- [`fingerprint(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

  A stable identifier for the underlying financial account within your
  application. Use it to recognize when the same account has been connected
  more than once.

- [`doshAccount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

  Empty type-specific details when available. Dosh account resources created
  or connected through the current API omit this field and cannot be used as
  payout destinations.

- [`id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

  Unique financial-account identifier with the `fa_`
  prefix.

- [`institution(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

  Enriched institution details when available, such as the institution
  identity and bank branch or mobile-money provider.

- [`label(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

  Human-readable account label. Connect and create require 5–40 characters.

- [`owner(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html)

  Account owner name and address.

  - [`owner(…).address(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

    Owner's address.

    - [`owner(…).address(…).city(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      City or town.

    - [`owner(…).address(…).country(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Country.

    - [`owner(…).address(…).id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Address identifier on responses that include it.

    - [`owner(…).address(…).line1(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      First address line.

    - [`owner(…).address(…).line2(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Second address line when provided.

    - [`owner(…).address(…).name(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Address label when provided.

    - [`owner(…).address(…).phone(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Contact phone number when provided.

    - [`owner(…).address(…).postCode(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Postal code when provided.

    - [`owner(…).address(…).region(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Region or state.

  - [`owner(…).name(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

    Account owner's name.

- [`pullConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html)

  Present while pull capability is enabled.

  - [`pullConfiguration(…).enabledAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `timestamp`

    When pull capability was enabled.

  - [`pullConfiguration(…).mandate(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

    Current authorization record.

    - [`pullConfiguration(…).mandate(…).createdAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `timestamp`

      When the mandate was created.

    - [`pullConfiguration(…).mandate(…).id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Mandate identifier.

    - [`pullConfiguration(…).mandate(…).ipAddress(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Submitted IP address, or an empty string when omitted.

    - [`pullConfiguration(…).mandate(…).userAgent(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Submitted user agent, or an empty string when omitted.

- [`pushConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html)

  Present while push capability is enabled. Payout eligibility also requires a supported account type, matching currency, and an active lifecycle state.

  - [`pushConfiguration(…).enabledAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `timestamp`

    When push capability was enabled.

- [`reference(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

  Your reconciliation identifier. Connect and create require 5–40
  characters.

- [`supplied(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

  Provenance for how the account details were supplied when available,
  including [`account(…).supplied(…).by(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html), optional context
  identifiers, and [`account(…).supplied(…).suppliedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html).

- [`type(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `enum`

  [`FinancialAccountType.BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#BANK_ACCOUNT),
  [`FinancialAccountType.DOSH_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#DOSH_ACCOUNT), or
  [`FinancialAccountType.WALLET`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#WALLET).

- [`verification(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

  Verification metadata when available. The current public response shape
  does not expose nested verification fields.

- [`wallet(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html)

  Present when account.type is "wallet" .

  - [`wallet(…).id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

    Wallet identifier.

  - [`wallet(…).mobileMoney(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `object`

    Mobile-money details.

    - [`wallet(…).mobileMoney(…).accountNumber(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `string`

      Normalized subscriber account number.

    - [`wallet(…).mobileMoney(…).network(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `enum`

      [`MobileMoneyNetwork.AIRTEL`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#AIRTEL), [`MobileMoneyNetwork.MTN`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#MTN), [`MobileMoneyNetwork.TELECEL`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#TELECEL), or [`MobileMoneyNetwork.VODAFONE`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#VODAFONE).

  - [`wallet(…).type(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) — `enum`

    [`WalletType.MOBILE_MONEY`](https://java.inttegro.dev/v8.3.0/com/inttegro/wallets/WalletType.html#MOBILE_MONEY).

## Connect a financial account

Register a mobile-money wallet or Ghana bank account for payments and
payouts. Dosh accounts can also be registered, but cannot receive
payouts. To make a supported account eligible as a payout destination,
set
`pushConfiguration(…).enabled(…)` to
`true`, then map the
returned account ID with [Set payout
destinations](https://studio.inttegro.com/machine/java/api/payouts.md#set-payout-destinations).

### Validation rules

- `label(…)` and `reference(…)`: Both must be 5–40 characters. Use `label(…)` for human-readable names and `reference(…)` for your internal identifiers.
- `currency(…)`: Currently `"ghs"`.
- `owner(…)`: Wallet and Dosh requests require `owner(…).name(…)` and `owner(…).address(…).country(…)`. Bank requests may supply those values in either top-level `owner(…)` or `bankAccount(…).ghanaBankAccount(…).holder(…)`; missing values are filled between the two objects.
- `type(…)`: Determines which nested object is required. [`FinancialAccountType.WALLET`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#WALLET) needs `wallet(…)`, [`FinancialAccountType.BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#BANK_ACCOUNT) needs `bankAccount(…)`, and [`FinancialAccountType.DOSH_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#DOSH_ACCOUNT) needs an empty `doshAccount(…)` object.
- **Wallet-specific**: When `type(…)` is [`FinancialAccountType.WALLET`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#WALLET), `wallet(…).type(…)` must be [`WalletType.MOBILE_MONEY`](https://java.inttegro.dev/v8.3.0/com/inttegro/wallets/WalletType.html#MOBILE_MONEY). A Dosh account uses [`FinancialAccountType.DOSH_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#DOSH_ACCOUNT) at the top level and a `doshAccount(…)` object.
- **Bank account-specific**: When `type(…)` is [`FinancialAccountType.BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#BANK_ACCOUNT), provide `bankAccount(…).type(…)` as [`BankAccountType.GHANA_BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/bankaccounts/BankAccountType.html#GHANA_BANK_ACCOUNT), an account `bankAccount(…).ghanaBankAccount(…).number(…)`, and at least one of `bankAccount(…).ghanaBankAccount(…).sortCode(…)` or `bankAccount(…).ghanaBankAccount(…).swiftCode(…)`.
- **Push/Pull config**: `pushConfiguration(…).enabled(…)` and `pullConfiguration(…).enabled(…)` are optional booleans. Connect only records whether pull is enabled; use [Enable pull capability](#enable-pull-capability) when you need to submit authorization context.

### Required attributes

- `bankAccount(…)` — `BankAccountConfig`

  Required when type is "bank\_account".

  - `bankAccount(…).ghanaBankAccount(…)` — `GhanaBankAccount`

    Required Ghana bank-account details.

    - `bankAccount(…).ghanaBankAccount(…).holder(…)` — `BankAccountOwner`

      Optional holder details used to fill missing top-level owner values.

    - `bankAccount(…).ghanaBankAccount(…).number(…)` — `String`

      Non-empty bank account number.

    - `bankAccount(…).ghanaBankAccount(…).sortCode(…)` — `String`

      Non-empty bank sort code. Required when `bankAccount(…).ghanaBankAccount(…).swiftCode(…)` is omitted.

    - `bankAccount(…).ghanaBankAccount(…).swiftCode(…)` — `String`

      Non-empty SWIFT or BIC code. Required when `bankAccount(…).ghanaBankAccount(…).sortCode(…)` is omitted.

  - `bankAccount(…).type(…)` — `BankAccountType`

    [`BankAccountType.GHANA_BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/bankaccounts/BankAccountType.html#GHANA_BANK_ACCOUNT).

- `currency(…)` — `String`

  Lowercase ISO 4217 currency code. Currently
  `"ghs"`.

- `doshAccount(…)` — `Map<String, Object>`

  Required as an empty object when type is "dosh\_account".

- `label(…)` — `String`

  Human-readable name, 5–40 characters.

- `owner(…)` — `BankAccountOwner`

  Owner details. Always provide this object for wallet and Dosh accounts; bank holder details may fill it.

  - `owner(…).address(…)` — `BankAccountOwnerAddress`

    Owner address.

    - `owner(…).address(…).city(…)` — `String`

      City or town.

    - `owner(…).address(…).country(…)` — `String`

      Required country.

    - `owner(…).address(…).line1(…)` — `String`

      First address line.

    - `owner(…).address(…).line2(…)` — `String`

      Second address line.

    - `owner(…).address(…).name(…)` — `String`

      Address label.

    - `owner(…).address(…).phone(…)` — `String`

      Contact phone number.

    - `owner(…).address(…).postCode(…)` — `String`

      Postal code.

    - `owner(…).address(…).region(…)` — `String`

      Region or state.

  - `owner(…).name(…)` — `String`

    Required owner name.

- `reference(…)` — `String`

  Your reconciliation identifier, 5–40 characters.

- `type(…)` — `FinancialAccountType`

  [`FinancialAccountType.BANK_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#BANK_ACCOUNT),
  [`FinancialAccountType.DOSH_ACCOUNT`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#DOSH_ACCOUNT), or
  [`FinancialAccountType.WALLET`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountType.html#WALLET).

- `wallet(…)` — `WalletConfig`

  Required when type is "wallet".

  - `wallet(…).mobileMoney(…)` — `WalletMobileMoney`

    Required mobile-money details.

    - `wallet(…).mobileMoney(…).accountNumber(…)` — `String`

      Valid subscriber phone number; normalized by the API.

    - `wallet(…).mobileMoney(…).network(…)` — `MobileMoneyNetwork`

      [`MobileMoneyNetwork.AIRTEL`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#AIRTEL), [`MobileMoneyNetwork.MTN`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#MTN), [`MobileMoneyNetwork.TELECEL`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#TELECEL), or [`MobileMoneyNetwork.VODAFONE`](https://java.inttegro.dev/v8.3.0/com/inttegro/paymentmethods/MobileMoneyNetwork.html#VODAFONE).

  - `wallet(…).type(…)` — `WalletType`

    [`WalletType.MOBILE_MONEY`](https://java.inttegro.dev/v8.3.0/com/inttegro/wallets/WalletType.html#MOBILE_MONEY).

### Optional attributes

- `customData(…)` — `CustomDataInput`

  Your metadata object. String values are stored directly; other JSON values are serialized to strings. Keys may be at most 256 characters and the serialized object may be at most 25 KB. See [Custom data](https://studio.inttegro.com/machine/java/api/custom-data.md).

- `description(…)` — `String`

  Long-form description (up to 200 characters) of how you use this
  account. Examples: `Vendor disbursement wallet`,
  `Balance top-up source - owner's MTN`, and
  `Customer refund processing`. Useful for team context,
  compliance documentation, and audit trails.

- `pullConfiguration(…)` — `PullPushConfig`

  Set whether pull capability is enabled at connection time. Use Enable pull instead when you need to record authorization context.

  - `pullConfiguration(…).enabled(…)` — `Boolean`

    Set `true` to create the current mandate.

- `pushConfiguration(…)` — `PullPushConfig`

  Set whether the account is push-enabled at connection time.

  - `pushConfiguration(…).enabled(…)` — `Boolean`

    Set `true` to enable push capability. Supported wallets and bank accounts can then qualify for payout-destination configuration.

**Request — POST /financial\_accounts/connect**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountCreateParams;
import com.inttegro.financialaccounts.FinancialAccountType;
import com.inttegro.bankaccounts.BankAccountOwner;
import com.inttegro.bankaccounts.BankAccountOwnerAddress;
import com.inttegro.wallets.WalletConfig;
import com.inttegro.wallets.WalletType;
import com.inttegro.wallets.WalletMobileMoney;
import com.inttegro.paymentmethods.MobileMoneyNetwork;
import com.inttegro.financialaccounts.PullPushConfig;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountCreateParams.builder()
      .label("Konadu Tailoring Collections")
      .reference("KONADU-MOMO-SETTLEMENT")
      .description("Primary settlement wallet for Konadu B2C operations.")
      .type(FinancialAccountType.WALLET)
      .currency("ghs")
      .owner(BankAccountOwner.builder()
          .address(BankAccountOwnerAddress.builder()
              .city("Accra")
              .country("Ghana")
              .line1("123 High Street")
              .name("Konadu Tailoring Ltd")
              .region("Greater Accra")
              .build())
          .name("Konadu Tailoring Ltd")
          .build())
      .wallet(WalletConfig.builder()
          .type(WalletType.MOBILE_MONEY)
          .mobileMoney(WalletMobileMoney.builder()
              .network(MobileMoneyNetwork.MTN)
              .accountNumber("0242057831")
              .build())
          .build())
      .pushConfiguration(PullPushConfig.builder()
          .enabled(true)
          .build())
      .pullConfiguration(PullPushConfig.builder()
          .enabled(false)
          .build())
      .build();
    var result = client.financialAccounts().connect(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "description": "Primary settlement wallet for Konadu B2C operations.",
    "label": "Konadu Tailoring Collections",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T10:22:11.745Z"
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account_number": "0242057831",
        "network": "mtn"
      }
    }
  }
}
```

## Disconnect a financial account

Stop new money movement to a financial account without deleting its
history. The account remains available through lookup and page, and the
response sets [`account(…).disconnectedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html).

If the account is currently configured as a payout destination for any
currency, the request fails unless you either remove it from payout
destinations first or set
`unsetAsPayoutDestination(…)` to
`true`. This prevents
accidentally breaking automatic payouts.

Disconnecting an already-disconnected account succeeds without changing
its original disconnect time.

### Request attributes

- `accountId(…)` — `String`

  Unique identifier of the account to disconnect. Required.

- `unsetAsPayoutDestination(…)` — `Boolean`

  When `true`, remove this account from every
  payout-destination mapping before disconnecting it. Defaults to
  `false`.

**Request — POST /financial\_accounts/disconnect**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountToggleParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountToggleParams.builder()
      .accountId("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0")
      .unsetAsPayoutDestination(true)
      .build();
    var result = client.financialAccounts().disconnect(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "currency": "ghs",
    "type": "wallet",
    "label": "Vendor settlement - MTN",
    "description": "Payout destination for marketplace vendor settlements",
    "disconnected_at": "2025-03-22T14:35:18.221Z",
    "created_at": "2025-01-15T09:12:33.445Z"
  }
}
```

## Reconnect a financial account

Restore a disconnected financial account while keeping its account ID and
history.

Reconnect only clears the account-level
[`account(…).disconnectedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) state. It preserves the same
account ID, historical payouts or charges, and any existing push or pull
configuration already stored on the record. If you removed this account
from payout destinations during disconnect, set those destinations again
separately.

Reconnecting an already-connected account succeeds without changing it.

### Request attributes

- `account_id` — `string` — wire-only

  Unique identifier of the account to reconnect. Required.

**Request — POST /financial\_accounts/reconnect**

```java
import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.financialAccounts().reconnect("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0");
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "currency": "ghs",
    "type": "wallet",
    "label": "Vendor settlement - MTN",
    "description": "Payout destination for marketplace vendor settlements",
    "created_at": "2025-01-15T09:12:33.445Z"
  }
}
```

## Create a financial account

Add a financial account from wallet, bank-account, or Dosh account details
you already have. This does not open an account with the financial
institution. Dosh accounts cannot receive payouts. If you are adding a
payout destination, use [Connect a financial
account](#connect-a-financial-account).

### Request and response

The request attributes and validation rules match [Connect a financial
account](#connect-a-financial-account).

Create responses can additionally include
[`account(…).supplied(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) provenance.

**Request — POST /financial\_accounts/create**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountCreateParams;
import com.inttegro.financialaccounts.FinancialAccountType;
import com.inttegro.bankaccounts.BankAccountOwner;
import com.inttegro.bankaccounts.BankAccountOwnerAddress;
import com.inttegro.wallets.WalletConfig;
import com.inttegro.wallets.WalletType;
import com.inttegro.wallets.WalletMobileMoney;
import com.inttegro.paymentmethods.MobileMoneyNetwork;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountCreateParams.builder()
      .label("Marketplace Seller Sub-Account")
      .reference("SELLER-001-COLLECTION")
      .description("Dedicated collection account for seller 001.")
      .type(FinancialAccountType.WALLET)
      .currency("ghs")
      .owner(BankAccountOwner.builder()
          .address(BankAccountOwnerAddress.builder()
              .city("Accra")
              .country("Ghana")
              .line1("45 Market Road")
              .name("Marketplace Seller Ltd")
              .region("Greater Accra")
              .build())
          .name("Marketplace Seller Ltd")
          .build())
      .wallet(WalletConfig.builder()
          .type(WalletType.MOBILE_MONEY)
          .mobileMoney(WalletMobileMoney.builder()
              .network(MobileMoneyNetwork.MTN)
              .accountNumber("0244123456")
              .build())
          .build())
      .build();
    var result = client.financialAccounts().create(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_X1Y2Z3A4B5C6D7E8F9G0H1I2J3K4L5M6N7O8P9Q",
    "created_at": "2025-03-18T11:30:00.000Z",
    "currency": "ghs",
    "description": "Dedicated collection account for seller 001.",
    "label": "Marketplace Seller Sub-Account",
    "owner": {
      "name": "Marketplace Seller Ltd",
      "address": {
        "application_id": "app_7WqP2mK9xR4tV6nL",
        "city": "Accra",
        "country": "Ghana",
        "id": "",
        "line_1": "45 Market Road",
        "name": "",
        "region": "Greater Accra"
      }
    },
    "reference": "SELLER-001-COLLECTION",
    "supplied": {
      "by": "merchant",
      "channel": "api",
      "supplied_at": "2025-03-18T11:30:00.000Z"
    },
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account_number": "0244123456",
        "network": "mtn"
      }
    }
  }
}
```

## Lookup a financial account

Retrieve a financial account, including its connection state, capabilities,
owner, institution, and type-specific details.

### Request attributes

- `account_id` — `string` — wire-only

  Non-empty financial-account ID returned by Connect or Create.

**Request — POST /financial\_accounts/lookup**

```java
import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.financialAccounts().lookup("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0");
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {
      "vendor_id": "VNDR-001",
      "region": "Greater Accra"
    },
    "description": "Primary settlement wallet for Konadu B2C operations.",
    "label": "Konadu Tailoring Collections",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "pull_configuration": {
      "enabled_at": "2025-03-17T14:30:00.000Z",
      "mandate": {
        "id": "fm_K3Lx9PqW7jZ2vN8mR5tY1hC6bF4dS0gA",
        "created_at": "2025-03-17T14:30:00.000Z",
        "ip_address": "102.176.95.12",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T10:22:11.745Z"
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account_number": "0242057831"
      }
    }
  }
}
```

## Update a financial account

Change the label, description, reference, owner, or custom data on a
financial account. To change its destination details, connect or create a
new account. Use the capability operations below to enable or disable push
and pull.

`currency`, `type`, and the
account-type-specific objects are not accepted by this operation. Create
or connect a new financial account when the destination itself changes.

### Request attributes

- `accountId(…)` — `String`

  Unique identifier of the account to update. Required.

- `customData(…)` — `CustomDataPatch`

  Application-specific metadata. Keys are merged into the existing object;
  a key sent as `null` is deleted. Maximum size: 25 KB
  when serialized.

- `description(…)` — `String`

  New description. Omit it to keep the current value.

- `label(…)` — `String`

  New human-readable name. Omit it to keep the current value.

- `owner(…)` — `BankAccountOwner`

  Replacement owner object. Supplying it replaces the complete stored owner; omitted nested values become empty or absent rather than being merged from the previous owner.

- `reference(…)` — `String`

  New reference. Omit it to keep the current value.

**Request — POST /financial\_accounts/update**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountUpdateParams;
import com.inttegro.CustomDataPatch;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountUpdateParams.builder()
      .accountId("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0")
      .label("Konadu Tailoring - Primary")
      .customData(new CustomDataPatch()
          .set("vendor_id", "VNDR-001")
          .set("region", "Greater Accra"))
      .build();
    var result = client.financialAccounts().update(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {
      "vendor_id": "VNDR-001",
      "region": "Greater Accra"
    },
    "description": "Primary settlement wallet for Konadu B2C operations.",
    "label": "Konadu Tailoring - Primary",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "id": "8pJ3mV7xQ2nK9rT4",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T10:22:11.745Z"
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account_number": "0242057831",
        "network": "mtn"
      }
    }
  }
}
```

## Enable pull capability

Authorize a financial account for payment flows that pull funds from it.
This operation records the mandate; it does not move money.

You can optionally send the authorization request's
`ip_address` and `user_agent`. Omit
either field when it is unavailable; the API does not derive these values
automatically for this operation.

If pull is already enabled, the request succeeds and preserves the
existing mandate, including its original
[`account(…).pullConfiguration(…).enabledAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html).  To replace `ip_address` or
`user_agent`, disable pull and enable it again with the
new authorization context.

### Request attributes

- `accountId(…)` — `String`

  Unique identifier of the account to enable pull for. Required.

- `ip_address` — `string` — wire-only

  IP address associated with the authorization, when available.

- `user_agent` — `string` — wire-only

  User agent associated with the authorization, when available.

**Request — POST /financial\_accounts/enable\_pull**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountToggleParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountToggleParams.builder()
      .accountId("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0")
      .build();
    var result = client.financialAccounts().enablePull(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Operations account for collections and transfers.",
    "label": "GCB Bank - Collections",
    "owner": {
      "name": "QuickPay Solutions Ltd",
      "address": {
        "city": "Kumasi",
        "country": "Ghana",
        "line_1": "Adum Commercial Street",
        "line_2": "Building 12",
        "name": "Regional Office",
        "phone": "+233322098765",
        "post_code": "AK-039",
        "region": "Ashanti"
      }
    },
    "pull_configuration": {
      "enabled_at": "2025-03-18T11:45:22.103Z",
      "mandate": {
        "id": "fm_K3Lx9PqW7jZ2vN8mR5tY1hC6bF4dS0gA",
        "created_at": "2025-03-18T11:45:22.103Z",
        "ip_address": "",
        "user_agent": ""
      }
    },
    "reference": "QUICKPAY-GCB-COLLECTIONS",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "0123456789",
        "name": "GCB BANK LTD",
        "branch": "Adum Branch",
        "swift_code": "GHCBGHAC",
        "sort_code": "040211",
        "holder": {
          "name": "QuickPay Solutions Ltd",
          "address": {
            "city": "Kumasi",
            "country": "Ghana",
            "line_1": "Adum Commercial Street",
            "line_2": "Building 12",
            "name": "Regional Office",
            "phone": "+233322098765",
            "post_code": "AK-039",
            "region": "Ashanti"
          }
        }
      }
    }
  }
}
```

## Disable pull capability

Revoke the account's current pull mandate. The operation removes
[`account(…).pullConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) from the account response,
including the mandate and its
[`account(…).pullConfiguration(…).enabledAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) timestamp.
Enabling pull later creates a new mandate, so obtain fresh authorization
before doing so.

Disabling pull when it is already disabled succeeds without changing the
account.

### Request attributes

- `accountId(…)` — `String`

  Unique identifier of the account to disable pull for. Required.

**Request — POST /financial\_accounts/disable\_pull**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountToggleParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountToggleParams.builder()
      .accountId("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0")
      .build();
    var result = client.financialAccounts().disablePull(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Primary settlement wallet for Konadu B2C operations.",
    "label": "Konadu Tailoring Collections",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account_number": "0242057831",
        "network": "mtn"
      }
    }
  }
}
```

## Enable push capability

Enable push capability on a financial account. This adds
[`account(…).pushConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html); it does not schedule a
payout or change destination mappings. A supported wallet or Ghana bank
account can then qualify as a payout destination when it is connected and
its currency matches the payout. Dosh accounts, disconnected accounts,
and archived accounts remain ineligible even when push is enabled.

If push is already enabled, the request succeeds and preserves its
original [`account(…).pushConfiguration(…).enabledAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html).

### Request attributes

- `accountId(…)` — `String`

  Unique identifier of the account to enable push for. Required.

**Request — POST /financial\_accounts/enable\_push**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountToggleParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountToggleParams.builder()
      .accountId("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0")
      .build();
    var result = client.financialAccounts().enablePush(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Business account for payroll and vendor settlements.",
    "label": "Stanbic Bank - Payroll",
    "owner": {
      "name": "TechFlow Ghana Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "Airport City",
        "line_2": "Building 5",
        "name": "Head Office",
        "phone": "+233302456789",
        "post_code": "GA-234",
        "region": "Greater Accra"
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T11:52:07.845Z"
    },
    "reference": "TECHFLOW-STANBIC-PAYROLL",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "5678901234",
        "name": "STANBIC BANK GHANA LTD",
        "branch": "Airport City Branch",
        "swift_code": "SBICGHAC",
        "sort_code": "190102",
        "holder": {
          "name": "TechFlow Ghana Ltd",
          "address": {
            "city": "Accra",
            "country": "Ghana",
            "line_1": "Airport City",
            "line_2": "Building 5",
            "name": "Head Office",
            "phone": "+233302456789",
            "post_code": "GA-234",
            "region": "Greater Accra"
          }
        }
      }
    }
  }
}
```

## Disable push capability

Remove [`account(…).pushConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccount.html) so the account can
no longer qualify as a payout destination.

If the financial account is configured as a payout destination for any
currency, the request fails unless you either remove it from payout
destinations first or set
`unsetAsPayoutDestination(…)` to
`true`.

Disabling push when it is already disabled succeeds without changing the
account.

### Request attributes

- `accountId(…)` — `String`

  Unique identifier of the account to disable push for. Required.

- `unsetAsPayoutDestination(…)` — `Boolean`

  When `true`, remove this account from every payout
  destination before disabling push. Defaults to
  `false`.

**Request — POST /financial\_accounts/disable\_push**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.FinancialAccountToggleParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FinancialAccountToggleParams.builder()
      .accountId("fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0")
      .build();
    var result = client.financialAccounts().disablePush(params);
  }
}
```

```json
{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Settlement account for marketplace operations.",
    "label": "Fidelity Bank - Settlement",
    "owner": {
      "name": "MarketHub Ghana Ltd",
      "address": {
        "city": "Kumasi",
        "country": "Ghana",
        "line_1": "Adum High Street",
        "line_2": "Floor 2",
        "name": "Regional Office",
        "phone": "+233322567890",
        "post_code": "AK-123",
        "region": "Ashanti"
      }
    },
    "reference": "MARKETHUB-FIDELITY-SETTLEMENT",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "4567890123",
        "name": "FIDELITY BANK GHANA",
        "branch": "High Street Branch",
        "swift_code": "FIDEGHAC",
        "sort_code": "240103",
        "holder": {
          "name": "MarketHub Ghana Ltd",
          "address": {
            "city": "Kumasi",
            "country": "Ghana",
            "line_1": "Adum High Street",
            "line_2": "Floor 2",
            "name": "Regional Office",
            "phone": "+233322567890",
            "post_code": "AK-123",
            "region": "Ashanti"
          }
        }
      }
    }
  }
}
```

## Page through financial accounts

Retrieve a numbered page of financial accounts. Results are not guaranteed
to be ordered by creation time.

### Request attributes

- `pageNumber(…)` — `Integer` — required

  1-based page index to fetch. Must be between 1 and 10 inclusive.

- `pageSize(…)` — `Integer`

  Requested number of accounts, between 1 and 256. Defaults to 256.Response [`page(…).size(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) is the number of accounts
  actually returned, not the requested size.

### Response shape

- `FinancialAccountsPage` contains [`page(…).number(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html), [`page(…).size(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html), and a [`page(…).accounts(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) array
- Each account uses the complete readable account shape; optional metadata and lifecycle fields are omitted when they have no stored value
- Type-specific details are nested under [`page(…).accounts(…)[].wallet(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) or [`page(…).accounts(…)[].bankAccount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) when available; current Dosh resources omit a [`page(…).accounts(…)[].doshAccount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) response object
- Push/pull configurations are included when enabled: [`page(…).accounts(…)[].pushConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) and [`page(…).accounts(…)[].pullConfiguration(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html)
- The endpoint has no server-side lifecycle filter; inspect [`page(…).accounts(…)[].archivedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) and [`page(…).accounts(…)[].disconnectedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/financialaccounts/FinancialAccountsPage.html) when present

**Request — POST /financial\_accounts/page**

```java
import com.inttegro.Client;
import com.inttegro.financialaccounts.PageFinancialAccountsParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = PageFinancialAccountsParams.builder()
      .pageNumber(1)
      .pageSize(50)
      .build();
    var result = client.financialAccounts().page(params);
  }
}
```

```json
{
  "page": {
    "number": 1,
    "size": 2,
    "accounts": [
      {
        "id": "fa_abc123xyz",
        "type": "wallet",
        "currency": "ghs",
        "label": "Primary Mobile Money",
        "description": "Main MTN wallet for customer payouts",
        "reference": "mtn_primary",
        "custom_data": {
          "region": "greater_accra",
          "purpose": "payouts"
        },
        "created_at": "2025-11-23T10:00:00Z",
        "push_configuration": {
          "enabled_at": "2025-11-23T10:05:00Z"
        },
        "wallet": {
          "id": "wal_xyz789",
          "type": "mobile_money",
          "mobile_money": {
            "network": "mtn",
            "account_number": "0242057831"
          }
        }
      },
      {
        "id": "fa_def456uvw",
        "type": "bank_account",
        "currency": "ghs",
        "label": "Settlement Account",
        "created_at": "2025-11-20T14:30:00Z",
        "bank_account": {
          "type": "ghana_bank_account",
          "ghana_bank_account": {
            "number": "4567890123",
            "name": "FIDELITY BANK GHANA",
            "branch": "High Street Branch",
            "swift_code": "FIDEGHAC",
            "sort_code": "240103",
            "holder": {
              "name": "MarketHub Ghana Ltd",
              "address": {
                "city": "Kumasi",
                "country": "Ghana",
                "line_1": "Adum High Street",
                "region": "Ashanti"
              }
            }
          }
        }
      }
    ]
  }
}
```

## Search financial accounts

Find financial accounts from remembered text or exact account attributes.
Results are discovery summaries; use the returned account ID with
[Lookup a financial account](#lookup-a-financial-account) before choosing a
payout destination or changing account capabilities.

## Use financial-account search for discovery, then verify eligibility

- Send `text`,
  `filters`,
  or both. Filters and facets accept only the wire field names
  `currency`, `status`, and
  `type`; field names are unqualified.
- Read the canonical account by
  [`results(…)[].resource(…).id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html)
  before evaluating lifecycle, currency, account details, or push and pull capabilities.
- Replay the identical request with
  [`nextCursor(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html)
  as the request cursor when
  [`hasMore(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html)
  is true. The cursor is opaque and request-bound.
- [`total(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html)
  and facet counts describe the result set;
  [`resultCount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html)
  describes the current page. Inspect
  [`total(…).relation(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html)
  before treating a total as exact.
- Check [`freshness(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html);
  use lookup whenever delayed, partial, unknown, or unavailable search data
  could change a decision.

### Request attributes

- `cursor` — `string`

  Opaque continuation cursor returned by the previous page. Replay the
  same request and add this value for the next page.

- `facets` — `array`

  Fields to group and count: currency, status, or type.

  - `facets.field` — `array` — required

    Route-local facet field.

  - `facets.limit` — `array`

    Maximum buckets, from 1 through 50. Defaults to 10.

- `filters` — `array`

  Exact constraints on currency, status, or type.

  - `filters.field` — `array` — required

    Route-local filter field.

  - `filters.operator` — `array` — required

    eq for one value or in for any supplied value.

  - `filters.values` — `array` — required

    One value for eq; one through 20 values for in.

- `pageSize` — `integer`

  Results per page, from `1` through `100`. Defaults to `20`.

- `sort` — `object`

  Result ordering.

  - `sort.direction` — `object` — required

    asc or desc. Relevance supports desc only.

  - `sort.field` — `object` — required

    relevance or updated\_at.

- `text` — `string`

  Search text, from 1 through 512 characters. Supply search text, exact
  filters, or both.

### Response

Returns a typed search page with discovery summaries, requested facet
counts, page and total counts, an optional [`nextCursor(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html),
and [`freshness(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/search/ResourceSearchPage.html) metadata. Search never replaces a
canonical account lookup.

**Request — POST /financial\_accounts/search**

```java
import com.inttegro.Client;
import com.inttegro.search.ResourceSearchRequest;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var request = ResourceSearchRequest.builder()
      .text("primary mobile money")
      .build();
    var page = client.financialAccounts().search(request);
  }
}
```

```json
{
  "search": {
    "results": [
      {
        "resource": { "type": "financial_account", "id": "fa_abc123xyz" },
        "title": "Primary Mobile Money",
        "status": "active",
        "updated_at": "2026-09-21T10:30:00Z"
      }
    ]
  }
}
```

## Related resources

- [Set payout destinations](https://studio.inttegro.com/machine/java/api/payouts.md#set-payout-destinations) - Map each payout currency to a connected, push-enabled financial account.
- [Schedule a payout](https://studio.inttegro.com/machine/java/api/payouts.md#schedule-a-payout) - Send available balance funds to an eligible destination.