Overview

Filtering

Payonify supports filtering of list endpoints to help you find specific resources. You can filter charges, refunds, checkout sessions, and payouts by various attributes to narrow down your results.

Supported Filters

The API supports the following filter parameters for the list endpoints:

Filter	Description	Format	Example
status	Filter by the current status of the resource	String	status=succeeded
start_date	Filter resources created on or after this date	YYYY-MM-DD	start_date=2025-01-15
end_date	Filter resources created on or before this date	YYYY-MM-DD	end_date=2025-04-30
currency	Filter by currency	Three-letter ISO code	currency=usd

Using Filters

You can combine filters to narrow down your search by adding them as query parameters to the list endpoints:

Code
 
GET /v1/charges?status=succeeded&start_date=2025-01-01&end_date=2025-01-31&currency=usd

This example retrieves all successful charges made in January 2025 in USD currency.

Date Filters

Date filters (start_date and end_date) allow you to search for resources within a specific time range:

• Format: ISO 8601 date format (YYYY-MM-DD)
• Time zone: All dates are interpreted in UTC+2
• Range: Both start_date and end_date are inclusive

If you provide an incorrect date format, the parameter will be ignored without returning an error.

Examples:

• Filter charges created on or after January 1, 2025:

  Code
   
  GET /v1/charges?start_date=2025-01-01

• Filter refunds created between March 15, 2025 and April 15, 2025:

  Code
   
  GET /v1/refunds?start_date=2025-03-15&end_date=2025-04-15

Status Filters

Each resource type has different possible status values:

Charge Statuses:

• requires_payment_method - The charge has been created but no payment method has been provided
• requires_authorization - The charge requires customer authorization
• pending - The charge is being processed
• succeeded - The charge completed successfully
• failed - The charge failed to process
• cancelled - The charge was cancelled

Refund Statuses:

• pending - The refund has been created but not yet processed
• processing - The refund is in progress
• succeeded - The refund completed successfully
• failed - The refund failed to process
• cancelled - The refund was cancelled

Checkout Session Statuses:

• open - The checkout session is active and can be used
• complete - The checkout was completed successfully
• expired - The checkout session has expired

Payout Statuses:

• pending - The payout has been created and is being processed
• paid - The payout completed successfully and funds have been delivered
• failed - The payout failed to process

Currency Filters

Use the currency parameter to filter by transaction currency:

• Supported values: usd, zwg
• Format: Three-letter ISO currency code (case-insensitive)

Examples:

• Filter checkout sessions in ZWG currency:

  Code
   
  GET /v1/checkout/sessions?currency=zwg

• Filter payouts by status and date range:

  Code
   
  GET /v1/payouts?status=paid&start_date=2025-01-01&end_date=2025-01-31

Combining Filters with Pagination

Filters can be combined with pagination parameters to create powerful queries:

Code
 
GET /v1/charges?status=succeeded&start_date=2025-01-01&currency=usd&first=5&after=cursor_xyz789

This example retrieves up to 5 successful USD charges created on or after January 1, 2025, starting after the specified cursor.

Error Handling

• If an invalid status value is provided, the API will return a 400 Bad Request error with an appropriate error message
• If an invalid currency is provided, the API will return a 400 Bad Request error
• Invalid date formats are silently ignored without causing an error

Performance Considerations

Using appropriate filters can significantly improve the performance of your API requests by reducing the amount of data that needs to be processed. When working with large datasets, combining filters with pagination is recommended to ensure optimal performance.