订单和支付

一次性订单

列出已完成订单

query($storeId: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: { status: { eq: "completed" } }
    limit: 50
  ) {
    id
    buyerEmail
    currency
    priceSnapshot {
      currency
      subtotal
      taxAmount
      total
      taxCategory
    }
    status
    metadata
    createdAt
  }
  onetimeOrdersCount(storeId: $storeId)
}

变量：

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }

按日期范围过滤

query($storeId: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: {
      createdAt: {
        gte: "2026-01-01T00:00:00.000Z"
        lte: "2026-03-31T23:59:59.999Z"
      }
    }
  ) {
    id
    buyerEmail
    status
    createdAt
  }
}

通过你的业务编号（`orderMerchantExternalId`）查询一次性订单

传入你在 checkout 创建时附加的 orderMerchantExternalId。

query($storeId: String!, $ref: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: { orderMerchantExternalId: { eq: $ref } }
  ) {
    id
    buyerEmail
    status
    orderMerchantExternalId
    createdAt
  }
}

变量：

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "ORDER-2026-00891" }

SDK 示例

const result = await client.graphql.query<{
  onetimeOrders: Array<{
    id: string;
    buyerEmail: string;
    priceSnapshot: { total: number; currency: string };
    status: string;
  }>;
}>({
  query: `query($storeId: String!) {
    onetimeOrders(storeId: $storeId, filter: { status: { eq: "completed" } }) {
      id buyerEmail priceSnapshot { total currency } status
    }
  }`,
  variables: { storeId: "STO_3bVzrkD0FJjFdZNLk8Ualx" },
});

订阅订单

列出活跃订阅

query($storeId: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { status: { in: ["active"] } }
  ) {
    id
    buyerEmail
    status
    billingPeriod
    createdAt
  }
  subscriptionOrdersCount(storeId: $storeId)
}

过滤取消中的订阅

query($storeId: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { status: { eq: "canceling" } }
  ) {
    id
    buyerEmail
    status
    createdAt
  }
}

通过你的业务编号（`orderMerchantExternalId`）查询订阅订单

传入你在 checkout 创建时附加的 orderMerchantExternalId。每次续期支付都会继承相同的值，因此一个业务号能串起整个订阅生命周期。

query($storeId: String!, $ref: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { orderMerchantExternalId: { eq: $ref } }
  ) {
    id
    buyerEmail
    status
    billingPeriod
    orderMerchantExternalId
    createdAt
  }
}

变量：

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "SUB-2026-01045" }

查询订阅当前在第几期

该订阅此刻所处的计费周期，取自通道通知并原样存储 —— Waffo 不计算、不推算。首期为 1，第 N 期为 N；0 表示通道已授权但尚未扣款。扣款失败同样递增，因此它不是成功扣款次数。第一条通道通知到达前为 null，本字段上线前创建的订阅同样为 null。与 webhook 的 data.periodNumber、Payment.periodNumber 是同一个概念，只是锚点不同 —— 见字段说明。本字段随订阅续期前移，而 Payment.periodNumber 冻结在它所属的那笔扣款上。

query($storeId: String!) {
  subscriptionOrders(storeId: $storeId, filter: { status: { in: ["active"] } }) {
    id
    orderMerchantExternalId
    currentPeriodStart
    currentPeriodEnd
    currentPeriodNumber
  }
}

支付

列出成功的支付

query {
  payments(
    filter: { status: { eq: "succeeded" } }
    limit: 100
  ) {
    id
    orderId
    status
    refundStatus
    snapshotAmountDetails {
      subtotal
      taxAmount
      total
      currency
    }
    createdAt
  }
  paymentsCount(filter: { status: { eq: "succeeded" } })
}

按日期范围过滤

query {
  payments(
    filter: {
      status: { eq: "succeeded" }
      createdAt: {
        gte: "2026-01-01T00:00:00.000Z"
        lte: "2026-03-31T23:59:59.999Z"
      }
    }
  ) {
    id
    orderId
    snapshotAmountDetails {
      subtotal
      taxAmount
      total
      currency
    }
    createdAt
  }
}

通过 Waffo 支付 ID 查询支付

query($paymentId: String!) {
  payment(id: $paymentId) {
    id
    orderId
    status
    refundStatus
    orderMerchantExternalId
    snapshotAmountDetails { total currency }
  }
}

变量：

{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }

通过你的业务编号（`orderMerchantExternalId`）查询支付

传入你在 checkout 创建时附加的 orderMerchantExternalId(与 webhook 载荷字段 data.orderMerchantExternalId 同名)。

query($ref: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
    id
    orderId
    status
    refundStatus
    orderMerchantExternalId
    createdAt
  }
}

变量：

{ "ref": "ORDER-2026-00891" }

对于订阅订单,每笔续期支付都继承相同的 orderMerchantExternalId。上述查询返回同一业务编号下的全部支付历史,按 createdAt DESC 排序。

查询某笔扣款属于第几期

periodNumber 是这笔扣款所属的周期 —— 首期为 1，第 N 次续费为 N —— 与订阅支付 webhook 为它下发的值相同。扣款失败同样占用一期，因此它不是成功扣款次数。一次性支付与本字段上线前创建的支付为 null。它冻结在自己那笔扣款上：一笔当前在第 3 期的订阅，其首期支付上仍是 periodNumber: 1。想知道订阅今天在第几期，请用 SubscriptionOrder.currentPeriodNumber。

query($ref: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
    id
    orderId
    status
    periodNumber
    createdAt
  }
}

变量：

{ "ref": "SUB-2026-01045" }

聚合与排序

按天聚合支付

paymentsAggregate 返回命中全部行的 count 及金额指标 amount（sum、avg、min、max），可选按至多 2 个维度分组。可用维度：status、currency、payment_method_type、card_brand、store，以及时间维度 created_period。granularity（day、week、month、quarter、year；默认 day）仅作用于时间维度。

query {
  paymentsAggregate(
    filter: { status: { eq: "succeeded" }, currency: { eq: "USD" } }
    groupBy: [created_period]
    granularity: day
  ) {
    count
    amount { sum avg min max }
    groups {
      keys { dimension value }
      count
      amount { sum }
    }
    isTruncated
  }
}

聚合的 amount 值为最小货币单位（如分）的整数字符串。金额按命中 filter 的所有行求和，因此涉及多币种时应按 currency 分组或过滤。分组按 count 降序、上限 100 组（isTruncated 标记是否被截断）；顶层的 count/amount 始终覆盖全部命中行。其它实体暴露相同结构：refundsAggregate、onetimeOrdersAggregate、subscriptionOrdersAggregate、payoutTicketsAggregate、settlementBatchesAggregate、webhookDeliveriesAggregate、emailDeliveriesAggregate。

使用 `orderBy` 排序

支持排序的列表查询接受 orderBy: [XxxOrderBy!]（枚举白名单），默认 created_at DESC。支付可用选项为 created_at_desc、created_at_asc、amount_desc、amount_asc。

query {
  payments(
    filter: { status: { eq: "succeeded" } }
    orderBy: [amount_desc]
    limit: 20
  ) {
    id
    status
    snapshotAmountDetails { total currency }
    createdAt
  }
}

退款（执行的记录）

退款记录（order.refunds）在 PSP 确认退款后写入。它们与退款工单分离 — 工单承载请求生命周期，退款记录承载执行结果。

通过 Waffo 退款 ID 查询退款

Refund 上两个业务号以扁平字段公开:orderMerchantExternalId(从原始订单继承)和 refundTicketMerchantExternalId(从原始退款工单继承) — 与 webhook 载荷同名。

query($refundId: String!) {
  refund(id: $refundId) {
    id
    paymentId
    ticketId
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

变量：

{ "refundId": "RFD_8aHbCcDdEeFfGgHhIiJjKk" }

Refund 上有两个金额。amount 是 Money 对象，按最小货币单位计（USD 49.00 是 "4900"，display 给出 "49.00"）；pspAmountDetails.amount 是支付通道实际退给买家的金额，本身就是展示格式字符串（"49.00"）。与通道账单对账请用 pspAmountDetails；申请金额与通道金额不一致时 isAmountMismatch 为 true。

通过支付（Waffo 支付 ID）查询退款

query($paymentId: String!) {
  refunds(filter: { paymentId: { eq: $paymentId } }) {
    id
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

通过你的业务编号查询退款

按退款工单业务号（创建退款工单时附加的）匹配 — 使用 refundTicketMerchantExternalId filter：

query($ref: String!) {
  refunds(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
    id
    paymentId
    ticketId
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

或按订单业务号匹配（返回所有挂在此 reference 下的支付的全部退款,适合订阅续期场景）— 在 payment 层 filter 并读取其 nested refunds：

query($paymentRef: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $paymentRef } }) {
    id
    orderMerchantExternalId
    refunds {
      id
      status
      refundTicketMerchantExternalId
      pspAmountDetails { amount currency }
      createdAt
    }
  }
}

退款工单

列出所有退款工单

query {
  refundTickets {
    id
    paymentId
    status
    requestedAmount
    reason
    createdAt
  }
  refundTicketsCount
}

过滤待处理退款

query {
  refundTickets(filter: { status: { eq: "pending" } }) {
    id
    paymentId
    requestedAmount
    reason
    createdAt
  }
}

特定支付的退款

query($paymentId: String!) {
  refundTickets(filter: { subjectId: { eq: $paymentId } }) {
    id
    status
    refundTicketMerchantExternalId
    versionData {
      reason
      requestedAmount { amount currency }
    }
    createdAt
  }
}

变量：

{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }

通过你的业务编号（`refundTicketMerchantExternalId`）查询退款工单

query($ref: String!) {
  refundTickets(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
    id
    status
    refundTicketMerchantExternalId
    versionData {
      reason
      requestedAmount { amount currency }
    }
    reviewNote
    rejectReason
    executedAt
    createdAt
  }
}

变量：

{ "ref": "REF-2026-00891" }

RefundTicket(请求)和 Refund(执行记录)是两个不同的 GraphQL 类型,但它们的业务侧标识跟 webhook 载荷同名:RefundTicket 和 Refund 都暴露 refundTicketMerchantExternalId;Refund 额外暴露 orderMerchantExternalId(从原始订单继承)。Webhook 载荷上携带相同的两个值 data.orderMerchantExternalId 与 data.refundTicketMerchantExternalId。

概览

认证

商户 API（API Key）

Customer Portal API（Session Token）

GraphQL

一次性订单

列出已完成订单

按日期范围过滤

通过你的业务编号（`orderMerchantExternalId`）查询一次性订单

SDK 示例

订阅订单

列出活跃订阅

过滤取消中的订阅

通过你的业务编号（`orderMerchantExternalId`）查询订阅订单

查询订阅当前在第几期

支付

列出成功的支付

按日期范围过滤

通过 Waffo 支付 ID 查询支付

通过你的业务编号（`orderMerchantExternalId`）查询支付

查询某笔扣款属于第几期

聚合与排序

按天聚合支付

使用 `orderBy` 排序

退款（执行的记录）

通过 Waffo 退款 ID 查询退款

通过支付（Waffo 支付 ID）查询退款

通过你的业务编号查询退款

退款工单

列出所有退款工单

过滤待处理退款

特定支付的退款

通过你的业务编号（`refundTicketMerchantExternalId`）查询退款工单

​一次性订单

​列出已完成订单

​按日期范围过滤

​通过你的业务编号（orderMerchantExternalId）查询一次性订单

​SDK 示例

​订阅订单

​列出活跃订阅

​过滤取消中的订阅

​通过你的业务编号（orderMerchantExternalId）查询订阅订单

​查询订阅当前在第几期

​支付

​列出成功的支付

​按日期范围过滤

​通过 Waffo 支付 ID 查询支付

​通过你的业务编号（orderMerchantExternalId）查询支付

​查询某笔扣款属于第几期

​聚合与排序

​按天聚合支付

​使用 orderBy 排序

​退款（执行的记录）

​通过 Waffo 退款 ID 查询退款

​通过支付（Waffo 支付 ID）查询退款

​通过你的业务编号查询退款

​退款工单

​列出所有退款工单

​过滤待处理退款

​特定支付的退款

​通过你的业务编号（refundTicketMerchantExternalId）查询退款工单

一次性订单

列出已完成订单

按日期范围过滤

通过你的业务编号（`orderMerchantExternalId`）查询一次性订单

SDK 示例

订阅订单

列出活跃订阅

过滤取消中的订阅

通过你的业务编号（`orderMerchantExternalId`）查询订阅订单

查询订阅当前在第几期

支付

列出成功的支付

按日期范围过滤

通过 Waffo 支付 ID 查询支付

通过你的业务编号（`orderMerchantExternalId`）查询支付

查询某笔扣款属于第几期

聚合与排序

按天聚合支付

使用 `orderBy` 排序

退款（执行的记录）

通过 Waffo 退款 ID 查询退款

通过支付（Waffo 支付 ID）查询退款

通过你的业务编号查询退款

退款工单

列出所有退款工单

过滤待处理退款

特定支付的退款

通过你的业务编号（`refundTicketMerchantExternalId`）查询退款工单