退款能力

更新时间：2024-08-07 14:10:59

1. 申请退款

1.1 接口说明

1. 可通过该接口发起签约支付单和代扣单退款，请注意
   1. 平台仅受理最近半年(180天)的退款
2. 退款回调地址会优先使用开发者在 退款接口 传入的 notify_url，如果退款接口没有传入，会填充开发者在开发者平台设置的 退款回调，该回调地址设置与查看步骤如下【小程序开发者平台 (opens new window) -> 交易管理 -> 支付管理 -> 支付设置 -> 默认回调地址】

1.2 基本信息

名称	内容
HTTP URL	https://open.kuaishou.com/openapi/mp/developer/epay/apply_contract_refund
HTTP Method	POST
Scope	需要具有小程序担保支付权限(scope.ks.epay)

1.3 请求头

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

1.4  请求参数

以下字段放在 query param 处：

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

以下字段放在 body json 处：

字段名	类型	是否必填	是否参与签名	说明
out_refund_no	string[6,32]	是	是	开发者的退款单号
out_order_no	string	否	是	开发者需要发起退款的支付订单号，商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一 示例值：2217752501201407033233368018
ks_withhold_no	string	否	是	快手小程序平台代扣订单号，即代扣回调里的订单号
ks_order_type	number	是	是	退款类型： 1 :  申请 周期代扣单 退款，需要传入代扣单号 ks_withhold_no 2 :  申请 支付并签约时的订单 退款，需传入商户系统的订单号 out_order_no
reason	string[1,80]	是	是	退款理由。1个汉字=2个字符
notify_url	string[1,256]	否	是	通知URL必须为直接可访问的URL，不允许携带查询串。
refund_amount	number	是	是	用户退款金额，单位为分。不允许传非整数的数值
attach	string[0,80]	否	是	开发者自定义字段，回调原样回传.1汉字=2字符；勿回传敏感信息
sign	string	是	否	开发者对核心字段签名, 防止传输过程中出现意外，签名方式见附录

1.5  请求示例

签约支付单退款示例

curl --location --request POST 'https://open.kuaishou.com/openapi/openapi/mp/developer/epay/apply_contract_refund?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJQUgLJCcZ8npmot-ZdBgcCP637mttUoYGPEv5RgFI_lqJlvIh3senYMleV49N05OT_0YztFVI9_rR21eJdx1hiqgHw4eYYvGbgH48yE5qGIlsaEkM6eJkoPbfUa_qSANYID35L6iIgnCb8d_k_DugrMbDIxWRiQmhOLrCCvktr7pdmDdTWDv0oDzAB' \
--header 'Content-Type: application/json' \
--data-raw '{
    "out_order_no":"1703148876761contractDemo",
    "out_refund_no":"1703148876761",
    "reason":"支付签约退款",
    "ks_order_type":2,
    "ks_withhold_no":"",
    "attach":"退款demo",
    "notify_url":"https://www.abidu.com/refund_notify",
    "refund_amount":"1",
    "sign":"4ef5bceef3e4fd8e79cd83c262c076c2"
}'

代扣单退款请求示例

curl --location --request POST 'https://open.kuaishou.com/openapi/openapi/mp/developer/epay/apply_contract_refund?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJQUgLJCcZ8npmot-ZdBgcCP637mttUoYGPEv5RgFI_lqJlvIh3senYMleV49N05OT_0YztFVI9_rR21eJdx1hiqgHw4eYYvGbgH48yE5qGIlsaEkM6eJkoPbfUa_qSANYID35L6iIgnCb8d_k_DugrMbDIxWRiQmhOLrCCvktr7pdmDdTWDv0oDzAB' \
--header 'Content-Type: application/json' \
--data-raw '{
    "out_order_no":"1703148876761contractDemo",
    "out_refund_no":"1703148876761",
    "reason":"支付签约退款",
    "ks_order_type":1,
    "ks_withhold_no":"624010201147476465250",
    "attach":"退款demo",
    "notify_url":"https://www.abidu.com/refund_notify",
    "refund_amount":"1",
    "sign":"4ef5bceef3e4fd8e79cd83c262c076c2"
}'

1.6 响应结果

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

字段名	类型	说明
result	number	状态码 1-业务处理成功
error_msg	string	错误提示信息
refund_no	string	快手小程序平台的退款单号

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误信息提示",
    "refund_no": "221072611585202788127" //快手小程序平台退款单号

当 result 不为 1 时，说明请求错误，错误信息详见文章末尾 错误码 处。

2. 退款回调

2.1 接口说明

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

由于网络波动等原因，可能会产生重复的通知消息，开发者需要做好幂等处理。

在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败并进行重试。

退款回调的地址是 申请退款接口中的 notify_url 字段，所以请务必保证该字段传输的正确性

2.2 基本信息

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

2.3  平台回调内容

以下字段放置到 body json中：

{
    "data": {
        "out_refund_no": "0007",
        "refund_amount": 1234,
        "attach": "this is some attach",
        "status": "SUCCESS",
        "ks_order_no": "121111200785144945641",
        "ks_refund_no": "221111211991390142641",
        "refund_type":"保证金账户退款",
        "ks_refund_fail_reason":"账户异常",
        "apply_refund_reason":"用户申请退款"
    },
    "message_id": "61901a3a-2b1f-40b6-af14-de34660d7541",
    "biz_type": "REFUND",
    "app_id": "ks656399649443988986",
    "timestamp": 1625728322061
}

其中和退款相关的主要是

字段名	类型	说明
refund_amount	number	退款金额
out_refund_no	string	开发者的退款单号。
attach	string	预下单时携带的开发者自定义信息
status	string	退款状态。 取值： PROCESSING-处理中，SUCCESS-成功，FAILED-失败
ks_order_no	string	快手小程序平台订单号。
ks_refund_no	string	快手小程序平台退款单号。
refund_type	string	退款账户说明
ks_refund_fail_reason	string	退款失败原因
apply_refund_reason	string	订单发起退款的原因

2.4 开发者返回内容

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

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

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

错误码

错误码	描述	排查建议
10000011	token 过期	调用 getAccessToken 重新生成 token
10000200	参数错误	对照错误提示和接口字段定义，检查对应的参数
10000302	请求频率太快，被限速。	请降低访问频率
10000500	系统故障	请联系相关开发人员进行排查
10000501	稍后重试	请等待1-2秒，再重试
10000606	接口参数签名错误	对照接口字段，检查签名字段是否正确
10000607	不合理的订单金额	请检查传入的订单金额是否合理
10000632	平台内部错误	请联系相关开发人员进行排查
10000627	平台退款处理异常	请联系相关开发人员进行排查
10000631	配置错误	请检查在小程序平台的支付信息是否完善
10000687	当前有正在退款中的订单	已存在受理中的订单
10000689	保证金账户余额不足	保证金余额不足，请充值保证金