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

# 订单与支付

> 跟踪交易，管理支付生命周期

## 概览

Waffo Pancake 中每次购买都会创建一个**订单**和一个关联的**支付**记录。订单代表客户的购买意图，而支付则跟踪实际的资金流动。

***

## 订单状态

订单根据产品类型有不同的状态集。

### 一次性订单

| 状态         | 说明         |
| ---------- | ---------- |
| `pending`  | 订单已创建，等待支付 |
| `paid`     | 支付成功，订单已完成 |
| `canceled` | 订单在完成前被取消  |

### 订阅订单

| 状态          | 说明                  |
| ----------- | ------------------- |
| `pending`   | 订阅已创建，等待首次支付        |
| `active`    | 订阅处于活跃状态，正常计费       |
| `trialing`  | 客户处于免费试用期           |
| `past_due`  | 支付失败，正在重试           |
| `canceling` | 已请求取消，在当前周期结束前仍保持活跃 |
| `canceled`  | 订阅已取消（在当前周期结束前仍可访问） |
| `expired`   | 订阅已过期               |
| `closed`    | 从未激活 — 支付超时         |

***

## 支付状态

<CardGroup cols={3}>
  <Card title="Pending" icon="clock" color="#f59e0b">
    支付已发起，等待处理。
  </Card>

  <Card title="Processing" icon="spinner" color="#3b82f6">
    支付正在处理中。
  </Card>

  <Card title="Succeeded" icon="check" color="#22c55e">
    支付已成功完成。
  </Card>

  <Card title="Failed" icon="xmark" color="#ef4444">
    支付在处理过程中失败。
  </Card>

  <Card title="Canceled" icon="ban" color="#6b7280">
    支付被取消（超时、商户操作或处理前买家取消）。
  </Card>

  <Card title="Refunded" icon="rotate-left" color="#6366f1">
    已处理全额退款。
  </Card>

  <Card title="Partially Refunded" icon="circle-half-stroke" color="#8b5cf6">
    已处理部分退款。
  </Card>
</CardGroup>

<Note>
  `processing` 可能出现在 Dashboard 中，但 API 和 GraphQL 不会返回该状态。API 返回的支付状态为：`pending`、`succeeded`、`failed`、`canceled`。
</Note>

<Note>
  退款状态通过 Payment 的 `refundStatus` 字段单独追踪（`none` / `pending` / `refunded` / `failed`），不属于支付状态值。
</Note>

***

## 支付列表

在表格中查看所有支付记录，包含以下列：

| 列    | 说明                                |
| ---- | --------------------------------- |
| 日期   | 交易时间戳                             |
| 金额   | 支付金额（显示格式字符串）                     |
| 税额   | 交易中收取的税费                          |
| 状态   | 当前支付状态                            |
| 支付方式 | `card`、`bank_transfer` 或 `wallet` |
| 客户   | 客户邮箱地址                            |
| 货币   | ISO 4217 货币代码                     |

### 筛选

| 筛选条件 | 选项                                                                          |
| ---- | --------------------------------------------------------------------------- |
| 状态   | `pending`、`processing`、`succeeded`、`failed`、`refunded`、`partially_refunded` |
| 日期范围 | 自定义起止日期                                                                     |

***

## 支付详情

点击任意支付记录查看完整信息。

### 交易信息

| 字段         | 说明            |
| ---------- | ------------- |
| Payment ID | UUID v4 标识符   |
| Order ID   | 关联订单          |
| Store ID   | 收款商店          |
| Amount     | 支付总额（显示格式字符串） |
| Currency   | ISO 4217 货币代码 |
| Status     | 当前支付状态        |
| Created At | ISO 8601 时间戳  |
| Updated At | ISO 8601 时间戳  |

### 金额详情

| 字段                   | 说明              |
| -------------------- | --------------- |
| `amount`             | 总收费金额           |
| `taxAmount`          | 金额中的税费部分        |
| `settlementCurrency` | 结算使用的货币         |
| `settlementAmount`   | 结算货币金额（显示格式字符串） |
| `refundedAmount`     | 已退款总额           |

### 账单信息

| 字段             | 说明        |
| -------------- | --------- |
| `country`      | 客户的账单国家   |
| `state`        | 账单州/地区    |
| `postcode`     | 账单邮编      |
| `isBusiness`   | 是否为企业购买   |
| `businessName` | 企业名称（如适用） |
| `taxId`        | 税号（如适用）   |

### 支付方式

支付记录会记载使用的支付方式：

| 方式      | 值               |
| ------- | --------------- |
| 信用卡/借记卡 | `card`          |
| 银行转账    | `bank_transfer` |
| 数字钱包    | `wallet`        |

更多支付方式相关的详细信息可在 `paymentMethodDetails` 字段中获取。该字段的结构因支付方式而异。

***

## 支持的支付方式

<CardGroup cols={3}>
  <Card title="银行卡" icon="credit-card">
    信用卡和借记卡支付。
  </Card>

  <Card title="银行转账" icon="building-columns">
    银行间直接转账。
  </Card>

  <Card title="钱包" icon="wallet">
    数字钱包支付（Apple Pay、Google Pay 等）。
  </Card>
</CardGroup>

***

## 退款

退款请求通过单独的工单制工作流处理。买家提交退款工单，指定支付和原因，商家审核后批准或拒绝请求。

<Note>
  有关退款流程、状态和政策的完整详情，请参阅[退款](/zh/customers/refunds)页面。
</Note>

**关键规则：**

* 一次性产品退款必须在支付后 **14 天**内申请
* 订阅取消在当前计费周期结束时生效
* 退款工单有自己的状态跟踪：`pending`、`approved`、`rejected`、`processing`、`succeeded`、`failed`

***

## API 参考

### 创建订单

订单创建采用两步收银台会话流程：

**第一步：创建收银台会话**（API Key 或 Store Slug 认证）

```bash theme={"system"}
curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "store-uuid",
    "productId": "product-uuid",
    "productType": "onetime",
    "currency": "USD"
  }'
```

响应返回 `sessionId` 和 `checkoutUrl`。收银台会话有 7 天有效期，会锁定产品版本和价格。

**第二步：创建订单**（API Key 认证）

<CodeGroup>
  ```bash 一次性订单 theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/onetime-order/create-order \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "checkoutSessionId": "session-uuid",
      "billingDetail": {
        "country": "US",
        "isBusiness": false,
        "state": "CA"
      }
    }'
  ```

  ```bash 订阅订单 theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/subscription-order/create-order \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "checkoutSessionId": "session-uuid",
      "billingDetail": {
        "country": "US",
        "isBusiness": false,
        "state": "CA"
      }
    }'
  ```
</CodeGroup>

两个端点都返回 `checkoutUrl`，买家应被重定向到该 URL 完成支付。

### 查询支付

使用 GraphQL 端点查询支付记录：

```graphql theme={"system"}
query {
  payments(storeId: "store-uuid", limit: 20) {
    id
    orderId
    amount
    currency
    status
    paymentMethod
    amountDetails {
      amount
      taxAmount
      settlementCurrency
      settlementAmount
      refundedAmount
    }
    billingDetail {
      country
      state
      postcode
      isBusiness
      businessName
      taxId
    }
    createdAt
  }
}
```

<Tip>
  所有金额均以显示格式字符串表示。例如，USD 中的 `"29.00"` 表示 \$29.00。对于零小数货币如 JPY，`"4500"` 表示 4500 日元。
</Tip>