You should login first to your account to test the APIs with.

List Transaction Events

The List Payout Transaction Events endpoint on Payiano returns a detailed, chronological history of all lifecycle events for a specific payout transaction. Each event represents a distinct stage in the payout flow, from initiation through final settlement or failure.

This endpoint is essential for:

  • Real-time monitoring: Track the current stage and progress of any payout transaction with precise timing information
  • Debugging and diagnostics: Examine event details to understand exactly why a payout failed or encountered issues
  • Audit and compliance: Maintain complete, timestamped records of every action in the payout lifecycle, including specific details for each event
  • Dashboard integration: Power user interfaces with detailed transaction progress indicators and contextual event information
  • Simulation verification: After using the simulation endpoint, verify that events were processed correctly and inspect their details
  • Webhook correlation: Match incoming webhook notifications with specific events and their detailed data
Relationship with Transaction Status and Current Event

Understanding how transaction events relate to other transaction fields:

  • Complete timeline vs current event: While the transaction's current_event field shows only the latest event, this endpoint provides the complete historical timeline of all events with their full details
  • Status correlation: Transaction status updates to success or failed only when the corresponding final event (success or failed) is completed. The details field in failed events contains specific error information
  • Event sequencing rules: Events follow a strict order: initiating → validating → processing → settling → success/failed. This endpoint always returns events in this chronological sequence
Common Use Cases
  • Customer support: Show users exactly where their payout is in the process and provide specific details about any issues from the details field
  • Operations monitoring: Create dashboards showing transaction volumes at each stage of the payout lifecycle with detailed event data
  • Quality assurance: Measure processing times for each event stage and analyze details to identify bottlenecks or common issues
  • Integration testing: After simulating events, verify that the event timeline matches expected behavior and inspect the generated details
  • Dispute resolution: Provide detailed evidence from event details of when each action occurred and what specific information was processed
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", "started_at", "transaction_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.

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", "started_at", "transaction_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:
[ "completed_at", "created_at", "name", "started_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 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:
[ "initiating", "validating", "processing", "settling", "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.

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

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.

started_at
Type: datetime

The timestamp indicating when this payout transaction event was started. 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.

details
Type: object|null

An optional object with extra information about the payout transaction event. It can contain only one key, and the key and its value depend on the event type.

failed
Type: object

An object providing details about the failure if the transaction event represents a failed state. This object includes information such as reason, error codes, messages, and any relevant data to help diagnose the issue.

reason
Type: enum
Possible values:
[ "invalid_bank_code", "invalid_currency_code", "rejected_by_beneficiary", "regulatory_reason", "closed_account", "frozen_or_blocked_account", "invalid_account_details", "insufficient_fund", "customer_deceased", "unknown" ]

A code indicating the specific reason for the failure of the payout transaction event. This helps in identifying the cause of the failure for troubleshooting and resolution.

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 "transaction_id": "01kaygedpfd02dm9cny5ds6ppe", 11 "completed_at": null, 12 "started_at": "1763154328752", 13 "details": null, 14 "created_at": "1763154328778", 15 "updated_at": "1763154328778" 16 } 17 ] 18}