Balances

BETA: This endpoint is subject to change without notice.

Every account with the balance capability has a balance that tracks funds across three positions: available, pending, and reserved. Individual transactions are recorded as balance lines.

For embedded accounts, funds typically arrive via transfers from the parent account, which settle immediately. For how charges settle into the parent account's balance before being transferred, see Custodial Balances.

Balance positions

Each position is broken down by currency. The amount field is in the smallest currency unit (e.g. pence for GBP).

Retrieving a balance

Use GetBalance for embedded accounts (which hold balance pooled within a parent's custodial bank account).

API reference

curl https://api.synaptopay.com/v1/accounts/acct_EMBEDDED_ACCOUNT/balance \
  -H "Authorization: Api-Key $API_KEY"

Response

{
  "available": [
    { "currency": "GBP", "amount": "150000" }
  ],
  "pending": [
    { "currency": "GBP", "amount": "25000" }
  ],
  "reserved": []
}

In this example, the account has 1,500.00 GBP available and 250.00 GBP pending.

Balance lines

Balance lines are the individual ledger entries that make up a balance. Each line records a single financial event — a charge, transfer, payout, or refund.

Fields

States

Types

Listing balance lines

API reference

curl -X POST https://api.synaptopay.com/v1/accounts/acct_EMBEDDED_ACCOUNT/balance/lines:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_size": 20
  }'

Response

{
  "balance_lines": [
    {
      "state": "SETTLED",
      "type": "TRANSFER",
      "currency": "GBP",
      "amount": "50000",
      "description": "January payout split",
      "create_time": "2026-01-15T10:30:00Z",
      "update_time": "2026-01-15T10:30:05Z"
    },
    {
      "state": "RESERVED",
      "type": "PAYOUT",
      "currency": "GBP",
      "amount": "-50000",
      "description": "",
      "create_time": "2026-01-16T09:00:00Z",
      "update_time": "2026-01-16T09:00:00Z"
    }
  ],
  "next_page_token": ""
}

In this example, the account received a 500.00 GBP transfer (positive, settled) and has a 500.00 GBP payout in progress (negative, reserved).

Filtering

You can filter balance lines by state, type, and time range:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_EMBEDDED_ACCOUNT/balance/lines:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "states": ["SETTLED"],
      "types": ["CHARGE", "TRANSFER"],
      "start_create_time": "2026-01-01T00:00:00Z",
      "end_create_time": "2026-02-01T00:00:00Z"
    },
    "page_size": 50
  }'

Pagination

When there are more results than page_size, the response includes a next_page_token. Pass it in the next request to retrieve the next page:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_EMBEDDED_ACCOUNT/balance/lines:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_size": 20,
    "page_token": "TOKEN_FROM_PREVIOUS_RESPONSE"
  }'

How funds arrive

For embedded accounts, funds typically arrive via transfers from the parent account. These settle immediately and appear as SETTLED balance lines with type TRANSFER.

Funds can also arrive via charge splits, where payment proceeds are allocated directly to child accounts. These appear as PENDING balance lines until settlement completes.

Webhooks

The following webhook events relate to balance changes:

See Flow Webhook Events for the full list and Webhooks for additional events including invoice events.