支付宝分账技术接入开发及代码接口实例详解

1 支付宝分账业务的场景

资金结算给二级商户后，平台商根据与二级商户约定的分账比例，将资金分到分账接收方。一般用于平台向二级商户抽佣场景。支付宝、微信、在线支付分账系统开发技术交流，欢迎和李铁牛程序员交流。

2 支付宝分账术语解释

分账发起方：发起分账的一方，这里指平台商；

分账支出方：分账资金的转出方。二级商户不需要签署分账协议即可分账。

分账接收方：接收分账资金的一方，平台商已被默认添加为接收方，二级商户可直接向平台商进行分账；其他接收方，平台商通过分账关系绑定接口，建立平台维度统一的 分账接收方列表，添加成功后，所有二级商户均可向其分账。分账接收方必须为实名认证的支付宝账户。

分账关系集：平台维度统一的 分账接收方列表，又称为 分账关系集。使用分账产品，需要将分账接收方维护在 分账关系集 内，否则分账会被拦截。可以通过分账关系维护接口来完成 分账关系集 的添加、删除和查询。

3 支付宝分账的功能进阶

默认情况下为同步分账模式，调用分账接口后，支付宝实时进行分账处理，分账接口同步返回分账的最终结果。同步分账对请求频率、单次传入的分账收款方有限制。如果分账频率超过30tps，或者单次分账的收款方超过 5 个，建议接入异步分账。

支付宝分账接入模式：

• 同步模式：调用分账接口后，支付宝实时进行分账处理，分账接口同步返回分账的最终结果。
• 异步模式：调用分账接口后，支付宝先受理分账请求，异步进行分账处理，分账处理结果请通过分账查询接口或者分账异步通知消息获取最终的分账结果。

3.1 同步模式及异步模式差异说明

分账接入模式	同步模式	异步模式
一笔订单最多可以发起多少次分账请求	50次	300 次
一笔分账请求最多可以传入多少个分账收款方	5	50
一笔分账请求传入多个分账收款方时，分账失败处理规则	一个收款方失败则全部失败，即只能全部成功或全部失败。	一个收款方失败，其他仍可成功，即可部分成功、部分失败。
分账结果获取方式	以分账同步返回结果为准。	以分账查询/异步通知结果为准。
单商户分账请求频率	最高 30tps/s。	最高 500tps/s。
模式特点	适用分账请求较少场景，技术集成简单。	适用分账请求较多，需要高分账性能保障的场景。

4 支付宝分账接入步骤

建议平台商在确认结算时，先进行资金冻结。保证分账时，二级商户支付宝余额的资金不被挪用。对于二级商户结算到卡场景，无需冻结，可以不传入分账冻结标识（结算到卡场景若上传冻结标识不生效）。

4.1 绑定分账关系

平台商作为分账收款方，不需要添加分账关系，可以直接从二级商户分账。如果需要分账给其他支付宝账号，需要通过 alipay.trade.royalty.relation.bind（分账关系绑定接口），将分账接收方添加到分账关系集中。分账关系集最多添加 20000 个。绑定分账关系时，不需要二级商户确认。

4.2 收单结算

交易收款 后，平台商通过 资金结算 的 alipay.trade.settle.confirm（统一收单确认结算接口）确认结算时，如果传入冻结标识 royalty_freeze=true，资金结算到商家支付宝余额后，会先处于冻结状态，冻结在不可用余额中，直到平台商触发解冻或超时自动解冻（系统默认在冻结 30 天后自动解冻）。

若不需要冻结，不需要传入 royalty_freeze。

4.3 分账剩余金额查询

分账请求前，可以同步获取分账剩余金额结果。如有需求，可通过 alipay.trade.order.onsettle.query（分账剩余金额查询接口）查询分账剩余金额。

4.4 分账

平台商通过 alipay.trade.settle.confirm（统一收单确认结算接口）确认结算后，通过 alipay.trade.order.settle（统一收单交易结算接口）发起分账请求，支持多次分账。分账收款方只支持实名认证的支付宝账号。在分账关系绑定后，如果分账收款方注销，则无法继续作为分账收款方。

前提条件：

• 同步分账：royalty_mode 无需设置，分账全部同时成功或失败，不触发异步，通过 alipay.trade.order.settle.query（交易分账查询接口）查询分账状态。
• 异步分账：royalty_mode=async，分账允许部分成功部分失败，商家可通过监听 alipay.trade.order.settle.notify（交易分账结果通知接口）接口接收异步分账通知，获取分账明细和状态。其中，在结果返回中，msg_type = ASYNC_SETTLE_RESULT 代表此通知为异步分账结果通知。
• 分账金额以平台商传入的为准，不支持按比例自动分账。值得注意的是，支付宝对于最高分账金额有管控。不能超过订单总金额（total_amont）的 30% + 已补差金额。（可通过 alipay.trade.royalty.rate.query（分账比例查询）查询账户最高分账比例）
• 分账时，支付宝会自动判断本笔订单是否有分账冻结。如果存在冻结，系统会自动将本次分账资金解冻后再转出。
• 可以查询 alipay.trade.query（统一收单线下交易查询），只有 trade_status 为 TRADE_SUCCESS（交易成功），允许分账。默认情况下，分账有效期最长不超过 12 个月，超期不允许分账。

4.5 分账解冻

确认结算时，如果传递了分账冻结标识，则需要对剩余冻结资金解冻。可在最后一笔分账请求时同时传入分账完结标识（royalty_finish=true），则本次分账成功后会自动将剩余资金解冻；也可通过调用分账接口，不传入分账条款，只传入分账完结标识完成剩余资金解冻。

• 若商家不主动发起分账解冻请求，系统默认在 30 天后将剩余资金解冻并将解冻结果进行通知。商家可通过监听 alipay.trade.order.settle.notify（交易分账结果通知）接口接收通知消息，其中 msg_type = AUTO_SETTLE_FINISH 代表超期自动分账解冻。
• 解冻后仍可发起分账，二级商户支付宝余额账号有资金即可分账成功，若余额不足则分账失败。

分账场景，同时上送完结标识，将剩余资金解冻：

{
  "biz_content": {
    "out_request_no": "settle201804120000",
    "trade_no": "2018040321001004090500070489",
    "royalty_parameters": [{
      "trans_in_type": "loginName",
      "trans_in": "[email protected]",
      "amount": 20,
      "desc": "1.1日物流服务费"
    }],
    "extend_params": {
      "royalty_finish": "true"
    }
  }
}

不分账，单独发起完结请求，将剩余资金解冻：

{
  "biz_content": {
    "out_request_no": "settle201804120000",
    "trade_no": "2018040321001004090500070489",
    "extend_params": {
      "royalty_finish": "true"
    }
  }
}

4.6 分账查询

分账请求提交后，可以同步获取到结果。后续如果有需要，可以通过alipay.trade.order.settle.query（交易分账查询接口）查询分账状态。

alipay.trade.query（统一收单线下交易查询接口）上送query_options=trade_settle_info，响应参数 trade_settle_info 返回 trade_no 关联所有分账信息。

4.7 退分账

若已分账资金需要退回，通过 alipay.trade.refund（统一收单交易退款接口）申请分账资金退回。退款接口允许只退分账，具体传参可查看退款接口入参示例。

5 支付宝分账规则

1. 平台商通过 alipay.trade.settle.confirm（统一收单确认结算接口）完成结算后，通过 alipay.trade.order.settle（统一收单交易结算接口）发起分账请求，支持多次分账。
   注意：必须在确认结算后才可分账，结算前不支持分账。
2. 最高分账金额不能超过订单总金额（total_amont）的 30% + 已补差金额，分账有效期最长 365 天。
3. 分账绑定和分账操作要求分账收入方支付宝账户必须实名注册，若未实名或注销账户则操作失败。
4. 确认结算（alipay.trade.settle.confirm）后需要等待 30s 再发起分账。单个商户分账请求频率最高 30 qps。基于同一笔订单的多次分账请求建议间隔 3s。
5. 使用分账冻结后，分账、退款、退补差时优先从冻结余额出资。若冻结余额不足，先将冻结资金全部解冻，从支付宝余额出资。退款同时退分账场景下，如退分账金额<退款金额，则出资顺序：则退分账资金优先出资，剩余部分按冻结资金>可用余额顺序补足。如退分账请求金额=退款金额，则出资顺序：退分账金额。
6. 若冻结资金已解冻，仍可以从余额户发起分账，只要在分账有效期且分账金额不超过最大可分账金额即可发起分账。
7. 分账时若接口返回 ACQ.MERCHANT_RISK_LIMIT（商户交易存在风险），建议二级商户电话联系 4007585858。
8. 分账资金流程

• • 结算到户分账资金流程：

    

  • 结算到卡分账资金流程：

    

异步模式的接入方式：

1. alipay.trade.order.settle（统一收单交易结算接口）指定异步。royalty_mode不传时，默认同步执行。传async表示先受理，支付宝内部异步执行。此时异步分账请求拿不到最终分账结果。
2. 可以通过 alipay.trade.order.settle.notify（交易分账结果通知接口），或者 alipay.trade.query（统一收单线下交易查询接口）获取分账结果

6 支付宝分账接口说明

6.1 API 列表

分账关系维护接口：

接口英文名	接口中文名	备注
alipay.trade.royalty.relation.bind	分账关系绑定	将分账收入方添加到分账关系集
alipay.trade.royalty.relation.unbind	分账关系解绑	将分账收入方从分账关系集中移除
alipay.trade.royalty.relation.batchquery	分账关系查询	查询分账收入方的绑定关系

分账请求接口：

接口英文名	接口中文名	备注
alipay.trade.order.settle	统一收单交易结算接口	分账请求接口

分账查询接口：

接口英文名	接口中文名	备注
alipay.trade.order.settle.query	交易分账查询接口	分账查询接口，查询一笔分账请求的分账结果
alipay.trade.royalty.rate.query	分账比例查询	查询账户最高分账比例
alipay.trade.query	统一收单线下交易查询	分账查询接口，可查看交易下的所有分账明细(同时也包含查询交易基本信息)
alipay.trade.order.onsettle.query	分账剩余金额查询接口	查询分账剩余金额信息

分账结果异步通知：

接口英文名	接口中文名	备注
alipay.trade.order.settle.notify	交易分账结果通知	开发者平台订阅后可接收分账结果消息。异步模式时建议必须接入，及时获取最终分账结果。

退分账接口：

接口英文名	接口中文名	备注
alipay.trade.refund	统一收单交易退款接口	用于卖家与第三方（如供应商或平台商）基于交易金额的退分佣信息。通过 refund_royalty_parameters 传递退分佣信息。

6.2 使用示例

注意：

• 请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。
• 分账只能从交易的收款账户分出，因此不需要在分账接口中传入分账支出方账户。

以 alipay.trade.order.settle 接口为例：

关键字段	描述	备注
royalty_mode	分账模式	同步执行：sync。 异步执行：async。 不传默认同步执行。
royalty_parameters	正向分账条款明细信息	复杂类型,需要指定资金处理类型 royalty_type 和目标账户 trans_in。 若冻结场景只想发起分账完结，不做分账，则分账参数不需要传入。
–royalty_type	分账类型	分账为：transfer；可为空，为空时默认为分账。
–trans_out_type	支出方账户类型	本场景不允许传入。
–trans_out	支出方账户	本场景不允许传入。
–trans_in_type	分账收入方账户类型	userId：表示是支付宝账号对应的支付宝唯一用户号。 loginName：表示是支付宝登录号。
–trans_in	分账收入方账户	trans_in_type 传入 userId：本参数为收入方的支付宝账号对应的支付宝唯一用户号，以 2088 开头的纯 16 位数字。 trans_in_type 传入 loginName：本参数为收入方的支付宝登录号。
–amount	分账金额	本次分账要分出的金额。
–desc	分账描述	会在分账收入方/分账付款方支付宝账户 余额明细 备注字段中展示。
extend_params
–royalty_finish	分账完结标识	完结：true。 不完结：false。

7 支付宝分账异步通知

1. 商家在应用的解决方案中添加 互联网平台直付通解决方案，产品绑定中含有 商家分账。
2. 在开发设置的 FROM 平台订阅订阅 alipay.trade.order.settle.notify（交易分账结果通知）。
3. 本消息接口同时支持 http(s) 方式和支持 WebSocket 长连接，若选择HTTP接入模式需额外设置 应用网关地址 作为通知接收地址。
4. 异步分账成功后，同时会触发 alipay.trade.order.settle.notify（交易分账结果通知）消息 API。
5. 验签：商户系统接收到异步通知以后，必须通过验签（验证通知中的 sign 参数）来确保支付通知是由支付宝发送的。

• 详细验签规则以及自验签流程参考 异步通知验签。
• http(s) 方式官方 SDK 请求接收验签可参考 SDK 接收以及验签示例代码。

详情可查看 订阅消息 指引。

注意：同步分账不触发 alipay.trade.order.settle.notify（交易分账结果通知）。