退款 - Waffo Pancake

概览

Waffo Pancake 使用退款工单系统。商家在仪表盘中或通过 API 发起退款，每次退款都会创建一个按照定义的生命周期流转的工单。

业务规则

这些规则由 API 强制执行，无法覆盖。

一次性产品支付后，商户可随时发起退款，没有时效限制。退款金额不超过订单金额，且不超过账户当前的可提款余额。
订阅的每笔支付同样通过退款工单退款。退款不会取消订阅，要停止后续扣款需另外取消订阅。
部分退款可通过在创建工单时提供自定义 amount（显示格式字符串，例如 “15.00”）来实现。

退款工单状态

每个退款工单按以下生命周期流转：

pending

退款工单已创建，等待审核。

approved

退款已批准。商户发起的退款提交后自动批准；买家在门户发起的申请由平台审核。

rejected

退款工单被拒绝。

processing

退款正在由支付服务商处理。

succeeded

退款已成功完成。

failed

退款处理失败。

退款到账时效与「处理中」的含义。 银行卡退款由发卡行受理，通常 3–10 个工作日内到账，最长不超过 14 个工作日；微信支付退款即时到账。工单处于 processing（处理中 / 审核中）表示已进入支付通道和银行受理阶段，平台不会在此之上再做内部财务审核。

创建退款工单

通过 API Key 认证调用 API 来创建退款工单。

端点

POST /v1/actions/refund-ticket/create-ticket

认证方式： API Key

请求体

string

必填

要退款的支付 ID（UUID v4）。

string

必填

退款原因说明。

string

退款金额，以显示格式字符串表示（如 “15.00”）。省略则为全额退款。

响应

string

创建的退款工单唯一 ID。

string

工单的初始状态。创建时始终为 pending。

string

退款金额，以显示格式字符串表示。

示例

cURL 标签页使用 API Key 鉴权 —— 三个签名请求头，不是 Bearer token。X-Signature 的计算方法见 API Key 认证。

curl -X POST https://api.waffo.ai/v1/actions/refund-ticket/create-ticket \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_xxx" \
  -H "X-Timestamp: 1705312200" \
  -H "X-Signature: BASE64_RSA_SHA256_SIGNATURE" \
  -d '{
    "paymentId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "Product not as described",
    "amount": "15.00"
  }'

商户端 SDK（@waffo/pancake-ts）目前还没有封装这个接口，请按上面的示例自行签名调用 REST。买家 token 客户端（client.customer(token)）上的 createRefundTicket() 目前会被网关以 403 拒绝，请不要使用。

查询退款工单

使用 GraphQL 检索退款工单数据。

query {
  refundTickets(storeId: "STORE_ID") {
    id
    paymentId
    storeId
    customerId
    reason
    status
    requestedAmount
    approvedAmount
    currency
    createdAt
    updatedAt
    resolvedAt
  }
}

字段	类型	说明
`id`	string	退款工单 ID
`paymentId`	string	关联的支付 ID
`storeId`	string	拥有该支付的商店
`customerId`	string	完成原始支付的买家
`reason`	string	退款原因
`status`	string	当前工单状态
`requestedAmount`	string	买家申请的金额（显示格式字符串）
`approvedAmount`	string	已批准的金额（可能与申请金额不同）
`currency`	string	ISO 4217 货币代码
`createdAt`	string	ISO 8601 时间戳
`updatedAt`	string	ISO 8601 时间戳
`resolvedAt`	string	ISO 8601 时间戳（未解决则为 null）

Webhook 通知

您可以配置 Webhooks 在退款工单事件发生时接收通知。有关设置说明，请参阅 Webhooks 指南。

减少退款请求

清晰的产品描述

准确的描述能减少”与预期不符”的退款请求。

提供试用期

让客户先试后买，减少购买后的后悔。

及时响应支持

快速解决问题，避免演变为退款请求。

可识别的账单描述

使用清晰的账单描述，让客户能识别扣款来源。

开始使用

功能

商户

商店

记录商

退款

概览

业务规则

退款工单状态

pending

approved

rejected

processing

succeeded

failed

创建退款工单

端点

请求体

响应

示例

查询退款工单

Webhook 通知

减少退款请求

​概览

​业务规则

​退款工单状态

pending

approved

rejected

processing

succeeded

failed

​创建退款工单

​端点

​请求体

​响应

​示例

​查询退款工单

​Webhook 通知

​减少退款请求

概览

业务规则

退款工单状态

创建退款工单

端点

请求体

响应

示例

查询退款工单

Webhook 通知

减少退款请求