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

# 获取订单状态 | GET /v1/order/status/{orderId}

> 通过 orderId 获取订单的完整状态和详情。返回带有状态、金额、交易信息和费用的 NotifyOrder 对象。

通过 `orderId` 获取任何订单（收款或付款）的当前状态和完整详情。此端点需要身份认证，用于商家服务器到服务器的通信。

## 请求

**`GET http://your-gateway:180/v1/order/status/{orderId}`**

### 路径参数

<ParamField path="orderId" type="string" required>
  您在创建收款或付款时指定的订单标识符。
</ParamField>

### cURL

```bash theme={null}
curl http://your-gateway:180/v1/order/status/order_1042 \
  -H "Content-Type: application/json"
```

***

## 响应

成功的请求返回 HTTP `200`，带 `R<NotifyOrder>` 信封。

### NotifyOrder 对象

<ResponseField name="orderId" type="string">
  创建收款或付款时使用的订单标识符。
</ResponseField>

<ResponseField name="uid" type="string">
  与订单关联的用户标识符（如果提供）。
</ResponseField>

<ResponseField name="orderType" type="string">
  订单类型：`COLLECTION` 或 `PAYOUT`。
</ResponseField>

<ResponseField name="status" type="string">
  当前订单状态：

  * `INIT` — 订单已创建，等待客户支付
  * `PENDING` — 检测到交易，等待确认
  * `PENDING_CONFIRMATION` — 等待区块确认
  * `SUCCESS` — 支付已成功确认
  * `EXPIRED` — 订单过期，未收到支付
  * `FAILED` — 交易失败
</ResponseField>

<ResponseField name="reason" type="string | null">
  如果订单失败或过期，此字段包含原因。否则为 `null`。
</ResponseField>

<ResponseField name="amount" type="string">
  请求的金额，十进制字符串格式。
</ResponseField>

<ResponseField name="actualAmount" type="string">
  实际收到/支付的金额。由于网络费用或部分支付，可能与 `amount` 不同。确认前为 `null`。
</ResponseField>

<ResponseField name="fee" type="string">
  平台处理手续费。由平台运营者配置费率结构；设置为 `"0.00"` 时不收取任何费用。
</ResponseField>

<ResponseField name="transaction" type="object | null">
  区块链交易详情。检测到交易前为 `null`。详见下方。
</ResponseField>

### Transaction 对象

<ResponseField name="chain" type="string">
  区块链网络。
</ResponseField>

<ResponseField name="symbol" type="string">
  代币符号。
</ResponseField>

<ResponseField name="txid" type="string">
  区块链交易哈希。
</ResponseField>

<ResponseField name="from" type="string">
  发送方的区块链地址。
</ResponseField>

<ResponseField name="to" type="string">
  接收方的区块链地址。
</ResponseField>

<ResponseField name="amount" type="string">
  十进制格式的转账金额。
</ResponseField>

<ResponseField name="blockNum" type="integer">
  包含此交易的区块号。
</ResponseField>

<ResponseField name="confirmedNum" type="integer">
  已收到的区块确认数。
</ResponseField>

<ResponseField name="status" type="string">
  区块链交易状态：`PENDING`、`SUCCESS` 或 `FAILED`。
</ResponseField>

<ResponseField name="timestamp" type="integer">
  交易被包含在区块中的 Unix 时间戳。
</ResponseField>

### 示例响应

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "data": {
    "orderId": "order_1042",
    "uid": "user_42",
    "orderType": "COLLECTION",
    "status": "SUCCESS",
    "reason": null,
    "amount": "250.00",
    "actualAmount": "249.50",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON",
      "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...",
      "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00",
      "blockNum": 12345678,
      "confirmedNum": 3,
      "status": "SUCCESS",
      "timestamp": 1717000123
    }
  }
}
```