alipay.trade.query 中如何约定 hb_fq_pay_info 参数？

2026-10-24支付小周

结论

hb_fq_pay_info 不是需要在某个页面中配置的请求参数，而是 alipay.trade.query 返回的花呗分期信息字段。

花呗分期的期数和手续费承担方等信息，需要在发起支付时通过 extend_params 中的 hb_fq_num、hb_fq_seller_percent 等参数设置。同时，商户必须具备对应的花呗分期产品能力。

如果当前支付宝商户账号已经成功签约花呗分期，通常不需要因为查询接口返回了 hb_fq_pay_info 而重新签约。产品是否生效，应以支付宝商家平台或开放平台控制台显示的状态为准。

为什么查询接口不能设置该参数

alipay.trade.query 用于查询已经发生的交易，不能修改交易的支付方式或分期方案。

以下参数的用途不同：

hb_fq_num：在支付时指定花呗分期期数。
hb_fq_seller_percent：在支付时指定商户承担的手续费比例。
hb_fq_pay_info：查询交易时返回实际的花呗分期结果。

因此，调用 alipay.trade.query 时不能临时设置或修改 hb_fq_pay_info。

处理步骤

1. 检查花呗分期签约状态

登录对应的支付宝商家平台或开放平台控制台，在产品签约、产品管理或能力管理中查看“花呗分期”的状态。

支付宝后台菜单可能会根据账号类型和平台版本调整，不必拘泥于固定路径。主要确认以下信息：

签约主体是否与接口调用所用的 app_id 和商户主体一致；
产品状态是否已经生效；
当前支付场景是否在签约范围内；
是否存在风控、权限或产品状态异常。

如果相关能力已经生效，一般无需重复签约。如果签约主体、应用或支付场景发生变化，则需要按照控制台提示重新申请或补充配置。

2. 在支付请求中设置分期参数

以 alipay.trade.pay 为例，花呗分期参数应放在 extend_params 中：

{
  "out_trade_no": "202609090001",
  "scene": "bar_code",
  "auth_code": "用户付款码",
  "subject": "订单商品",
  "total_amount": "100.00",
  "extend_params": {
    "hb_fq_num": "3",
    "hb_fq_seller_percent": "100"
  }
}

其中：

hb_fq_num 表示分期期数。可用期数以当前支付宝接口文档和商户签约能力为准。
hb_fq_seller_percent 表示商户承担的分期手续费比例。具体取值范围和费用规则以签约协议及官方文档为准。

3. 查询交易结果

查询时只需传入支付宝交易号 trade_no，或者商户订单号 out_trade_no：

{
  "out_trade_no": "202609090001"
}

如果这笔交易实际使用了花呗分期，且接口在当前场景下会返回相关信息，响应中可能包含：

{
  "code": "10000",
  "msg": "Success",
  "out_trade_no": "202609090001",
  "trade_no": "支付宝交易号",
  "trade_status": "TRADE_SUCCESS",
  "hb_fq_pay_info": {
    "user_install_num": "3"
  }
}

该示例仅用于说明字段层级。hb_fq_pay_info 实际包含哪些子字段，以当前接口文档和真实响应为准。

没有返回 `hb_fq_pay_info` 怎么办

建议依次检查：

原支付请求是否传入了花呗分期参数；
用户最终是否使用花呗分期完成支付；
交易发生时，商户的花呗分期能力是否已经生效；
查询的订单是否属于同一商户和同一应用；
当前版本的接口是否要求通过 query_options 指定扩展返回信息。

不要自行将 hb_fq_pay_info 加入 query_options。只有当前官方接口文档明确将它列为可选值时，才能这样传递，否则可能触发参数校验错误。

注意事项

签约花呗分期并不代表每笔交易都会返回 hb_fq_pay_info。结果还取决于支付请求、用户选择和支付宝侧的判断。
查询接口返回的内容应直接作为交易结果使用，不要根据请求参数自行拼装分期结果。
沙箱与正式环境的能力、签约状态和返回内容可能不同，不能根据沙箱表现直接推断正式环境的情况。
如果控制台显示已经签约，但正式交易始终无法使用花呗分期，应携带 app_id、商户订单号、支付宝交易号，以及接口响应中的 sub_code、sub_msg，联系支付宝技术支持核查，无需直接重复签约。