支付宝三合一收款码的买家备注对应哪个API字段

2026-10-24支付老李

结论

买家在支付宝付款页面填写的”备注”，通常没有对应的开放 API 字段。通过 alipay.trade.precreate、alipay.trade.query 或支付异步通知，一般无法从 buyer_remark、remark 等字段中获取这段内容。

以下几个字段容易与买家备注混淆：

body：商户创建交易时传入的商品描述，不是买家填写的备注。
subject：商户传入的订单标题。
passback_params：商户自定义的回传参数，不是买家备注。
out_trade_no：商户订单号，不能用来接收买家备注。

支付宝客户端是否显示买家备注，取决于收款码产品类型、付款入口和客户端版本。部分收钱码交易会在收款方的账单详情中显示”付款备注”，但这不代表开放 API 也会返回这段内容。因此，不能根据客户端页面是否展示来判断接口能否取到该字段。

原因

支付宝开放 API 返回的是标准交易数据，包括订单号、金额、买卖双方标识、交易状态和商户提交的商品信息。买家在收银台临时填写的备注属于支付宝端的附加信息，并不是当面付接口公开的标准响应字段。

例如，商户创建扫码支付订单时可以提交：

{
  "out_trade_no": "ORDER_202609090001",
  "total_amount": "100.00",
  "subject": "门店消费",
  "body": "线下扫码订单"
}

其中，body 是商户创建订单时设置的”商品描述”。买家付款时另外填写的备注不会覆盖 body，两者是不同的数据。

如何确认实际接口返回

可以检查以下两处原始数据：

支付宝异步通知中的完整参数。
alipay.trade.query 的完整响应。

不要只查看 SDK 对象中挑选出来的几个字段。建议保存脱敏后的完整响应，再逐项核对。常见响应大致如下：

{
  "trade_no": "202609092200...",
  "out_trade_no": "ORDER_202609090001",
  "buyer_logon_id": "abc***@example.com",
  "trade_status": "TRADE_SUCCESS",
  "total_amount": "100.00",
  "buyer_pay_amount": "100.00",
  "subject": "门店消费",
  "body": "线下扫码订单"
}

如果完整响应和异步通知中都没有备注字段，就不能根据客户端页面上的文字，推断它对应 body 或其他参数。

需要保存备注时怎么处理

如果业务系统必须保存备注，可以在商户自己的页面中收集备注，将其与 out_trade_no 一起写入业务数据库，然后再创建支付宝订单。

String outTradeNo = orderService.createOrder(buyerRemark);

AlipayTradePrecreateRequest request = new AlipayTradePrecreateRequest();

AlipayTradePrecreateModel model = new AlipayTradePrecreateModel();
model.setOutTradeNo(outTradeNo);
model.setTotalAmount("100.00");
model.setSubject("门店消费");
model.setBody("线下扫码订单");

request.setBizModel(model);

AlipayTradePrecreateResponse response = alipayClient.execute(request);

备注可以单独保存在数据库中：

INSERT INTO payment_order (
    out_trade_no,
    buyer_remark,
    payment_status
) VALUES (
    'ORDER_202609090001',
    '少放辣椒',
    'WAIT_BUYER_PAY'
);

支付成功后，再根据异步通知中的 out_trade_no 更新订单状态。这样，备注由业务系统自行管理，不依赖支付宝客户端是否展示或返回。

如果需要将内部业务标识带入支付通知，可以使用 passback_params：

model.setPassbackParams(
    URLEncoder.encode("channel=store_001", StandardCharsets.UTF_8)
);

passback_params 是商户提交的自定义参数，不能用来读取买家在支付宝付款页面填写的内容。其编码方式和具体回传范围，应以当前接入接口的官方文档为准。

注意事项

不要把买家备注当作 body。body 是商户创建交易时传入的商品描述。
不要自行读取或假设存在未公开的 buyer_remark、memo 等字段。
支付宝客户端账单详情中的内容可能随产品入口和版本变化，不适合作为系统数据来源。
如果某个收款码服务商声称可以返回买家备注，需要确认该字段是否为服务商提供的扩展字段，而不是支付宝标准开放 API 字段。
如果备注会影响订单履约，应由商户收集并保存，再通过 out_trade_no 与支付宝交易关联。