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: array_of_strings|null
Min: 3

This parameter enables free-text search across key payment link fields (including but not limited to title, 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 payment link 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", "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", "reference_id", "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
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.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: 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", "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
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", "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 .