The List Payout Transactions endpoint on
Payiano allows companies to fetch a
complete record of all payout transactions covering vendors,
partners, service providers, and employees. Each record includes
transaction details, amounts, status, and timestamps for clear
financial visibility.
Results can be filtered, sorted, and paginated to simplify navigation
across large datasets. This endpoint supports multiple payout methods,
such as bank transfers, mobile wallets,
and InstaPay, helping finance teams monitor outgoing
payments efficiently and maintain audit-ready records.
Use this API to gain real-time insight into your company’s payout
activity, track payment progress, and ensure transparency across
all disbursement workflows.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission payout.transactions.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 transactions.
So, a combination of page=1 and per_page=25 returns the
first 25 payout transactions items. A combination of page=2 and
per_page=25 returns the next 25 payout transactions items.
per_page
per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]
The maximum number of payout transactions items to return in the response.
q
q
Type: array_of_strings|null
Min: 3
This parameter enables free-text search across key payout transactions fields
(including but not limited to reference_id, status and source_type), 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 transactions 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.
filters
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.
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
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
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.
This attribute specifies the name of the field to be aggregated.
metrics
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
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.
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 completed_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
total_pages
Type: integer
The total number of pages that are available for the payout transactions
search criteria.
current_page
current_page
Type: integer
The current pagination page.
per_page
per_page
Type: integer
The amount of payout transactions items return per page.
total_items
total_items
Type: integer
The total number of payout transactions that match the search criteria.
items
items
Type: array_of_objects
The list of payout transactions that match the search criteria.
id
id
Type: ulid
Length: 26
The unique ID assigned to each payout transaction 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 transaction. This ULID is
automatically created by our system and is used to uniquely identify
and track each payout transaction in our database.
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each payout transaction. It's
primary role is to distinguish one payout transaction from another, ensuring
that each payout transaction 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 transaction endpoint with sending identify_by
query parameter with value reference_id.
Including it in every payout request helps ensure idempotency and prevents accidental duplicate processing. It’s highly recommended to always include this parameter when initiating a payout.
status
status
Type: enum
Possible values:
["pending","failed","success"]
This attribute indicates the current status of the payout transaction.
receiver_amount
receiver_amount
Type: object
Contains detailed information about the amount received by the payout
beneficiary. Similar to sender_amount, it breaks down the base amount,
any fees, total amount, and currency code.
base_amount
base_amount
Type: decimal
The payout amount before any receiving-side fees or deductions.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
fee_amount
fee_amount
Type: decimal
The fee amount charged on the receiving end, if applicable.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
total_amount
total_amount
Type: decimal
The final amount credited to the receiver after all deductions.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
currency_code
currency_code
Type: enum
Possible values:
["EGP"]
The three-character ISO-4217 Currency Code that identifies the currency for the payout transaction receiver amount. Your business
should be eligible to use the selected currency code.
sender_amount
sender_amount
Type: object
Contains detailed information about the amount sent by the company
during payout. It includes the base transaction amount, applicable
fees, total amount, and the currency code.
base_amount
base_amount
Type: decimal
The base payout amount before any fees are applied.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
fee_amount
fee_amount
Type: decimal
The total fee applied to the transaction, if any.
The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
total_amount
total_amount
Type: decimal
The total amount after fees, representing the actual payout deducted
from the sender’s balance. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
currency_code
currency_code
Type: enum
Possible values:
["EGP"]
The three-character ISO-4217 Currency Code that identifies the currency for the payout transaction sender amount. Your business
should be eligible to use the selected currency code.
source_type
source_type
Type: enum
Possible values:
["balance"]
This attribute indicates the source type of the payout transaction.
source_details
source_details
Type: object
Provides information about the source of funds for the payout transaction,
including details of the originating balance or account.
balance
balance
Type: object
The payment balance used as the source of funds for this payout transaction.
It identifies which company balance or wallet the payout was debited from.
id
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
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.
receiver_type
receiver_type
Type: enum
Possible values:
["recipient"]
This attribute indicates the receiver type of the payout transaction.
receiver_details
receiver_details
Type: object
Contains information about the payout recipient, including the destination
account and related configuration details used to process the transaction.
recipient
recipient
Type: object
Describes the recipient details associated with an existing payout
transaction, including the configured payment method and destination
information.
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
Describes the recipient details associated with an existing payout
transaction, including the configured payment method and destination
information.
ach
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
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
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
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
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
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
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
number
Type: string
Max: 34
The full IBAN number. Example: EG380019000500000000263180002
account_number
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
number
Type: string
Min: 4
Max: 30
The local bank account number. Example: 263180002
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.
holder_name
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
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.
completed_at
completed_at
Type: datetime|null
Indicates the timestamp when the payout transaction was successfully completed
and finalized. This field is null until the transaction reaches a terminal
state such as failed or success.
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.
created_at
created_at
Type: datetime
The created datetime of the payout transaction.
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 transaction.
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.