Requires
read_financeaccess scope.
The List Reserved Fund Details API returns the list of security deposits details.
Reserved Fund refers to the details of merchant security deposits collected by the proprietary payment system. For each order payment, security deposits are collected according to specific rules based on risk control policies. These deposits are divided into two typesโโFixed Security Deposit and Variable Security Deposit.
Fixed Security Deposit
- Collected until a predetermined amount is reached
- Once the maximum amount is met, no additional deposits are required
Rolling/Variable Security Deposit
- Collected for each individual transaction
- A portion of each order payment is held as security
This API is especially useful for:
- Retrieving detailed information about reserved funds.
- Filtering reserve data based on time ranges and currency.
- Paginating results efficiently with cursor-based pagination.
Request Parameters
Public Request Parameters
Query Parameters
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
created_at_min | string | No | "1714281600" | Start time for reserve details (Unix timestamp). |
created_at_max | string | No | "1714368000" | End time for reserve details (Unix timestamp). |
limit | int32 | No | 10 | A limit on the number of objects to return. Range: 1-100 (default is 10). |
cursor | string | No | "abc123" | Cursor for pagination; use the cursor value returned in the previous response. |
currency | string | No | "USD" | Currency of the settlement account. |
Response Explanation
Public Response Parameters
Successful Response
| Field | Type | Example | Description |
|---|---|---|---|
code | string | "Success" | Status code for the response. |
message | string | "Request successful" | Additional message about the response. |
data | object | Contains the reserve fund details. | |
data.list | array | Array of reserve fund detail objects. | |
data.list[].store_id | string | "store123" | Store ID associated with the reserve fund. |
data.list[].currency | string | "USD" | Currency of the settlement account. |
data.list[].transaction_id | string | "txn456" | Transaction ID for the reserve fund. |
data.list[].pay_amount | string | "100.00" | Payment amount associated with the reserve. |
data.list[].reserve_amount | string | "10.00" | Amount reserved for the transaction. |
data.list[].created_at | string | "1714281600" | Creation time of the reserve details (Unix timestamp). |
data.list[].merchant_id | string | "merchant789" | Merchant ID associated with the reserve. |
data.has_more | boolean | true | Indicates if there are more pages of results. |
data.cursor | string | "abc123" | Cursor to fetch the next page of results. |
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 | cursor is not invalid. | wrong cursor |