@spec connect(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.CreateRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Attaches an existing wallet, Ghana bank account, or Dosh account to the application.

Use connect/3 for an account that already exists outside Inttegro. It records the relationship and may initiate provider verification. It does not silently grant every capability: read the returned account's verification, push, and pull configuration before using it.

Example: connect a mobile-money wallet

mobile_money =
  Inttegro.FinancialAccounts.WalletRequestWalletMobileMoney.new!(
    account_number: "0244000042",
    network: :mtn
  )

wallet =
  Inttegro.FinancialAccounts.WalletRequestWallet.new!(
    type: :mobile_money,
    mobile_money: mobile_money
  )

request =
  Inttegro.FinancialAccounts.WalletRequest.new!(
    currency: "ghs",
    label: "Operations wallet",
    owner: owner,
    reference: "operations-wallet-001",
    type: :wallet,
    wallet: wallet
  )

Inttegro.FinancialAccounts.connect(client, request,
  idempotency_key: "connect-operations-wallet-001"
)

Returns {:ok, account} when the relationship is recorded, or {:error, exception} when the request is invalid, rejected by a provider, or cannot be completed. A successful response can still require later verification.

@spec create(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.CreateRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Provisions a new wallet, Ghana bank account, or Dosh account managed through Inttegro.

Use this operation when Inttegro should create or establish the financial account. To attach an account that already exists, use connect/3 instead. Choose the concrete request struct that matches the account type; Inttegro.FinancialAccounts.CreateRequest.t/0 links all supported variants.

The returned Inttegro.FinancialAccounts.FinancialAccount is the current account snapshot. Creation does not guarantee that push or pull is ready: inspect verification, push_configuration, and pull_configuration before offering the account for money movement.

Example: create a mobile-money wallet

owner =
  Inttegro.FinancialAccounts.OwnerInput.new!(
    name: "Ama Mensah",
    address:
      Inttegro.FinancialAccounts.OwnerInputAddress.new!(country: "GH")
  )

mobile_money =
  Inttegro.FinancialAccounts.WalletRequestWalletMobileMoney.new!(
    account_number: "0244000042",
    network: :mtn
  )

wallet =
  Inttegro.FinancialAccounts.WalletRequestWallet.new!(
    type: :mobile_money,
    mobile_money: mobile_money
  )

request =
  Inttegro.FinancialAccounts.WalletRequest.new!(
    currency: "ghs",
    label: "Primary collections wallet",
    owner: owner,
    reference: "wallet-primary-001",
    type: :wallet,
    wallet: wallet
  )

Inttegro.FinancialAccounts.create(client, request,
  idempotency_key: "create-wallet-primary-001"
)

Returns {:ok, account} or {:error, exception}. Reuse the idempotency key only when retrying this same creation intent.

@spec disable_pull(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.IDRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Stops new supported payments from pulling funds from the account.

The operation removes the active pull configuration and its mandate. It does not cancel or reverse payment activity already submitted. Push remains independent and is unchanged.

Example

request =
  Inttegro.FinancialAccounts.IDRequest.new!(account_id: "fa_...")

Inttegro.FinancialAccounts.disable_pull(client, request,
  idempotency_key: "disable-pull-fa-001"
)

Returns the updated account as {:ok, account} or {:error, exception}.

@spec disable_push(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.DisableRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Prevents the account from receiving new payouts and supported transfers.

Disabling push does not reverse transfers already submitted. If the account is configured as a payout destination, the operation is rejected unless unset_as_payout_destination is true; this avoids silently leaving payout routing pointed at a disabled account.

Example

request =
  Inttegro.FinancialAccounts.DisableRequest.new!(
    account_id: "fa_...",
    unset_as_payout_destination: true
  )

Inttegro.FinancialAccounts.disable_push(client, request,
  idempotency_key: "disable-push-fa-001"
)

Returns the updated account as {:ok, account} or {:error, exception}.

@spec disconnect(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.DisableRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Disconnects the financial account from new Inttegro activity without deleting its history.

Use this when the relationship should be suspended but historical payments, payouts, and audit records must remain referentially intact. If the account is currently a payout destination, set unset_as_payout_destination: true or the request is rejected.

Example

request =
  Inttegro.FinancialAccounts.DisableRequest.new!(
    account_id: "fa_...",
    unset_as_payout_destination: true
  )

Inttegro.FinancialAccounts.disconnect(client, request,
  idempotency_key: "disconnect-fa-001"
)

Returns {:ok, account} with its disconnection state or {:error, exception}. Disconnecting does not reverse activity already submitted.

@spec enable_pull(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.EnablePullRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Enables supported payments to collect funds from the account.

Pull describes money moving from this account. Enabling it creates a mandate. Pass the real payer IP address and user agent captured by your application; Inttegro deliberately does not infer them from the server-to-server SDK request. Do not substitute your backend's network identity for the payer context.

Example

request =
  Inttegro.FinancialAccounts.EnablePullRequest.new!(
    account_id: "fa_...",
    ip_address: payer_ip_address,
    user_agent: payer_user_agent
  )

Inttegro.FinancialAccounts.enable_pull(client, request,
  idempotency_key: "enable-pull-fa-001"
)

Returns {:ok, account} with a populated pull_configuration and mandate when enabled, or {:error, exception} when the account or supplied mandate context is ineligible.

@spec enable_push(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.IDRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Enables the account to receive payouts and other supported transfers from Inttegro.

Push describes money moving to this account. Enabling it does not enable collections from the account; that is the separate pull capability. Provider support and verification can vary, so inspect push_configuration on the returned account rather than assuming the capability was available from the account type alone.

Example

request =
  Inttegro.FinancialAccounts.IDRequest.new!(account_id: "fa_...")

Inttegro.FinancialAccounts.enable_push(client, request,
  idempotency_key: "enable-push-fa-001"
)

Returns {:ok, account} when the capability is enabled, or {:error, exception} when account state, verification, or provider policy prevents it.

@spec lookup(Inttegro.Client.t(), Inttegro.FinancialAccounts.IDRequest.t(), keyword()) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Retrieves the current state of one financial account owned by the authenticated application.

Lookup has no account-side effect. Use it after creation, connection, capability changes, or verification to refresh the authoritative state. In particular, inspect verification, disconnected_at, push_configuration, and pull_configuration instead of inferring readiness from an earlier request.

Example

request =
  Inttegro.FinancialAccounts.IDRequest.new!(account_id: "fa_...")

case Inttegro.FinancialAccounts.lookup(client, request) do
  {:ok, %Inttegro.FinancialAccounts.FinancialAccount{} = account} ->
    {:ok, account}

  {:error, %Inttegro.Errors.APIError{status: 404}} ->
    {:error, :financial_account_not_found}

  {:error, error} ->
    {:error, error}
end

Returns {:ok, account} or {:error, exception}.

@spec page(Inttegro.Client.t(), Inttegro.FinancialAccounts.PageRequest.t(), keyword()) ::
  {:ok, Inttegro.FinancialAccounts.Page.t()} | {:error, Exception.t()}

Retrieves one numbered page of financial accounts owned by the authenticated application.

page_number starts at 1; page_size controls the maximum number of accounts returned. The response's size is the number returned in this page, not a total across the application. When building an inventory or calculating totals, continue requesting pages until a page is empty.

Example

request =
  Inttegro.FinancialAccounts.PageRequest.new!(
    page_number: 1,
    page_size: 100
  )

with {:ok, page} <- Inttegro.FinancialAccounts.page(client, request) do
  Enum.each(page.accounts, &IO.inspect(&1.id))
end

Returns {:ok, %Inttegro.FinancialAccounts.Page{}} or {:error, exception}.

@spec reconnect(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.IDRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Reconnects a previously disconnected financial account.

Reconnection restores the relationship but does not promise that every previous capability or verification remains active. Inspect the returned account and explicitly enable any required push or pull capability that is absent.

Example

request =
  Inttegro.FinancialAccounts.IDRequest.new!(account_id: "fa_...")

case Inttegro.FinancialAccounts.reconnect(client, request,
       idempotency_key: "reconnect-fa-001"
     ) do
  {:ok, account} ->
    {:ok, account.push_configuration, account.pull_configuration}

  {:error, error} ->
    {:error, error}
end

Returns {:ok, account} or {:error, exception}.

@spec update(
  Inttegro.Client.t(),
  Inttegro.FinancialAccounts.UpdateRequest.t(),
  keyword()
) ::
  {:ok, Inttegro.FinancialAccounts.FinancialAccount.t()}
  | {:error, Exception.t()}

Changes mutable metadata on an existing financial account.

The request can update the label, description, external reference, owner details, or custom_data. It does not replace account credentials, change the account type, or enable push or pull. Use the dedicated capability operations for those state changes.

Example

request =
  Inttegro.FinancialAccounts.UpdateRequest.new!(
    account_id: "fa_...",
    label: "Treasury payouts",
    reference: "treasury-payouts-2026"
  )

Inttegro.FinancialAccounts.update(client, request,
  idempotency_key: "rename-fa-treasury-payouts-2026"
)

Returns the updated account snapshot as {:ok, account} or an error tuple. A transport error leaves the outcome unknown, so retry the same intent with the same idempotency key.