🔒
Requires read_finance access scope.

The List Payment Orders API returns a list of payment orders. The objects are sorted in descending order by creation date, with the most recently created object appearing first.

This API is especially useful for:

Retrieving a paginated list of payment orders.
Filtering payment orders based on their creation date.
Identifying payment statuses for order processing.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Field	Type	Required	Example	Description
`cursor`	string	No	`c3VwZXItY3Vyc29y`	Cursor for pagination, use the cursor from the response to retrieve the next page.
`limit`	int32	No	`10`	A limit on the number of objects to be returned. Ranges from 1 to 100. Default is 10.
`created_at_min`	string	No	`1714309200`	Filters payment orders created after a specified timestamp (Unix format).
`created_at_max`	string	No	`1714312800`	Filters payment orders created before a specified timestamp (Unix format).
`status`	string	No	`succeeded`	Filter payment orders by status. Valid values are: `succeeded`: The payment has been completed successfully, and the funds are confirmed. `failed`: The payment has failed, and the funds were not successfully processed. `requires_action`: Additional action is required to complete the payment, such as user verification (e.g., 3D authentication). `init`: The payment order has been created but not yet processed. `canceled`: The payment order has been canceled, and no funds were processed or have been returned. `processing`: The payment is currently in process, with the final result pending confirmation.

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Field	Type	Example	Description
`code`	string	`Success`	The status of the API response.
`message`	string	`Success`	A descriptive message for the response status.
`data`	object		Contains the main response data.
`data.has_more`	boolean	`true`	Indicates whether there are more results to retrieve.
`data.cursor`	string	`c3VwZXItY3Vyc29y`	The cursor for the next page of results.
`data.list`	array		A list of payment order objects.
`data.list[]. id`	string	`123456789`	The unique ID of the payment order.
`data.list[]. fee_details`	object	`{ ... }`	Contains details about transaction fees.
`data.list[]. fee_details. trans_fee_amount`	string	`10.00`	The transaction fee amount.
`data.list[]. fee_details. fee_currency`	string	`USD`	The currency of the transaction fee.
`data.list[]. fee_details. foreign_settlement_fee`	string	`5.00`	The foreign settlement fee.
`data.list[]. created_at`	string	`2024-04-28T06:00:00Z`	The creation timestamp of the payment order.
`data.list[]. finished_at`	string	`2024-04-28T06:05:00Z`	The completion timestamp of the payment order.
`data.list[]. payment_status`	string	`succeeded`	The current payment status of the order.
`data.list[]. payment_method`	string	`credit_card`	The payment method used (e.g., credit card, PayPal).
`data.list[]. card_brand`	string	`Visa`	The brand of the credit card used.
`data.list[]. pay_currency`	string	`USD`	The currency in which the payment was made.
`data.list[]. pay_amount`	string	`100.00`	The payment amount in the specified currency.
`data.list[]. converted_amount`	string	`130.00`	The converted amount in the store's base currency.
`data.list[]. reserve_amount`	string	`50.00`	The reserved amount, if applicable.
`data.list[]. order_id`	string	`987654321`	The ID of the associated order.

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Description	Example
`code`	string	The error code indicating the type of issue.	`InvalidParameter`
`message`	string	A detailed message describing the error.	`wrong cursor`

Field	Type	Example	Description
`error`	String	`"store is not active"`	Indicates an error encountered during the process

Error Detail

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`
500	InvalidParameter	wrong cursor	wrong cursor

API Structure Overview