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/js-api/open/payment/getOrderPaymentWithSign.md.

getOrderPaymentWithSign

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

支持版本

前端库版本不低于 0.0.28。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片支持

接入准备

前置条件

  • Android:需用户已登录并完成抖音账号绑定,且当前处于前台可见页面
  • iOS:需用户已登录并完成抖音账号绑定

使用说明

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

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

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

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

调用方式

异步 API

getOrderPaymentWithSign(params: GetOrderPaymentWithSignParams): Promise<GetOrderPaymentResult>

入参

名称类型必填默认值约束说明
orderIdstring是--平台交易订单号。

应使用 `requestOrder` 返回的真实预下单结果,不要传入业务侧订单号或自行构造的值。
signDatastring是--支付并签约所需的签约参数。

该字段必须由业务服务端按支付并签约接入协议生成并返回,前端应原样透传。
signDbAuthorizationstring是--`signData` 对应的请求签名。

该字段必须由业务服务端生成并与 `signData` 一并返回,前端应原样透传。

调用示例

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);

成功返回

名称类型必返说明
logIdstring是用于服务端排查问题的日志 ID。
orderIdstring是本次拉起收银台所使用的平台交易订单号。

返回示例

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

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

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

错误码

errNoerrMsg平台触发条件处理建议
114operation cancelledAndroid用户在收银台中取消了支付操作用户需要时可再次调用 `getOrderPaymentWithSign` 重新拉起收银台。

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS
103feature not support当前环境不支持该能力Android、iOS

平台差异

  • Android:需在前台可见的 Activity 中调用,应用退至后台或无有效页面时会返回失败。
  • Android:用户主动取消支付时返回顶层 errNo 114(operation cancelled);iOS 在该场景不返回顶层专属 errNo。