统一收单交易退款接口
开发环境
开发环境
POST
/v3/alipay/trade/refund
交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款。
支付宝退款支持单笔交易分多次退款，多次退款需要提交原支付订单的订单号和设置不同的退款请求号。一笔退款失败后重新提交，要保证重试时退款请求号不能变更，防止该笔交易重复退款。
同一笔交易累计提交的退款金额不能超过原始交易总金额。
\2. 请严格按照接口文档中的参数进行接入。若在此接口中传入【非当前接口文档中的参数】会造成【退款失败或重复退款】。
\3. 该接口不可与其他退款产品混用。若商户侧同一笔退款请求已使用了当前接口退款的情况下，【再使用其他退款产品进行退款】可能会造成【重复退款】。
\4. 退款成功判断说明：接口返回fund_change=Y为退款成功，fund_change=N或无此字段值返回时需通过退款查询 接口进一步确认退款状态。详见退款成功判断指导。注意，接口中code=10000，仅代表本次退款请求成功，不代表退款成功。
错误码
公共错误码
业务错误码
| 状态码 | 错误码 | 错误描述 | 解决方案 |
|---|---|---|---|
| 400 | ACQ.ALLOC_AMOUNT_VALIDATE_ERROR | 退分账金额超限 | 请调整退分账金额后重试 |
| 400 | ACQ.BUYER_ENABLE_STATUS_FORBID | 买家状态异常 | 联系支付宝小二确认买家状态异常原因，或者可联系买家进行线下退款处理 |
| 400 | ACQ.BUYER_ERROR | 买家状态异常 | 联系支付宝小二确认买家状态异常原因，或者可联系买家进行线下退款处理 |
| 400 | ACQ.BUYER_NOT_EXIST | 买家不存在 | 买家已经注销账号，建议联系买家进行线下退款处理 |
| 400 | ACQ.CURRENCY_NOT_SUPPORT | 退款币种不支持 | 请确认传入的退款币种是否正确 |
| 400 | ACQ.CUSTOMER_VALIDATE_ERROR | 账户已注销或者被冻结 | 请查询账户状态：1. 如果账户已注销，请线下处理；2. 如果账户已冻结，请联系支付宝小二确认冻结原因。 |
| 400 | ACQ.DISCORDANT_REPEAT_REQUEST | 请求信息不一致 | 退款请求号对应的退款已经执行成功，且本次请求的退款金额与之前请求的金额不一致，请检查传入的退款金额是否正确。 或者通过退款查询接口获取退款执行结果。 |
| 400 | ACQ.ENTERPRISE_PAY_BIZ_ERROR | 因公付业务异常 | 如果提示“当前交易不含企业出资”，请确认交易是否包含企业出资，如果不包含则接口入参不能指定enterprise_pay_info参数，如果确认包含则联系支付宝核实。 如果提示“无效企业退款金额”，请检查指定的企业退款金额是否超过当前交易企业支付的金额。 其它情况，请联系支付宝小二。 |
| 400 | ACQ.INVALID_PARAMETER | 参数无效 | 请根据接口返回的错误信息，检查请求参数，修改后重新发起请求 |
| 400 | ACQ.NOT_ALLOW_PARTIAL_REFUND | 不支持部分退款 | 由于交易使用了特定的优惠券等场景，该笔交易不支持部分退款，请对交易进行全额退款或者联系买家 进行线下退款处理 |
| 400 | ACQ.ONLINE_TRADE_VOUCHER_NOT_ALLOW_REFUND | 交易不允许退款 | 此交易中核销了购买的代金券，不允许进行退款，可联系买家进行线下退款处理 |
| 400 | ACQ.OVERDRAFT_AGREEMENT_NOT_MATCH | 垫资退款接口传入模式和签约配置不一致 | 请检查垫资退款合约中的出资方式，修改合约或接口传参后重试 |
| 400 | ACQ.OVERDRAFT_ASSIGN_ACCOUNT_INVALID | 垫资退款出资账号和商户信息不一致 | 垫资退款出资账号必须为商户名下支付宝账号，请更换出资账号后重试 |
| 400 | ACQ.REASON_TRADE_BEEN_FREEZEN | 请求退款的交易被冻结 | 联系支付宝小二，确认该笔交易的具体情况 |
| 400 | ACQ.REASON_TRADE_REFUND_FEE_ERR | 退款金额无效 | 同一笔交易累计请求的退款金额不能大于交易总金额，请检查退款请求的金额是否正确。 |
| 400 | ACQ.REASON_TRADE_STATUS_INVALID | 交易状态异常 | 查询交易，确认交易是否是支付成功状态，是的话可联系支付宝小二确认交易状态 |
| 400 | ACQ.REFUND_ACCOUNT_NOT_EXIST | 退款出资账号不存在或账号异常 | 检查退款出资账号状态，账号正常后重试 |
| 400 | ACQ.REFUND_AMT_NOT_EQUAL_TOTAL | 退款金额超限 | 1、请检查退款金额 是否正确，请求的退款金额不能大于交易总金额； 2、如果不是全额退款，退款请求号必填，请检查是否传入了退款请求号； |
| 400 | ACQ.REFUND_CHARGE_ERROR | 退收费异常 | 请过一段时间后再重试发起退款 |
| 400 | ACQ.REFUND_FEE_ERROR | 交易退款金额有误 | 请检查传入的退款金额是否正确 |
| 400 | ACQ.REFUND_ROYALTY_PAYEE_ACCOUNT_NOT_EXIST | 退分账收入方账户不存在 | 退分账收入方账户不存在，请确认收入方账号是否正确，更换账号后重新发起 |
| 400 | ACQ.SELLER_BALANCE_NOT_ENOUGH | 卖家余额不足 | 商户支付宝账户充值后重新发起退款即可 |
| 400 | ACQ.SYSTEM_ERROR | 系统错误 | 接口返回系统错误情况下，当前请求的退款可能成功也可能失败。 1、请使用相同的参数再次重试调用，需要保证退款请求号和退款金额不能变更。如果前一次退款请求已经处理成功，接口会幂等返回成功；如果前一次退款请求没有成功，接口会重试执行退款操作； 2、或者通过退款查询接口查询退款执行结果，发起退款查询接口需要保证间隔退款请求大于5秒以上； |
| 400 | ACQ.TRADE_HAS_CLOSE | 交易已关闭 | 该交易已关闭，不能再进行退款，请确认请求退款的交易是否未支付或者已完成退款 |
| 400 | ACQ.TRADE_HAS_FINISHED | 交易已完结 | 该交易已完结（已超过退款期限），不允许进行退款（即使重试也无法成功），建议联系买家进行线下退款处理。 |
| 400 | ACQ.TRADE_NOT_ALLOW_REFUND | 当前交易不允许退款 | 检查当前交易的状态是否为交易成功状态以及签约的退款属性是否允许退款，确认后，重新发起请求 |
| 400 | ACQ.TRADE_NOT_EXIST | 交易不存在 | 检查请求中的交易号和商户订单号是否正确，确认后重新发起 |
| 400 | ACQ.TRADE_SETTLE_ERROR | 交易结算异常 | 请检查传入的退结算项信息是否正确，如果正确请联系支付宝小二 |
| 400 | ACQ.TRADE_STATUS_ERROR | 交易状态非法 | 查询交易，确认交易是否已经付款 |
| 400 | ACQ.USER_NOT_MATCH_ERR | 交易用户不匹配 | 请联系支付宝小二处理 |
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST 'http://dev-cn.your-api-server.com/v3/alipay/trade/refund' \
--header 'authorization: ALIPAY-SHA256withRSA app_id=$appid,timestamp=$now,nonce=$uuid,expired_seconds=600,sign=$sign' \
--header 'alipay-request-id: $requestid' \
--header 'Content-Type: application/json' \
--data-raw '{
"out_trade_no":"20150320010101001",
"trade_no":"2014112611001004680073956707",
"refund_amount":200.12,
"refund_reason":"正常退款",
"out_request_no":"HZ01RF001",
"refund_goods_detail":[
{
"goods_id":"apple-01",
"refund_amount":19.50,
"out_item_id":"outItem_01",
"out_sku_id":"outSku_01"
}
],
"refund_royalty_parameters":[
{
"royalty_type":"transfer",
"trans_out":"2088101126765726",
"trans_out_type":"userId",
"trans_in_type":"userId",
"trans_in":"2088101126708402",
"amount":0.1,
"desc":"分账给2088101126708402",
"royalty_scene":"达人佣金",
"trans_in_name":"张三"
}
],
"query_options":[
"refund_detail_item_list"
]
}'响应示例响应示例
200 - 成功示例
{
"trade_no": "2013112011001004330000121536",
"out_trade_no": "6823789339978248",
"buyer_logon_id": "159****5620",
"fund_change": "Y",
"refund_fee": 88.88,
"refund_detail_item_list": [
{
"fund_channel": "ALIPAYACCOUNT",
"amount": 10,
"real_amount": 11.21,
"fund_type": "DEBIT_CARD"
}
],
"store_name": "望湘园联洋店",
"buyer_user_id": "2088101117955611",
"send_back_fee": "1.8",
"refund_hyb_amount": "10.24",
"refund_charge_info_list": [
{
"refund_charge_fee": 0.01,
"switch_fee_rate": "0.01",
"charge_type": "trade",
"refund_sub_fee_detail_list": [
{
"refund_charge_fee": 0.1,
"switch_fee_rate": "0.01"
}
]
}
]
}请求参数
Header 参数
authorization
string
必需
示例值:
ALIPAY-SHA256withRSA app_id=$appid,timestamp=$now,nonce=$uuid,expired_seconds=600,sign=$sign
alipay-request-id
string
必需
示例值:
$requestid
Content-Type
string
必需
示例值:
application/json
Body 参数application/json
返回响应
修改于 2023-11-20 08:06:44