> ## Documentation Index
> Fetch the complete documentation index at: https://pay-docs.holdstation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Orders

> Query a paginated list of payment orders with optional filtering.

## Overview

Partners can query a list of their payment orders with optional filtering by state, type, and date range.

<ParamField query="type" type="integer[]">
  Filter by order type. `1` = Deposit, `2` = Withdrawal.
</ParamField>

<ParamField query="state" type="integer[]">
  Filter by order state. `1` = New, `2` = Processing, `3` = Completed, `4` = Failed, `5` = Closed.
</ParamField>

<ParamField query="processing_state" type="integer[]">
  Filter by processing state. Deposit: `10`–`16`. Withdrawal: `20`–`25`. See table below.
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination.
</ParamField>

<ParamField query="page_size" type="integer">
  Number of results per page.
</ParamField>

<ParamField query="sort_by" type="string">
  Sort field. Available values: `created_at`, `expired_at`, `amount`.
</ParamField>

<ParamField query="sort_desc" type="boolean">
  If `true`, sort in descending order.
</ParamField>

<ParamField query="created_at_from" type="integer">
  Filter orders created after this Unix timestamp (seconds).
</ParamField>

<ParamField query="created_at_to" type="integer">
  Filter orders created before this Unix timestamp (seconds).
</ParamField>

<ParamField query="expired_at_from" type="integer">
  Filter orders expiring after this Unix timestamp (seconds).
</ParamField>

<ParamField query="expired_at_to" type="integer">
  Filter orders expiring before this Unix timestamp (seconds).
</ParamField>

<ParamField query="recipient" type="string">
  Filter by token recipient wallet address.
</ParamField>

<ParamField query="reference_nos" type="string[]">
  Filter by a list of partner reference numbers.
</ParamField>

## Processing State Values

| Value | Name                          | Description                          |
| ----- | ----------------------------- | ------------------------------------ |
| `10`  | DepositFiatPending            | Waiting for user to deposit fiat     |
| `11`  | DepositFiatConfirmed          | Fiat deposit confirmed               |
| `12`  | DepositFiatFailed             | Fiat deposit failed                  |
| `13`  | DepositCryptoPending          | Waiting for USDT transfer on-chain   |
| `14`  | DepositCryptoConfirmed        | USDT transfer confirmed              |
| `15`  | DepositCryptoFailed           | USDT transfer failed                 |
| `16`  | DepositFiatWaitingForApproval | Fiat payment pending manual approval |
| `20`  | WithdrawCryptoPending         | Waiting for user to transfer USDT    |
| `21`  | WithdrawCryptoConfirmed       | USDT transfer confirmed on-chain     |
| `22`  | WithdrawCryptoFailed          | USDT transfer failed                 |
| `23`  | WithdrawFiatPending           | Waiting for VND bank transfer        |
| `24`  | WithdrawFiatConfirmed         | VND bank transfer confirmed          |
| `25`  | WithdrawFiatFailed            | VND bank transfer failed             |

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "success",
    "data": {
      "orders": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "code": 100001,
          "order_type": 1,
          "state": 3,
          "processing_state": 14,
          "amount": "2575000",
          "outcome": "100",
          "currency": "vnd",
          "rate": "25750",
          "original_rate": "25500",
          "token_address": "0x55d398326f99059ff775485246999027b3197955",
          "chain_id": 56,
          "recipient": "0xUSER_WALLET_ADDRESS",
          "reference_no": "DEPOSIT-001",
          "external_id": "ext-001",
          "partner_id": "partner-xyz",
          "user_id": "user-abc",
          "provider": 1,
          "processing_time": 12400,
          "client_ip": "127.0.0.1",
          "callback": "https://yourapp.com/api/webhooks/payment",
          "fees": { "service_fee": 5000, "min_fee": 2000 },
          "total_fee_vnd": 5000,
          "pay_data": {
            "bank_account_name": "CONG TY HOLDSTATION",
            "bank_account_number": "9876543210",
            "bank_bin_code": "970423",
            "bank_name": "Tien Phong Bank",
            "bank_short_code": "TPBank",
            "payment_link": "https://dl.vietqr.io/pay?...",
            "qr_code": "00020101021238...",
            "qr_image": "data:image/png;base64,...",
            "external_id": "hpay-ext-001"
          },
          "payment_info": null,
          "reference": {
            "hs_rate": 25000,
            "usdt_rate": 25500,
            "token_rate": 1.0,
            "partner_rate": 25750,
            "spread": 0.02,
            "buffer_rate": 0.005,
            "buffered_rate_usdt": 25628,
            "buffered_rate_partner": 25750,
            "addition_share_rate": 0,
            "partner_override_revenue": 0,
            "sim_webhook_id": ""
          },
          "body": {},
          "error": null,
          "created_at": { "seconds": 1700000000, "nanos": 0 },
          "updated_at": { "seconds": 1700012400, "nanos": 0 },
          "expired_at": { "seconds": 1700003600, "nanos": 0 }
        }
      ],
      "total_count": 1
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "invalid request",
    "error_code": "BAD_REQUEST",
    "message": "Invalid parameters"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "unauthorized",
    "error_code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseExample>