get https://{subdomain}.myshoplaza.com/openapi/2024-07/shoplazza-payment/payment-orders
Requires
financeaccess 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
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
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 |