Skip to main content

Set up financial accounts

Financial accounts identify where Inttegro can send or pull money. For payouts, connect a supported mobile money wallet or Ghana bank account, enable push capability, then map that account as the payout destination for its currency.

Use MCP after setup

An authenticated AI agent can verify payout settings and later payout activity after setup. Connecting financial accounts still uses the Financial Accounts API or dashboard.

MCP tools: get_payout_settings or list_payouts

Use this guide for the setup flow. Use the Financial Accounts API reference for exact request and response shapes.

What a financial account does

A financial account stores account details, owner information, capability state, lifecycle state, and optional institution details. It does not move money by itself.

TaskUse
Register an existing accountConnect a financial account
Check one accountLookup a financial account
List connected accountsPage through financial accounts
Allow payout useEnable push capability
Route payouts to the accountSet payout destinations
Stop future useDisconnect a financial account

Supported account types

TypePayout useRequired details
wallet with wallet.type: "mobile_money"Supported when the account is active, push-enabled, and uses the payout currency.Mobile money provider and account number.
bank_account with bank_account.type: "ghana_bank_account"Supported when the account is active, push-enabled, complete, and uses the payout currency.Account number plus either sort code or SWIFT/BIC.
dosh_accountNot supported as a payout destination.Empty dosh_account object for recordkeeping.

Do not treat a connected account as payout-ready just because it exists. Payout routing also depends on currency, capability state, lifecycle state, and destination configuration.

Before you connect

Collect the details you need before calling the API:

  • the account type;
  • the currency, currently ghs for supported Ghana payout flows;
  • a label and reference, each between 5 and 40 characters;
  • owner name and country for wallet and Dosh accounts;
  • holder, account number, and sort code or SWIFT/BIC for Ghana bank accounts; and
  • whether the account should be push-enabled immediately.

For a bank account, owner and holder details can fill each other when one side is missing. For a wallet, send explicit owner information.

Connect the account

Use Connect a financial account when the customer or merchant is registering an account that already exists outside Inttegro.

The useful wallet shape is:

{
  "type": "wallet",
  "currency": "ghs",
  "label": "Primary MTN wallet",
  "reference": "payout-wallet-001",
  "owner": {
    "name": "Adwoa Mensah",
    "address": {
      "country": "Ghana"
    }
  },
  "wallet": {
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "0241234567"
    }
  },
  "push_configuration": {
    "enabled": true
  }
}

The useful Ghana bank shape is:

{
  "type": "bank_account",
  "currency": "ghs",
  "label": "Primary bank account",
  "reference": "payout-bank-001",
  "bank_account": {
    "type": "ghana_bank_account",
    "ghana_bank_account": {
      "number": "0123456789",
      "sort_code": "030100",
      "holder": "Adwoa Mensah"
    }
  },
  "push_configuration": {
    "enabled": true
  }
}

Store the returned financial account ID. Payout destination setup uses that ID, not the account number.

If Inttegro can match the supplied bank or mobile money details to a known institution, the account may include an institution object. Treat institution details as descriptive metadata. Capability state and payout destination configuration still decide whether money can move.

Capabilities

Financial accounts have separate push and pull capabilities.

CapabilityMeaning
PushInttegro can send money to the account. This is required for payout destinations.
PullInttegro can debit the account when the product flow supports it and the right authorization exists.

You can send capability configuration while connecting the account, or change it later with the capability endpoints. Enabling pull records capability state; it is not the same thing as initiating a debit.

Make it a payout destination

Connecting an account is only the first step. To receive payouts, the account must also be selected as the payout destination for its currency.

  1. Confirm the account is not disconnected.
  2. Confirm the account type is payout-supported: mobile money wallet or Ghana bank account.
  3. Confirm the account currency matches the payout currency.
  4. Confirm push capability is enabled.
  5. Call Set payout destinations with the financial account ID.
  6. Verify the result with Get payout settings.

The destination map is currency-based:

{
  "destinations": {
    "ghs": "fa_H3cNv7pQf9WbLt2mJs6yXrPq4Kz1Vd5G0aEiUo"
  }
}

Read that as “send eligible GHS payouts to this financial account.” Updating the destination affects future payouts. It does not rewrite payouts that are already scheduled, executing, or completed.

Lifecycle

Disconnect an account when it should no longer be used for new money movement. A disconnected account remains available for lookup and listing, but it is not eligible for new payouts.

Reconnect clears disconnected_at; it does not restore payout destination mappings that were removed during disconnect, and it does not perform external authorization. After reconnecting, verify capabilities and payout destinations again before relying on the account.

Capability changes, disconnect, and reconnect operations are idempotent. Retrying the same request should leave the account in the same intended state.

Troubleshooting

SymptomCheck first
The account cannot be used as a payout destinationCheck its type, currency, push capability, connection state, and whether it is connected to the same Inttegro account.
A Ghana bank account is rejectedSend account number plus either sort_code or swift_code; include holder or owner information.
A wallet is rejectedConfirm type: "wallet", wallet.type: "mobile_money", a supported provider, account number, owner name, and owner country.
Automatic payouts do not runCheck payout settings, destination map, eligible balance, and recent open payouts.
Institution details look wrong or missingUse the financial account ID and submitted source details when contacting support. Institution metadata is not the payout-routing control.
You need to change the destination accountConnect the new account, enable push, then update the currency destination map. Do not rely on editing an old destination in place.