> ## 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 使用**退款工单**系统。买家通过 API 或客户门户申请退款，每次申请都会创建一个按照定义的生命周期流转的工单。商家在仪表盘中审核和处理工单。

***

## 业务规则

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

* **一次性产品**在支付后 **14 天**内可申请退款。
* **订阅**不使用退款工单系统。取消在当前计费周期结束时生效。
* **部分退款**可通过在创建工单时提供自定义 `amount`（显示格式字符串，例如 "15.00"）来实现。

***

## 退款工单状态

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

<CardGroup cols={3}>
  <Card title="pending" icon="clock" color="#f59e0b">
    已申请退款，等待审核。
  </Card>

  <Card title="approved" icon="check" color="#22c55e">
    商家已批准退款。
  </Card>

  <Card title="rejected" icon="xmark" color="#ef4444">
    退款申请被拒绝。
  </Card>

  <Card title="processing" icon="spinner" color="#8b5cf6">
    退款正在由支付服务商处理。
  </Card>

  <Card title="succeeded" icon="check-double" color="#3b82f6">
    退款已成功完成。
  </Card>

  <Card title="failed" icon="triangle-exclamation" color="#dc2626">
    退款处理失败。
  </Card>
</CardGroup>

***

## 创建退款工单

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

### 端点

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

**认证方式：** API Key

### 请求体

<ParamField body="paymentId" type="string" required>
  要退款的支付 ID（UUID v4）。
</ParamField>

<ParamField body="reason" type="string" required>
  退款原因说明。
</ParamField>

<ParamField body="amount" type="string">
  退款金额，以显示格式字符串表示（如 "15.00"）。省略则为全额退款。
</ParamField>

### 响应

<ResponseField name="ticketId" type="string">
  创建的退款工单唯一 ID。
</ResponseField>

<ResponseField name="status" type="string">
  工单的初始状态。创建时始终为 `pending`。
</ResponseField>

<ResponseField name="requestedAmount" type="string">
  退款金额，以显示格式字符串表示。
</ResponseField>

### 示例

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/refund-ticket/create-ticket \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "paymentId": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "Product not as described",
      "amount": "15.00"
    }'
  ```

  ```typescript SDK theme={"system"}
  import { WaffoPancake } from "@waffo/pancake-ts";

  const client = new WaffoPancake({
    merchantId: process.env.WAFFO_MERCHANT_ID!,
    privateKey: process.env.WAFFO_PRIVATE_KEY!,
  });

  const { ticketId, status, requestedAmount } = await client.refunds.createTicket({
    paymentId: "550e8400-e29b-41d4-a716-446655440000",
    reason: "Product not as described",
    amount: "15.00",
  });
  ```
</CodeGroup>

***

## 查询退款工单

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

```graphql theme={"system"}
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 指南](/zh/integrate/webhooks)。

***

## 减少退款请求

<AccordionGroup>
  <Accordion title="清晰的产品描述">
    准确的描述能减少"与预期不符"的退款请求。
  </Accordion>

  <Accordion title="提供试用期">
    让客户先试后买，减少购买后的后悔。
  </Accordion>

  <Accordion title="及时响应支持">
    快速解决问题，避免演变为退款请求。
  </Accordion>

  <Accordion title="可识别的账单描述">
    使用清晰的账单描述，让客户能识别扣款来源。
  </Accordion>
</AccordionGroup>