统一收单交易结算接口
开发环境
开发环境
POST
/v3/alipay/trade/refund
用于在卖家交易成功之后，基于交易订单，进行卖家与第三方（如供应商或平台商）的资金再分配。一般用于第三方从卖家抽佣场景。
注意:
\1. 订单确认结算后，才可发起分账。
\2. 同一笔订单，同步分账和异步分账不能混用。如果业务上存在一次分账请求超过5个分账收款方的情况，推荐使用异步分账。
\3. 建议支付成功后间隔 30s 再发起该接口请求
\4. 单个卖家请求频率最高 30 TPS。接口报错FREQUENCY_LIMIT 请控制请求频率
\5. 如果接口调用超时或者返回ACQ.SYSTEM_ERROR ACQ.TRADE_SETTLE_ERROR 当前请求可能成功也可能失败。请使用相同的参数再次重试调用，外部请求号和金额等均不能变更。如果前一次分账已经成功，接口会幂等返回成功；如果前一次分账请求没有成功，接口会重试执行分账操作
公共错误码
业务错误码
| 状态码 | 错误码 | 错误描述 | 解决方案 |
|---|---|---|---|
| 400 | ACQ.ACCESS_FORBIDDEN | 无权限使用接口，请确认请求商户是否签约了对应的产品合约 | 请确认商户是否签约了对应的产品合约，如果未签约，请先完成产品签约 |
| 400 | ACQ.ALLOC_AMOUNT_VALIDATE_ERROR | 分账金额超过最大可分账金额 | 普通分账场景：分账金额应<=订单金额分账比例-净已分账金额； 直付通分账场景：分账金额应<=订单金额分账比例+净补差金额-净已分账金额； 请检查订单金额及分账记录，若仍有疑问，请联系支付宝小二； 小tip：若需要提升分账比例，可在支付宝商户中心（https://b.alipay.com）自助申请提升分账比例，操作路径：【支付宝商家中心b.alipay.com】->【首页】->【产品中心】->【产品签约管理】->【商家分账】->【修改信息】->【最大分账比例调整】 |
| 400 | ACQ.ALLOC_REFUSE_AFTER_REFUND | 全额退款后不允许分账 | 全额退款后不允许分账，请停止发起请求 |
| 400 | ACQ.ALLOC_REFUSE_BEFORE_SETTLE | 商家资金暂未结算，暂不支持分账 | 请在确认结算后发起分账，否则分账请求会失败 |
| 400 | ACQ.ASYNC_ALLOC_NOT_SUPPORT_IN_PERIOD | 账期内不允许异步分账 | 直付通商户签约为账期模式时，确认结算前不允许异步分账。 |
| 400 | ACQ.CUSTOMER_VALIDATE_ERROR | 账户已注销或者被冻结 | 请联系支付宝小二申诉解冻。可通过alipay.user.info.share(支付宝会员授权信息查询接口)查询账户状态user_status |
| 400 | ACQ.DISCORDANT_REPEAT_REQUEST | 请求被篡改 | 与已有请求的请求流水相同，但明细信息不同，请检查请求参数后重新发起请求 |
| 400 | ACQ.DUP_OUT_REQUEST_NO | 请求号重复 | out_request_no重复，但分账明细信息与原请求不同。 若需要发起新的分账请求，请修改out_request_no，不可重复； 若需要查原请求状态，需要保证请求信息与原订单信息完全一致，建议通过状态查询接口查询分账结果 |
| 400 | ACQ.FREQUENCY_LIMITED | 请求频率过高或账务热点 | 建议支付完成30s后再发起分账，单商户分账请求频率建议不超过30tps，同一笔订单的多笔分账请求建议间隔3s ，建议调整请求间隔后重试，如有需求，请联系支付宝小二 |
| 400 | ACQ.ILLEGAL_REQUEST | 不满足业务规则，请求被拦截 | 不满足业务规则，请根据错误描述解决 |
| 400 | ACQ.ILLEGAL_SETTLE_STATE | 结算状态非法 | 结算单所在状态不允许进行分账操作，请检查前置动作是否完成。 说明：如果签约为账期模式，需要先调确认结算接口（alipay.trade.settle.confirm）结算后才可以分账。 |
| 400 | ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数，修改后重新发起请求 |
| 400 | ACQ.INVALID_REPLENISH_AMOUNT | 补差金额错误 | 补差金额错误，请检查补差金额是否正确，补差金额不能超过外部订单金额（orig_total_amount）- 支付订单金额（total_amont） |
| 400 | ACQ.MERCHANT_RISK_LIMIT | 商户交易存在风险 | 商户存在风险，风险解除后可恢复正常交易，如有疑问可咨询支付宝小二处理。 |
| 400 | ACQ.MUST_ALLOC_FROM_ROOT_ACCOUNT | 只允许从交易的收款账户分账 | 请检查分账条款。分账只能从交易的收款账户分出，因此不需要在分账接口中传入分账支出方账户。 |
| 400 | ACQ.NOT_SUPPORT_ROYALTY | 不支持分账 | 该交易类型不支持分账操作，如有需求，请联系支付宝小二 |
| 400 | ACQ.PARTNER_ERROR | 应用APP_ID填写错误 | 请确认APP_ID的状态，如有疑问可到支持中心提问 |
| 400 | ACQ.REASON_TRADE_STATUS_INVALID | 交易状态异常 | 订单所在状态下不允许进行分账操作 |
| 400 | ACQ.REPLENISH_ACCOUNT_INVALID | 补差账户不在补差协议中 | 商户需在签约补差产品的情况下，将补差账户填入补差协议中才可进行补差操作。请先确认补差账户是否在补差协议中。 |
| 400 | ACQ.ROYALTY_ACCOUNTS_EQUAL | 分账支出方和收入方不能相同 | 请将支出方和收入方相同的分账条款剔除，再发起请求 |
| 400 | ACQ.ROYALTY_ACCOUNT_INVALID | 分账账户不支持 | 指定的账户不支持分账操作，如有需求，请联系支付宝小二 |
| 400 | ACQ.ROYALTY_ACCOUNT_NAME_NOT_MATCH | 分账收入方姓名不匹配 | 收款方姓名与支付宝账号认证姓名不一致，请核实支付宝账号信息重新发起 |
| 400 | ACQ.ROYALTY_ACCOUNT_NOT_EXIST | 分账账户不存在 | 请确认接口传入的分账账户是否正确。 说明：需确认分账账户是否已注销，若已注销需换账户重试。 |
| 400 | ACQ.ROYALTY_PAYER_ACCOUNT_NOT_CERTIFY | 付款方账号未实名 | 请在支付宝完成实名认证 实名认证操作路径： 个人用户：手机端登陆支付宝APP->我的->个人信息->身份信息->实名认证； 企业用户：PC 端登录 商家平台，完成企业支付宝认证，可查看 电脑端开通企业支付宝-操作手册。 说明：alipay.user.info.share(支付宝会员授权信息查询接口)，返回 is_certified 是否通过实名认证，T 是通过 F 是没有实名认证。 |
| 400 | ACQ.ROYALTY_PAYER_ACCOUNT_NOT_EXIST | 付款方账户不存在 | 请确认付款方账号是否正确，更换账号后重新发起 |
| 400 | ACQ.ROYALTY_PAYER_ACCOUNT_NO_BALANCE | 付款方账号无支付宝账户 | 付款方支付宝账号未开立余额账户，请确认付款方账号是否正确，更换账号后重新发起 |
| 400 | ACQ.ROYALTY_RECEIVER_ACCOUNT_NOT_CERTIFY | 收款方账号未实名 | 请在支付宝完成实名认证，或更换一个已认证账号作为收款方。实名认证操作路径： 个人用户：手机端登录支付宝客户端 > 我的 > 个人信息 > 身份信息 > 实名认证。 企业用户：PC 端登录 商家平台，完成企业支付宝认证，可查看 电脑端开通企业支付宝-操作手册。 说明：alipay.user.info.share(支付宝会员授权信息查询接口)，返回 is_certified 是否通过实名认证，T 是通过 F 是没有实名认证。 |
| 400 | ACQ.ROYALTY_RECEIVER_ACCOUNT_NOT_EXIST | 收款方账户不存在 | 收款方支付宝账号未开立余额账户，请确认收款方账号是否正确，可更换收款方账号或引导收款方开立余额账户后再重新发起。 开立余额账户操作路径： 个人用户：手机端登录支付宝客户端 > 我的 > 余额 > 补充身份信息。 企业用户：PC 端登录 商家平台，完成企业支付宝认证，可查看 电脑端开通企业支付宝-操作手册。 |
| 400 | ACQ.ROYALTY_RECEIVER_ACCOUNT_NO_BALANCE | 收款方账号无支付宝账户 | 收款方支付宝账号未开立余额账户，请确认收款方账号是否正确，更换账号后重新发起 |
| 400 | ACQ.ROYALTY_RECEIVER_INVALID | 未签约“商家分账”产品或者未添加分账关系，请签约“商家分账”产品，并通过 alipay.trade.royalty.relation.bind 接口将收入方添加到分账关系后再分账 | 未签约“商家分账”产品或者未添加分账关系，请签约“商家分账”产品，并通过 alipay.trade.royalty.relation.bind 接口将收入方添加到分账关系后再分账 |
| 400 | ACQ.SECONDARY_MERCHANT_ID_INVALID | 二级商户不存在 | 请检查传入的二级商户编号是否正确 |
| 400 | ACQ.SETTLE_ENTITY_ID_INVALID | 结算主体不存在 | 请确认接口传入的分账账户是否正确 |
| 400 | ACQ.SETTLE_SCENE_NOT_SUPPORT | 当前业务场景不支持分账 | 不支持的业务类型或者场景，请检查是否错误使用 |
| 400 | ACQ.SETTLE_TO_CARD_NOT_SUPPORT | 签约收款到银行账户场景不支持分账 | 收款到银行账户场景不支持分账，若需分账，建议解约收款到银行账户产品后再试 解约路径：登录 商家平台 > 产品中心 > 产品签约管理 > 收款到银行账户 > 解除合约。 |
| 400 | ACQ.SYSTEM_ERROR | 接口返回错误 | 接口返回系统错误情况下，当前请求可能成功也可能失败。1. 请使用相同的参数再次重试调用，外部请求号和金额等均不能变更。如果前一次分账已经成功，接口会幂等返回成功；如果前一次分账请求没有成功，接口会重试执行分账操作；2. 也可以通过 alipay.trade.order.settle.query 查询分账结果，发起查询接口需要保证间隔分账请求大于5秒以上 |
| 400 | ACQ.TRADE_NOT_EXIST | 交易不存在 | 修改交易号后，重新发起请求 |
| 400 | ACQ.TRADE_SETTLE_ERROR | 分账处理失败 | 检查分账明细后，重新发起请求 |
| 400 | ACQ.TRADE_STATUS_ERROR | 交易状态不合法 | 必须为交易成功状态才允许进行分账，请检查交易状态 |
| 400 | ACQ.TRADE_STATUS_ERROR | 交易已关闭 | 交易已关闭。请确认该笔交易是否已全额退款或未曾支付 |
| 400 | ACQ.TRADE_STATUS_ERROR | 交易已完结 | 交易已完结。该交易已经超过可结算周期，交易可结算周期在签约时设置，如果您的周期过短，请联系BD或小二改签 |
| 400 | ACQ.TXN_RESULT_ACCOUNT_BALANCE_NOT_ENOUGH | 账户余额不足 | 分账出资方账户余额不足，请确认账户余额充足后再发起重试 说明：若由于资金进入商家支付宝余额后经常会被其他任务（如余额宝自动转入）将资金转移走，导致商家余额不足无法分账。因此建议接入冻结能力，保证分账资金不被挪用，详情可查看 接入指南 |
| 400 | ACQ.UN_SUPPORT_BIZ_TYPE | 不支持的业务类型或者场景 | 不支持的业务类型或者场景，请检查是否错误使用 |
| 400 | ACQ.USER_ACCOUNT_HAD_FREEZEN | 用户账户被冻结 | 分账出资方或收入方账户被冻结，请联系支付宝小二确认冻结原因 |
| 400 | ACQ.USER_LOGONID_DUP | 收款方登录号对应多个支付宝账户 | 收款方登录号与他人重复，无法收款，建议收款方账户类型使用收款方userId，trans_in_type上送userId，或联系收款方修改登录号，与对方核对后上送新登录号。 |
关联异步通知
触发通知类型
| 通知类型 | 描述 | 默认开启 |
|---|---|---|
| tradeStatus.TRADE_SUCCESS | 支付成功 | 1 |
请求示例请求示例
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": "2015070921001004130000127422",
"settle_no": "20210718002530070036530006474222"
}请求参数
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:20:52