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/server-api/payment.md.

支付相关 API

本文提供豆包应用插件支付服务端 API 的请求参数、响应字段、状态枚举、回调协议、签名规则和支付错误码参考。

如果你还没有完成商户开户、应用绑定和证书配置,请先阅读《支付接入(服务端)》。服务端 API 的请求域名、应用级 Access Token 获取方式、通用响应结构和通用重试原则,参见《服务端 API 总览》。

调用前准备

调用支付能力前,请确认以下事项均已完成:

  1. 商户账户已通过审核,且处于可用状态。
  2. 商户已绑定到当前应用插件,并已取得该环境下的 merchantUid。
  3. 服务端已取得有效的应用级 Access Token。
  4. 需要使用普通支付或接收支付回调时,已配置开发者证书和平台证书。
  5. 回调地址可以从公网通过 HTTPS 访问,并能保存原始请求体用于验签。

测试环境和正式环境的应用、商户、证书、访问令牌与订单数据相互隔离,不能混用。

Access Token 与支付签名的区别

支付链路中会出现三种不同的认证信息:

认证信息使用位置作用
X-DB-AccessToken本文列出的服务端 API 请求头验证调用方属于哪个应用插件
dbAuthorization应用插件前端 requestOrder 的参数证明预下单数据由开发者服务端生成且未被篡改
X-DB-Authorization豆包开放平台发送的支付、退款、签约和代扣回调请求头供开发者服务端验证回调来自豆包开放平台

三者不能相互替代。本文列出的服务端 API 使用应用级 Access Token,不要求额外携带 X-DB-Authorization;支付签名主要用于预下单数据和回调验签。

商户标识 merchantUid

merchantUid 是豆包开放平台为收款商户分配的唯一标识。它不是应用插件 AppID,也不能由开发者自行生成。

在开始支付联调前,请在豆包开发者平台确认商户已经与当前应用插件绑定成功,并保存平台展示的 merchantUid。如果尚未获得该标识,或者商户仍处于审核中、停用或解绑状态,应先按照《支付接入(服务端)》完成商户开户和应用绑定,不能使用其他应用或其他环境的商户标识代替。

同一标识在不同协议中的字段名不同:

使用位置字段名
应用插件预下单参数merchantUid
服务端 API 响应和回调消息merchant_uid

收到订单查询结果或回调后,应校验 app_id、merchant_uid、业务单号和金额是否与本地订单一致。

业务单号

支付接口同时使用开发者生成的业务单号和豆包开放平台生成的平台单号。建议在本地同时保存两者。

业务对象开发者单号平台单号
普通支付订单out_order_noorder_id
退款单out_refund_norefund_id
签约单out_auth_order_noauth_order_id
协议支付订单out_pay_order_nopay_order_id

开发者单号应在当前应用的对应业务范围内保持唯一,长度不超过 64 个字符。创建类请求超时后,结果可能已经生效;不要立即更换业务单号重复创建,应先使用原业务单号调用查询接口确认结果。

API 索引

接口用途
查询订单查询普通支付订单的支付状态与支付信息
创建退款为已支付订单发起全部或部分退款
查询退款查询单笔退款,或查询指定订单下的退款列表
通知履约完成商品或服务交付完成后通知豆包开放平台
查询签约订单查询签约关系的当前状态
解除签约由开发者主动解除签约关系
创建协议支付订单基于有效签约关系创建代扣订单
查询协议支付订单查询代扣订单状态和失败原因
关闭协议支付订单关闭尚未完成的代扣订单

请求与响应说明

服务端 API 均使用相同的请求头:

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

下文的响应字段表只列出各接口 data 中的业务字段。code、msg、log_id 等通用字段及其处理方式见《服务端 API 总览》。示例中的订单号、金额、用户标识和回调地址仅用于说明格式。

查询订单

查询普通支付订单的当前状态、金额和支付信息。查询接口可用于主动确认支付结果,也可用于回调丢失或状态存疑时的补偿查询。

请求

POST /api/trade_basic/v1/developer/order_query
字段类型必填说明
order_idstring条件必填平台订单号;与 out_order_no 至少填写一个
out_order_nostring条件必填开发者订单号;与 order_id 至少填写一个

建议每次只使用一种单号查询;如果同时填写,两者必须指向同一订单。

curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/order_query' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_order_no": "order-20260716-0001"
  }'

响应

data 字段类型说明
app_idstring应用插件 AppID
order_idstring平台订单号
out_order_nostring开发者订单号
merchant_uidstring收款商户标识
pay_statusstring支付状态,见下表
total_amountstring订单总金额,单位为分
trade_timestring订单创建时间,毫秒时间戳
pay_timestring支付完成时间,毫秒时间戳;未完成支付时可能不返回
pay_typestring支付方式;支付成功后返回
pay_order_nostring支付渠道订单号;支付成功后返回

pay_status 枚举:

值说明建议处理
INIT订单已创建等待支付或继续查询
PROCESSING支付处理中不要发货,继续查询或等待回调
SUCCESS支付成功校验订单和金额后进入履约
CLOSED订单已关闭终止支付流程
FAIL支付失败终止本次支付并允许用户重新发起
{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456",
  "data": {
    "app_id": "app_example",
    "order_id": "order_platform_001",
    "out_order_no": "order-20260716-0001",
    "merchant_uid": "merchant_example",
    "pay_status": "SUCCESS",
    "total_amount": "200",
    "trade_time": "1784160000000",
    "pay_time": "1784160060000",
    "pay_type": "BYTE_PAY",
    "pay_order_no": "pay_channel_001"
  }
}

该接口为只读接口,可以使用相同参数安全重试。订单不存在时返回 500020005;查询了不受该接口支持的订单类型时可能返回 500020009。

创建退款

为已支付成功的普通支付订单或协议支付订单发起全部退款或部分退款。

请求

POST /api/trade_basic/v1/developer/refund_create
字段类型必填说明
order_idstring条件必填原支付订单的平台订单号;与 out_order_no 至少填写一个
out_order_nostring条件必填原支付订单的开发者订单号;与 order_id 至少填写一个
out_refund_nostring是开发者退款单号,在当前应用内保持唯一,最长 64 个字符
refund_reasonstring否退款原因
refund_total_amountstring是退款总金额,正整数,单位为分
refund_sku_listarray否退款商品明细
notify_urlstring否退款结果回调地址;填写时必须是合法且可访问的 URL,正式环境建议使用 HTTPS

refund_sku_list 元素字段:

字段类型必填说明
sku_idstring是原订单中的商品标识
refund_amountstring是该商品的退款金额,单位为分
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/refund_create' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_order_no": "order-20260716-0001",
    "out_refund_no": "refund-20260716-0001",
    "refund_reason": "用户申请退款",
    "refund_total_amount": "100",
    "refund_sku_list": [
      {
        "sku_id": "sku-1",
        "refund_amount": "100"
      }
    ],
    "notify_url": "https://example.com/callback/refund"
  }'

响应

data 字段类型说明
refund_idstring平台退款单号
{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456",
  "data": {
    "refund_id": "refund_platform_001"
  }
}

out_refund_no 是本接口的幂等键。同一个退款业务必须始终使用同一个 out_refund_no 和相同的退款参数;不要将同一退款单号用于不同订单或不同金额。请求超时后,先使用原 out_refund_no 调用“查询退款”,确认不存在后再决定是否重试。

未填写 notify_url 时不会收到退款结果回调,需要通过“查询退款”获取最终状态。

常见支付错误包括:退款单号冲突 500020003、原订单不存在 500020005、订单类型不支持退款 500020010、商户绑定不存在 500020011、相同退款单号对应的参数不一致 500020012,以及订单结算期间暂不允许退款 500020013。

查询退款

按退款单号查询单笔退款,或按平台订单号查询该订单下的退款列表。

请求

POST /api/trade_basic/v1/developer/refund_query
字段类型必填说明
order_idstring三选一平台订单号。使用该字段时返回订单下的退款列表
refund_idstring三选一平台退款单号
out_refund_nostring三选一开发者退款单号

三个查询字段必须且只能填写一个。

curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/refund_query' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_refund_no": "refund-20260716-0001"
  }'

响应

data 字段类型说明
refund_listarray退款记录列表

refund_list 元素字段:

字段类型说明
order_idstring原支付订单的平台订单号
refund_idstring平台退款单号
out_refund_nostring开发者退款单号
refund_statusstring退款状态,见下表
refund_total_amountstring退款总金额,单位为分
refund_create_timestring退款创建时间,毫秒时间戳
refund_finish_timestring退款完成时间,毫秒时间戳;未完成时可能不返回

refund_status 枚举:

值说明
PROCESSING退款处理中
SUCCESS退款成功
FAIL退款失败
{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456",
  "data": {
    "refund_list": [
      {
        "order_id": "order_platform_001",
        "refund_id": "refund_platform_001",
        "out_refund_no": "refund-20260716-0001",
        "refund_status": "SUCCESS",
        "refund_total_amount": "100",
        "refund_create_time": "1784160100000",
        "refund_finish_time": "1784160160000"
      }
    ]
  }
}

该接口为只读接口,可以使用相同参数安全重试。平台订单不存在时返回 500020005,退款单不存在时返回 500020006,退款订单类型不受支持时可能返回 500020010。

通知履约完成

当已支付订单对应的商品或服务交付完成后,通知豆包开放平台更新履约状态。只有业务实际履约完成后才能调用本接口。

请求

POST /api/trade_basic/v1/developer/fulfill_push_finish
字段类型必填说明
order_idstring条件必填平台订单号;与 out_order_no 至少填写一个
out_order_nostring条件必填开发者订单号;与 order_id 至少填写一个
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/fulfill_push_finish' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_order_no": "order-20260716-0001"
  }'

响应

本接口成功时不返回 data:

{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456"
}

同一订单重复通知履约完成不会产生重复履约结果,但调用前仍应由业务服务记录本地履约状态,避免在商品尚未交付时误调用。订单不存在时返回 500020005。

查询签约订单

查询签约关系的当前状态。创建协议支付订单前,应先调用本接口确认签约关系处于可用状态。

请求

POST /api/trade_basic/v1/developer/query_sign_order
字段类型必填说明
auth_order_idstring条件必填平台签约单号;与 out_auth_order_no 至少填写一个
out_auth_order_nostring条件必填开发者签约单号;与 auth_order_id 至少填写一个

建议每次只使用一种单号查询;如果同时填写,两者必须指向同一签约单。

curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/query_sign_order' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_auth_order_no": "sign-20260716-0001"
  }'

响应

data 字段类型说明
app_idstring应用插件 AppID
auth_order_idstring平台签约单号
out_auth_order_nostring开发者签约单号
open_idstring签约用户在当前应用下的 OpenID
service_idstring签约服务 ID
statusstring签约状态,见下表
merchant_uidstring商户标识
unsign_sourceinteger解约来源;解约后返回。 1 表示用户主动解约, 2 表示商户解约
sign_timestring签约时间,毫秒时间戳;签约完成后返回

status 枚举:

值说明是否可用于创建协议支付订单
TOBESERVED等待用户完成签约否
SERVING签约关系生效中是
CANCEL已解约否
TIMEOUT用户未在有效期内完成签约否
DONE签约关系已结束否
{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456",
  "data": {
    "app_id": "app_example",
    "auth_order_id": "sign_platform_001",
    "out_auth_order_no": "sign-20260716-0001",
    "open_id": "open_id_example",
    "service_id": "service_example",
    "status": "SERVING",
    "merchant_uid": "merchant_example",
    "sign_time": "1784160000000"
  }
}

该接口为只读接口,可以使用相同参数安全重试。签约单不存在或不属于当前应用时返回 500020005。

解除签约

由开发者主动解除已有签约关系。解约后,该签约关系不能再用于创建新的协议支付订单。

请求

POST /api/trade_basic/v1/developer/terminate_sign
字段类型必填说明
auth_order_idstring是平台签约单号,最长 64 个字符
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/terminate_sign' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "auth_order_id": "sign_platform_001"
  }'

响应

本接口成功时不返回 data:

{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456"
}

对已经解约的签约单重复调用会返回成功。TIMEOUT 或 DONE 状态不能执行解约;签约单不存在或不属于当前应用时返回 500020005。调用成功后,仍应通过“查询签约订单”或签约结果回调确认最终状态。

创建协议支付订单

基于处于 SERVING 状态的签约关系创建协议支付订单。协议支付订单会按照签约服务的规则执行扣款。

请求

POST /api/trade_basic/v1/developer/create_sign_pay
字段类型必填说明
auth_order_idstring是平台签约单号,最长 64 个字符
pay_dataobject是协议支付订单数据

pay_data 字段:

字段类型必填说明
sku_listarray是商品明细;可以传空数组,非空时每项必须满足下表规则
out_pay_order_nostring是开发者协议支付订单号,在当前应用内保持唯一,最长 64 个字符
total_amountstring是订单总金额,非负整数,单位为分
order_namestring是订单名称
order_descstring是订单描述
currencystring否币种。省略或传空字符串时使用 CNY ;目前只支持 CNY
pay_expire_secondsstring否支付有效期,单位为秒。省略或传 0 时使用 300 秒,最大为 172800 秒
pay_notify_urlstring否协议支付结果回调地址;填写时必须是合法且可访问的 URL,正式环境建议使用 HTTPS

sku_list 元素字段:

字段类型必填说明
sku_idstring是商品标识,最长 64 个字符
pricestring是商品单价,正整数,单位为分
quantitystring是商品数量,正整数
titlestring是商品名称,最长 256 个字符
total_amountstring是商品小计,必须等于 price × quantity ,单位为分

当 sku_list 非空时,所有商品小计之和必须等于 pay_data.total_amount。

curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/create_sign_pay' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "auth_order_id": "sign_platform_001",
    "pay_data": {
      "sku_list": [
        {
          "sku_id": "sku-1",
          "price": "100",
          "quantity": "2",
          "title": "示例商品",
          "total_amount": "200"
        }
      ],
      "out_pay_order_no": "sign-pay-20260716-0001",
      "total_amount": "200",
      "order_name": "会员订阅",
      "order_desc": "示例会员月度订阅",
      "currency": "CNY",
      "pay_expire_seconds": "300",
      "pay_notify_url": "https://example.com/callback/sign-pay"
    }
  }'

响应

data 字段类型说明
pay_order_idstring平台协议支付订单号
{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456",
  "data": {
    "pay_order_id": "sign_pay_platform_001"
  }
}

out_pay_order_no 是本接口的业务幂等标识。请求超时后,先使用原 out_pay_order_no 调用“查询协议支付订单”,不要更换单号重复创建。签约单必须处于 SERVING 状态;其他状态会返回参数错误。常见支付错误包括业务单号已存在 500020002、签约单不存在 500020005 和商户绑定不存在 500020011。

查询协议支付订单

查询协议支付订单的支付状态、支付信息和失败原因。

请求

POST /api/trade_basic/v1/developer/query_sign_pay
字段类型必填说明
pay_order_idstring条件必填平台协议支付订单号;与 out_pay_order_no 至少填写一个
out_pay_order_nostring条件必填开发者协议支付订单号;与 pay_order_id 至少填写一个

建议每次只使用一种单号查询;如果同时填写,两者必须指向同一订单。

curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/query_sign_pay' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_pay_order_no": "sign-pay-20260716-0001"
  }'

响应

data 字段类型说明
app_idstring应用插件 AppID
auth_order_idstring关联的平台签约单号
pay_order_idstring平台协议支付订单号
out_pay_order_nostring开发者协议支付订单号
merchant_uidstring收款商户标识
pay_statusstring支付状态,见下表
total_amountstring订单总金额,单位为分
trade_timestring订单创建时间,毫秒时间戳
pay_success_sourceinteger支付成功来源。 1 表示用户主动支付, 2 表示协议扣款成功
pay_timestring支付完成时间,毫秒时间戳;未完成时可能不返回
pay_typestring支付方式;支付成功后返回
pay_order_nostring支付渠道订单号;支付成功后返回
sign_pay_fail_codestring协议支付失败码;失败时可能返回
sign_pay_fail_msgstring协议支付失败原因;失败时可能返回

pay_status 枚举:

值说明建议处理
INIT订单已创建等待执行扣款
PROCESSING扣款处理中继续查询或等待回调
SUCCESS扣款成功校验订单和金额后进入履约
CLOSED订单已关闭终止本次扣款
FAIL扣款失败读取失败码和失败原因,终止本次扣款
{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456",
  "data": {
    "app_id": "app_example",
    "auth_order_id": "sign_platform_001",
    "pay_order_id": "sign_pay_platform_001",
    "out_pay_order_no": "sign-pay-20260716-0001",
    "merchant_uid": "merchant_example",
    "pay_status": "SUCCESS",
    "total_amount": "200",
    "trade_time": "1784160000000",
    "pay_success_source": 2,
    "pay_time": "1784160060000",
    "pay_type": "BYTE_PAY",
    "pay_order_no": "pay_channel_001"
  }
}

该接口为只读接口,可以使用相同参数安全重试。协议支付订单不存在或不属于当前应用时返回 500020005。当 pay_status 不是最终状态时,不要据此履约;继续查询或等待回调。

关闭协议支付订单

关闭尚未完成的协议支付订单。订单关闭后不能继续扣款。

请求

POST /api/trade_basic/v1/developer/close_sign_pay
字段类型必填说明
pay_order_idstring条件必填平台协议支付订单号;与 out_pay_order_no 至少填写一个
out_pay_order_nostring条件必填开发者协议支付订单号;与 pay_order_id 至少填写一个
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/close_sign_pay' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "out_pay_order_no": "sign-pay-20260716-0001"
  }'

响应

本接口成功时不返回 data:

{
  "code": 0,
  "msg": "success",
  "log_id": "20260716120000ABCDEF123456"
}

已处于 CLOSED 状态的订单重复关闭会返回成功;SUCCESS 或 FAIL 状态的订单不能关闭。支付成功后如需退回资金,应调用“创建退款”,不能调用本接口。协议支付订单不存在或不属于当前应用时返回 500020005。

回调协议

支付、退款、签约或协议支付状态发生变化后,豆包开放平台会向开发者配置的回调地址发送 HTTP POST 请求。回调由豆包开放平台主动发起,不是开发者需要调用的 OpenAPI。

回调回调地址来源type
支付结果回调预下单参数中的 payNotifyUrlpayment
退款结果回调创建退款时传入的 notify_urlrefund
签约结果回调签约服务配置的回调地址sign_callback
协议支付结果回调创建协议支付订单时传入的 pay_notify_urlsign_pay_callback

回调请求头

请求头必填说明
Content-Type是固定为 application/json
X-DB-Logid是本次回调的请求标识,排查问题时请保留
X-DB-Authorization是豆包开放平台生成的签名认证信息,验签规则见支付签名与验签

回调外层结构

所有支付回调使用相同的外层结构:

字段类型必填说明
typestring是回调类型
versionstring是回调协议版本,当前为 1.0
msgstring是JSON 字符串;需要再次解析才能得到业务字段
{
  "type": "payment",
  "version": "1.0",
  "msg": "{\"app_id\":\"app_example\",\"order_id\":\"order_platform_001\",\"out_order_no\":\"order-20260716-0001\",\"merchant_uid\":\"merchant_example\",\"pay_status\":\"SUCCESS\",\"total_amount\":\"200\",\"event_time\":\"1784160060000\",\"pay_type\":\"BYTE_PAY\",\"pay_order_no\":\"pay_channel_001\"}"
}

验签时必须使用收到的完整原始请求体字节。不要先把外层 JSON 或 msg 解析后重新序列化,再用新生成的字节验签。

支付结果回调

当 type 为 payment 时,msg 解析后的字段如下:

字段类型必填说明
app_idstring是应用插件 AppID
order_idstring是平台订单号
out_order_nostring是开发者订单号
merchant_uidstring是收款商户标识
pay_statusstring是支付结果;当前回调通知最终成功状态 SUCCESS
total_amountstring是订单总金额,单位为分
event_timestring是事件发生时间,毫秒时间戳
pay_typestring是支付方式: ALI_PAY 、 WECHAT_PAY 或 BYTE_PAY
pay_order_nostring是支付渠道订单号

支付成功后,先核对 app_id、订单号、merchant_uid 和 total_amount,再将本地订单更新为已支付。不要只根据回调中的单个状态字段直接发货。

退款结果回调

当 type 为 refund 时,msg 解析后的字段如下:

字段类型必填说明
app_idstring是应用插件 AppID
order_idstring是原支付订单的平台订单号
refund_idstring是平台退款单号
out_refund_nostring是开发者退款单号
refund_statusstring是最终退款状态: SUCCESS 或 FAIL
refund_total_amountstring是退款总金额,单位为分
event_timestring是事件发生时间,毫秒时间戳

退款回调只通知最终结果,不通知 PROCESSING 中间状态。

{
  "type": "refund",
  "version": "1.0",
  "msg": "{\"app_id\":\"app_example\",\"order_id\":\"order_platform_001\",\"refund_id\":\"refund_platform_001\",\"out_refund_no\":\"refund-20260716-0001\",\"refund_status\":\"SUCCESS\",\"refund_total_amount\":\"100\",\"event_time\":\"1784160160000\"}"
}

签约结果回调

当 type 为 sign_callback 时,msg 解析后的字段如下:

字段类型必填说明
app_idstring是应用插件 AppID
auth_order_idstring是平台签约单号
out_auth_order_nostring是开发者签约单号
statusstring是签约状态,与“查询签约订单”的 status 枚举一致
unsign_sourceinteger否解约来源。 1 表示用户主动解约, 2 表示商户解约;解约时返回
event_timestring是事件发生时间,毫秒时间戳
{
  "type": "sign_callback",
  "version": "1.0",
  "msg": "{\"app_id\":\"app_example\",\"auth_order_id\":\"sign_platform_001\",\"out_auth_order_no\":\"sign-20260716-0001\",\"status\":\"SERVING\",\"event_time\":\"1784160000000\"}"
}

协议支付结果回调

当 type 为 sign_pay_callback 时,msg 解析后的字段如下:

字段类型必填说明
app_idstring是应用插件 AppID
auth_order_idstring是关联的平台签约单号
pay_order_idstring是平台协议支付订单号
out_pay_order_nostring是开发者协议支付订单号
pay_statusstring是支付结果: SUCCESS 或 FAIL
total_amountstring是订单总金额,单位为分
event_timestring是事件发生时间,毫秒时间戳
merchant_uidstring是收款商户标识
pay_success_sourceinteger否支付成功来源。 1 表示用户主动支付, 2 表示协议扣款成功
pay_typestring否支付方式;支付成功时返回
pay_order_nostring否支付渠道订单号;支付成功时返回
sign_pay_fail_codestring否协议支付失败码;失败时可能返回
sign_pay_fail_msgstring否协议支付失败原因;失败时可能返回
{
  "type": "sign_pay_callback",
  "version": "1.0",
  "msg": "{\"app_id\":\"app_example\",\"auth_order_id\":\"sign_platform_001\",\"pay_order_id\":\"sign_pay_platform_001\",\"out_pay_order_no\":\"sign-pay-20260716-0001\",\"pay_status\":\"FAIL\",\"total_amount\":\"200\",\"event_time\":\"1784160160000\",\"merchant_uid\":\"merchant_example\",\"sign_pay_fail_code\":\"PAY_RISK_REJECT\",\"sign_pay_fail_msg\":\"支付风险校验未通过\"}"
}

成功响应与重试

回调验签通过并且业务结果已经可靠保存后,开发者服务端必须返回 HTTP 200 和以下 JSON:

{
  "code": 0,
  "msg": "success"
}

如果未返回 HTTP 200,或者响应体中的 code 和 msg 不符合上述格式,豆包开放平台会将本次回调视为失败并重试。回调可能因此重复到达,也可能与主动查询结果交错到达。接收服务必须做到:

  • 使用 type 与对应的平台单号作为幂等依据;同一结果重复到达时不能重复发货、重复记账或重复退款。
  • 只允许合法的状态转换,不允许较早的消息把本地终态回退为中间状态。
  • 业务处理较慢时,先将已验签的事件可靠写入队列或数据库,再返回成功;不要在结果尚未保存时提前返回成功。
  • 长时间未收到回调或对回调结果有疑问时,调用对应查询接口确认状态。

下载账单

按商户、交易类型、交易状态和日期范围生成账单文件。接口会在服务端提交导出任务并同步等待文件生成;成功时只返回下载地址,不返回导出任务 ID,也不提供后续查询或恢复任务的接口。

请求

POST /api/trade_basic/v1/developer/bill_download
字段类型必填说明
merchant_uidstring是收款商户标识,必须已绑定当前应用插件
trade_typestring否交易类型:PAY 表示支付账单,REFUND 表示退款账单;不填写或传空字符串表示全部
start_datestring是查询起始日期,格式为 yyyyMMdd,按东八区自然日解释
end_datestring是查询结束日期,格式为 yyyyMMdd,按东八区自然日解释,包含当天
trade_statusstring否交易状态:PROCESSING、SUCCESS 或 FAIL;不填写或传空字符串表示全部

日期范围必须满足以下规则:

  • start_date 和 end_date 必须是真实有效的日期,不能使用 yyyy-MM-dd、时间戳或其他格式。
  • end_date 不能早于 start_date。
  • 查询范围最多包含 31 个东八区自然日(起止日期均计入)。例如,20260801 至 20260831 合法,20260801 至 20260901 不合法。超过 31 天的范围应拆分为多个请求。
  • 单日账单应将 start_date 和 end_date 设置为同一天。
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/bill_download' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "merchant_uid": "merchant_example",
    "trade_type": "PAY",
    "start_date": "20260801",
    "end_date": "20260803",
    "trade_status": "SUCCESS"
  }'

响应

data 字段类型说明
download_urlstring账单文件下载地址
{
  "code": 0,
  "msg": "success",
  "log_id": "20260813120000ABCDEF123456",
  "data": {
    "download_url": "https://example.com/bills/bill-20260801-20260803.csv"
  }
}

调用边界与重试

  • 本接口是同步接口。服务端会先创建或复用相同查询条件的导出任务,再轮询等待文件生成;调用方只需处理本次响应,不需要保存或查询导出任务 ID。
  • 当前单次同步等待最长约 30 秒。请求超时或返回服务错误时,不能据此判断财经侧任务一定失败;建议使用完全相同的查询参数有限重试。
  • 新导出请求按 merchant_uid 限制为每分钟 1 次。商户归属校验通过后才计入限流;短期内使用完全相同参数重试且已有成功结果时,会直接复用下载地址,不占用新的导出限流额度。
  • 相同参数包括应用、merchant_uid、trade_type、trade_status、start_date 和 end_date。修改任一筛选条件会被视为新的导出请求。
  • 获得下载地址后应及时下载并妥善保存账单文件。
  • 参数格式、日期范围、枚举值或商户绑定不合法时返回参数错误;调用过于频繁时返回 500000002。这些错误不应使用原请求高频重试。

文件样例

交易明细报表20260530-20260601_260814140149240405544990.csv189 B

下载结算账单

按商户、时间类型和日期范围生成结算账单 CSV 文件。接口会在服务端提交导出任务并同步等待文件生成;成功时只返回下载地址,不返回导出任务 ID,也不提供后续查询或恢复任务的接口。

请求

POST /api/trade_basic/v1/developer/settle_bill_download

请求头沿用本文的通用请求头,X-DB-AccessToken 必须为当前应用插件的有效应用级 Access Token。

字段类型必填说明
merchant_uidstring是收款商户标识,必须已绑定当前应用插件
time_typestring是时间类型:"0" 表示按结算时间查询;"1" 表示按下单时间查询。必须以字符串传入
start_datestring是查询起始日期,格式为 yyyyMMdd,按东八区(UTC+8)自然日解释,包含当天
end_datestring是查询结束日期,格式为 yyyyMMdd,按东八区(UTC+8)自然日解释,包含当天

日期范围必须满足以下规则:

  • 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 筛选;请勿套用“下载账单”的交易类型和状态参数。
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/settle_bill_download' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "merchant_uid": "merchant_example",
    "time_type": "0",
    "start_date": "20260801",
    "end_date": "20260831"
  }'

响应

data 字段类型说明
download_urlstring结算账单 CSV 文件的带签名下载地址。无需传入文件名,应及时下载并妥善保存;链接过期后不可继续使用
{
  "code": 0,
  "msg": "success",
  "log_id": "20261009120000ABCDEF123456",
  "data": {
    "download_url": "https://example.com/bills/settle-bill-20260801-20260831.csv"
  }
}

调用边界与重试

  • 本接口为同步接口。服务端创建或短期复用相同查询条件的导出任务,等待文件生成后返回 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 指向验签方
生成预下单 dbAuthorization开发者服务端开发者私钥开发者证书豆包开放平台
验证支付相关回调豆包开放平台平台私钥平台证书开发者服务端

开发者私钥只能保存在开发者服务端。开发者服务端需要保存当前有效的开发者证书和平台证书,并在证书轮换期间按证书序列号选择正确证书;未知的 cert_serial 必须拒绝,不能遍历所有证书尝试验签。

待签名字符串

按照以下顺序构造待签名字符串:

HTTP_METHOD + "\n" +
REQUEST_PATH + "\n" +
CANONICAL_QUERY + "\n" +
BODY_SHA256_HEX + "\n" +
TIMESTAMP + "\n" +
NONCE

各部分规则如下:

部分规则
HTTP_METHOD使用大写方法名,例如 POST
REQUEST_PATH以 / 开头,只包含路径,不包含域名和 query
CANONICAL_QUERY按 key 字典序排列;同一 key 的多个值也按字典序排列,再以 key=value 和 & 拼接。没有 query 时保留空字符串
BODY_SHA256_HEX对实际发送的原始 UTF-8 请求体字节计算 SHA-256,输出小写十六进制
TIMESTAMP秒级 Unix 时间戳字符串,不是毫秒时间戳
NONCE使用密码学安全随机源生成,每次签名必须使用新值

CANONICAL_QUERY 中的 key 和 value 使用 URL 解码后的原始值参与排序和拼接。拼接结果固定包含五个换行符。Query 为空时,第三行仍然保留为空行;末尾不增加额外换行。请求体计算摘要后不能再次格式化或重新序列化。

如果加密库提供 SHA256withECDSA 之类的高层接口,应将完整待签名字符串交给该接口,由其完成 SHA-256;如果使用接收摘要的低层 ECDSA 接口,则先自行计算一次 SHA-256。不要先计算摘要,再把摘要交给会再次执行 SHA-256 的高层接口。

授权信息格式

dbAuthorization 和 X-DB-Authorization 使用相同的单行字段格式:

algorithm="ECDSA_SHA256",version="1",signature="<PADDED_BASE64URL_DER_SIGNATURE>",cert_serial="<CERT_SERIAL>",nonce="<NONCE>",timestamp="<UNIX_SECONDS>"

字段顺序和格式应保持一致,不要插入额外空格、换行或折行:

字段说明
algorithm固定为 ECDSA_SHA256
version固定为 1
signatureECDSA ASN.1 DER 签名的 padded Base64URL 字符串,末尾可能包含 =
cert_serial十六进制证书序列号。开发者签名时填写开发者证书序列号,平台回调时填写平台证书序列号
nonce本次请求的唯一随机值
timestamp与待签名字符串一致的秒级 Unix 时间戳

不要把 ECDSA 签名编码为固定长度的 r || s,也不要使用会主动删除 = 的 Raw Base64URL 编码。

生成预下单 dbAuthorization

应用插件前端 requestOrder 使用以下固定签名上下文:

HTTP_METHOD = POST
REQUEST_PATH = /requestOrder
CANONICAL_QUERY = 空字符串
BODY = 最终交给应用插件前端的 data 原始 UTF-8 字节

服务端生成流程:

  1. 从可信订单数据计算商品、金额和 merchantUid,生成最终 data 字符串。
  2. 计算 data 原始字节的 SHA-256 摘要,并构造待签名字符串。
  3. 使用开发者 ECC P-256 私钥生成 ECDSA ASN.1 DER 签名。
  4. 将签名编码为保留 = 补位的 Base64URL 字符串。
  5. 使用开发者证书序列号组装 dbAuthorization。
  6. 将同一份 data 字符串和 dbAuthorization 返回给应用插件前端,由前端原样传给 requestOrder。

完成签名后,不要再对 data 执行 JSON.parse、JSON.stringify、字段重排或格式化。即使 JSON 解析结果相同,原始字节变化也会导致验签失败。

验证回调签名

回调验签流程:

  1. 在读取和解析 JSON 前保存请求体原始字节。
  2. 从 X-DB-Authorization 中解析并校验 algorithm、version、signature、cert_serial、nonce 和 timestamp。
  3. 根据 cert_serial 选择对应的平台证书,并检查证书有效期。
  4. 校验 timestamp 是否在服务允许的时间窗口内;在共享存储中记录 nonce,拒绝时间窗口内的重复值。
  5. 使用实际收到的 HTTP 方法、回调路径、query 和原始请求体构造待签名字符串。
  6. 对 signature 进行 padded Base64URL 解码,得到 ASN.1 DER 字节。
  7. 使用平台证书中的 P-256 公钥执行 ECDSA-SHA256 验签。
  8. 只有验签通过后,才解析外层 JSON 和 msg 并处理业务。

多实例部署时,nonce 去重必须使用所有实例共享且支持原子写入的存储。服务器时间应保持同步;生产日志中不要记录私钥、完整签名、完整授权头或包含用户数据的完整请求体。

支付错误码

每个接口可能返回通用错误、应用凭证错误和支付业务错误。程序应根据 code 判断处理方式,不要根据可能调整的 msg 文本编写业务分支。

常用调用错误

错误码含义处理建议
500000000服务暂时无法完成请求保留 log_id ,按接口幂等规则有限重试;持续失败时联系技术支持
500000001请求参数错误检查必填字段、单号组合、金额格式、状态和回调地址,不要原样重试
500000002调用频率过高降低频率并使用递增等待时间重试
500000003签名验证失败检查证书、签名算法、原始请求体、时间戳、nonce 和编码方式
500000004无权执行该操作检查用户、应用、商户和资源是否匹配
500010003应用级 Access Token 已过期重新获取并缓存新的应用级 Access Token 后重试
500010004应用级 Access Token 无效检查令牌是否属于当前应用和环境,重新获取后重试
500010006用户会话 Token 已过期仅“检查用户支付风险”可能返回;使用当前会话中的新 Token 重试
500010007用户会话 Token 无效仅“检查用户支付风险”可能返回;检查请求头和用户会话

支付业务错误

错误码含义常见接口处理建议
500020002开发者订单号已存在创建协议支付订单、预下单使用原业务单号查询已有订单,不要换号重复扣款
500020003开发者退款单号已存在创建退款使用原 out_refund_no 查询退款;不要把同一单号用于另一笔退款
500020004支付签名异常预下单或签名相关支付流程核对证书、待签名字符串、Body 摘要和签名编码
500020005订单不存在订单、退款、履约、签约和协议支付接口检查平台单号或开发者单号是否正确,并确认订单属于当前应用和环境
500020006退款单不存在查询退款检查 refund_id 或 out_refund_no ,并确认退款创建请求是否成功
500020007开发者签约单号已存在创建签约单查询已有签约单,不要重复创建签约关系
500020008签约单状态不允许当前操作签约和协议支付接口查询签约单状态,仅在符合接口要求的状态下继续
500020009订单类型不受支持查询订单等改用该订单类型对应的查询或处理接口
500020010该订单类型不支持退款创建退款、查询退款确认传入的是普通支付订单或受支持的协议支付订单
500020011未找到可用的商户绑定预下单、创建协议支付订单确认商户已绑定当前应用,且 merchantUid 与环境一致
500020012同一退款单号对应的请求参数不一致创建退款使用首次请求的订单和金额;需要新退款时生成新的 out_refund_no
500020013订单结算期间暂不允许退款创建退款稍后使用相同 out_refund_no 重试;重试前先查询退款状态

对于创建退款、创建协议支付订单等可能产生资金或订单状态变化的接口,网络超时不能视为失败。再次提交前,应先使用原业务单号调用对应查询接口确认结果。