Account Pools

A cash pool is a collection of payment accounts from one or more payment service providers that you want to manage as a single unit. Cash pools aggregate balances across multiple accounts, providing a unified view of your funds for financial reporting, treasury management, and reconciliation.

Cash pools can be created in two ways:

• Static pools: Explicitly specify which accounts to include. Membership is fixed until you edit the pool.
• Dynamic pools: Define a query that matches accounts at evaluation time. New accounts that match the query — including accounts discovered on a fresh connector cycle after the pool was created — are automatically included in the pool's next balance query. Accounts removed from the connector (uninstalled, or now non-matching) drop out the same way.

Why cash pools?#

When managing funds across multiple financial institutions, you often need to view and analyze balances from different accounts together. For example, you might have:

• A Stripe account for card payments
• A PayPal account for alternative payments
• A bank account for direct transfers

Rather than querying each account individually, cash pools let you:

• View aggregated balances across all accounts in real-time
• Track historical balances at specific points in time
• Simplify financial reporting with consolidated balance views
• Enable reconciliation against your internal ledger
• Monitor liquidity across multiple financial institutions
• Automatically include new accounts that match your criteria (dynamic pools)

Pool structure#

A cash pool contains:

• ID: Unique UUID identifier
• Name: Human-readable name (must be unique)
• Created at: Timestamp when the pool was created
• Pool accounts: Array of account IDs included in the pool (for static pools)
• Query: JSON query defining account matching criteria (for dynamic pools)

Creating cash pools#

Cash pools are created via the Payments API using one of two approaches:

Static pools#

Specify exact accounts to include in the pool:

curl -X POST $FORMANCE_API_URL/api/payments/v3/pools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Static Pool",
    "accountIDs": [
      "stripe:acc_1234567890",
      "wise:account-uuid-here"
    ]
  }'

Dynamic pools#

Define criteria that automatically match accounts:

curl -X POST $FORMANCE_API_URL/api/payments/v3/pools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All USD Stripe Accounts",
    "query": "{\"$match\": {\"connector_id\": \"stripe:connector-id\", \"default_asset\": \"USD\"}}"
  }'

Query syntax#

Dynamic pools use the same query syntax as the List Accounts API. Supported query fields include:

• connector_id: Match accounts from specific connectors
• default_asset: Filter by currency/asset
• type: Account type (e.g., INTERNAL, EXTERNAL)
• name: Account name matching
• psu_id: Payment service user ID
• metadata.{key}: Custom metadata fields

Query examples#

All EUR accounts across connectors:

{
  "name": "EUR Accounts",
  "query": "{\"$match\": {\"default_asset\": \"EUR\"}}"
}

Stripe accounts only:

{
  "name": "Stripe Pool",
  "query": "{\"$match\": {\"connector_id\": \"stripe:connector-123\"}}"
}

Internal accounts with specific metadata:

{
  "name": "Business Accounts",
  "query": "{\"$match\": {\"type\": \"INTERNAL\", \"metadata.category\": \"business\"}}"
}

Static vs. Dynamic pools#

When to use static pools#

• Fixed account sets: When you have a specific, unchanging group of accounts
• Mixed criteria: When accounts don't follow a consistent pattern
• Fine-grained control: When you need to include/exclude specific accounts manually

When to use dynamic pools#

• Dynamic environments: When new accounts are frequently created
• Connector-based grouping: All accounts from a specific payment provider
• Currency segregation: Separate pools for different currencies
• Automated workflows: When pools need to be configured declaratively via API

Using cash pools#

Balance queries#

Pool balance endpoints aggregate balances from all accounts in the pool by asset:

Latest aggregated balances:

curl -X GET $FORMANCE_API_URL/api/payments/v3/pools/<POOL_ID>/balances/latest

Historical balances at a specific timestamp:

curl -X GET $FORMANCE_API_URL/api/payments/v3/pools/<POOL_ID>/balances

Balance aggregation logic:

1. Static pools: Fetches balances from the specified account IDs
2. Dynamic pools: Runs the query to find matching accounts, then fetches their balances
3. Groups by asset/currency
4. Sums amounts for each asset
5. Returns array of aggregated balances

Using pools with Reconciliation

Cash pools can be used as balance sources in ledger_vs_pool_drift and source_parity control templates. Rules can compare a pool with Ledger or with another pool, use a per-asset tolerance, and read each source at an independent point in time.

{
  "templateKind": "source_parity",
  "templateSpec": {
    "left": {
      "kind": "ledger",
      "ledger": "main",
      "query": { "$match": { "address": "control:provider" } }
    },
    "right": {
      "kind": "payments_pool",
      "poolID": "<POOL_ID>"
    },
    "tolerance": { "USD/2": 0 }
  }
}

See Getting Started with Reconciliation for the complete rule and evaluation workflow.