The List Payout Accounts endpoint in Payiano allows your company
to retrieve and monitor all existing payout accounts. This includes accounts associated
with vendors, employees, partners, or any third parties eligible for receiving payouts.
You can filter and paginate results, making it easy to track accounts across different
payout methods—such as bank transfers, mobile wallets, or InstaPay—and view their current
status or configuration. This endpoint is useful for financial teams to review account
data, manage compliance, and keep payout operations organized and auditable.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission payout.accounts.view
Request
Request body schema:
application/json
Query parameters:
page
page
Type: integer|null
Default: 1
The page number to be retrieved, for the list of payout accounts.
So, a combination of page=1 and per_page=25 returns the
first 25 payout accounts items. A combination of page=2 and
per_page=25 returns the next 25 payout accounts items.
per_page
per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]
The maximum number of payout accounts items to return in the response.
q
q
Type: array_of_strings|null
Min: 3
This parameter enables free-text search across key payout accounts fields
(including but not limited to name, reference_id and description), 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 payout accounts items.
sort
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.
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
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.
includes
includes
Type: array_of_enums|null
Possible values:
["account.recipient"]
A list of additional payout accounts relations to return, if available. Feel free
to send the relations you would like to return with every item. See Including Resources to better understand how this is working.
Response
200
Response schema:
application/json
Response body:
total_pages
total_pages
Type: integer
The total number of pages that are available for the payout accounts
search criteria.
current_page
current_page
Type: integer
The current pagination page.
per_page
per_page
Type: integer
The amount of payout accounts items return per page.
total_items
total_items
Type: integer
The total number of payout accounts that match the search criteria.
items
items
Type: array_of_objects
The list of payout accounts that match the search criteria.
id
id
Type: ulid
Length: 26
The unique ID assigned to each payout account 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 payout account. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout account in our database.
name
name
Type: string
Min: 1
Max: 100
A unique and descriptive name for the payout account. This name helps identify the account in your
system, especially when managing multiple payout recipients such as vendors, employees, or partners.
For example, you might use 'Vendor Main Bank Account' or 'Employee Payroll Wallet'.
Please note that duplicate values are not allowed. Only alpha-numeric
characters, dashes, underscores, and spaces are allowed: [A-Za-z0-9-_ ].
is_active
is_active
Type: boolean
Default: true
This value indicates whether the payout account is active or not. This flag can be used
to control the payout account's availability in runtime environments or listings without
deleting or removing the payout account from records. A true value means the payout account
is active and functioning, while a false value implies that the payout account is
deactivated or not in use.
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each payout account. It's
primary role is to distinguish one payout account from another, ensuring
that each payout account can be individually tracked and managed without
any confusion.
Please note that duplicate values are not allowed. Only alpha-numeric
characters, dashes, and underscores are allowed: [A-Za-z0-9-_].
The reference_id
value is used to Identify Resource when you consume any payout account endpoint with sending identify_by
query parameter with value reference_id.
description
description
Type: string|null
Max: 1000
Optional text to describe the payout account in more detail. You can include information about
the account’s intended usage, payment method, or recipient. For example: “Used for monthly
vendor settlements via InstaPay” or “Payroll account for contract employees.”
This field helps teams understand the context or restrictions associated with the account.
recipient
recipient
Type: object
The payout recipient model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each payout recipient 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 payout recipient. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout recipient in our database.
type
type
Type: enum
Possible values:
["ach","ewallet","instapay"]
Specifies the payout recipient type. This determines how the destination is
configured (e.g., ACH, e-wallet, or InstaPay).
details
details
Type: object
This attribute is used to define the recipient’s payout destination based on
the selected payment method. Only one method (e.g., ACH, e-wallet, or InstaPay)
is allowed per request. This ensures accurate routing of the payout to the
intended destination.
ach
ach
Type: object
This attribute contains ACH (Automated Clearing House) configuration used to
define the recipient's local bank transfer details. This object is required
when the payout method is ACH.
country_code
country_code
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where the payout recipient is located. This code is part of the standard
international country codes set by the ISO .
ewallet
ewallet
Type: object
This attribute defines payout configuration for recipients using Meeza
compatible e-wallets such as Vodafone Cash, Etisalat Cash, and Orange
Money. Required when the payout method is set to e-wallet.
phone_number
phone_number
Type: string
The phone number registered to the recipient’s e-wallet account.
It must follow international format (e.g., +201000320310) and belong
to a supported provider like Vodafone, Etisalat, or Orange.
instapay
instapay
Type: object
Defines recipient details for payouts via InstaPay, using a registered mobile
number or InstaPay Payment Number (IPN) linked to a bank account in Egypt.
ipn
ipn
Type: string
The InstaPay Payment Number (IPN) of the recipient. This is typically a
registered mobile number or a virtual payment identifier used to receive
funds through the InstaPay network in Egypt.
created_at
created_at
Type: datetime
The created datetime of the payout recipient.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the payout recipient.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
is_deleted
is_deleted
Type: boolean
Default: false
This value indicates whether the payout account is deleted or not. This flag can be used to
control the payout account's availability in runtime without actual deleting or removing the
payout account from records. A true value means the payout account is deleted, while a false
value implies that the payout account is not deleted and functioning.
created_at
created_at
Type: datetime
The created datetime of the payout account.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the payout account.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
deleted_at
deleted_at
Type: datetime|null
The deleted datetime of the payout account.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
Response sample:
1{2"per_page": 25,3"total_pages": 1,4"total_items": 1,5"current_page": 1,6"items": [7{8"id": "01jzkbcqdk1pasnm9hxmwf4wjh",9"name": "Vendor Main Bank Account",10"is_active": true,11"reference_id": "7c0e6b41-00db-374e-9d0f-541109ea5d45",12"description": "Primary bank account for weekly vendor payments via ACH.",13"recipient": {14"id": "01jzpk5q40pwfjx56mskdecs70",15"type": "ach",16"details": {17"ach": {18"country_code": "EG"19},20"ewallet": {21"phone_number": null22},23"instapay": {24"ipn": null25}26},27"created_at": "1752031747985",28"updated_at": "1752031747985"29},30"is_deleted": false,31"created_at": "1751922385803",32"updated_at": "1751922385803",33"deleted_at": null34}35]36}