订单和支付

一次性订单

列出已完成订单

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

支付

列出成功的支付

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 排序。

聚合与排序

按天聚合支付

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

通过支付（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。

收银台会话

查询会话详情

query($sessionId: ID!) {
  checkoutSession(id: $sessionId) {
    id
    productType
    currency
    status
    expiresAt
    createdAt
  }
}

变量：

{ "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000" }

概览

认证

商户 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`）查询退款工单

收银台会话

查询会话详情