订单与支付

概览

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

订单状态

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

一次性订单

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

订阅订单

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

支付状态

Pending

支付已发起，等待处理。

Processing

支付正在处理中。

Succeeded

支付已成功完成。

Failed

支付在处理过程中失败。

Canceled

支付被取消（超时、商户操作或处理前买家取消）。

Refunded

已处理全额退款。

Partially Refunded

已处理部分退款。

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

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

支付列表

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

列	说明
日期	交易时间戳
金额	支付金额（显示格式字符串）
税额	交易中收取的税费
状态	当前支付状态
支付方式	`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`	买家的卡实际被扣款的币种（可能与 `currency` 不同）——见本地币种定价
`settlementAmount`	该币种下的扣款金额（显示格式字符串）
`refundedAmount`	已退款总额

账单信息

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

支付方式

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

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

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

支持的支付方式

银行卡

信用卡和借记卡支付。

银行转账

银行间直接转账。

钱包

数字钱包支付（Apple Pay、Google Pay 等）。

退款

退款通过单独的工单制工作流处理。商家在仪表盘中或通过 API 创建退款工单，指定支付和原因。

有关退款流程、状态和政策的完整详情，请参阅退款页面。

关键规则：

一次性产品退款没有时效限制，支付后商家随时可以退款
订阅取消在当前计费周期结束时生效
退款工单有自己的状态跟踪：pending、approved、rejected、processing、succeeded、failed

API 参考

创建订单

订单创建采用两步收银台会话流程： 第一步：创建收银台会话（API Key 或 Store Slug 认证） cURL 示例使用 API Key 鉴权 —— 三个签名请求头，不是 Bearer token。X-Signature 的计算方法见 API Key 认证，或直接用 SDK 由它代签。

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_xxx" \
  -H "X-Timestamp: 1705312200" \
  -H "X-Signature: BASE64_RSA_SHA256_SIGNATURE" \
  -d '{
    "productId": "PROD_2aUyqjCzEIiEcYMKj7TZtw",
    "currency": "USD"
  }'

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_xxx" \
  -H "X-Timestamp: 1705312200" \
  -H "X-Signature: BASE64_RSA_SHA256_SIGNATURE" \
  -d '{
    "productId": "PROD_5dXBtmF2HLlHfbPNm0Wcnz",
    "currency": "USD"
  }'

响应返回 sessionId、checkoutUrl 和 expiresAt。产品类型由 productId 解析，一次性商品和订阅商品用同一个调用。会话会锁定产品版本和价格快照；默认 24 小时过期，API Key 调用可用 expiresInSeconds 调整，建议 1 分钟 ~ 7 天。 第二步：创建订单（API Key 认证）

curl -X POST https://api.waffo.ai/v1/actions/onetime-order/create-order \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_xxx" \
  -H "X-Timestamp: 1705312200" \
  -H "X-Signature: BASE64_RSA_SHA256_SIGNATURE" \
  -d '{
    "checkoutSessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
    "language": "zh-Hans",
    "billingDetail": {
      "country": "US",
      "isBusiness": false,
      "state": "CA"
    }
  }'

curl -X POST https://api.waffo.ai/v1/actions/subscription-order/create-order \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_xxx" \
  -H "X-Timestamp: 1705312200" \
  -H "X-Signature: BASE64_RSA_SHA256_SIGNATURE" \
  -d '{
    "checkoutSessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
    "language": "zh-Hans",
    "billingDetail": {
      "country": "US",
      "isBusiness": false,
      "state": "CA"
    }
  }'

language 为必填，取值须是收银台支持的语言之一。两个端点都返回 checkoutUrl（把买家重定向到这里完成支付）和 nextCheckoutUrl（买家从支付通道返回时落到的替换会话地址，见会话生命周期）。

查询支付

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

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
  }
}

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

开始使用

功能

商户

商店

记录商

概览

订单状态

一次性订单

订阅订单

支付状态

Pending

Processing

Succeeded

Failed

Canceled

Refunded

Partially Refunded

支付列表

筛选

支付详情

交易信息

金额详情

账单信息

支付方式

支持的支付方式

银行卡

银行转账

钱包

退款

API 参考

创建订单

查询支付

​概览

​订单状态

​一次性订单

​订阅订单

​支付状态

Pending

Processing

Succeeded

Failed

Canceled

Refunded

Partially Refunded

​支付列表

​筛选

​支付详情

​交易信息

​金额详情

​账单信息

​支付方式

​支持的支付方式

银行卡

银行转账

钱包

​退款

​API 参考

​创建订单

​查询支付

概览

订单状态

一次性订单

订阅订单

支付状态

支付列表

筛选

支付详情

交易信息

金额详情

账单信息

支付方式

支持的支付方式

退款

API 参考

创建订单

查询支付