支付接入(服务端)
本文介绍如何为豆包应用插件接入支付能力。完成接入后,用户可以在应用插件中确认订单并完成付款,你的服务端可以查询支付结果、处理退款,并在商品或服务交付后通知豆包开放平台。
支付过程由三部分共同完成:
- 你的应用插件负责向服务端请求支付参数、创建平台订单并拉起收银台。
- 你的服务端负责保存开发者订单、生成签名、查询支付结果、处理回调、申请退款和通知履约完成。
- 豆包开放平台负责创建平台订单、提供收银台、处理支付和退款,并向你的服务端发送结果通知。
开始前
开始开发前,请先确认已经创建豆包应用插件,并具备修改应用插件代码和部署服务端接口的能力。相关操作可参考以下文档:
接入前准备
创建应用并获取应用凭证
这里的“应用凭证”是创建应用插件后获得的 AppID 和 AppSecret:
- AppID 对应服务端接口中的
app_id,用于标识调用方应用。 - AppSecret 对应
app_secret,用于证明应用身份,属于服务端密钥。 X-DB-AccessToken不是长期应用凭证,而是服务端使用 AppID 和 AppSecret 换取的短期应用级 Access Token。
按以下步骤准备:
- 按《快速开始》创建应用插件。
- 在豆包开发者平台打开目标应用,进入“开发设置”,记录应用插件 ID,并获取该应用的 App Secret。
- 将 AppSecret 保存到服务端的密钥管理系统或受保护的环境变量中,不要写入代码仓库、公开配置或应用插件代码。
- 服务端按照《获取应用级别鉴权 Token》调用 Token 接口,传入
app_id、app_secret和固定值client_credential,缓存接口返回的 Access Token。 - 调用服务端支付 API 时,将未过期的 Token 放入
X-DB-AccessToken请求头。
准备完成的标准是:服务端能够独立获取应用级 Access Token,并在 Token 过期前刷新;应用插件前端不接触 AppSecret 或 Access Token。Token 接口的路径、有效期、完整请求和错误码统一见《服务端 API 总览》。
开通并绑定商户账户
商户账户用于收款,必须与当前应用插件绑定。预下单参数中的 merchantUid 来自已绑定的收款商户,不能使用 AppID 代替,也不能由开发者自行生成。
不同商户类型所需的开户材料可能不同。请按以下步骤申请并确认绑定关系:
- 先完成应用插件创建,并确认需要接入支付的 AppID。
- 如果开发者平台中的目标应用已展示商户开户入口,按页面提交企业名称、统一社会信用代码、联系人和手机号等要求的信息;如果没有入口,按照《联系与支持》发起“应用插件支付商户开户”申请。
- 根据支持团队提供的要求完成主体资质审核、账户开通和协议确认。
- 由平台将开通后的商户账户绑定到目标 AppID,并向开发者提供或展示对应的
merchantUid。 - 在正式下单前核对绑定关系,确认当前 AppID、商户主体和
merchantUid属于同一测试环境或正式环境。
只有同时满足“商户账户已开通”“商户已绑定当前应用”“已取得可用的 merchantUid”三个条件,才算完成支付商户准备。未完成时不要使用测试值发起正式支付。
配置支付证书
支付请求以及支付、退款回调都使用证书完成身份校验:开发者服务端使用开发者私钥对请求加签,并在签名头中携带开发者证书序列号;收到平台回调后,使用平台证书验签。证书生成与上传、平台证书获取、加签验签的数据方向、算法及示例代码统一参见 关于证书,本页不重复展开。待签名字符串、X-DB-Authorization 格式、签名生成和验签步骤详见《支付相关 API》。
准备开发者订单和回调地址
服务端需要持久化开发者订单,至少保存开发者订单号、平台订单号、AppID、merchantUid、金额、支付状态、退款单号和关键时间。支付与退款请求都需要稳定的开发者单号,以便在请求超时后查询结果和安全重试。
支付回调地址必须是可从公网访问的 HTTPS 地址。回调处理程序需要读取原始请求体、验证平台签名、校验订单和金额、识别重复通知,并快速返回平台要求的成功响应。
私钥、AppSecret 和 Access Token 只能保存在服务端安全环境中。预下单签名仅在当前支付请求中返回给应用插件使用,不应写入日志或长期存储。
支付接入自检清单
联调前请确认:
- AppID、Access Token、商户和证书均属于同一环境。
- 商户已完成开户、开通支付能力,并绑定当前 AppID。
merchantUid使用当前应用绑定的商户 UID。- 支付证书和签名已按《8.1 关于证书》完成配置。
- 签名使用的
data与传给requestOrder的内容完全一致。 - 支付、退款回调地址可通过公网访问,并已实现验签和幂等处理。
商户“已创建”不代表“已完成开户”。出现“该场景无可用支付方式”时,请优先检查开户状态、应用绑定关系和支付能力状态。
支付流程
下图展示从生成预下单参数、拉起收银台到服务端确认支付结果的完整时序:
一笔支付按以下顺序完成:
- 用户在应用插件中确认购买,你的服务端创建开发者订单,并生成唯一的
outOrderNo。 - 你的服务端根据已保存的订单信息组装预下单参数,将最终 JSON 序列化为字符串,并生成对应的
dbAuthorization。 - 应用插件使用服务端返回的
data和dbAuthorization调用requestOrder,获得平台订单号orderId。 - 应用插件使用
orderId调用getOrderPayment拉起收银台。 - 收银台交互结束后,应用插件向你的服务端查询开发者订单状态。你的服务端调用平台订单查询接口进行确认。
- 豆包开放平台向你的服务端发送支付结果回调。服务端完成验签、订单和金额校验后,安全地更新订单状态。
订单查询结果和支付回调可能以不同顺序到达,也可能重复到达。服务端应使用同一套订单状态规则处理两种结果,避免重复发货、重复记账或将已支付订单改回处理中。
请注意:应用插件成功创建平台订单或收银台正常关闭,都不能证明用户已经付款。只有你的服务端查询到支付成功,或收到并验证通过支付成功回调后,才能将开发者订单更新为已支付。
订单状态和重试规则
outOrderNo 是开发者订单的唯一标识,同一业务订单重试时应保持不变。收银台正常返回不代表支付成功,最终结果以服务端查询或验签通过的支付回调为准。
退款重试时应复用原 out_refund_no;请求超时后先查询退款结果,不要立即生成新的退款单号。
生成预下单参数
预下单参数必须由你的服务端根据已保存的订单信息生成,不应由应用插件自行拼装。data 是 JSON 字符串,主要字段如下:
服务端应校验商品金额、数量和订单总金额的一致性,并使用整数表示分,避免浮点数计算造成金额误差。outOrderNo 应在创建订单时生成并持久化,不要在重试预下单时更换。
下面的示例只展示订单参数组装。signRequest 是示意函数名,具体实现参考关于证书; X-DB-Authorization 格式见《支付相关 API》:
预下单签名的请求方法固定为 POST,签名路径固定为 /requestOrder,查询字符串为空。签名必须基于最终返回给应用插件的 data 原始字节生成;签名后不要再次解析、格式化或重新序列化该字符串,否则可能导致验签失败。
应用插件发起支付
应用插件从你的服务端取得预下单参数后,先创建平台订单,再拉起收银台。完整 API 定义和错误码见《JS API 说明》:
保存 requestOrder 返回的 orderId,并将它与开发者订单关联。调用失败时可记录 logId 或错误对象中的 errLogId 用于排查,但不要记录签名和完整支付参数。
调用服务端支付 API
支付服务端接口均使用 POST 和 application/json,并通过请求头携带应用级访问凭证。Token 的获取与刷新见《服务端 API 总览》,各支付接口的完整字段和错误码见《支付相关 API》:
通用响应结构如下:
不能只根据 HTTP 状态码判断调用是否成功。你的服务端还必须检查响应中的 code;非 0 时记录经过脱敏的请求信息、code、msg 和 log_id。
查询订单信息
收银台交互结束或用户刷新订单页面时,应用插件向你的服务端查询开发者订单;你的服务端再向豆包开放平台确认支付状态:
例如,使用开发者订单号查询订单:
订单查询结果中的 pay_status 表示平台支付状态:
对未知状态不要按成功处理,也不要因为收银台关闭或前端异常直接将订单判定为支付失败。
处理支付回调
支付和退款回调地址
- 支付和退款回调地址均以接口参数为准,与应用详情中的“事件回调”配置无关。
- 退款回调地址不会自动继承支付的
payNotifyUrl;需要接收退款回调时,必须在refund_create中传入notify_url。 - 支付和退款可以使用同一个地址,服务端通过
type区分事件。 - 未传
notify_url时不会收到退款回调,需要调用refund_query查询最终结果。
支付结果回调发送到预下单参数中的 payNotifyUrl。请求方法为 POST,主要请求头如下:
回调请求体外层包含 type、version 和 msg。支付回调的 type 为 payment,version 当前为 1.0;msg 中包含 app_id、order_id、out_order_no、pay_status、total_amount、event_time、pay_type 和 pay_order_no 等支付结果字段。
处理回调时应遵循以下顺序:
- 保留原始请求体,并先校验
X-DB-Authorization,不要使用重新序列化后的 JSON 验签。 - 按签名认证规范校验时间戳、nonce、证书序列号和签名,拒绝过期或重复请求。
- 解析外层结构和
msg,确认type、version和字段类型符合预期。 - 根据
out_order_no查找本地订单,校验app_id、order_id和total_amount。 - 使用开发者订单号和平台订单号识别重复通知。重复回调不得重复更新订单、发货或记账。
- 成功处理后返回 HTTP 200 和固定响应;发货、记账等耗时操作应异步执行,避免回调响应超时。
未按上述格式返回时,平台会将本次通知视为失败并重试。回调处理异常或结果存在冲突时,应保留 X-DB-Logid,并主动调用订单查询接口核对最终状态。
退款
退款必须由你的服务端发起,不能由应用插件直接调用平台退款接口。
申请退款
refund_create 支持整单退款和部分退款,主要参数包括:
查询退款单信息
退款创建成功只表示豆包开放平台已经受理。应用插件展示退款状态时,应由你的服务端调用 refund_query 查询:
接口受理成功会返回平台退款单号 refund_id,这只表示退款请求已创建。服务端应通过退款回调或 refund_query 获取最终状态:
退款回调发送到 notify_url,外层 type 为 refund。验签、重复通知处理和响应要求与支付回调相同;你的服务端还应校验 refund_id、out_refund_no、原订单号和退款金额。
同一笔退款重试时应复用原 out_refund_no,不要因为网络超时立即生成新退款单号。无法确认请求是否被受理时,先使用该退款单号查询结果。
履约完成通知
商品或服务完成交付后,由你的服务端调用 /api/trade_basic/v1/developer/fulfill_push_finish/ 通知豆包开放平台履约完成。请求通过 order_id 或 out_order_no 标识订单。
只有你的服务端确认商品或服务已经交付后,才能发送履约完成通知。调用失败时保留 log_id,并使用同一个订单号重试。平台成功接收通知不代表商品或服务已经完成交付,实际履约状态仍以你的订单系统为准。
安全与可靠性要求
- 金额、商户、商品和订单号以服务端保存的数据为准,不接受应用插件前端直接传入的金额作为下单依据。
- AppSecret、私钥、Access Token 和验签证书不得写入应用插件代码、公开配置、代码仓库或日志。
- 签名、验签和哈希计算必须使用原始字节;不要在签名后重新格式化 JSON。
- Access Token 应按有效期缓存并提前刷新,获取失败时不要使用过期凭证无限重试。
- 支付和退款回调必须支持重复通知、乱序到达和并发处理。更新订单状态前,应检查当前状态,避免将已经完成的订单改回处理中。
- 网络超时不表示请求一定失败。创建订单或申请退款超时后,应先使用原订单号或退款单号查询结果,再决定是否重试。
- 日志应记录脱敏后的开发者订单号、接口、耗时、
code和log_id,不得记录完整支付参数、签名、凭证或用户敏感信息。
常见问题
预下单验签失败
确认签名方法为 POST、签名路径为 /requestOrder、查询字符串为空,并检查签名使用的 data 与传给 requestOrder 的字符串是否逐字节一致。
收银台返回后订单仍为处理中
收银台返回不表示支付成功。请由你的服务端调用订单查询接口;若仍为 PROCESS,保持处理中并稍后重试,不要由应用插件直接改为成功或失败。
已收到支付回调但本地订单未更新
检查回调验签、app_id、订单号和金额校验是否通过,并使用 X-DB-Logid 排查。若回调内容和本地状态冲突,以平台订单查询结果进行核对。
退款请求超时
不要立即更换 out_refund_no 重复申请。先使用原退款单号调用退款查询接口,确认平台是否已经受理。
服务端支付 API 返回 HTTP 200,但调用没有成功
平台接口通过响应体中的 code 表示调用结果。始终检查 code,并在非 0 时保留 msg 和 log_id。