> 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.

# 支付相关 API

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

如果你还没有完成商户开户、应用绑定和证书配置，请先阅读[《支付接入（服务端）》](/apps-plugin/docs/backend-development/payment.md)。服务端 API 的请求域名、应用级 Access Token 获取方式、通用响应结构和通用重试原则，参见[《服务端 API 总览》](/apps-plugin/docs/server-api/overview.md)。

## 调用前准备

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

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

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

### Access Token 与支付签名的区别

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

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

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

## 商户标识 merchantUid

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

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

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

<table><colgroup><col width="365"/><col width="365"/></colgroup><tbody><tr><td>使用位置</td><td>字段名</td></tr><tr><td>应用插件预下单参数</td><td><code>merchantUid</code></td></tr><tr><td>服务端 API 响应和回调消息</td><td><code>merchant_uid</code></td></tr></tbody></table>

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

## 业务单号

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

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>业务对象</td><td>开发者单号</td><td>平台单号</td></tr><tr><td>普通支付订单</td><td><code>out_order_no</code></td><td><code>order_id</code></td></tr><tr><td>退款单</td><td><code>out_refund_no</code></td><td><code>refund_id</code></td></tr><tr><td>签约单</td><td><code>out_auth_order_no</code></td><td><code>auth_order_id</code></td></tr><tr><td>协议支付订单</td><td><code>out_pay_order_no</code></td><td><code>pay_order_id</code></td></tr></tbody></table>

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

## API 索引

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

## 请求与响应说明

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

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

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

## 查询订单

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

### 请求

```http
POST /api/trade_basic/v1/developer/order_query
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>order_id</code></td><td>string</td><td>条件必填</td><td>平台订单号；与  <code>out_order_no</code>  至少填写一个</td></tr><tr><td><code>out_order_no</code></td><td>string</td><td>条件必填</td><td>开发者订单号；与  <code>order_id</code>  至少填写一个</td></tr></tbody></table>

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

```bash
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"
  }'
```

### 响应

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td><code>data</code>  字段</td><td>类型</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>应用插件 AppID</td></tr><tr><td><code>order_id</code></td><td>string</td><td>平台订单号</td></tr><tr><td><code>out_order_no</code></td><td>string</td><td>开发者订单号</td></tr><tr><td><code>merchant_uid</code></td><td>string</td><td>收款商户标识</td></tr><tr><td><code>pay_status</code></td><td>string</td><td>支付状态，见下表</td></tr><tr><td><code>total_amount</code></td><td>string</td><td>订单总金额，单位为分</td></tr><tr><td><code>trade_time</code></td><td>string</td><td>订单创建时间，毫秒时间戳</td></tr><tr><td><code>pay_time</code></td><td>string</td><td>支付完成时间，毫秒时间戳；未完成支付时可能不返回</td></tr><tr><td><code>pay_type</code></td><td>string</td><td>支付方式；支付成功后返回</td></tr><tr><td><code>pay_order_no</code></td><td>string</td><td>支付渠道订单号；支付成功后返回</td></tr></tbody></table>

`pay_status` 枚举：

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>值</td><td>说明</td><td>建议处理</td></tr><tr><td><code>INIT</code></td><td>订单已创建</td><td>等待支付或继续查询</td></tr><tr><td><code>PROCESSING</code></td><td>支付处理中</td><td>不要发货，继续查询或等待回调</td></tr><tr><td><code>SUCCESS</code></td><td>支付成功</td><td>校验订单和金额后进入履约</td></tr><tr><td><code>CLOSED</code></td><td>订单已关闭</td><td>终止支付流程</td></tr><tr><td><code>FAIL</code></td><td>支付失败</td><td>终止本次支付并允许用户重新发起</td></tr></tbody></table>

```json
{
  "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`。

## 创建退款

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

### 请求

```http
POST /api/trade_basic/v1/developer/refund_create
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>order_id</code></td><td>string</td><td>条件必填</td><td>原支付订单的平台订单号；与  <code>out_order_no</code>  至少填写一个</td></tr><tr><td><code>out_order_no</code></td><td>string</td><td>条件必填</td><td>原支付订单的开发者订单号；与  <code>order_id</code>  至少填写一个</td></tr><tr><td><code>out_refund_no</code></td><td>string</td><td>是</td><td>开发者退款单号，在当前应用内保持唯一，最长 64 个字符</td></tr><tr><td><code>refund_reason</code></td><td>string</td><td>否</td><td>退款原因</td></tr><tr><td><code>refund_total_amount</code></td><td>string</td><td>是</td><td>退款总金额，正整数，单位为分</td></tr><tr><td><code>refund_sku_list</code></td><td>array</td><td>否</td><td>退款商品明细</td></tr><tr><td><code>notify_url</code></td><td>string</td><td>否</td><td>退款结果回调地址；填写时必须是合法且可访问的 URL，正式环境建议使用 HTTPS</td></tr></tbody></table>

`refund_sku_list` 元素字段：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>sku_id</code></td><td>string</td><td>是</td><td>原订单中的商品标识</td></tr><tr><td><code>refund_amount</code></td><td>string</td><td>是</td><td>该商品的退款金额，单位为分</td></tr></tbody></table>

```bash
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"
  }'
```

### 响应

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td><code>data</code>  字段</td><td>类型</td><td>说明</td></tr><tr><td><code>refund_id</code></td><td>string</td><td>平台退款单号</td></tr></tbody></table>

```json
{
  "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`。

## 查询退款

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

### 请求

```http
POST /api/trade_basic/v1/developer/refund_query
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>order_id</code></td><td>string</td><td>三选一</td><td>平台订单号。使用该字段时返回订单下的退款列表</td></tr><tr><td><code>refund_id</code></td><td>string</td><td>三选一</td><td>平台退款单号</td></tr><tr><td><code>out_refund_no</code></td><td>string</td><td>三选一</td><td>开发者退款单号</td></tr></tbody></table>

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

```bash
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"
  }'
```

### 响应

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td><code>data</code>  字段</td><td>类型</td><td>说明</td></tr><tr><td><code>refund_list</code></td><td>array</td><td>退款记录列表</td></tr></tbody></table>

`refund_list` 元素字段：

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>说明</td></tr><tr><td><code>order_id</code></td><td>string</td><td>原支付订单的平台订单号</td></tr><tr><td><code>refund_id</code></td><td>string</td><td>平台退款单号</td></tr><tr><td><code>out_refund_no</code></td><td>string</td><td>开发者退款单号</td></tr><tr><td><code>refund_status</code></td><td>string</td><td>退款状态，见下表</td></tr><tr><td><code>refund_total_amount</code></td><td>string</td><td>退款总金额，单位为分</td></tr><tr><td><code>refund_create_time</code></td><td>string</td><td>退款创建时间，毫秒时间戳</td></tr><tr><td><code>refund_finish_time</code></td><td>string</td><td>退款完成时间，毫秒时间戳；未完成时可能不返回</td></tr></tbody></table>

`refund_status` 枚举：

<table><colgroup><col width="365"/><col width="365"/></colgroup><tbody><tr><td>值</td><td>说明</td></tr><tr><td><code>PROCESSING</code></td><td>退款处理中</td></tr><tr><td><code>SUCCESS</code></td><td>退款成功</td></tr><tr><td><code>FAIL</code></td><td>退款失败</td></tr></tbody></table>

```json
{
  "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`。

## 通知履约完成

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

### 请求

```http
POST /api/trade_basic/v1/developer/fulfill_push_finish
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>order_id</code></td><td>string</td><td>条件必填</td><td>平台订单号；与  <code>out_order_no</code>  至少填写一个</td></tr><tr><td><code>out_order_no</code></td><td>string</td><td>条件必填</td><td>开发者订单号；与  <code>order_id</code>  至少填写一个</td></tr></tbody></table>

```bash
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`：

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

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

## 查询签约订单

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

### 请求

```http
POST /api/trade_basic/v1/developer/query_sign_order
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>条件必填</td><td>平台签约单号；与  <code>out_auth_order_no</code>  至少填写一个</td></tr><tr><td><code>out_auth_order_no</code></td><td>string</td><td>条件必填</td><td>开发者签约单号；与  <code>auth_order_id</code>  至少填写一个</td></tr></tbody></table>

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

```bash
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"
  }'
```

### 响应

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td><code>data</code>  字段</td><td>类型</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>应用插件 AppID</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>平台签约单号</td></tr><tr><td><code>out_auth_order_no</code></td><td>string</td><td>开发者签约单号</td></tr><tr><td><code>open_id</code></td><td>string</td><td>签约用户在当前应用下的 OpenID</td></tr><tr><td><code>service_id</code></td><td>string</td><td>签约服务 ID</td></tr><tr><td><code>status</code></td><td>string</td><td>签约状态，见下表</td></tr><tr><td><code>merchant_uid</code></td><td>string</td><td>商户标识</td></tr><tr><td><code>unsign_source</code></td><td>integer</td><td>解约来源；解约后返回。 <code>1</code>  表示用户主动解约， <code>2</code>  表示商户解约</td></tr><tr><td><code>sign_time</code></td><td>string</td><td>签约时间，毫秒时间戳；签约完成后返回</td></tr></tbody></table>

`status` 枚举：

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>值</td><td>说明</td><td>是否可用于创建协议支付订单</td></tr><tr><td><code>TOBESERVED</code></td><td>等待用户完成签约</td><td>否</td></tr><tr><td><code>SERVING</code></td><td>签约关系生效中</td><td>是</td></tr><tr><td><code>CANCEL</code></td><td>已解约</td><td>否</td></tr><tr><td><code>TIMEOUT</code></td><td>用户未在有效期内完成签约</td><td>否</td></tr><tr><td><code>DONE</code></td><td>签约关系已结束</td><td>否</td></tr></tbody></table>

```json
{
  "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`。

## 解除签约

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

### 请求

```http
POST /api/trade_basic/v1/developer/terminate_sign
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>是</td><td>平台签约单号，最长 64 个字符</td></tr></tbody></table>

```bash
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`：

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

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

## 创建协议支付订单

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

### 请求

```http
POST /api/trade_basic/v1/developer/create_sign_pay
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>是</td><td>平台签约单号，最长 64 个字符</td></tr><tr><td><code>pay_data</code></td><td>object</td><td>是</td><td>协议支付订单数据</td></tr></tbody></table>

`pay_data` 字段：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>sku_list</code></td><td>array</td><td>是</td><td>商品明细；可以传空数组，非空时每项必须满足下表规则</td></tr><tr><td><code>out_pay_order_no</code></td><td>string</td><td>是</td><td>开发者协议支付订单号，在当前应用内保持唯一，最长 64 个字符</td></tr><tr><td><code>total_amount</code></td><td>string</td><td>是</td><td>订单总金额，非负整数，单位为分</td></tr><tr><td><code>order_name</code></td><td>string</td><td>是</td><td>订单名称</td></tr><tr><td><code>order_desc</code></td><td>string</td><td>是</td><td>订单描述</td></tr><tr><td><code>currency</code></td><td>string</td><td>否</td><td>币种。省略或传空字符串时使用  <code>CNY</code> ；目前只支持  <code>CNY</code></td></tr><tr><td><code>pay_expire_seconds</code></td><td>string</td><td>否</td><td>支付有效期，单位为秒。省略或传  <code>0</code>  时使用 300 秒，最大为 172800 秒</td></tr><tr><td><code>pay_notify_url</code></td><td>string</td><td>否</td><td>协议支付结果回调地址；填写时必须是合法且可访问的 URL，正式环境建议使用 HTTPS</td></tr></tbody></table>

`sku_list` 元素字段：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>sku_id</code></td><td>string</td><td>是</td><td>商品标识，最长 64 个字符</td></tr><tr><td><code>price</code></td><td>string</td><td>是</td><td>商品单价，正整数，单位为分</td></tr><tr><td><code>quantity</code></td><td>string</td><td>是</td><td>商品数量，正整数</td></tr><tr><td><code>title</code></td><td>string</td><td>是</td><td>商品名称，最长 256 个字符</td></tr><tr><td><code>total_amount</code></td><td>string</td><td>是</td><td>商品小计，必须等于  <code>price × quantity</code> ，单位为分</td></tr></tbody></table>

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

```bash
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"
    }
  }'
```

### 响应

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td><code>data</code>  字段</td><td>类型</td><td>说明</td></tr><tr><td><code>pay_order_id</code></td><td>string</td><td>平台协议支付订单号</td></tr></tbody></table>

```json
{
  "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`。

## 查询协议支付订单

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

### 请求

```http
POST /api/trade_basic/v1/developer/query_sign_pay
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>pay_order_id</code></td><td>string</td><td>条件必填</td><td>平台协议支付订单号；与  <code>out_pay_order_no</code>  至少填写一个</td></tr><tr><td><code>out_pay_order_no</code></td><td>string</td><td>条件必填</td><td>开发者协议支付订单号；与  <code>pay_order_id</code>  至少填写一个</td></tr></tbody></table>

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

```bash
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"
  }'
```

### 响应

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td><code>data</code>  字段</td><td>类型</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>应用插件 AppID</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>关联的平台签约单号</td></tr><tr><td><code>pay_order_id</code></td><td>string</td><td>平台协议支付订单号</td></tr><tr><td><code>out_pay_order_no</code></td><td>string</td><td>开发者协议支付订单号</td></tr><tr><td><code>merchant_uid</code></td><td>string</td><td>收款商户标识</td></tr><tr><td><code>pay_status</code></td><td>string</td><td>支付状态，见下表</td></tr><tr><td><code>total_amount</code></td><td>string</td><td>订单总金额，单位为分</td></tr><tr><td><code>trade_time</code></td><td>string</td><td>订单创建时间，毫秒时间戳</td></tr><tr><td><code>pay_success_source</code></td><td>integer</td><td>支付成功来源。 <code>1</code>  表示用户主动支付， <code>2</code>  表示协议扣款成功</td></tr><tr><td><code>pay_time</code></td><td>string</td><td>支付完成时间，毫秒时间戳；未完成时可能不返回</td></tr><tr><td><code>pay_type</code></td><td>string</td><td>支付方式；支付成功后返回</td></tr><tr><td><code>pay_order_no</code></td><td>string</td><td>支付渠道订单号；支付成功后返回</td></tr><tr><td><code>sign_pay_fail_code</code></td><td>string</td><td>协议支付失败码；失败时可能返回</td></tr><tr><td><code>sign_pay_fail_msg</code></td><td>string</td><td>协议支付失败原因；失败时可能返回</td></tr></tbody></table>

`pay_status` 枚举：

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>值</td><td>说明</td><td>建议处理</td></tr><tr><td><code>INIT</code></td><td>订单已创建</td><td>等待执行扣款</td></tr><tr><td><code>PROCESSING</code></td><td>扣款处理中</td><td>继续查询或等待回调</td></tr><tr><td><code>SUCCESS</code></td><td>扣款成功</td><td>校验订单和金额后进入履约</td></tr><tr><td><code>CLOSED</code></td><td>订单已关闭</td><td>终止本次扣款</td></tr><tr><td><code>FAIL</code></td><td>扣款失败</td><td>读取失败码和失败原因，终止本次扣款</td></tr></tbody></table>

```json
{
  "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` 不是最终状态时，不要据此履约；继续查询或等待回调。

## 关闭协议支付订单

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

### 请求

```http
POST /api/trade_basic/v1/developer/close_sign_pay
```

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>pay_order_id</code></td><td>string</td><td>条件必填</td><td>平台协议支付订单号；与  <code>out_pay_order_no</code>  至少填写一个</td></tr><tr><td><code>out_pay_order_no</code></td><td>string</td><td>条件必填</td><td>开发者协议支付订单号；与  <code>pay_order_id</code>  至少填写一个</td></tr></tbody></table>

```bash
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`：

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

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

## 回调协议

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

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>回调</td><td>回调地址来源</td><td><code>type</code></td></tr><tr><td>支付结果回调</td><td>预下单参数中的  <code>payNotifyUrl</code></td><td><code>payment</code></td></tr><tr><td>退款结果回调</td><td>创建退款时传入的  <code>notify_url</code></td><td><code>refund</code></td></tr><tr><td>签约结果回调</td><td>签约服务配置的回调地址</td><td><code>sign_callback</code></td></tr><tr><td>协议支付结果回调</td><td>创建协议支付订单时传入的  <code>pay_notify_url</code></td><td><code>sign_pay_callback</code></td></tr></tbody></table>

### 回调请求头

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>请求头</td><td>必填</td><td>说明</td></tr><tr><td><code>Content-Type</code></td><td>是</td><td>固定为  <code>application/json</code></td></tr><tr><td><code>X-DB-Logid</code></td><td>是</td><td>本次回调的请求标识，排查问题时请保留</td></tr><tr><td><code>X-DB-Authorization</code></td><td>是</td><td>豆包开放平台生成的签名认证信息，验签规则见支付签名与验签</td></tr></tbody></table>

### 回调外层结构

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

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>type</code></td><td>string</td><td>是</td><td>回调类型</td></tr><tr><td><code>version</code></td><td>string</td><td>是</td><td>回调协议版本，当前为  <code>1.0</code></td></tr><tr><td><code>msg</code></td><td>string</td><td>是</td><td>JSON 字符串；需要再次解析才能得到业务字段</td></tr></tbody></table>

```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` 解析后的字段如下：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>是</td><td>应用插件 AppID</td></tr><tr><td><code>order_id</code></td><td>string</td><td>是</td><td>平台订单号</td></tr><tr><td><code>out_order_no</code></td><td>string</td><td>是</td><td>开发者订单号</td></tr><tr><td><code>merchant_uid</code></td><td>string</td><td>是</td><td>收款商户标识</td></tr><tr><td><code>pay_status</code></td><td>string</td><td>是</td><td>支付结果；当前回调通知最终成功状态  <code>SUCCESS</code></td></tr><tr><td><code>total_amount</code></td><td>string</td><td>是</td><td>订单总金额，单位为分</td></tr><tr><td><code>event_time</code></td><td>string</td><td>是</td><td>事件发生时间，毫秒时间戳</td></tr><tr><td><code>pay_type</code></td><td>string</td><td>是</td><td>支付方式： <code>ALI_PAY</code> 、 <code>WECHAT_PAY</code>  或  <code>BYTE_PAY</code></td></tr><tr><td><code>pay_order_no</code></td><td>string</td><td>是</td><td>支付渠道订单号</td></tr></tbody></table>

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

### 退款结果回调

当 `type` 为 `refund` 时，`msg` 解析后的字段如下：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>是</td><td>应用插件 AppID</td></tr><tr><td><code>order_id</code></td><td>string</td><td>是</td><td>原支付订单的平台订单号</td></tr><tr><td><code>refund_id</code></td><td>string</td><td>是</td><td>平台退款单号</td></tr><tr><td><code>out_refund_no</code></td><td>string</td><td>是</td><td>开发者退款单号</td></tr><tr><td><code>refund_status</code></td><td>string</td><td>是</td><td>最终退款状态： <code>SUCCESS</code>  或  <code>FAIL</code></td></tr><tr><td><code>refund_total_amount</code></td><td>string</td><td>是</td><td>退款总金额，单位为分</td></tr><tr><td><code>event_time</code></td><td>string</td><td>是</td><td>事件发生时间，毫秒时间戳</td></tr></tbody></table>

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

```json
{
  "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` 解析后的字段如下：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>是</td><td>应用插件 AppID</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>是</td><td>平台签约单号</td></tr><tr><td><code>out_auth_order_no</code></td><td>string</td><td>是</td><td>开发者签约单号</td></tr><tr><td><code>status</code></td><td>string</td><td>是</td><td>签约状态，与“查询签约订单”的  <code>status</code>  枚举一致</td></tr><tr><td><code>unsign_source</code></td><td>integer</td><td>否</td><td>解约来源。 <code>1</code>  表示用户主动解约， <code>2</code>  表示商户解约；解约时返回</td></tr><tr><td><code>event_time</code></td><td>string</td><td>是</td><td>事件发生时间，毫秒时间戳</td></tr></tbody></table>

```json
{
  "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` 解析后的字段如下：

<table><colgroup><col width="183"/><col width="183"/><col width="183"/><col width="183"/></colgroup><tbody><tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr><tr><td><code>app_id</code></td><td>string</td><td>是</td><td>应用插件 AppID</td></tr><tr><td><code>auth_order_id</code></td><td>string</td><td>是</td><td>关联的平台签约单号</td></tr><tr><td><code>pay_order_id</code></td><td>string</td><td>是</td><td>平台协议支付订单号</td></tr><tr><td><code>out_pay_order_no</code></td><td>string</td><td>是</td><td>开发者协议支付订单号</td></tr><tr><td><code>pay_status</code></td><td>string</td><td>是</td><td>支付结果： <code>SUCCESS</code>  或  <code>FAIL</code></td></tr><tr><td><code>total_amount</code></td><td>string</td><td>是</td><td>订单总金额，单位为分</td></tr><tr><td><code>event_time</code></td><td>string</td><td>是</td><td>事件发生时间，毫秒时间戳</td></tr><tr><td><code>merchant_uid</code></td><td>string</td><td>是</td><td>收款商户标识</td></tr><tr><td><code>pay_success_source</code></td><td>integer</td><td>否</td><td>支付成功来源。 <code>1</code>  表示用户主动支付， <code>2</code>  表示协议扣款成功</td></tr><tr><td><code>pay_type</code></td><td>string</td><td>否</td><td>支付方式；支付成功时返回</td></tr><tr><td><code>pay_order_no</code></td><td>string</td><td>否</td><td>支付渠道订单号；支付成功时返回</td></tr><tr><td><code>sign_pay_fail_code</code></td><td>string</td><td>否</td><td>协议支付失败码；失败时可能返回</td></tr><tr><td><code>sign_pay_fail_msg</code></td><td>string</td><td>否</td><td>协议支付失败原因；失败时可能返回</td></tr></tbody></table>

```json
{
  "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：

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

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

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

## 下载账单

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

### 请求

```http
POST /api/trade_basic/v1/developer/bill_download

```

| 字段             | 类型     | 必填 | 说明                                                 |
| -------------- | ------ | -- | -------------------------------------------------- |
| `merchant_uid` | string | 是  | 收款商户标识，必须已绑定当前应用插件                                 |
| `trade_type`   | string | 否  | 交易类型：`PAY` 表示支付账单，`REFUND` 表示退款账单；不填写或传空字符串表示全部    |
| `start_date`   | string | 是  | 查询起始日期，格式为 `yyyyMMdd`，按东八区自然日解释                    |
| `end_date`     | string | 是  | 查询结束日期，格式为 `yyyyMMdd`，按东八区自然日解释，包含当天               |
| `trade_status` | string | 否  | 交易状态：`PROCESSING`、`SUCCESS` 或 `FAIL`；不填写或传空字符串表示全部 |

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

- `start_date` 和 `end_date` 必须是真实有效的日期，不能使用 `yyyy-MM-dd`、时间戳或其他格式。
- `end_date` 不能早于 `start_date`。
- 查询范围最多包含 31 个东八区自然日（起止日期均计入）。例如，`20260801` 至 `20260831` 合法，`20260801` 至 `20260901` 不合法。超过 31 天的范围应拆分为多个请求。
- 单日账单应将 `start_date` 和 `end_date` 设置为同一天。

```bash
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_url` | string | 账单文件下载地址 |

```json
{
  "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`。这些错误不应使用原请求高频重试。

### 文件样例

<a data-download-card data-size="189 B" href="/apps-plugin/docs/wiki-downloads/TPYBweLbwiYD3ZkPRe3cH3Gsnbc-01.bin" download="交易明细报表20260530-20260601_260814140149240405544990.csv">交易明细报表20260530-20260601\_260814140149240405544990.csv</a>

## 下载结算账单

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

### 请求

```http
POST /api/trade_basic/v1/developer/settle_bill_download
```

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

| 字段             | 类型     | 必填 | 说明                                            |
| -------------- | ------ | -- | --------------------------------------------- |
| `merchant_uid` | string | 是  | 收款商户标识，必须已绑定当前应用插件                            |
| `time_type`    | string | 是  | 时间类型：`"0"` 表示按结算时间查询；`"1"` 表示按下单时间查询。必须以字符串传入 |
| `start_date`   | string | 是  | 查询起始日期，格式为 `yyyyMMdd`，按东八区（UTC+8）自然日解释，包含当天   |
| `end_date`     | string | 是  | 查询结束日期，格式为 `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` 筛选；请勿套用“下载账单”的交易类型和状态参数。

```bash
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_url` | string | 结算账单 CSV 文件的带签名下载地址。无需传入文件名，应及时下载并妥善保存；链接过期后不可继续使用 |

```json
{
  "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 编码。

### 证书与密钥方向

<table><colgroup><col width="146"/><col width="146"/><col width="146"/><col width="146"/><col width="146"/></colgroup><tbody><tr><td>场景</td><td>签名方</td><td>使用的私钥</td><td><code>cert_serial</code>  指向</td><td>验签方</td></tr><tr><td>生成预下单  <code>dbAuthorization</code></td><td>开发者服务端</td><td>开发者私钥</td><td>开发者证书</td><td>豆包开放平台</td></tr><tr><td>验证支付相关回调</td><td>豆包开放平台</td><td>平台私钥</td><td>平台证书</td><td>开发者服务端</td></tr></tbody></table>

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

### 待签名字符串

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

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

各部分规则如下：

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

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

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

### 授权信息格式

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

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

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

<table><colgroup><col width="365"/><col width="365"/></colgroup><tbody><tr><td>字段</td><td>说明</td></tr><tr><td><code>algorithm</code></td><td>固定为  <code>ECDSA_SHA256</code></td></tr><tr><td><code>version</code></td><td>固定为  <code>1</code></td></tr><tr><td><code>signature</code></td><td>ECDSA ASN.1 DER 签名的 padded Base64URL 字符串，末尾可能包含  <code>=</code></td></tr><tr><td><code>cert_serial</code></td><td>十六进制证书序列号。开发者签名时填写开发者证书序列号，平台回调时填写平台证书序列号</td></tr><tr><td><code>nonce</code></td><td>本次请求的唯一随机值</td></tr><tr><td><code>timestamp</code></td><td>与待签名字符串一致的秒级 Unix 时间戳</td></tr></tbody></table>

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

### 生成预下单 dbAuthorization

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

```plaintext
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` 文本编写业务分支。

### 常用调用错误

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

### 支付业务错误

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

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