退款

本地收单

退款

PayCools 支持通过商户平台或退款 API 发起退款。您可以在商户平台中手动处理退款，也可以通过 API 将退款接入自己的业务流程。

退款业务概述

什么是退款

退款路径：资金从商户账户退回，通过用户支付时的原渠道返回
退款类型：支持全额退款与部分退款
触发方式：商户通过接口发起，或通过商户后台操作
手续费：根据具体产品与渠道，退款可能产生手续费（请咨询商务）

退款类型

类型	说明
全额退款	退回订单的全部金额，需订单未退款且未超过退款期限
部分退款	退回订单的部分金额，支持多次部分退款（累计金额不超过原订单金额）

备注

多次部分退款累计规则：一笔订单可发起多次部分退款，系统会累计已退款金额并校验剩余可退金额，累计退款金额不得超过原订单金额。例如原订单 100 元，先退 30 元、再退 50 元合法；若再退 30 元则失败（仅剩 20 元可退）。

退款状态

状态码	状态	说明
PENDING	退款待处理	退款已受理，等待处理；若因余额不足等原因暂时无法执行，将停留在此状态并自动重试
PROCESS	退款处理中	退款正在处理中
COMPLETED	退款成功	资金已退回用户账户
FAILED	退款失败	退款失败（如订单异常、渠道拒绝、账户问题）
CANCELLED	退款取消	退款单被取消，不再继续处理

备注

退款取消（CANCELLED）：当退款因余额不足等原因暂时无法执行时，退款单会停留在 PENDING（退款待处理），PayCools 会定时自动重试；若持续无法完成（例如余额长期不足），7 天后该退款单会被置为 CANCELLED（退款取消）。商户可在补足余额后重新发起退款。

退款期限与手续费

维度	说明
退款期限	通常在订单结算后的一定时间窗口内可退款，具体期限因渠道 / 国家而异
原路退款	资金按用户支付时的原渠道退回，部分渠道可能不支持原路（需改用代付）
手续费	根据渠道与产品配置不同，部分退款包含手续费退还、部分则不包含
到账时效	取决于原渠道，通常实时到数小时，个别渠道可能 T+1

注意

由于渠道限制和费用承担方配置不同，部分退款包含手续费退还，部分则不包含。具体规则请咨询商务。

退款 vs 交易撤销

维度	退款（Refund）	交易撤销（Void）
适用时间	已结算订单（通常有较长退款期限）	仅当天已付款但未结算的订单
资金流向	订单已结算，需从商户账户退回资金给用户	订单未结算，直接作废，资金未实际结算给商户
支持范围	支持更广泛的渠道与国家	目前仅支持泰国动态二维码
时效	结算后较长时间窗口内	当天未结算（如泰国 23:00 结算切换点前）

应用场景

电商退款：用户购买商品后因商品问题或个人原因申请退货退款。

全额退款（整单退货）或部分退款（部分商品退货）
处理时效：根据渠道不同，通常实时到数小时

服务取消退款：用户预订服务后因故取消，需退回已付金额。

酒店预订取消、机票退票、活动报名取消
可能有退款时效限制（如起飞前 24 小时可全额退）
扣除违约金后的剩余金额：部分退款

重复支付退款：因网络问题或其他原因导致重复支付，需退还其中一笔。

商户识别重复订单后，对其中一笔发起全额退款
建议商户侧做好幂等 / 防重逻辑，减少此类场景

价格调整退款：商品价格变动或优惠生效后，需退还差价。

保价服务：购买后降价，退还差价
使用部分退款，退还差价金额而非整单退款

退款前提

发起退款前，请确认原交易满足以下条件：

支付方式支持退款；
交易状态为支付成功；
该交易当前没有正在处理的退款；
本次退款金额不超过交易的可退金额；
待结算余额足以支付本次退款；
通过商户平台操作时，您的账户已开通退款权限。

通过商户平台退款

登录 PayCools 商户平台。
进入交易管理→收款交易。
找到需要退款的交易，点击退款，并按照页面提示完成操作。

PayCools 商户平台发起退款页面

备注

后台发起的退款不会进行回调通知，可以在后台查看退款进度

通过 API 退款

1. 发起退款

在您的服务端提交退款申请，并关联需要退款的原交易。您需要为本次退款设置唯一的退款单号，并提交退款金额和退款原因。以下为退款申请的请求示例。

退款申请请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/refund' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "your appId",
    "sign": "***********************,
    "param": "{\"originalTransactionId\":\"CU5U4892099236335616\",\"mchRefundOrderId\":\"T0WRCHULVhpkJOGs\",\"refundReason\":\"testRefund\",\"refundAmount\":100,\"countryCode\":\"PH\",\"refundCallbackUrl\":\"http://www.test.com\",\"timestamp\":1722415059}"
}'

退款申请响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
     "mchRefundOrderId": "UDzQ37ruxde2T6vuy",
     "refundTransactionId": "R2104894311513591808",
     "refundCreateTime": "2026-09-29 19:21:26",
     "refundAmount": 100,
     "refundStatus": "PENDING"
  }
}

PayCools 接收退款申请后，会返回退款单信息和当前退款状态。退款申请受理成功不代表退款已经完成。

2. 确认退款结果

退款申请提交后，您可以通过退款结果通知或主动查询确认退款状态，并据此更新退款记录。退款仍在处理时，请等待最终结果。退款状态更新后，PayCools 会将退款结果发送至您设置的通知地址。收到通知后，请验签并更新退款记录。

退款结果通知请求示例

{
    "param": "{\"eventName\":\"payment.refund.success\",\"feeRefunded\":0,\"mchRefundOrderId\":\"UDzQ37ruxde2T6vuy\",\"originalTransactionId\":\"CU5U4892099236335616\",\"refundAmount\":100,\"refundCreateTime\":\"2026-09-29 19:21:26\",\"refundReason\":\"testRefund\",\"refundReturnTime\":\"2026-09-29 19:38:04\",\"refundStatus\":\"COMPLETED\",\"refundTransactionId\":\"R2104894311513591808\"}",
    "sign": "*******************"
}

退款结果通知响应示例

{
  "code": 10000,
  "msg": "string",
  "data": {}
}

退款