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

# getOrderPaymentWithSign

使用预下单号和签约参数拉起支付并签约收银台。

## 支持版本

前端库版本不低于 `0.0.28`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>支持</td></tr>
</tbody>
</table>

## 接入准备

### 前置条件

- **Android**：需用户已登录并完成抖音账号绑定，且当前处于前台可见页面
- **iOS**：需用户已登录并完成抖音账号绑定

## 使用说明

此 API 属于三方支付并签约流程，与支付按钮组件根据平台签约状态发起的豆包平台免密支付不是同一流程。

支付是主流程，签约是附带流程。如果签约参数无效，收银台会降级为仅支付。

`signData` 和 `signDbAuthorization` 必须由业务服务端生成，不能在前端自行构造。
此 API 成功不代表支付或签约成功，最终状态必须由业务服务端分别通过查询接口或结果回调确认。

- 调用会拉起收银台并需要用户交互，请在用户明确触发支付的交互场景中调用；请勿在无用户操作的后台逻辑中调用。

## 调用方式

### 异步 API

```typescript
getOrderPaymentWithSign(params: GetOrderPaymentWithSignParams): Promise<GetOrderPaymentResult>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>平台交易订单号。<br><br>应使用 `requestOrder` 返回的真实预下单结果，不要传入业务侧订单号或自行构造的值。</td></tr>
<tr><td><code>signData</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>支付并签约所需的签约参数。<br><br>该字段必须由业务服务端按支付并签约接入协议生成并返回，前端应原样透传。</td></tr>
<tr><td><code>signDbAuthorization</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>`signData` 对应的请求签名。<br><br>该字段必须由业务服务端生成并与 `signData` 一并返回，前端应原样透传。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import {
  getOrderPaymentWithSign,
  type GetOrderPaymentWithSignParams
} from '@doubao-dev/framework/api';

// 业务方自行实现：从业务服务端获取支付并签约参数；该函数不是 SDK API。
declare function getPaymentAndSignParamsFromBusinessServer():
  Promise<GetOrderPaymentWithSignParams>;
// 业务方自行实现：通过业务服务端分别确认支付与签约状态；该函数不是 SDK API。
declare function refreshPaymentAndSignStatusFromBusinessServer(orderId: string): Promise<void>;

const paymentParams = await getPaymentAndSignParamsFromBusinessServer();
const result = await getOrderPaymentWithSign(paymentParams);
console.log(result.orderId);
await refreshPaymentAndSignStatusFromBusinessServer(result.orderId);
```

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>logId</code></td><td><code>string</code></td><td>是</td><td>用于服务端排查问题的日志 ID。</td></tr>
<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>本次拉起收银台所使用的平台交易订单号。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "orderId": "order-id",
  "logId": "20260519xxxx"
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 114,
  "errMsg": "operation cancelled"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android</td><td>用户在收银台中取消了支付操作</td><td>用户需要时可再次调用 `getOrderPaymentWithSign` 重新拉起收银台。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

- **Android**：需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
- **Android**：用户主动取消支付时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
