List balance transactions

API contract v1.0.0

On this page

listBalanceTransactions

GET/v1/balance-transactions

Required scopesfinance:read

The Developer role can't grant finance:read by default. Use a key created by an Owner or Admin.

Retrieves masked balance transactions. Each balance transaction is one increase or decrease in a balance bucket: amount is a signed integer, where a positive value increases the bucket and a negative value decreases it. A transfer between buckets appears as two balance transactions under the same ledger_transaction_id, one decrease and one increase. Each one carries both the time the business event occurred (occurred_at) and the time it was posted (booked_at). booked_at serves as the creation time: results are ordered by booked_at descending, with ties broken by id descending, and created_gte and created_lt apply to booked_at. A late-arriving fact appears at the time it was actually posted, and past balance transactions aren't rewritten.

Request headers

Request headers	Required	Format	Description
Authorization	Yes	Bearer <API_KEY>	Server-side key, to be used only on the merchant's server. The merchant and environment are derived from the key. A missing, invalid, revoked or expired key returns 401.

Query parameters

Name	Type	Required	Description
`currency`	string	No	Filter by currency. Constraints: `Format ^[A-Z]{3}$` Example: `USD`
`bucket`	string	No	Filter by balance bucket. `pending` `available` `reserve` `risk_hold` `refund_pending` `payout_pending` `merchant_receivable` More values may be added in the future. Don't treat a status you don't recognize as success. Example: `available`
`source_type`	string	No	Filter by source business type, for example payment, refund, dispute or settlement. Constraints: `Length 1–64` Example: `payment`
`source_id`	string	No	Filter by source business object ID. Constraints: `Length 1–64` Example: `pay_demo_001`
`limit`	integer	No	Number of items per page. The default is 20 and the maximum is 100. Constraints: `1–100Default 20`
`cursor`	string	No	The next_cursor from the previous page's response. An opaque string: don't parse it or build one yourself. Send the same filters as for the first page. Constraints: `Length 1–512`
`created_gte`	string(date-time)	No	Lower bound of the creation time (inclusive), as ISO 8601 with a time zone. Example: `2026-09-23T00:00:00Z`
`created_lt`	string(date-time)	No	Upper bound of the creation time (exclusive), as ISO 8601 with a time zone. Example: `2026-09-24T00:00:00Z`

Request example

curl

curl -X GET 'https://api.fluxan.co/v1/balance-transactions?limit=20' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

Placeholders to replace

<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal

Note

Server API keys must only be used on your own server, so the docs site doesn't offer interactive API testing. Get a test key: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)

Responses

The balance transaction list.

A transfer between buckets: two balance transactions under the same ledger_transaction_id, one decrease and one increase

{
  "data": [
    {
      "id": "btx_demo_002",
      "type": "funds_released",
      "source_type": "payment",
      "source_id": "pay_demo_001",
      "bucket": "available",
      "amount": 9650,
      "currency": "USD",
      "occurred_at": "2026-09-25T00:00:00Z",
      "booked_at": "2026-09-25T00:00:02Z",
      "ledger_transaction_id": "ltx_demo_001"
    },
    {
      "id": "btx_demo_001",
      "type": "funds_released",
      "source_type": "payment",
      "source_id": "pay_demo_001",
      "bucket": "pending",
      "amount": -9650,
      "currency": "USD",
      "occurred_at": "2026-09-25T00:00:00Z",
      "booked_at": "2026-09-25T00:00:02Z",
      "ledger_transaction_id": "ltx_demo_001"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_demo_031"
}

Response fields

Paginated list: data is an array of objects. When has_more is true, use next_cursor to fetch the next page. See the object section for field descriptions.

Name	Type	Required	Description
`data`	array<BalanceTransaction>	Required
`id`	string	Required	Balance transaction ID. Example: `btx_demo_001`
`type`	string	Required	Posting type, for example payment_captured (payment captured), refund_reserved (reserved for refunds), settlement_reserved (reserved for settlement) or funds_released (funds released). Tolerate new values. Example: `payment_captured`
`source_type`	string	Required	Source business object type, for example payment, refund, dispute, settlement, payout, payout_return (payout return) or adjustment. Example: `payment`
`source_id`	string	Required	Source business object ID. Example: `pay_demo_001`
`bucket`	string	Required	Balance bucket: pending, available, reserve, risk_hold, refund_pending, payout_pending, merchant_receivable. `pending` `available` `reserve` `risk_hold` `refund_pending` `payout_pending` `merchant_receivable` More values may be added in the future. Don't treat a status you don't recognize as success. Example: `available`
`amount`	integer(int64)	Required	Signed amount, in the smallest currency unit: a positive value increases the balance bucket and a negative value decreases it. Example: `9650`
`currency`	string	Required	Currency. Constraints: `Format ^[A-Z]{3}$` Example: `USD`
`occurred_at`	string(date-time)	Required	The time the business event occurred. Example: `2026-09-23T09:05:00Z`
`booked_at`	string(date-time)	Required	Posting time. A late-arriving fact is never made to look as if it arrived on time. Example: `2026-09-23T09:05:01Z`
`ledger_transaction_id`	string	Required	The related ledger transaction ID. The two balance transactions of a transfer between buckets share the same ID. Example: `ltx_demo_001`
`has_more`	boolean	Required	Whether there is a next page. Example: `false`
`next_cursor`	stringNullable	Required	The cursor for the next page; null when there is no next page. Example: `null`
`request_id`	string	Required	Unique identifier of this request. Example: `req_demo_005`

Possible error codes

HTTP	Error code	When it occurs	How to handle
400	invalid_request	`Idempotency-Key` is missing; the order ID contains invalid characters; `payment_method_data` and `payment_method_id` are submitted together; `confirm=false` carries card details; `confirm=true` has no `return_url`; a checkout session request sends both groups of identity parameters, or neither; a `browser_info` / `billing_details` field the provider requires is missing; the cursor, time format or `limit` is invalid	Fix the request according to `error.field` and resubmit it; don't charge again automatically
401	unauthenticatedCommon	No `Authorization` header was sent; the key was copied incompletely; the old key expired after a rotation; the key was revoked	Check your credentials: on the API Key page in the merchant portal, verify the key's status and environment
403	forbiddenCommon	Creating a refund with a read-only key; calling `getEvent` without the read scope for the event's business area; if the request's source IP isn't on the key's allowlist, the more specific `ip_not_allowed` is returned	Use a key that has the required scope; don't work around the restriction
429	rate_limitedCommon	A rate limit per merchant and per key; switching keys doesn't get around the merchant's overall limit	Wait for `Retry-After` seconds, then retry with the original idempotency key
500	internal_errorCommon	—	Retry with the original idempotency key, or query by merchant order ID / refund ID; never charge again with a new key
502 / 503	upstream_unavailableCommon	A provider or platform dependency failed, and the platform can't confirm whether this request took effect	Same as above

Notes

amount is signed: a positive value increases the balance bucket and a negative value decreases it. A transfer between buckets is two balance transactions under the same ledger_transaction_id, one decrease and one increase.
Each balance transaction carries both occurred_at (when the event occurred) and booked_at (when it was posted). created_gte and created_lt apply to booked_at.
A late-arriving fact appears at the time it was actually posted, and past balance transactions aren't rewritten.

Error codes and HTTP status

Was this page helpful?