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

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: 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
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:
[ "created_at", "deleted_at", "description", "id", "is_active", "name", "recipient.created_at", "recipient.id", "recipient.type", "recipient.updated_at", "recipient_id", "reference_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
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: mixed|null

Apply complex filtering conditions using nested logical groups and comparison operators. Supports advanced querying with AND/OR logic, multiple operators, and hierarchical conditions. See Filtering Reference for complete documentation, operator list, 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
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
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
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
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
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 InstaPay” 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", "instapay" ]

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

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

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