> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 退款

> 客户退货或要求退回服务费用时，发起退款将资金退还给客户。

<h2 id="overview">概览</h2>

当客户希望退货或退回服务时，你可以使用退款操作将资金退还给客户。请及时处理退款，以免客户向发卡行发起争议。

<h2 id="refund-service-information">退款服务说明</h2>

下表介绍 UQPAY 提供的退款服务的更多信息：

| **项目**    | **详情**                                                                                              |
| --------- | --------------------------------------------------------------------------------------------------- |
| **退款有效期** | UQPAY 不对商户发起退款请求的时间做限制。只要订单状态允许退款，商户可随时发起退款。退款最终是否成功取决于渠道的退款有效期，UQPAY 会直接透传渠道的处理结果。                 |
| **退款条件**  | 仅当 Payment Intent 的 `intent_status` 为 `SUCCEEDED` 时才允许退款。                                           |
| **可退款金额** | UQPAY 支持全额退款、部分退款和多次部分退款。单笔交易的多次部分退款总金额不得超过用户实际支付的原始金额。                                             |
| **费用项目**  | 在商务合同中约定。                                                                                           |
| **退款方式**  | 你可以通过 [Create a refund API](/zh/global-acquiring/v1.6/api-reference/create-refund) 或 UQPAY 控制台发起退款。 |

<h2 id="refund-processing">退款处理流程</h2>

按以下步骤处理退款：

1. 通过 [API](/zh/global-acquiring/v1.6/api-reference/create-refund) 或控制台，针对指定的 Payment Intent 或 Payment Attempt 发起退款
2. 你会立即收到退款请求已接收并正在处理的提示
3. 退款成功后，你会通过 webhook 收到通知

<h2 id="refund-statuses">退款状态</h2>

基于 UQPAY 的支付系统设计，退款有以下几种状态：

| 状态           | 说明      | 阶段   | Webhook 事件                   |
| ------------ | ------- | ---- | ---------------------------- |
| `INITIATED`  | 退款已发起   | 初始状态 | `acquiring.refund.created`   |
| `PROCESSING` | 退款处理中   | 处理中  | -                            |
| `SUCCEEDED`  | 退款已成功完成 | 终态   | `acquiring.refund.succeeded` |
| `FAILED`     | 退款失败    | 终态   | `acquiring.refund.failed`    |

<h2 id="how-to-refund-a-payment">如何对一笔支付发起退款</h2>

<h3 id="refund-payment-via-api">通过 API 退款</h3>
下例展示调用 [Create a refund](/zh/global-acquiring/v1.6/api-reference/create-refund) API 的请求和响应。
<h4 id="sample-request">示例请求</h4>

```json theme={null}
{
    "payment_intent_id": "PI1960644127393583104",
    "amount": "7.77",
    "reason": "Custom refund reason",
    "metadata": {
        "echo_test": "any value"
    }
}
```

<h4 id="sample-response">示例响应</h4>

```json theme={null}
{
    "amount": "7.77",
    "create_time": "2025-08-27T18:06:40+08:00",
    "currency": "SGD",
    "metadata": {
        "echo_test": "any value"
    },
    "payment_attempt_id": "PA1960644127573938176",
    "payment_refund_id": "RF1960645128594919424",
    "reason": "Custom refund reason",
    "refund_status": "INITIATED",
    "update_time": "2025-08-27T18:06:40+08:00"
}
```

你可以通过监听 `acquiring.refund.succeeded` webhook，或主动调用 [**Retrieve a refund**](/zh/global-acquiring/v1.6/api-reference/retrieve-refund) API 查询 `refund_status`，来判断退款是否已成功处理。
<h3 id="refund-payment-via-dashboard">通过控制台退款</h3>

!\[\[Pasted image 20250828140526.png]]