List balances

API contract v1.0.0

On this page

listBalances

GET/v1/balances

Required scopesfinance:read

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

Returns the merchant's balance buckets by currency, one entry per currency. The result is returned all at once with no pagination: has_more is always false and next_cursor is null. Never add amounts in different currencies to get a "total balance". net_position is for display only and can't replace available when you determine the settleable amount.

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

Name	Type	Required	Description
`currency`	string	No	Return only the specified currency. Constraints: `Format ^[A-Z]{3}$` Example: `USD`

currency

string

Return only the specified currency.

Constraints: Format ^[A-Z]{3}$

Example: USD

Request example

curl

curl -X GET 'https://api.fluxan.co/v1/balances?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

Balances for each currency.

One entry per currency; amounts in different currencies must not be added together

{
  "data": [
    {
      "currency": "USD",
      "pending": 125000,
      "available": 482050,
      "reserve": 50000,
      "risk_hold": 0,
      "refund_pending": 3500,
      "payout_pending": 200000,
      "merchant_receivable": 0,
      "book_payable": 860550,
      "net_position": 860550
    },
    {
      "currency": "JPY",
      "pending": 300000,
      "available": 1250000,
      "reserve": 100000,
      "risk_hold": 0,
      "refund_pending": 0,
      "payout_pending": 0,
      "merchant_receivable": 0,
      "book_payable": 1650000,
      "net_position": 1650000
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_demo_030"
}

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<Balance>	Required
`currency`	string	Required	Currency. Constraints: `Format ^[A-Z]{3}$` Example: `USD`
`pending`	integer(int64)	Required	Pending settlement: the net amount from payments that succeeded but haven't yet met all the conditions for funds receipt, settlement period or reconciliation; it can't be paid out. Constraints: `≥ 0` Example: `9650`
`available`	integer(int64)	Required	Settleable: the amount that meets the release conditions and isn't reserved; the only bucket that can be used for payouts. Constraints: `≥ 0` Example: `8650`
`reserve`	integer(int64)	Required	Reserve: the amount held back under the rules and waiting to be released. Constraints: `≥ 0` Example: `1000`
`risk_hold`	integer(int64)	Required	Risk hold: the held amount tied to a specific risk action or dispute. Constraints: `≥ 0` Example: `0`
`refund_pending`	integer(int64)	Required	Reserved for refunds: the amount reserved by refunds that are under review or processing. Constraints: `≥ 0` Example: `0`
`payout_pending`	integer(int64)	Required	Reserved for payouts: the amount reserved by an active settlement whose payout isn't confirmed as complete yet. Constraints: `≥ 0` Example: `0`
`merchant_receivable`	integer(int64)	Required	Pending recovery: a receivable the platform holds against the merchant, created by an actual forced debit and similar cases; it isn't part of the merchant's available funds. Constraints: `≥ 0` Example: `0`
`book_payable`	integer(int64)	Required	The merchant's book payable balance = pending + available + reserve + risk_hold + refund_pending + payout_pending. Constraints: `≥ 0` Example: `19300`
`net_position`	integer(int64)	Required	The merchant's net position (for display only) = book_payable - merchant_receivable. It can be negative and can't replace available. Example: `19300`
`has_more`	boolean	Required	Always false. Example: `false`
`next_cursor`	stringNullable	Required	Always null. Example: `null`
`request_id`	string	Required	Unique identifier of this request. Example: `req_demo_004`

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

One entry per currency, returned all at once with no pagination (has_more is always false).
Only available can be used for payouts. net_position is for display only, can be negative, and can't replace available.

Warning

Never add balances in different currencies.

Error codes and HTTP status

Was this page helpful?