List Transaction Events

The List Payout Transaction Events endpoint on Payiano returns a detailed, chronological log of all lifecycle events associated with a specific payout transaction. Each event represents a distinct stage in the payout process.

Events follow Payiano’s standardized payout lifecycle, including:

  • initiated – transaction has been created and registered
  • validating – verification and compliance checks are in progress
  • funds_processing – funds are being processed or transferred
  • receiver_settled – receiving account has been credited
  • success – payout completed successfully
  • failed – payout could not be processed

This endpoint is essential for:

  • monitoring the real-time progress of payouts
  • diagnosing delays, failures, or processor issues
  • building financial audit reports with full traceability
  • supporting internal dashboards or automated alerting systems

All results can be filtered, paginated, and sorted for efficient navigation across high-volume payout activity. Use this API to maintain transparent, audit-ready visibility over every step of the payout lifecycle.

GET/payout/transactions/{transaction_id}/events
Sandbox: https://api.payiano.dev/v1/payout/transactions/{transaction_id}/events
Live: https://api.payiano.com/v1/payout/transactions/{transaction_id}/events
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.transactions.view
Request
Request body schema:
application/json
Path parameters:
transaction_id
required
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.

Query parameters:
page
Type: integer|null
Default: 1

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

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

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

q
Type: array_of_strings|null
Min: 3

This parameter enables free-text search across key payout transaction events fields (including but not limited to name), 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 transaction events 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:
[ "completed_at", "created_at", "id", "name", "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.

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:
[ "completed_at", "created_at", "id", "name", "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:
[ "completed_at", "created_at", "name", "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 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
Type: integer

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

current_page
Type: integer

The current pagination page.

per_page
Type: integer

The amount of payout transaction events items return per page.

total_items
Type: integer

The total number of payout transaction events that match the search criteria.

items
Type: array_of_objects

The list of payout transaction events that match the search criteria.

id
Type: ulid
Length: 26

The unique ID assigned to each payout transaction event 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 event. This ULID is automatically created by our system and is used to uniquely identify and track each payout transaction event in our database.

name
Type: enum
Possible values:
[ "initiated", "validating", "funds_processing", "receiver_settled", "failed", "success" ]

Identifies the type of lifecycle event recorded for the payout transaction. Each event represents a specific step or state change that occurred during the transaction’s processing.

completed_at
Type: datetime|null

The timestamp indicating when this payout transaction event was completed. This value remains null until the event has finished processing. 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
Type: datetime

The created datetime of the payout transaction event. 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 transaction event. 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": "01ka22zz6a9s0rs3dffj1p5868", 9 "name": "validating", 10 "completed_at": null, 11 "created_at": "1763154328778", 12 "updated_at": "1763154328778" 13 } 14 ] 15}