SDK 中如何传递 extend_params.royalty_freeze 参数？

2026-10-24支付阿杰

结论

extend_params.royalty_freeze 不属于 RoyaltyInfo，两者不能相互替代。通过 SDK 调用支付接口时，需要把 royalty_freeze 放在 extend_params 对象中，并随完整的 biz_content 一起提交。

如果当前 SDK 的强类型模型没有提供这个字段，可以直接构造 biz_content JSON。也可以升级 SDK，查看新版模型是否已经支持 extend_params。

参数结构

请求结构如下：

{
  "out_trade_no": "202609120001",
  "total_amount": "100.00",
  "subject": "订单标题",
  "extend_params": {
    "royalty_freeze": "true"
  }
}

RoyaltyInfo 用来描述分账明细和分账参与方等信息，extend_params.royalty_freeze 则是扩展控制参数。虽然两者都与分账有关，但用途不同，不能混用。

Java SDK 示例

如果 SDK 模型没有对应的 setter，可以不使用缺少字段的强类型模型，直接设置 biz_content：

AlipayTradePayRequest request = new AlipayTradePayRequest();

JSONObject bizContent = new JSONObject();
bizContent.put("out_trade_no", "202609120001");
bizContent.put("scene", "bar_code");
bizContent.put("auth_code", "用户付款码");
bizContent.put("subject", "订单标题");
bizContent.put("total_amount", "100.00");

JSONObject extendParams = new JSONObject();
extendParams.put("royalty_freeze", "true");

bizContent.put("extend_params", extendParams);

request.setBizContent(bizContent.toJSONString());

AlipayTradePayResponse response = alipayClient.execute(request);

有些 SDK 提供了 setExtendParams，但接收的参数类型是字符串。这种情况下，可以传入序列化后的 JSON：

JSONObject extendParams = new JSONObject();
extendParams.put("royalty_freeze", "true");

model.setExtendParams(extendParams.toJSONString());
request.setBizModel(model);

应该使用 setBizContent 还是 setBizModel，要看当前 SDK 版本以及对应接口模型的定义。

PHP SDK 示例

$bizContent = [
    'out_trade_no' => '202609120001',
    'scene' => 'bar_code',
    'auth_code' => '用户付款码',
    'subject' => '订单标题',
    'total_amount' => '100.00',
    'extend_params' => [
        'royalty_freeze' => 'true',
    ],
];

$request->setBizContent(
    json_encode($bizContent, JSON_UNESCAPED_UNICODE)
);

注意事项

royalty_freeze 必须放在 extend_params 内，不能作为 biz_content 的一级字段提交。
不要将它写入 RoyaltyInfo，否则 SDK 可能会忽略该参数，或者生成不符合接口要求的请求结构。
参数值需要严格遵循对应支付接口文档。如果文档要求字符串，就应使用 "true"，不要自行改为 JSON 布尔值 true。
extend_params 通常属于业务参数 biz_content，不应将整个对象添加为公共请求参数。
同时使用 RoyaltyInfo 和 extend_params.royalty_freeze 时，需要分别设置，并检查最终生成的 biz_content 是否同时包含这两部分数据。
不同支付接口、产品权限和 SDK 版本可能有所不同。提交前，应以当前接口文档中的请求示例和实际 SDK 方法签名为准。如果接口文档支持该字段，但 SDK 模型没有提供，直接构造 biz_content JSON 通常更适合兼容现有接口。