# 退款能力

更新时间：2024-08-21 18:02:13

# 1、支付退款

# 1.1、场景说明

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。

注意：

在途资金中的所有货款均是与订单关联的，只有当该订单在途资金中剩余金额超过退款金额时，才可以进行在途资金的退款。

当可提现金额也不足退款金额时，会退款失败，为了避免出现订单无法退款的情况出现，请根据业务情况自行保留一部分可提现金额在系统中。

退款的资金判断流程如下：

# 1.2、接口说明

退款回调地址会优先使用开发者在 退款接口 传入的 notify_url，如果退款接口没有传入，会填充开发者在开发者平台设置的退款回调，该回调地址设置与查看步骤如下【小程序开发者平台 (opens new window) -> 交易管理 -> 支付管理 -> 支付设置 -> 默认回调地址】

# 1.2.1、基本信息

名称	内容
HTTP URL	https://open.kuaishou.com/openapi/mp/developer/epay/apply_refund
HTTP Method	POST
接口频次	30QPS(小程序app_id维度)

# 1.2.2、请求头

名称	字段类型	内容
Content-Type	String	固定值: "application/json"

# 1.2.3、入参

query param参数

字段名	类型	是否必填	是否参与签名	说明
app_id	string	是	是	小程序 AppID
access_token	string	是	否	拥有小程序支付权限的access token，获取方式见getAccessToken

body json参数

字段名	类型	是否必填	是否参与签名	说明
out_order_no	string	是	是	开发者需要发起退款的支付订单号，商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一示例值：2217752501201407033233368018
out_refund_no	string[6,32]	是	是	开发者的退款单号
reason	string[1,80]	是	是	退款理由。1个汉字=2个字符
attach	string[0,80]	否	是	开发者自定义字段，回调原样回传. 注：1汉字=2字符；勿回传敏感信息
notify_url	string[1,256]	否	是	通知URL必须为直接可访问的URL，不允许携带查询串。
refund_amount	number	否	是	用户退款金额，单位为分。不允许传非整数的数值
multi_copies_goods_info	string[1, 500]	否(单商品多份场景必填)	是	单商品购买多份场景，示例值：[{"copies":2}]，内容见multi_copies_goods_info字段说明
sign	string	是	否	开发者对核心字段签名, 防止传输过程中出现意外，签名方式见附录

multi_copies_goods_info字段说明

字段名	类型	说明
copies	number	退款份数

# 1.2.4、请求示例

# Http请求示例

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/epay/apply_refund?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJABVi9jvzBiHqK8ftAbMG6OsPtSy4V02gKbaX0jv2PEo-mUlhN6dpJLCO7RoI7GbkEbKKh-Vlfq5S0bN-Wgl_jjxoSXmId3s_9TpqnCS4FlyiXkIhhIiC5L9gIWwswVuCQQyTxEtvMRH6zMwpfvAQ3x6F_IrakPygFMAE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "notify_url":"https://qa-mp.test.kuaishou.com/zeus/epay/notify",
    "attach":"退款demo",
    "reason":"测试退款",
    "out_order_no":"1700813954820demob",
    "out_refund_no":"1700813954820RefundNo",
    "refund_amount":"10",
    "sign":"af2b2d3160853a76fd31496391ea74aa"
}'

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
refund_no	string	快手小程序平台的退款单号

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误信息提示",
    "refund_no": "221072611585202788127"
}

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

退款相关错误码如下

错误码	错误信息	排查建议
10000607	退款金额超限	发起退款申请时，入参refund_amount大于实际可退款金额，请确认剩余可退金额。
10000627	退款调用异常	退款调用内部支付中心抛异常，请联系快手小程序客服帮忙排查

# 1.3、退款回调

# 1.3.1、接口说明

在平台代扣成功/失败后，快手小程序服务端会通过 HTTP POST 请求方式回调开发者提供的 HTTP 退款回调地址。回调的内容使用小程序 secret key 进行签名，具体回调方式和重试策略见附录 (opens new window)。请注意：

由于网络波动等原因，可能会产生重复的通知消息，开发者需要做好幂等处理。
在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败并进行重试。
退款回调的地址是申请退款接口中的 notify_url 字段，所以请务必保证该字段传输的正确性

# 1.3.2、基本信息

名称	内容
HTTP URL	开发者在申请退款接口传入的 notify_url 字段
HTTP Method	POST

# 1.3.4、平台回调内容

以下字段放置到 body json中：

{
  "data": {
    "app_id": "ksdemo",
    "out_order_no": "32692405096780880",
    "out_refund_no": "72527320050520992",
    "ks_order_no": "124080110171614089593",
    "ks_refund_no": "224080111992676195593",
    "refund_amount": 10900,
    "status": "SUCCESS",
    "refund_time": 1722480482401,
    "channel": "WECHAT_SFT",
    "refund_type": "结算前退款",
    "apply_refund_reason": "多拍/拍错/不想要",
    "ks_refund_fail_reason": null,
    "order_amount": 10900,
    "attach": "32692405096780880"
  },
  "biz_type": "REFUND",
  "message_id": "522c4733-99c1-4209-b4d2-c469bd9c376e",
  "app_id": "ks669628973557796916",
  "timestamp": 1722480483488
}

其中和退款相关的主要是

字段名	类型	说明
out_order_no	string	开发者订单号
out_refund_no	string	开发者退款单号
ks_order_no	string	快手小程序平台订单号
ks_refund_no	string	快手小程序平台退款单号。
refund_amount	number	退款金额，单位分
status	string	退款状态。取值： PROCESSING-处理中，SUCCESS-成功，FAILED-失败
refund_time	number	退款完成时间
channel	string	退款渠道:WECHAT_SFT - 微信 ALIPAY_ZFT - 支付宝
refund_type	string	退款账户说明，枚举值为： "结算前退款" "结算后退款" "保证金账户退款"
apply_refund_reason	string	订单发起退款的原因
ks_refund_fail_reason	string	退款失败原因
order_amount	number	订单金额
attach	string	预下单时携带的开发者自定义信息

# 1.3.5、开发者返回内容

开发者在接收到回调消息，并正确处理后，需要返回以下内容格式，以通知小程序平台不再持续回调：

{
  "result" : 1,   //必填。 1-成功，其他-失败。失败小程序平台会尝试重推此消息
  "message_id" : "ChFvYXV0aC5hY2Nlc3NUb2tlbhJQvpR51x8In46B1sDB" //当前消息的message_id
}

如果开发者没有返回或者返回的result不等于1，则小程序平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！