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

# 退款

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

## 概览

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

## 退款服务说明

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

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

## 退款处理流程

按以下步骤处理退款：

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

## 退款状态

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

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

## 如何对一笔支付发起退款

通过 API 退款
下例展示调用 [Create a refund](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/create-refund.md) API 的请求和响应。
示例请求

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

#### 示例响应

```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**](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/retrieve-refund.md) API 查询 `refund_status`，来判断退款是否已成功处理。
通过控制台退款

1. 在商户后台打开 **Payments** → **Transactions**。
2. 打开符合条件的支付，或使用其行操作菜单，然后选择 **Refund**。
3. 输入不超过可退款金额的退款金额，选择原因，然后提交退款。

只有支付可退款且当前角色拥有退款权限时，Refund 操作才会显示。你可以通过 **Refunds** 标签页、退款 Webhook 或 Retrieve a refund API 跟踪结果。

## 预授权请款后的退款

预授权退款要求PaymentIntent为`SUCCEEDED`、`available_to_capture`为零且`captured_amount`大于零。退款金额以已请款金额为基准，不以原始授权金额为基准。渠道明确拒绝的最终请款不能作为退款依据。请款受理不等于渠道已完成处理，请结合查询PaymentIntent返回的`capture_records`检查结果。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.