跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/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 或 UQPAY 控制台发起退款。

​
退款处理流程

按以下步骤处理退款：
  1. 通过 API 或控制台，针对指定的 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 API 的请求和响应。

​
示例请求

{
    "payment_intent_id": "PI1960644127393583104",
    "amount": "7.77",
    "reason": "Custom refund reason",
    "metadata": {
        "echo_test": "any value"
    }
}

​
示例响应

{
    "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 API 查询 refund_status，来判断退款是否已成功处理。

​
通过控制台退款

![[Pasted image 20250828140526.png]]