通用场景
订单售后退款
公共请求参数
业务请求参数
out_refund_id｜外部退款流水号必选string[1,128]
【描述】外部退款流水号,标识一次退款请求，需要保证在订单号下唯一。
注：针对同一次退款请求，如果调用接口失败或异常了，重试时需要保证退款流水号不能变更，防止该笔交易重复退款。支付宝会保证同样的退款流水号多次请求只会退一次。
【示例值】2023032501502300000001520000019936
refund｜退款金额必选string[1,11]
【描述】退款金额,单位：元，精确到小数点后两位
【示例值】88.88
以下参数 二选一 传入必选
order_id｜交易组件订单号string[1,128]
【描述】交易组件订单号；order_id和out_order_id二选一
【示例值】2015042321001004720200028594
out_order_id｜商户订单号string[1,64]
【描述】商户订单号，创建订单请求由商户传入；order_id和out_order_id二选一
【示例值】6823789339978248
以下参数 二选一 传入
user_id｜买家支付宝用户idstring[1,32]
【描述】买家支付宝用户id；open_id和user_id二选一
新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088***
open_id｜用户open_idstring[1,128]
【描述】买家open_id；open_id和user_id二选一 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
installment_order_id｜分期单id可选string
【描述】分期单号,指定分期退款的时候需要传入
【示例值】2015042321001004720200028594
refund_reason｜退款原因可选string[1,256]
【描述】退款原因说明。
商家自定义，将会在商户和用户的pc退款账单详情中展示
【示例值】正常退款
item_infos｜退款商品信息可选array
【描述】部分商品退款信息
period_list｜分期列表条件必选array[1,1]
【描述】分期数
【必选条件】当订单模板类型为regular_go时,必须传入分期数，本次只支持单次分期退款
【示例值】["1"]
out_item_id｜商户商品id可选string[1,64]
【描述】商户商品id
【示例值】123
out_sku_id｜商户商品sku_id可选string[1,64]
【描述】商户商品sku_id,提报商品库的商品，sku维度的商品该字段必传
【示例值】34567576565656
refund_amount｜商品退款金额可选string[1,11]
【描述】商品退款金额，单位：元，精确到小数点后两位
【示例值】12.88
goods_id｜商品的编号可选string[1,32]
【描述】商户侧商品的编号，应与alipay.open.mini.order.create接口所传的商品goods_id保持一致
【示例值】1234567
certificate_info｜商品退款凭证信息可选minirefundcertificatedto
【描述】商品退款凭证信息，在本地生活等场景下，需要填入凭证号进行退款。
certificate_id｜商品对应的凭证id必选string[28,28]
【描述】本地商品对应的凭证id
【示例值】2023052700445005718800000190
常见请求示例
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.open.mini.order.refund&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'app_auth_token=${app_auth_token}' \
-f 'biz_content={
"order_id":"2015042321001004720200028594",
"out_order_id":"6823789339978248",
"out_refund_id":"2023032501502300000001520000019936",
"installment_order_id":"2015042321001004720200028594",
"user_id":"2088***",
"open_id":"074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5",
"refund":"88.88",
"refund_reason":"正常退款",
"item_infos":[
{
"out_sku_id":"34567576565656",
"out_item_id":"123",
"refund_amount":"12.88",
"goods_id":"1234567",
"period_list":[
"1"
],
"certificate_info":{
"certificate_id":"2023052700445005718800000190"
}
}
]
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
refund_id｜退款id必选string(34)
【描述】退款id
【示例值】2023032501502300000001520000019936
send_back_fee｜退款金额可选string(11)
【描述】本次商户实际退回金额,单位"元"
【示例值】1.88
响应示例
正常示例
异常示例
{
"alipay_open_mini_order_refund_response": {
"code": "10000",
"msg": "success",
"refund_id": "2023032501502300000001520000019936",
"send_back_fee": "1.88"
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| invalid_parameter | 参数有误 | 请根据接口返回的参数非法的具体错误信息，修改参数后进行重试 |
| group_buy_not_refund | 拼团中不能退款 | 拼团成功或者失败后退款 |
| item_not_match | 商品id信息与已存商品id信息不匹配 | 请检查商品信息是否和下单时的一致 |
| mrch_order_error | 订单处理错误退款失败 | 退款失败 |
| order_id_not_exist | 订单号不存在 | 请填写正确的订单号 |
| security_check_failed | 安全检查失败。该操作存在安全风险。 | 风控安全检测失败，请检查该笔操作是否存在安全风险。 |
| seller_balance_not_enough | 商家余额不足 | 商家账户余额不足，请商家先充值之后再发起退款。 |