Custodial Balances

BETA: This endpoint is subject to change without notice.

Standalone accounts that process card payments have a custodial bank account — a bank account held by you that Synapto has API access to. The custodial bank account is set up during onboarding, and you are provided the account details (e.g. sort code and account number) so that you can send and receive bank transfers.

The custodial balance endpoint shows the account's own share of funds in the bank account — it excludes any funds that have been transferred to child accounts. It also includes an additional suspense position for unreconciled bank transactions.

For embedded account balances, see Balances.

Retrieving a custodial balance

API reference

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

Response

{
  "available": [
    { "currency": "GBP", "amount": "500000" }
  ],
  "pending": [
    { "currency": "GBP", "amount": "150000" }
  ],
  "reserved": [],
  "suspense": [
    { "currency": "GBP", "amount": "75000" }
  ]
}

Positions

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

The first three positions work the same way as for embedded account balances. The suspense position is unique to custodial balances.

Settlement

When a charge (payment intent) succeeds, the funds are not immediately available. Here is the full lifecycle:

The payment intent and charge states do not change at settlement — they remain SUCCEEDED from the moment the payment is confirmed. Settlement is tracked entirely through balance line states.

Use the payment_intent.settled webhook event to be notified when funds become available. See Flow Webhook Events for details.

Refunds

Refunds follow a similar pattern. When a refund succeeds, a RESERVED balance line (with type REFUND) is created on your account and the available balance is reduced immediately. The refund balance line moves from RESERVED to SETTLED when the funds settle.

As with charges, the refund's own state (SUCCEEDED) does not change at settlement. Use the refund.settled webhook event to be notified when refund settlement completes.

Suspense

When a transaction occurs on the custodial bank account that cannot be automatically matched to a known operation, it appears in the suspense position. Funds remain in suspense until they are reconciled — matched to a specific purpose via the Dashboard.

A positive suspense amount represents incoming funds that have not yet been allocated. A negative amount represents an unreconciled outgoing transaction. Suspense funds are not included in the available balance until they are reconciled.

Why funds end up in suspense

There are several reasons transactions may appear in suspense:

Incoming:

• Card settlement — when a card acquirer settles a batch of charges, the net settlement amount arrives as a bank deposit. This is normally reconciled automatically, but may require manual intervention if the settlement data is incomplete or inconsistent.
• Funding your balance — if you want to maintain a float (e.g. to transfer funds to embedded accounts ahead of receiving card settlement), you can send a bank transfer to the custodial bank account. The deposit appears in suspense and can be allocated to your available balance.
• Invoice payment by bank transfer — if your customers pay invoices via bank transfer rather than card, those deposits arrive at the custodial bank account and appear in suspense. They can then be allocated to the corresponding open invoices.

Outgoing bank transactions that cannot be matched to a known operation (e.g. a payout) also appear in suspense as a negative amount.

How suspense is resolved

Suspense items are managed in the Dashboard under the Suspense tab. From there, you can:

• Allocate to an account — move the full suspense amount to an account's available balance (e.g. when funding your balance)
• Reconcile with a remittance — match a settlement deposit against individual charges using an acquirer remittance file
• Allocate to invoices — apply an incoming bank transfer to one or more open invoices, marking them as paid

Once reconciled, the funds move out of suspense and into the appropriate balance positions.

Monitoring suspense via API

The public API provides the aggregate suspense amount via GetCustodialBalance. Individual suspense items are not available through the API — they are managed exclusively through the Dashboard.

To be notified when funds settle, listen for the payment_intent.settled webhook event. See Flow Webhook Events for details.

When to use which balance endpoint

Calling the wrong endpoint for your account type returns an error. Both types use the same ListBalanceLines endpoint to view individual transactions.