Standardized Listing Overview

Payiano's API defines a unified standard for retrieving resource collections through list endpoints. This approach ensures consistent data access across all core business entities such as: Payment Links , Customers , and Checkouts .

This unified listing pattern minimizes redundancy, improves query performance, and keeps integrations consistent across all Payiano APIs — from analytics dashboards to merchant integrations.

Unified Design Principles

  • Unified Interface: All list endpoints share the same parameter naming, response format, and structure, reducing the learning curve and promoting consistent integrations.
  • Cross-Resource Consistency: Apply the same integration patterns across different business domains while maintaining type safety and predictable behavior.
  • Optimized Developer Experience: The uniform design reduces boilerplate code and makes switching between resources seamless.

Key Listing Features

  • Full-text Search: Perform lightweight indexed searches using the q parameter across relevant fields.
  • Pagination: Control result size and offset using page and per_page parameters. This ensures efficient data retrieval and optimal API performance by loading only the required subset of results per request.
  • Filtering: Refine your results using flexible, structured conditions via the filters parameter. Filters allow you to narrow down collections based on field values, ranges, or nested relationships — making it easy to retrieve only the most relevant data for your use case. Learn more about filtering
    {     "node": "group", "logic": "and",
    "filters": [
    {     "node": "condition", "field": "payment_details.amount", "operator": "gte", "value": 2000 },
    {     "node": "condition", "field": "payment_details.status", "operator": "eq", "value": "paid" } ] }
  • Flexible Response Formats: Endpoints can return data in multiple formats ideal for both API integrations and reporting workflows. Using the response_type parameter, developers can choose between standard JSON results, aggregated analytics, or export-ready files (CSV, XLS, XLSX) all from the same endpoint. Learn more about response types
  • Resource Relationships: Enhance your API responses by including related resources using the includes parameter. This powerful feature allows you to fetch associated data in a single request, reducing the need for multiple API calls. Learn more about including resources
  • Optimized Sorting:

    The sort parameter supports multi-column sorting while maintaining query performance.

    Example: Sort payment links by title (A–Z), then by newest creation date, and finally by payment amount.
    • Maximum of 5 sort fields per request
    • Explicit direction control for each field
    • Nested field support (e.g., payment_details.amount)
    [
    {     "field": "title", "direction": "asc" },
    {     "field": "created_at", "direction": "desc" },
    {     "field": "payment_details.amount", "direction": "asc" } ]
    Note: If a request includes more than 5 sort fields, the system will automatically limit the sort array to the first 5 valid fields to ensure optimal performance and maintain query efficiency.
GET/payment/payment_links
Sandbox: https://api.payiano.dev/v1/payment/payment_links
Live: https://api.payiano.com/v1/payment/payment_links
Request
Request body schema:
application/json
Query parameters:
page
Type: integer|null
Default: 1

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

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

The maximum number of payment link items to return in the response.

q
Type: string|null
Min: 3

This parameter enables free-text search across key payment link fields (including but not limited to title 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 payment link 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", "customer_id", "description", "due_date", "expires_at", "id", "payment_details.amount", "payment_details.currency_code", "payment_details.is_completed", "payment_details.paid_amount", "payment_details.paid_at", "payment_details.remaining_amount", "payment_details.status", "payment_details.total_amount", "title", "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:
[ "payment_link.checkout", "payment_link.checkout.payer", "payment_link.checkout.payer.billing_address", "payment_link.checkout.payer.billing_address.country", "payment_link.checkout.payer.shipping_address", "payment_link.checkout.payer.shipping_address.country", "payment_link.customer", "payment_link.customer.billing_address", "payment_link.customer.billing_address.country", "payment_link.customer.metadata", "payment_link.customer.shipping_address", "payment_link.customer.shipping_address.country", "payment_link.customer.tags", "payment_link.customer.tags.metadata", "payment_link.metadata", "payment_link.payment_details" ]

A list of additional payment link 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", "title", "payment_details.currency_code", "payment_details.amount", "payment_details.total_amount", "payment_details.paid_amount", "payment_details.remaining_amount", "payment_details.status", "payment_details.is_completed", "payment_details.paid_at", "customer_id", "description", "due_date", "expires_at", "created_at", "updated_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", "customer_id", "due_date", "expires_at", "id", "payment_details.amount", "payment_details.currency_code", "payment_details.is_completed", "payment_details.paid_amount", "payment_details.paid_at", "payment_details.remaining_amount", "payment_details.status", "payment_details.total_amount", "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", "due_date", "expires_at", "payment_details.currency_code", "payment_details.is_completed", "payment_details.paid_at", "payment_details.status", "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 .