Accounts

An account in Connectivity is a stable representation of an account that lives on an upstream payment provider — a Stripe balance, a Bankingcircle settlement account, a Mangopay wallet, a Coinbase Prime trading wallet. Each PSP-side account maps one-to-one to a Connectivity PSPAccount, so the rest of the platform can reason about provider balances and flows through a uniform shape regardless of which connector they came from.

Account model#

Every account carries:

Internal accounts are operationally relevant — the connector can fetch balances, surface payment history, and (where supported) initiate outbound transfers from them. External accounts are destination-only: funds can land in them via Payment Initiation, but no balance or transaction history is fetched.

Listing accounts#

Formance Console#

Open the Accounts tab in the sidebar. The page lists every account synced from every installed connector with filterable columns for connector, asset, type, and creation date. Click an account to see its metadata, raw upstream payload, and (for internal accounts) the latest balance per asset.

API#

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts

To filter by connector or type, post a query body:

curl -s "$STACK/api/payments/v3/accounts?pageSize=15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"$match": {"connectorID": "'$CONNECTOR_ID'", "type": "INTERNAL"}}' | jq

A single account by id:

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts/<ACCOUNT_ID>

The same $match operator works against default_asset, metadata.<key>, and psu_id for Open Banking accounts — see Cash pools for the full query syntax.

Reading balances#

Balances are fetched per cycle by the connector's FetchBalances capability and stored as point-in-time snapshots. No provider exposes a historical balance series, so Connectivity surfaces only the latest value per (account, asset):

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts/<ACCOUNT_ID>/balances

Returns one row per asset the account holds. Empty when the account type is EXTERNAL (those don't carry balances).

For aggregating balances across many accounts (treasury views, reconciliation against a ledger), wrap them in a cash pool — the pool endpoints sum balances by asset across every account in the pool.

Internal accounts#

INTERNAL accounts are operationally controlled accounts at the provider:

• a Stripe acct_* balance,
• a Bankingcircle settlement account,
• a Mangopay wallet,
• a Coinbase Prime trading wallet,
• etc.

You can read balances, see the full transaction history, and (when the connector supports it) initiate transfers and payouts from them:

1. Transfer — INTERNAL → INTERNAL movement at the same connector.
2. Payout — INTERNAL → EXTERNAL movement (e.g. settlement to a bank account).

See Payment Initiation for the v3 API.

External accounts#

EXTERNAL accounts are destination-only: bank accounts, beneficiaries, or counterparty wallets the provider knows about but doesn't operationally control on your behalf. No balance or transaction history is fetched. You move funds to them via Payment Initiation.

Creating an external account#

Some connectors let you create an external account on the provider side from the Connectivity API — useful when you want to register a new beneficiary before payouting to it:

curl -X POST $FORMANCE_API_URL/api/payments/v3/bank-accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc — main",
    "country": "FR",
    "iban": "FR1420041010050500013M02606",
    "swiftBicCode": "PSSTFRPPMON",
    "accountNumber": "0500013M026",
    "metadata": {
      "customer_id": "cust_123"
    }
  }'

The connector must declare CAPABILITY_CREATE_BANK_ACCOUNT — see the capability matrix. The response links the freshly-created bank account to the connector's account list; fetch it back with v3GetAccount against the returned ID.