Balance changes

Balance changes report the ledger movement behind any flow, whichever payment business caused it. Read Events overview first for the envelope, deduplication, and the rules that apply to every event.

Events on this page

Event	What it notifies you of	Type
`payment.account.balance.updated`	One account’s available balance moved for one token, and what caused it. This is the only event that reports what each account actually received.	Standard

`payment.account.balance.updated`

Fires when the available balance of a Payments account changes for a specific token. It is also how you see what each account actually received. An order’s credited_amount, for example, includes the portion split out as your developer fee, so it is not the merchant’s credited amount. One order settlement produces one balance event per account involved.

Event content

Field	Type	Description
`data_type`	`string`	Always `PaymentAccountBalanceUpdate`.
`source_account`	`string`	Which account moved. For a merchant account this is the merchant ID; for the developer account it is `developer`.
`source_id`	`string`	The ID of the business record that caused the change: the order ID, refund ID, payout ID, bulk send item ID, or, for top-ups and unexpected deposits, the transaction ID.
`source_type`	`string`	What caused the change: • `OrderIn` — an order payment (including late payments after the order reached a final status). • `TopUp` — a top-up. • `UnexceptedIn` — an unexpected deposit. • `RefundOut` — a refund. • `Payout` — a payout. • `UnexceptedOut` — an unexpected outgoing payment. • `Allocation` — an allocation. • `BulkSend` — a bulk send. • `SettlementNetwork` — the settlement network. • `OnrampIn` — a fiat on-ramp deposit.
`token_id`	`string`	The token whose balance changed.
`amount`	`string`	The change, truncated to two decimal places.
`amount_raw`	`string`	The same change, in the token’s own precision, without padded zeros (for example `100`, `0.123456`).
`balance_before`	`string`	The balance before the change, truncated to two decimal places.
`balance_before_raw`	`string`	The balance before the change, in the token’s own precision.
`balance_after`	`string`	The balance after the change, truncated to two decimal places.
`balance_after_raw`	`string`	The balance after the change, in the token’s own precision.
`flow_direction`	`string`	The direction of the change: • `in` — funds flow into the account. • `out` — funds flow out of the account.
`update_time`	`integer`	When the balance was updated, in Unix timestamp (seconds).

Sample events

Each sample shows the data object only. The envelope around it is the same for every event — see Event structure.

An order credits the merchant and the developer

One order settlement produces one event per account. The two together add up to the order’s credited_amount.

{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "M1001",
  "source_id": "order_001",
  "source_type": "OrderIn",
  "token_id": "ETH_USDC",
  "amount": "100.00",
  "amount_raw": "100",
  "balance_before": "1250.00",
  "balance_before_raw": "1250",
  "balance_after": "1350.00",
  "balance_after_raw": "1350",
  "flow_direction": "in",
  "update_time": 1744690100
}

{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "developer",
  "source_id": "order_001",
  "source_type": "OrderIn",
  "token_id": "ETH_USDC",
  "amount": "2.00",
  "amount_raw": "2",
  "balance_before": "830.00",
  "balance_before_raw": "830",
  "balance_after": "832.00",
  "balance_after_raw": "832",
  "flow_direction": "in",
  "update_time": 1744690100
}

A payout leaves the developer account

flow_direction is out and source_id is the payout ID.

{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "developer",
  "source_id": "payout_001",
  "source_type": "Payout",
  "token_id": "ETH_USDC",
  "amount": "500.00",
  "amount_raw": "500",
  "balance_before": "832.00",
  "balance_before_raw": "832",
  "balance_after": "332.00",
  "balance_after_raw": "332",
  "flow_direction": "out",
  "update_time": 1744700600
}

Keeping your own balances current

Webhook messages do not carry real-time balances, so that the values you read cannot be stale relative to concurrent activity.

To update balances as events arrive: call List merchant balances or Get developer balances when a webhook lands.
To reconcile fees: use the transaction query endpoints or Generate reports.
To avoid running out of gas: poll List Fee Station token balance and alert on your own consumption rate. Several failure codes across payouts, refunds, and bulk sends trace back to an empty Fee Station.

Overview

Initial Setup

Pay-In

Funds Management

Reference

Events on this page

`payment.account.balance.updated`

Event content

Sample events

An order credits the merchant and the developer

A payout leaves the developer account

Keeping your own balances current

​Events on this page

​payment.account.balance.updated

​Event content

​Sample events

​An order credits the merchant and the developer

​A payout leaves the developer account

​Keeping your own balances current

Events on this page

`payment.account.balance.updated`

Event content

Sample events

An order credits the merchant and the developer

A payout leaves the developer account

Keeping your own balances current