PAYATHON 2026

当面付扫码支付不使用SDK时是否有完整API文档？

支付阿杰

明确结论

可以。即使不使用支付宝 SDK，也能根据支付宝开放平台的 OpenAPI 接口文档自行开发。

alipay.trade.query 并非只能通过扫码支付 SDK 调用。SDK 封装了请求组装、签名、发送和验签等步骤。接口的公共请求参数、业务参数、响应字段和错误码，仍以支付宝开放平台提供的官方文档为准。

需要查看哪些文档

自行对接时，通常需要参考以下文档：

  1. 接口文档
    查看 alipay.trade.query 等接口的业务请求参数、响应参数、必填规则和错误码。

  2. 公共请求参数说明
    查看 app_id、method、format、charset、sign_type、sign、timestamp、version 和 biz_content 等字段的定义。

  3. 签名与验签文档
    SDK 会自动完成请求签名和响应验签，自行开发时需要实现这两部分。

  4. 密钥配置说明
    应用需要配置应用公钥或支付宝公钥，并妥善保管应用私钥。平台密钥模式和签名方式应与当前应用配置一致，具体要求以官方文档为准。

  5. 沙箱与生产环境说明
    沙箱和生产环境使用的网关、应用 ID、密钥及账号不能混用。

alipay.trade.query 的参数结构

调用该接口时，请求参数分为公共参数和业务参数两层。

公共参数

常见的公共参数包括：

app_id
method=alipay.trade.query
format=JSON
charset=utf-8
sign_type=RSA2
sign
timestamp
version=1.0
biz_content

这些参数用于指定调用的接口、字符集和签名方式，并携带签名结果。

业务参数

查询交易时，通常使用支付宝交易号或商户订单号。例如：

{
  "out_trade_no": "ORDER_202609090001"
}

或者：

{
  "trade_no": "支付宝交易号"
}

out_trade_no 和 trade_no 的必填关系、长度限制，以及接口支持的其他可选字段，可能随开放平台文档调整。开发时应查看当前 alipay.trade.query 接口页面中的参数表。

不使用 SDK 的调用流程

1. 组装业务参数

将业务参数序列化为紧凑的 JSON 字符串，作为 biz_content 的值：

{"out_trade_no":"ORDER_202609090001"}

2. 组装公共参数

app_id=你的应用ID
biz_content={"out_trade_no":"ORDER_202609090001"}
charset=utf-8
format=JSON
method=alipay.trade.query
sign_type=RSA2
timestamp=2026-09-09 10:30:00
version=1.0

3. 生成签名

通常按以下步骤处理：

  1. 排除 sign 字段和空值字段。
  2. 按参数名称的字典序排序。
  3. 以 key=value 格式组织参数，并使用 & 连接。
  4. 使用应用私钥和约定的签名算法生成签名。
  5. 对签名结果进行 Base64 编码。
  6. 将生成的签名写入 sign 参数。

待签名字符串的结构如下：

app_id=你的应用ID&biz_content={"out_trade_no":"ORDER_202609090001"}&charset=utf-8&format=JSON&method=alipay.trade.query&sign_type=RSA2&timestamp=2026-09-09 10:30:00&version=1.0

参数排序、字符编码、空值处理和 URL 编码的顺序必须严格遵守官方签名规范。上面的字符串只用于展示结构，不能直接作为实际请求的签名结果。

4. 发送 HTTP 请求

生成签名后，可以向支付宝开放平台网关发送表单请求：

curl -X POST 'https://openapi.alipay.com/gateway.do' \
  -H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
  --data-urlencode 'app_id=你的应用ID' \
  --data-urlencode 'method=alipay.trade.query' \
  --data-urlencode 'format=JSON' \
  --data-urlencode 'charset=utf-8' \
  --data-urlencode 'sign_type=RSA2' \
  --data-urlencode 'timestamp=2026-09-09 10:30:00' \
  --data-urlencode 'version=1.0' \
  --data-urlencode 'biz_content={"out_trade_no":"ORDER_202609090001"}' \
  --data-urlencode 'sign=程序生成的签名'

这里的时间戳仅用于展示格式，实际调用时应使用当前时间。网关地址和签名配置应以当前开放平台文档及应用环境为准。

5. 解析并验证响应

响应一般包含接口响应节点和签名字段，结构类似：

{
  "alipay_trade_query_response": {
    "code": "响应码",
    "msg": "响应说明",
    "trade_no": "支付宝交易号",
    "out_trade_no": "商户订单号",
    "trade_status": "交易状态"
  },
  "sign": "支付宝响应签名"
}

这段 JSON 仅用于说明响应结构，不代表真实交易的返回结果。完整字段、字段出现条件和业务含义，应查看接口文档中的“响应参数”部分。

程序不能只根据 HTTP 状态码判断查询是否成功，还要检查业务响应中的 code、sub_code、msg、sub_msg 等字段，并验证支付宝的响应签名。

常见注意事项

  • alipay.trade.query 是开放平台接口名，并非 SDK 独有的方法。
  • SDK 中的请求类、模型类和执行方法只是对 OpenAPI 的封装，接口参数仍以官方接口文档为准。
  • biz_content 必须是符合接口定义的 JSON，不能随意改变字段类型。
  • 签名前使用的原始值必须与实际发送值一致，否则容易导致验签失败。
  • 对请求参数进行 URL 编码，不代表需要提前对待签名字符串进行 URL 编码。处理顺序必须遵守签名规范。
  • 应当校验响应签名，不能直接信任返回 JSON 中的交易状态。
  • 查询接口返回成功，只说明查询请求处理成功。最终交易结果还要根据 trade_status 判断。
  • 支付结果通知应与主动查询配合使用，不能只依赖前端跳转结果。
  • 日志中不要记录应用私钥、完整签名原文或用户敏感信息。
  • 接口字段可能随产品能力及开放平台文档更新而变化，开发时应以当前官方接口页面为准。

备注：内容仅供参考。