PAYATHON 2026

商户如何判断支付宝支付单是否使用花呗分期？

支付阿杰

结论

要判断已支付订单是否实际使用了花呗分期，可在交易成功后调用 alipay.trade.query，查看响应中的 hb_fq_pay_info：

  • 如果存在 hb_fq_pay_info.user_install_num，且值是有效的分期期数，如 3、6、12，说明买家实际使用了花呗分期。
  • 如果该字段不存在或为空，通常说明订单未使用花呗分期，但还需根据当前接入产品和支付宝开放平台对应接口文档确认。
  • fund_bill_list 或对账单中的资金渠道只能辅助识别资金来源，无法可靠区分花呗一次性付款和花呗分期。
  • 普通交易对账单通常没有适用于所有产品的统一花呗分期标记，不建议只根据对账单判断。

推荐查询方式

支付完成后，通过商户订单号查询交易：

{
  "out_trade_no": "ORDER_202609090001"
}

也可以使用支付宝交易号：

{
  "trade_no": "2026090922001412345678901234"
}

调用接口：

alipay.trade.query

如果订单使用了花呗分期，响应中可能包含以下信息：

{
  "code": "10000",
  "msg": "Success",
  "trade_status": "TRADE_SUCCESS",
  "out_trade_no": "ORDER_202609090001",
  "trade_no": "2026090922001412345678901234",
  "hb_fq_pay_info": {
    "user_install_num": "6"
  }
}

其中：

hb_fq_pay_info.user_install_num = 6

表示买家实际选择了 6 期花呗分期。

Java 判断示例

不同版本的支付宝 SDK 在对象类型和 Getter 名称上可能略有差异。下面是核心判断逻辑，实际代码应以项目使用的 SDK 为准：

AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();

AlipayTradeQueryModel model = new AlipayTradeQueryModel();
model.setOutTradeNo("ORDER_202609090001");
request.setBizModel(model);

AlipayTradeQueryResponse response = alipayClient.execute(request);

if (!response.isSuccess()) {
    throw new IllegalStateException(
        "支付宝交易查询失败: " + response.getCode() + " " + response.getSubMsg()
    );
}

boolean huabeiInstallment = false;
Integer installmentCount = null;

if (response.getHbFqPayInfo() != null
        && response.getHbFqPayInfo().getUserInstallNum() != null) {
    installmentCount = Integer.valueOf(
        response.getHbFqPayInfo().getUserInstallNum()
    );
    huabeiInstallment = installmentCount > 0;
}

if (huabeiInstallment) {
    System.out.println("该订单使用了花呗分期，期数：" + installmentCount);
} else {
    System.out.println("未查询到花呗分期信息");
}

如果当前 SDK 没有将 hb_fq_pay_info 映射为对象，可以直接读取原始 JSON 响应：

JsonNode root = objectMapper.readTree(rawResponse);
JsonNode payInfo = root.path("alipay_trade_query_response")
                       .path("hb_fq_pay_info");

int installmentCount = payInfo.path("user_install_num").asInt(0);
boolean huabeiInstallment = installmentCount > 0;

为什么不能只看请求参数

商户下单时可能通过扩展参数配置花呗分期，例如：

{
  "extend_params": {
    "hb_fq_num": "6",
    "hb_fq_seller_percent": "100"
  }
}

其中：

  • hb_fq_num 是商户配置的分期期数。
  • hb_fq_seller_percent 是商户承担手续费的比例。

这些参数只表示下单配置，不能证明买家最终使用了花呗分期。订单可能尚未支付、支付失败，实际支付流程也可能与预期不同。因此，判断结果应以支付成功后的查询响应为准，不能只依赖商户保存的下单参数。

fund_bill_list 能否用于判断

查询结果或支付通知中可能包含：

{
  "fund_bill_list": [
    {
      "fund_channel": "PCREDIT",
      "amount": "100.00"
    }
  ]
}

fund_channel 描述的是资金渠道。在某些接口或产品场景中，PCREDIT 可能与花呗信用支付有关，但它无法稳定区分以下情况：

  • 花呗一次性付款；
  • 花呗分期付款；
  • 不同签约产品下的渠道差异。

因此，fund_bill_list 只能作为辅助信息，不能代替 hb_fq_pay_info.user_install_num。

对账单中的识别方式

支付宝普通交易对账单的“资金渠道”“业务描述”等字段中，可能出现与花呗有关的信息。不过，这些字段会受到对账单类型、签约产品和账单版本的影响，通常不能作为统一且稳定的花呗分期标记。

建议在支付成功后按以下方式处理：

  1. 调用 alipay.trade.query，确认交易的最终状态。
  2. 保存完整的查询响应，尤其是 hb_fq_pay_info。
  3. 将是否使用分期及分期期数写入商户自己的订单表。
  4. 下载对账单后，通过 trade_no 或 out_trade_no 核对金额和状态。
  5. 对账时不要根据业务描述文本重新推测支付方式。

订单表可以增加以下字段：

ALTER TABLE payment_order
    ADD COLUMN is_huabei_installment BOOLEAN NOT NULL DEFAULT FALSE,
    ADD COLUMN huabei_installment_count INT NULL;

注意事项

  • 交易状态达到 TRADE_SUCCESS 或业务认可的其他最终成功状态后，再记录支付方式。
  • 异步通知中是否包含 hb_fq_pay_info，取决于具体产品和接口的返回定义。如果通知中没有该字段，应主动调用 alipay.trade.query。
  • hb_fq_num 首先是下单配置，不能将其视为实际支付结果。
  • 不要根据订单金额、手续费金额或业务描述推断订单是否使用了分期。
  • 不同支付宝产品、接口版本和 SDK 对字段的支持可能存在差异。如果 alipay.trade.query 没有返回 hb_fq_pay_info，应先核对当前签约产品及该接口的最新参数说明，再决定是否使用产品专属对账单，或联系支付宝技术支持确认。

备注：内容仅供参考。