Overview of Available Balances

The balances or available funds refer to the amount of money that is ready for transfer, withdrawn or payout through Payiano's automated processes or explicitly through the Transfers API, Utilities API or Payouts API. These funds are immediately accessible for various financial transactions.

Real-Time Fund Availability

To provide a breakdown of the available balance, Payiano organizes it by currency. This means that you can see how much money is available for each specific currency. This information is crucial for businesses and organizations to manage their finances effectively, as it allows them to track and access funds that are ready for use or disbursement, facilitating seamless financial operations.

  • Instant Access: Funds reflected in the balances are immediately accessible for transfers, withdrawals, or payouts.
  • Real-Time Updates: The balance information is updated in real time, ensuring accuracy and immediacy.
  • Currency Categorization: Balances are organized by currency, facilitating easy management of multi-currency funds.
GET/payment/balances
Sandbox: https://api.payiano.dev/v1/payment/balances
Live: https://api.payiano.com/v1/payment/balances
Security
  • Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
  • Your access token should be associated to this permission balances_view
Request
Request body schema:
application/json
Query parameters:
page
Type: integer|null
Default: 1

The page number to be retrieved, for the list of balances. So, a combination of page=1 and per_page=25 returns the first 25 balances items. A combination of page=2 and per_page=25 returns the next 25 balances items.

per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]

The maximum number of balances items to return in the response.

q
Type: array_of_strings|null
Min: 3

This parameter enables free-text search across key balances fields (including but not limited to currency_code), requiring a minimum of 3 characters per search term. It performs case-insensitive partial matching, and returns relevance-ranked results while automatically handling special characters. This provides a simple yet powerful way to quickly find relevant balances items.

sort
Type: array_of_objects|null

Control the ordering of results with sophisticated multi-column sorting. Specify an array of objects, each containing a field and direction. Maximum 5 sort fields per request to maintain optimal performance.

field
Type: enum
Possible values:
[ "available_amount", "currency_code", "id", "pending_amount" ]

This attribute specifies the field used for sorting. It can be a direct attribute of the resource or a related field referenced using dot notation.

direction
Type: enum
Possible values:
[ "asc", "desc" ]

This attribute specifies the sorting direction. It can be either asc for ascending order or desc for descending order. Please note that the value is case-sensitive.

Response
200
Response schema:
application/json
Response body:
total_pages
Type: integer

The total number of pages that are available for the balances search criteria.

current_page
Type: integer

The current pagination page.

per_page
Type: integer

The amount of balances items return per page.

total_items
Type: integer

The total number of balances that match the search criteria.

items
Type: array_of_objects

The list of balances that match the search criteria.

id
Type: ulid
Length: 26

The unique ID assigned to each balance which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every balance. This ULID is automatically created by our system and is used to uniquely identify and track each balance in our database.

currency_code
Type: enum
Possible values:
[ "EGP" ]

The three-character ISO-4217 Currency Code that identifies the currency for the balance. Your business should be eligible to use the selected currency code.

available_amount
Type: decimal

The available amount value to be withdrawn. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

pending_amount
Type: decimal

The pending amount value to be collected. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

Response sample:
1
{ 2 "per_page": 25, 3 "total_pages": 1, 4 "total_items": 1, 5 "current_page": 1, 6
 "items": [ 7
 { 8 "id": "01hqh45s7826hfwdze8dp1z21f", 9 "currency_code": "EGP", 10 "available_amount": 1000, 11 "pending_amount": 550 12 } 13 ] 14}