List Payout Accounts

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 and mobile wallets—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.

GET/payout/accounts
Sandbox: https://api.payiano.dev/v1/payout/accounts
Live: https://api.payiano.com/v1/payout/accounts
Security
  • 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
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
Type: integer|null
Default: 25
Possible values: [1 ... 200]

The maximum number of payout accounts items to return in the response.

q
Type: string|null
Min: 3

This parameter enables free-text search across key payout accounts fields (including but not limited to name 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. It could accept an array_of_strings as well.

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
required
Type: enum
Possible values:
[ "created_at", "deleted_at", "description", "id", "is_active", "name", "recipient.created_at", "recipient.id", "recipient.type", "recipient.updated_at", "recipient_id", "updated_at" ]

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
required
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
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.

filters
Type: object|null
Apply complex filtering conditions using nested logical groups and comparison operators. Supports advanced querying with and/or logic, multiple operators, and hierarchical conditions.

The filtering system supports unlimited nesting depth , allowing you to build sophisticated query logic. Each group can contain a mix of conditions and other groups. See Filtering Reference for complete documentation, operator list, and examples.
node
required
Type: enum
Possible values:
[ "group" ]

Used exclusively as the root filter node. Specifies the type of the root filter node. At the root level, only a logical group node is supported. A group node acts as a container that combines one or more filter conditions or nested groups using AND/OR logic. Nested group and condition nodes may appear within this root group to build complex filtering structures.

logic
required
Type: enum
Possible values:
[ "and", "or" ]

This parameter is used exclusively on group nodes. Defines how filters within a filter group are logically combined. This parameter is used exclusively on group nodes and determines how the group evaluates its child filters or nested groups:

• and — all contained conditions must match
• or — at least one contained condition must match

Logical groups can be nested to construct complex filtering expressions with mixed AND/OR logic across multiple levels.

filters
required
Type: array_of_objects

This parameter is used exclusively on group nodes. Contains the filter nodes (conditions or groups) within this logical group. Groups can be nested to create complex hierarchical filtering logic.

node
Type: enum
Possible values:
[ "group", "condition" ]

Specifies the type of filter node. A filter node can be either a logical group or a condition:

• group — a logical grouping of multiple filters combined with AND/OR logic
• condition — a single filter condition specifying a field, operator, and value

Filter nodes can be nested to create complex filtering structures.

logic
Type: enum
Possible values:
[ "and", "or" ]

This parameter is used exclusively on group nodes. Defines how filters within a filter group are logically combined. This parameter is used exclusively on group nodes and determines how the group evaluates its child filters or nested groups:

• and — all contained conditions must match
• or — at least one contained condition must match

Logical groups can be nested to construct complex filtering expressions with mixed AND/OR logic across multiple levels.

filters
Type: array_of_objects

This parameter is used exclusively on group nodes. Contains the filter nodes (conditions or groups) within this logical group. Groups can be nested to create complex hierarchical filtering logic.

field
Type: enum
Possible values:
[ "id", "name", "is_active", "description", "recipient_id", "recipient.id", "recipient.type", "recipient.created_at", "recipient.updated_at", "created_at", "updated_at", "deleted_at" ]

This parameter is used exclusively on condition nodes. It specifies the field evaluated by the filter condition. The selected field determines which operators are available and the expected format of the comparison value based on its data type.

operator
Type: enum
Possible values:
[ "eq", "not_eq", "gt", "gte", "lt", "lte", "starts_with", "not_starts_with", "ends_with", "not_ends_with", "contains", "not_contains", "in", "not_in", "between", "not_between", "is_null", "is_not_null" ]

This parameter is used exclusively on condition nodes. It specifies the comparison operator applied to the selected field. The set of supported operators depends on the field and its data type, and only operators that are valid for the chosen field can be used. Available operators for each field are provided in the response and presented in the filter selection. Refer to the Filtering Reference for the complete operator list, expected value formats, and usage examples.

value
Type: mixed

This parameter is used exclusively on condition nodes. The value used by the selected operator to evaluate the field. The expected structure and data type of this parameter depend on both the field type and the operator:

• Scalar operators (eq, not_eq, gt, gte, lt, lte, starts_with, ends_with, contains, and their negations) expect a single value matching the field type (for example, string or number).

• List operators (in, not_in) expect an array of values compatible with the field type.

• Range operators (between, not_between) expect an array of exactly two values representing the inclusive lower and upper bounds.

• Null-check operators (is_null, is_not_null) do not accept a value and must be used without this parameter.

Supplying a value that does not match the operator or field type will result in a validation error in strict mode. See the Filtering Reference for supported operators, applicable field types, and examples.

response_type
Type: enum|null
Default: json_list
Possible values:
[ "json_list", "json_aggregate", "export_csv", "export_xls", "export_xlsx" ]

Specifies the output format of the datatable response, supporting both JSON and export file types for easy integration and reporting. Refer to Response Types for more details.

aggregations
Type: object|null

Defines how to aggregate and group data when response_type is set to json_aggregate. This parameter enables analytical style responses suitable for dashboards and reports. Refer to Aggregations for more details.

fields
required
Type: array_of_objects

Defines the fields to be aggregated along with their respective metrics. Maximum 5 aggregation fields per request to maintain optimal performance.

field
required
Type: enum
Possible values:
[ "created_at", "deleted_at", "id", "is_active", "recipient.created_at", "recipient.id", "recipient.type", "recipient.updated_at", "recipient_id", "updated_at" ]

This attribute specifies the name of the field to be aggregated.

metrics
required
Type: array_of_enums
Possible values:
[ "avg", "count", "sum" ]

Defines the aggregation metrics to apply to the selected field. Note that the avg and sum metrics are applicable only to numeric fields.

group_by
required
Type: array_of_objects|null
Specifies the dimensions used to group aggregated data results. Each object defines a field by which records will be grouped before applying aggregation metrics. Maximum 5 aggregation group by fields per request to maintain optimal performance.

Grouping enables developers to analyze data trends across categories, dates, or other meaningful dimensions.

If no group_by fields are provided, the system performs a global aggregation across the entire dataset. In such cases, the response includes a single summary group, typically referencing the latest created_at value.
field
required
Type: enum
Possible values:
[ "created_at", "deleted_at", "is_active", "recipient.created_at", "recipient.type", "recipient.updated_at", "updated_at" ]
Specifies the field name used for grouping results within the aggregation. This determines how records are organized and segmented when computing metrics.

When grouping by a datetime or timestamp field such as created_at , the system automatically groups by the date portion only , ignoring the time component. This enables daily-based aggregations instead of precise timestamp level grouping.

By default, grouping operations use the server's timezone ( UTC ). You can override this behavior by specifying the X-Preferred-Response-Timezone header in your request. Learn more about timezone handling in our Datetime & Timezone Reference .
Response
200
Response schema:
application/json
Response body:
total_pages
Type: integer

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

current_page
Type: integer

The current pagination page.

per_page
Type: integer

The amount of payout accounts items return per page.

total_items
Type: integer

The total number of payout accounts that match the search criteria.

items
Type: array_of_objects

The list of payout accounts that match the search criteria.

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
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
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
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
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 EWallet” or “Payroll account for contract employees.” This field helps teams understand the context or restrictions associated with the account.

recipient_id
Type: ulid

The unique identifier of the payout recipient. This value links the payout account to the correct recipient, ensuring funds are routed to the intended destination.

recipient
Type: object

The payout recipient model details.

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: enum
Possible values:
[ "ach", "ewallet" ]

Specifies the payout recipient type. This determines how the destination is configured (e.g., ACH or e-wallet).

details
Type: object

Describes the recipient details associated with an existing payout transaction, including the configured payment method and destination information.

ach
Type: object

This attribute defines the recipient's ACH (Automated Clearing House) bank account information used for local transfers. It is required when the payout method type is set to ach. The structure is country specific and must match the banking format of the recipient's country.

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 bank is located. This code is part of the standard international country codes set by the ISO .

bank_code
Type: string

A short code identifying the recipient's bank. This value must correspond to one of the supported bank codescodes for the selected country_code. For example, MISR for Banque Misr in Egypt or NBE for National Bank of Egypt. Bank codes are typically returned in uppercase and should be submitted as-is.

holder_name
Type: string
Min: 2
Max: 70

The full legal name of the bank account holder, exactly as registered with the bank. This name will be used for validation by banking partners and should match the account record.

number_type
Type: enum
Possible values:
[ "iban", "account_number" ]

Indicates the format of the bank account number — iban for international accounts ( e.g. Egypt, EU, KSA ) or account_number for local accounts in non-IBAN countries ( e.g. US, India ). This determines which field is required in number_details.

number_details
Type: object

Contains the bank account number details. The structure of this object changes dynamically based on the selected number_type. Only one key should exist, matching the number_type value, and each key contains the fields required for that specific account format.

iban
Type: object

Used when number_type is iban. Contains the IBAN number, a globally recognized format that includes the country code, bank identifier, and account number.

number
Type: string
Max: 34

The full IBAN number. Example: EG380019000500000000263180002

account_number
Type: object

Used when number_type is account_number. Contains the recipient's local bank account number. Common in countries where IBAN is not applicable or used as an alternative, such as Egypt, the United States, or India.

number
Type: string
Min: 4
Max: 30

The local bank account number. Example: 263180002

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
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.

holder_name
Type: string
Min: 2
Max: 70

The full name of the e-wallet account holder as registered with the e-wallet provider. This name is used to verify the recipient's identity and ensure accurate delivery of funds.

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
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
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
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
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
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_id": "01jzpk5q40pwfjx56mskdecs70", 14
 "recipient": { 15 "id": "01jzpk5q40pwfjx56mskdecs70", 16 "type": "ach", 17
 "details": { 18
 "ach": { 19 "country_code": "EG", 20 "bank_code": "MISR", 21 "holder_name": "Tarek Gamal", 22 "number_type": "iban", 23
 "number_details": { 24
 "iban": { 25 "number": "EG380019000500000000263180002" 26 } 27 } 28 } 29 }, 30 "created_at": "1752031747985", 31 "updated_at": "1752031747985" 32 }, 33 "is_deleted": false, 34 "created_at": "1751922385803", 35 "updated_at": "1751922385803", 36 "deleted_at": null 37 } 38 ] 39}