For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/backend-development/payment.md.

支付接入(服务端)

提示

本文介绍如何为豆包应用插件接入支付能力。完成接入后,用户可以在应用插件中确认订单并完成付款,你的服务端可以查询支付结果、处理退款,并在商品或服务交付后通知豆包开放平台。

支付过程由三部分共同完成:

  • 你的应用插件负责向服务端请求支付参数、创建平台订单并拉起收银台。
  • 你的服务端负责保存开发者订单、生成签名、查询支付结果、处理回调、申请退款和通知履约完成。
  • 豆包开放平台负责创建平台订单、提供收银台、处理支付和退款,并向你的服务端发送结果通知。

开始前

开始开发前,请先确认已经创建豆包应用插件,并具备修改应用插件代码和部署服务端接口的能力。相关操作可参考以下文档:

需要了解的内容对应文档
注册开发者账号、创建应用插件《快速开始》
AppID、AppSecret、应用级 Access Token、通用响应和鉴权方式《服务端 API 总览》及《获取应用级别鉴权 Token》
支付接口的完整字段、签名算法、回调结构和支付错误码《支付相关 API》
应用插件支付 API 的完整参数、返回值和错误码《JS API 说明》
资金流、结算周期和账户中心《支付方案介绍》
无法自助完成的商户开户申请《联系与支持》

接入前准备

创建应用并获取应用凭证

这里的“应用凭证”是创建应用插件后获得的 AppID 和 AppSecret:

  • AppID 对应服务端接口中的 app_id,用于标识调用方应用。
  • AppSecret 对应 app_secret,用于证明应用身份,属于服务端密钥。
  • X-DB-AccessToken 不是长期应用凭证,而是服务端使用 AppID 和 AppSecret 换取的短期应用级 Access Token。

按以下步骤准备:

  1. 按《快速开始》创建应用插件。
  2. 在豆包开发者平台打开目标应用,进入“开发设置”,记录应用插件 ID,并获取该应用的 App Secret。
  3. 将 AppSecret 保存到服务端的密钥管理系统或受保护的环境变量中,不要写入代码仓库、公开配置或应用插件代码。
  4. 服务端按照《获取应用级别鉴权 Token》调用 Token 接口,传入 app_id、app_secret 和固定值 client_credential,缓存接口返回的 Access Token。
  5. 调用服务端支付 API 时,将未过期的 Token 放入 X-DB-AccessToken 请求头。

准备完成的标准是:服务端能够独立获取应用级 Access Token,并在 Token 过期前刷新;应用插件前端不接触 AppSecret 或 Access Token。Token 接口的路径、有效期、完整请求和错误码统一见《服务端 API 总览》。

开通并绑定商户账户

商户账户用于收款,必须与当前应用插件绑定。预下单参数中的 merchantUid 来自已绑定的收款商户,不能使用 AppID 代替,也不能由开发者自行生成。

不同商户类型所需的开户材料可能不同。请按以下步骤申请并确认绑定关系:

  1. 先完成应用插件创建,并确认需要接入支付的 AppID。
  2. 如果开发者平台中的目标应用已展示商户开户入口,按页面提交企业名称、统一社会信用代码、联系人和手机号等要求的信息;如果没有入口,按照《联系与支持》发起“应用插件支付商户开户”申请。
  3. 根据支持团队提供的要求完成主体资质审核、账户开通和协议确认。
  4. 由平台将开通后的商户账户绑定到目标 AppID,并向开发者提供或展示对应的 merchantUid。
  5. 在正式下单前核对绑定关系,确认当前 AppID、商户主体和 merchantUid 属于同一测试环境或正式环境。

只有同时满足“商户账户已开通”“商户已绑定当前应用”“已取得可用的 merchantUid”三个条件,才算完成支付商户准备。未完成时不要使用测试值发起正式支付。

配置支付证书

支付请求以及支付、退款回调都使用证书完成身份校验:开发者服务端使用开发者私钥对请求加签,并在签名头中携带开发者证书序列号;收到平台回调后,使用平台证书验签。证书生成与上传、平台证书获取、加签验签的数据方向、算法及示例代码统一参见 关于证书,本页不重复展开。待签名字符串、X-DB-Authorization 格式、签名生成和验签步骤详见《支付相关 API》。

准备开发者订单和回调地址

服务端需要持久化开发者订单,至少保存开发者订单号、平台订单号、AppID、merchantUid、金额、支付状态、退款单号和关键时间。支付与退款请求都需要稳定的开发者单号,以便在请求超时后查询结果和安全重试。

支付回调地址必须是可从公网访问的 HTTPS 地址。回调处理程序需要读取原始请求体、验证平台签名、校验订单和金额、识别重复通知,并快速返回平台要求的成功响应。

私钥、AppSecret 和 Access Token 只能保存在服务端安全环境中。预下单签名仅在当前支付请求中返回给应用插件使用,不应写入日志或长期存储。

支付接入自检清单

联调前请确认:

  • AppID、Access Token、商户和证书均属于同一环境。
  • 商户已完成开户、开通支付能力,并绑定当前 AppID。
  • merchantUid 使用当前应用绑定的商户 UID。
  • 支付证书和签名已按《8.1 关于证书》完成配置。
  • 签名使用的 data 与传给 requestOrder 的内容完全一致。
  • 支付、退款回调地址可通过公网访问,并已实现验签和幂等处理。

商户“已创建”不代表“已完成开户”。出现“该场景无可用支付方式”时,请优先检查开户状态、应用绑定关系和支付能力状态。

支付流程

下图展示从生成预下单参数、拉起收银台到服务端确认支付结果的完整时序:

一笔支付按以下顺序完成:

  1. 用户在应用插件中确认购买,你的服务端创建开发者订单,并生成唯一的 outOrderNo。
  2. 你的服务端根据已保存的订单信息组装预下单参数,将最终 JSON 序列化为字符串,并生成对应的 dbAuthorization。
  3. 应用插件使用服务端返回的 data 和 dbAuthorization 调用 requestOrder,获得平台订单号 orderId。
  4. 应用插件使用 orderId 调用 getOrderPayment 拉起收银台。
  5. 收银台交互结束后,应用插件向你的服务端查询开发者订单状态。你的服务端调用平台订单查询接口进行确认。
  6. 豆包开放平台向你的服务端发送支付结果回调。服务端完成验签、订单和金额校验后,安全地更新订单状态。

订单查询结果和支付回调可能以不同顺序到达,也可能重复到达。服务端应使用同一套订单状态规则处理两种结果,避免重复发货、重复记账或将已支付订单改回处理中。

请注意:应用插件成功创建平台订单或收银台正常关闭,都不能证明用户已经付款。只有你的服务端查询到支付成功,或收到并验证通过支付成功回调后,才能将开发者订单更新为已支付。

订单状态和重试规则

场景处理方式
requestOrder 成功保存返回的 orderId,用于拉起收银台
requestOrder 超时使用原 outOrderNo 查询结果,不要立即创建新订单
用户取消或关闭收银台查询支付状态,不能直接判定支付失败
再次发起支付orderId 有效时,使用原 orderId 再次拉起收银台
提示 out_order_no already exist查询并恢复原订单,不要更换订单号重复预下单
状态仍为处理中稍后再次查询,并等待支付回调
查询或回调确认成功幂等更新本地订单,避免重复发货或记账

outOrderNo 是开发者订单的唯一标识,同一业务订单重试时应保持不变。收银台正常返回不代表支付成功,最终结果以服务端查询或验签通过的支付回调为准。

退款重试时应复用原 out_refund_no;请求超时后先查询退款结果,不要立即生成新的退款单号。

生成预下单参数

预下单参数必须由你的服务端根据已保存的订单信息生成,不应由应用插件自行拼装。data 是 JSON 字符串,主要字段如下:

字段必填说明
skuList否商品列表,每项包含 skuId、price、quantity、title 和 totalAmount。
outOrderNo是开发者订单号,长度不超过 64 byte;同一开发者订单应保持不变。
merchantUid是收款商户 UID。
totalAmount是订单总金额,人民币场景单位为分。
orderName是订单名称。
orderDesc是订单描述。
currency否币种,当前人民币使用 CNY。
payExpireSeconds否支付有效期,单位为秒;不传或传 0 时默认为 300 秒,最长不超过 48 小时。
payNotifyUrl否该笔订单的支付结果回调地址,必须使用 HTTPS。

服务端应校验商品金额、数量和订单总金额的一致性,并使用整数表示分,避免浮点数计算造成金额误差。outOrderNo 应在创建订单时生成并持久化,不要在重试预下单时更换。

下面的示例只展示订单参数组装。signRequest 是示意函数名,具体实现参考关于证书; X-DB-Authorization 格式见《支付相关 API》:

const orderData = {
  skuList: [
    {
      skuId: 'sku_001',
      price: 1000,
      quantity: 1,
      title: '示例商品',
      totalAmount: 1000,
    },
  ],
  outOrderNo: 'order_202607150001',
  merchantUid: '<merchant-uid>',
  totalAmount: 1000,
  orderName: '示例订单',
  orderDesc: '示例商品 × 1',
  currency: 'CNY',
  payExpireSeconds: 300,
  payNotifyUrl: 'https://example.com/callbacks/payment',
};

const data = JSON.stringify(orderData);
const dbAuthorization = signRequest({
  method: 'POST',
  path: '/requestOrder',
  query: '',
  body: data,
});

return { data, dbAuthorization };

预下单签名的请求方法固定为 POST,签名路径固定为 /requestOrder,查询字符串为空。签名必须基于最终返回给应用插件的 data 原始字节生成;签名后不要再次解析、格式化或重新序列化该字符串,否则可能导致验签失败。

应用插件发起支付

应用插件从你的服务端取得预下单参数后,先创建平台订单,再拉起收银台。完整 API 定义和错误码见《JS API 说明》:

import { getOrderPayment, requestOrder } from '@doubao-dev/framework/api';

const material = await getPaymentMaterialFromServer();
const { orderId, logId } = await requestOrder({
  data: material.data,
  dbAuthorization: material.dbAuthorization,
});

await getOrderPayment({ orderId });

// 收银台返回不代表支付成功,应向你的服务端查询订单状态。
await refreshOrderFromServer(orderId);

保存 requestOrder 返回的 orderId,并将它与开发者订单关联。调用失败时可记录 logId 或错误对象中的 errLogId 用于排查,但不要记录签名和完整支付参数。

调用服务端支付 API

支付服务端接口均使用 POST 和 application/json,并通过请求头携带应用级访问凭证。Token 的获取与刷新见《服务端 API 总览》,各支付接口的完整字段和错误码见《支付相关 API》:

X-DB-AccessToken: <access-token>
Content-Type: application/json

通用响应结构如下:

{
  "code": 0,
  "msg": "success",
  "log_id": "20260715000000000000000000000000",
  "data": {}
}

不能只根据 HTTP 状态码判断调用是否成功。你的服务端还必须检查响应中的 code;非 0 时记录经过脱敏的请求信息、code、msg 和 log_id。

能力HTTP Path关键参数
查询订单详情/api/trade_basic/v1/developer/order_query/order_id、out_order_no 二选一。
申请退款/api/trade_basic/v1/developer/refund_create/原订单标识二选一,并传入 out_refund_no、refund_reason 和 refund_total_amount。
查询退款详情/api/trade_basic/v1/developer/refund_query/order_id、out_refund_no、refund_id 三选一。
推送履约完成通知/api/trade_basic/v1/developer/fulfill_push_finish/order_id、out_order_no 二选一。

查询订单信息

收银台交互结束或用户刷新订单页面时,应用插件向你的服务端查询开发者订单;你的服务端再向豆包开放平台确认支付状态:

例如,使用开发者订单号查询订单:

async function queryOrder(outOrderNo: string, accessToken: string) {
  const response = await fetch(
    '<platform-api-origin>/api/trade_basic/v1/developer/order_query/',
    {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        'X-DB-AccessToken': accessToken,
      },
      body: JSON.stringify({ out_order_no: outOrderNo }),
    },
  );

  const result = await response.json();
  if (!response.ok || result.code !== 0) {
    throw new Error(`查询订单失败,log_id=${result.log_id ?? 'unknown'}`);
  }
  return result.data;
}

订单查询结果中的 pay_status 表示平台支付状态:

状态说明处理方式
PROCESS支付处理中。保持处理中,可稍后再次查询。
SUCCESS支付成功。校验订单号、AppID 和金额后,将订单更新为已支付;重复结果不得触发重复发货。

对未知状态不要按成功处理,也不要因为收银台关闭或前端异常直接将订单判定为支付失败。

处理支付回调

支付和退款回调地址

回调类型地址来源回调 type
支付结果预下单参数中的 payNotifyUrlpayment
退款结果refund_create 中的 notify_urlrefund
  • 支付和退款回调地址均以接口参数为准,与应用详情中的“事件回调”配置无关。
  • 退款回调地址不会自动继承支付的 payNotifyUrl;需要接收退款回调时,必须在 refund_create 中传入 notify_url。
  • 支付和退款可以使用同一个地址,服务端通过 type 区分事件。
  • 未传 notify_url 时不会收到退款回调,需要调用 refund_query 查询最终结果。

支付结果回调发送到预下单参数中的 payNotifyUrl。请求方法为 POST,主要请求头如下:

请求头说明
Content-Type固定为 application/json。
X-DB-Logid平台日志 ID,用于问题排查。
X-DB-Authorization平台生成的回调签名,需按《支付相关 API》的签名认证规范验签。

回调请求体外层包含 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 等支付结果字段。

处理回调时应遵循以下顺序:

  1. 保留原始请求体,并先校验 X-DB-Authorization,不要使用重新序列化后的 JSON 验签。
  2. 按签名认证规范校验时间戳、nonce、证书序列号和签名,拒绝过期或重复请求。
  3. 解析外层结构和 msg,确认 type、version 和字段类型符合预期。
  4. 根据 out_order_no 查找本地订单,校验 app_id、order_id 和 total_amount。
  5. 使用开发者订单号和平台订单号识别重复通知。重复回调不得重复更新订单、发货或记账。
  6. 成功处理后返回 HTTP 200 和固定响应;发货、记账等耗时操作应异步执行,避免回调响应超时。
{
  "code": 0,
  "msg": "success"
}

未按上述格式返回时,平台会将本次通知视为失败并重试。回调处理异常或结果存在冲突时,应保留 X-DB-Logid,并主动调用订单查询接口核对最终状态。

退款

退款必须由你的服务端发起,不能由应用插件直接调用平台退款接口。

申请退款

refund_create 支持整单退款和部分退款,主要参数包括:

字段必填说明
order_id / out_order_no二选一标识原支付订单。
out_refund_no是开发者退款单号,长度不超过 64 byte;一次退款请求应保持不变。
refund_reason是退款原因。
refund_total_amount是退款金额,单位为分。
refund_sku_list否多商品订单退款时填写,商品 ID 必须与下单时一致。
notify_url否退款结果回调地址。

查询退款单信息

退款创建成功只表示豆包开放平台已经受理。应用插件展示退款状态时,应由你的服务端调用 refund_query 查询:

接口受理成功会返回平台退款单号 refund_id,这只表示退款请求已创建。服务端应通过退款回调或 refund_query 获取最终状态:

状态说明
PROCESSING退款处理中。
SUCCESS退款成功。
FAIL退款失败。

退款回调发送到 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。