支付相关 API
本文提供豆包应用插件支付服务端 API 的请求参数、响应字段、状态枚举、回调协议、签名规则和支付错误码参考。
如果你还没有完成商户开户、应用绑定和证书配置,请先阅读《支付接入(服务端)》。服务端 API 的请求域名、应用级 Access Token 获取方式、通用响应结构和通用重试原则,参见《服务端 API 总览》。
调用前准备
调用支付能力前,请确认以下事项均已完成:
- 商户账户已通过审核,且处于可用状态。
- 商户已绑定到当前应用插件,并已取得该环境下的
merchantUid。 - 服务端已取得有效的应用级 Access Token。
- 需要使用普通支付或接收支付回调时,已配置开发者证书和平台证书。
- 回调地址可以从公网通过 HTTPS 访问,并能保存原始请求体用于验签。
测试环境和正式环境的应用、商户、证书、访问令牌与订单数据相互隔离,不能混用。
Access Token 与支付签名的区别
支付链路中会出现三种不同的认证信息:
三者不能相互替代。本文列出的服务端 API 使用应用级 Access Token,不要求额外携带 X-DB-Authorization;支付签名主要用于预下单数据和回调验签。
商户标识 merchantUid
merchantUid 是豆包开放平台为收款商户分配的唯一标识。它不是应用插件 AppID,也不能由开发者自行生成。
在开始支付联调前,请在豆包开发者平台确认商户已经与当前应用插件绑定成功,并保存平台展示的 merchantUid。如果尚未获得该标识,或者商户仍处于审核中、停用或解绑状态,应先按照《支付接入(服务端)》完成商户开户和应用绑定,不能使用其他应用或其他环境的商户标识代替。
同一标识在不同协议中的字段名不同:
收到订单查询结果或回调后,应校验 app_id、merchant_uid、业务单号和金额是否与本地订单一致。
业务单号
支付接口同时使用开发者生成的业务单号和豆包开放平台生成的平台单号。建议在本地同时保存两者。
开发者单号应在当前应用的对应业务范围内保持唯一,长度不超过 64 个字符。创建类请求超时后,结果可能已经生效;不要立即更换业务单号重复创建,应先使用原业务单号调用查询接口确认结果。
API 索引
请求与响应说明
服务端 API 均使用相同的请求头:
下文的响应字段表只列出各接口 data 中的业务字段。code、msg、log_id 等通用字段及其处理方式见《服务端 API 总览》。示例中的订单号、金额、用户标识和回调地址仅用于说明格式。
查询订单
查询普通支付订单的当前状态、金额和支付信息。查询接口可用于主动确认支付结果,也可用于回调丢失或状态存疑时的补偿查询。
请求
建议每次只使用一种单号查询;如果同时填写,两者必须指向同一订单。
响应
pay_status 枚举:
该接口为只读接口,可以使用相同参数安全重试。订单不存在时返回 500020005;查询了不受该接口支持的订单类型时可能返回 500020009。
创建退款
为已支付成功的普通支付订单或协议支付订单发起全部退款或部分退款。
请求
refund_sku_list 元素字段:
响应
out_refund_no 是本接口的幂等键。同一个退款业务必须始终使用同一个 out_refund_no 和相同的退款参数;不要将同一退款单号用于不同订单或不同金额。请求超时后,先使用原 out_refund_no 调用“查询退款”,确认不存在后再决定是否重试。
未填写 notify_url 时不会收到退款结果回调,需要通过“查询退款”获取最终状态。
常见支付错误包括:退款单号冲突 500020003、原订单不存在 500020005、订单类型不支持退款 500020010、商户绑定不存在 500020011、相同退款单号对应的参数不一致 500020012,以及订单结算期间暂不允许退款 500020013。
查询退款
按退款单号查询单笔退款,或按平台订单号查询该订单下的退款列表。
请求
三个查询字段必须且只能填写一个。
响应
refund_list 元素字段:
refund_status 枚举:
该接口为只读接口,可以使用相同参数安全重试。平台订单不存在时返回 500020005,退款单不存在时返回 500020006,退款订单类型不受支持时可能返回 500020010。
通知履约完成
当已支付订单对应的商品或服务交付完成后,通知豆包开放平台更新履约状态。只有业务实际履约完成后才能调用本接口。
请求
响应
本接口成功时不返回 data:
同一订单重复通知履约完成不会产生重复履约结果,但调用前仍应由业务服务记录本地履约状态,避免在商品尚未交付时误调用。订单不存在时返回 500020005。
查询签约订单
查询签约关系的当前状态。创建协议支付订单前,应先调用本接口确认签约关系处于可用状态。
请求
建议每次只使用一种单号查询;如果同时填写,两者必须指向同一签约单。
响应
status 枚举:
该接口为只读接口,可以使用相同参数安全重试。签约单不存在或不属于当前应用时返回 500020005。
解除签约
由开发者主动解除已有签约关系。解约后,该签约关系不能再用于创建新的协议支付订单。
请求
响应
本接口成功时不返回 data:
对已经解约的签约单重复调用会返回成功。TIMEOUT 或 DONE 状态不能执行解约;签约单不存在或不属于当前应用时返回 500020005。调用成功后,仍应通过“查询签约订单”或签约结果回调确认最终状态。
创建协议支付订单
基于处于 SERVING 状态的签约关系创建协议支付订单。协议支付订单会按照签约服务的规则执行扣款。
请求
pay_data 字段:
sku_list 元素字段:
当 sku_list 非空时,所有商品小计之和必须等于 pay_data.total_amount。
响应
out_pay_order_no 是本接口的业务幂等标识。请求超时后,先使用原 out_pay_order_no 调用“查询协议支付订单”,不要更换单号重复创建。签约单必须处于 SERVING 状态;其他状态会返回参数错误。常见支付错误包括业务单号已存在 500020002、签约单不存在 500020005 和商户绑定不存在 500020011。
查询协议支付订单
查询协议支付订单的支付状态、支付信息和失败原因。
请求
建议每次只使用一种单号查询;如果同时填写,两者必须指向同一订单。
响应
pay_status 枚举:
该接口为只读接口,可以使用相同参数安全重试。协议支付订单不存在或不属于当前应用时返回 500020005。当 pay_status 不是最终状态时,不要据此履约;继续查询或等待回调。
关闭协议支付订单
关闭尚未完成的协议支付订单。订单关闭后不能继续扣款。
请求
响应
本接口成功时不返回 data:
已处于 CLOSED 状态的订单重复关闭会返回成功;SUCCESS 或 FAIL 状态的订单不能关闭。支付成功后如需退回资金,应调用“创建退款”,不能调用本接口。协议支付订单不存在或不属于当前应用时返回 500020005。
回调协议
支付、退款、签约或协议支付状态发生变化后,豆包开放平台会向开发者配置的回调地址发送 HTTP POST 请求。回调由豆包开放平台主动发起,不是开发者需要调用的 OpenAPI。
回调请求头
回调外层结构
所有支付回调使用相同的外层结构:
验签时必须使用收到的完整原始请求体字节。不要先把外层 JSON 或 msg 解析后重新序列化,再用新生成的字节验签。
支付结果回调
当 type 为 payment 时,msg 解析后的字段如下:
支付成功后,先核对 app_id、订单号、merchant_uid 和 total_amount,再将本地订单更新为已支付。不要只根据回调中的单个状态字段直接发货。
退款结果回调
当 type 为 refund 时,msg 解析后的字段如下:
退款回调只通知最终结果,不通知 PROCESSING 中间状态。
签约结果回调
当 type 为 sign_callback 时,msg 解析后的字段如下:
协议支付结果回调
当 type 为 sign_pay_callback 时,msg 解析后的字段如下:
成功响应与重试
回调验签通过并且业务结果已经可靠保存后,开发者服务端必须返回 HTTP 200 和以下 JSON:
如果未返回 HTTP 200,或者响应体中的 code 和 msg 不符合上述格式,豆包开放平台会将本次回调视为失败并重试。回调可能因此重复到达,也可能与主动查询结果交错到达。接收服务必须做到:
- 使用
type与对应的平台单号作为幂等依据;同一结果重复到达时不能重复发货、重复记账或重复退款。 - 只允许合法的状态转换,不允许较早的消息把本地终态回退为中间状态。
- 业务处理较慢时,先将已验签的事件可靠写入队列或数据库,再返回成功;不要在结果尚未保存时提前返回成功。
- 长时间未收到回调或对回调结果有疑问时,调用对应查询接口确认状态。
下载账单
按商户、交易类型、交易状态和日期范围生成账单文件。接口会在服务端提交导出任务并同步等待文件生成;成功时只返回下载地址,不返回导出任务 ID,也不提供后续查询或恢复任务的接口。
请求
日期范围必须满足以下规则:
start_date和end_date必须是真实有效的日期,不能使用yyyy-MM-dd、时间戳或其他格式。end_date不能早于start_date。- 查询范围最多包含 31 个东八区自然日(起止日期均计入)。例如,
20260801至20260831合法,20260801至20260901不合法。超过 31 天的范围应拆分为多个请求。 - 单日账单应将
start_date和end_date设置为同一天。
响应
调用边界与重试
- 本接口是同步接口。服务端会先创建或复用相同查询条件的导出任务,再轮询等待文件生成;调用方只需处理本次响应,不需要保存或查询导出任务 ID。
- 当前单次同步等待最长约 30 秒。请求超时或返回服务错误时,不能据此判断财经侧任务一定失败;建议使用完全相同的查询参数有限重试。
- 新导出请求按
merchant_uid限制为每分钟 1 次。商户归属校验通过后才计入限流;短期内使用完全相同参数重试且已有成功结果时,会直接复用下载地址,不占用新的导出限流额度。 - 相同参数包括应用、
merchant_uid、trade_type、trade_status、start_date和end_date。修改任一筛选条件会被视为新的导出请求。 - 获得下载地址后应及时下载并妥善保存账单文件。
- 参数格式、日期范围、枚举值或商户绑定不合法时返回参数错误;调用过于频繁时返回
500000002。这些错误不应使用原请求高频重试。
文件样例
交易明细报表20260530-20260601_260814140149240405544990.csv189 B
下载结算账单
按商户、时间类型和日期范围生成结算账单 CSV 文件。接口会在服务端提交导出任务并同步等待文件生成;成功时只返回下载地址,不返回导出任务 ID,也不提供后续查询或恢复任务的接口。
请求
请求头沿用本文的通用请求头,X-DB-AccessToken 必须为当前应用插件的有效应用级 Access Token。
日期范围必须满足以下规则:
start_date和end_date必须是真实有效的日期,不能使用yyyy-MM-dd、时间戳或带时分秒的格式。end_date不能早于start_date;单日账单应将两个字段设置为同一天。- 查询范围最多包含 31 个东八区自然日(起止日期均计入)。例如,
20260801至20260831合法,20260801至20260901不合法。更长范围应拆分为多个不超过 31 天的请求。 - 查询范围覆盖起始日
00:00:00至结束日23:59:59(东八区),不支持精确到时分秒筛选。 - 本接口不支持商户订单号、
trade_type或trade_status筛选;请勿套用“下载账单”的交易类型和状态参数。
响应
调用边界与重试
- 本接口为同步接口。服务端创建或短期复用相同查询条件的导出任务,等待文件生成后返回 URL;调用方不需要保存或查询导出任务 ID。
- 默认单次服务端轮询等待最长约 30 秒,创建任务和网络调用还会产生额外耗时。客户端请求超时建议设置为 60 秒,避免在文件生成前主动断开。
- 新导出请求默认按
merchant_uid限制为每 60 秒 1 次,商户归属校验通过后才计入限流。拆分日期范围导出时,各次新请求应间隔至少 60 秒。 - 在短期复用有效期内,完全相同参数且已有成功结果的请求会直接返回下载地址,不占用新的导出限流额度。相同参数包括应用、
merchant_uid、time_type、start_date和end_date;仅存在处理中任务并不代表免于限流。 - 短期复用不是账单内容永久不变的保证;复用有效期结束后,相同条件可能重新生成文件。
- 请求超时或返回服务错误时,不能据此判断财经侧导出任务一定失败。调用方可按限流间隔使用相同参数有限重试,不应高频重试。
- 参数格式、日期范围、
time_type或商户绑定不合法时返回参数错误;调用过于频繁时返回500000002。请先修正参数或等待限流窗口结束。 - 查询范围内没有记录时,仍可能成功返回仅包含表头的 CSV;成功取得 URL 不代表一定存在账单明细。
支付签名与验签
支付签名使用 ECDSA P-256 和 SHA-256。签名值使用 ASN.1 DER 格式,再以保留 = 补位的 URL-safe Base64 编码。
证书与密钥方向
开发者私钥只能保存在开发者服务端。开发者服务端需要保存当前有效的开发者证书和平台证书,并在证书轮换期间按证书序列号选择正确证书;未知的 cert_serial 必须拒绝,不能遍历所有证书尝试验签。
待签名字符串
按照以下顺序构造待签名字符串:
各部分规则如下:
CANONICAL_QUERY 中的 key 和 value 使用 URL 解码后的原始值参与排序和拼接。拼接结果固定包含五个换行符。Query 为空时,第三行仍然保留为空行;末尾不增加额外换行。请求体计算摘要后不能再次格式化或重新序列化。
如果加密库提供 SHA256withECDSA 之类的高层接口,应将完整待签名字符串交给该接口,由其完成 SHA-256;如果使用接收摘要的低层 ECDSA 接口,则先自行计算一次 SHA-256。不要先计算摘要,再把摘要交给会再次执行 SHA-256 的高层接口。
授权信息格式
dbAuthorization 和 X-DB-Authorization 使用相同的单行字段格式:
字段顺序和格式应保持一致,不要插入额外空格、换行或折行:
不要把 ECDSA 签名编码为固定长度的 r || s,也不要使用会主动删除 = 的 Raw Base64URL 编码。
生成预下单 dbAuthorization
应用插件前端 requestOrder 使用以下固定签名上下文:
服务端生成流程:
- 从可信订单数据计算商品、金额和
merchantUid,生成最终data字符串。 - 计算
data原始字节的 SHA-256 摘要,并构造待签名字符串。 - 使用开发者 ECC P-256 私钥生成 ECDSA ASN.1 DER 签名。
- 将签名编码为保留
=补位的 Base64URL 字符串。 - 使用开发者证书序列号组装
dbAuthorization。 - 将同一份
data字符串和dbAuthorization返回给应用插件前端,由前端原样传给requestOrder。
完成签名后,不要再对 data 执行 JSON.parse、JSON.stringify、字段重排或格式化。即使 JSON 解析结果相同,原始字节变化也会导致验签失败。
验证回调签名
回调验签流程:
- 在读取和解析 JSON 前保存请求体原始字节。
- 从
X-DB-Authorization中解析并校验algorithm、version、signature、cert_serial、nonce和timestamp。 - 根据
cert_serial选择对应的平台证书,并检查证书有效期。 - 校验
timestamp是否在服务允许的时间窗口内;在共享存储中记录nonce,拒绝时间窗口内的重复值。 - 使用实际收到的 HTTP 方法、回调路径、query 和原始请求体构造待签名字符串。
- 对
signature进行 padded Base64URL 解码,得到 ASN.1 DER 字节。 - 使用平台证书中的 P-256 公钥执行 ECDSA-SHA256 验签。
- 只有验签通过后,才解析外层 JSON 和
msg并处理业务。
多实例部署时,nonce 去重必须使用所有实例共享且支持原子写入的存储。服务器时间应保持同步;生产日志中不要记录私钥、完整签名、完整授权头或包含用户数据的完整请求体。
支付错误码
每个接口可能返回通用错误、应用凭证错误和支付业务错误。程序应根据 code 判断处理方式,不要根据可能调整的 msg 文本编写业务分支。
常用调用错误
支付业务错误
对于创建退款、创建协议支付订单等可能产生资金或订单状态变化的接口,网络超时不能视为失败。再次提交前,应先使用原业务单号调用对应查询接口确认结果。