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

# 订单 API

> 使用 Merchant API 查询订单、确认付款状态并安全履约。

完整查询参数和响应数据结构请以生成的端点页面为准。

<CardGroup cols={2}>
  <Card title="列出订单" icon="list" href="/zh/api-reference/endpoint/orders">
    筛选并分页读取组织内的订单。
  </Card>

  <Card title="读取订单" icon="file-magnifying-glass" href="/zh/api-reference/endpoint/get-order">
    查看单个订单及可用的付款渠道标识。
  </Card>
</CardGroup>

## 列表与详情规则

列表操作适用于付款状态核对和日常运营。其 `status` 筛选匹配面向用户的
`displayStatus`，响应同时保留标准状态。还可以通过 `customer_id` 或 Anyway
`subscription_id` 缩小订单范围。Merchant API 的订单详情不会公开支付服务商或服务商
账户标识。

`orderId` 是标准订单标识。旧的响应字段 `id` 返回相同值，但已弃用。`amount` 使用展示
单位，`amountCents` 则是存储的最小货币单位金额。

银行卡订单还可能包含 `fundsSettled` 和 `settledAvailableOn`。请使用 `fundsSettled`
判断资金是否符合提现条件；`settledAvailableOn` 只是支付服务商预计的可用时间。没有该结算
生命周期的付款方式会省略这两个字段。

## 订阅关系

定期付款产生的订单会包含 `subscriptionId`。首笔付款没有 `originalOrderId`；每笔续费订单
会用 `originalOrderId` 指向首笔订单。使用
`GET /v1/orders?subscription_id=SUB_EXAMPLE` 可以读取一项订阅的订单历史。

## 付款链接关联数据

把付款链接发给买家时，可以追加经过 URL 编码的查询参数：

```text theme={null}
https://pay.anyway.sh/pay/PL_EXAMPLE?merchant_reference=PUR_456&user_id=USR_123&source=web
```

买家打开结账后，Anyway 会先把这些查询参数作为 `merchantMetadata` 存入结账尝试记录。如果
参数名匹配 `merchant_reference` 或 `merchantReference`，Anyway 还会把它的值提升到结账尝试
记录中独立的 `merchantReference` 字段，同时在 `merchantMetadata` 中保留原始键值对。

付款确认后，这两个字段会从结账尝试记录一起复制到订单记录。订阅续费订单会从首笔订单继承
它们。因此结账结束后，订单响应和 Webhook 仍能返回同一份关联数据。

付款链接查询参数会通过两个互补字段公开：

* `merchantReference` 是从 `merchant_reference` 查询参数提升得到的值。它是一级关联字段，
  会单独存储，订单列表可以通过 `merchant_reference` 筛选。
* `merchantMetadata` 以字符串键值对保存付款链接上的所有自定义查询参数。Merchant API
  会在订单响应中返回这份映射，但不能用任意元数据键筛选订单列表。

从 Webhook 或成功跳转取得订单 ID 后，可以查询订单并读取这两个字段：

```bash theme={null}
curl "https://merchant-api-prod.anyway.sh/v1/orders/ORD_EXAMPLE" \
  -H "X-API-Key: ak_YOUR_MERCHANT_API_KEY"
```

```json theme={null}
{
  "success": true,
  "message": "Order retrieved",
  "data": {
    "orderId": "ORD_EXAMPLE",
    "status": "PAID",
    "merchantReference": "PUR_456",
    "merchantMetadata": {
      "merchant_reference": "PUR_456",
      "user_id": "USR_123",
      "source": "web"
    }
  }
}
```

请把 `merchantMetadata`、买家备注和 URL 查询参数视为不可信输入；不要只靠这些内容授权
访问或决定价格。

## 履约

只根据已验证的付款状态或已验证的 `order.paid` Webhook 履约，并以 Anyway 订单 ID 做幂等。Anyway 会防止重复付款事件和已付款状态回退，但你自己的履约处理器也必须能接受重试。

<Warning>
  API 成功响应并不会让买家可控的元数据变得可信。授权和定价必须来自服务端控制的记录。
</Warning>