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/requestOrder.md.

requestOrder

交易预下单,获取拉起收银台所需的平台交易订单号。

支持版本

前端库版本不低于 0.0.28。

支持平台

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

支持场景

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

使用说明

调用前,前端应先请求业务服务端,由业务服务端构造下单参数并完成签名。 不要在前端生成 data 或 dbAuthorization,也不要把证书或私钥下发到前端。

使用 DoubaoPaymentButton 时,应在组件请求订单号的回调中获取或创建预下单, 再将本 API 返回的 orderId 交给组件继续普通支付或平台免密支付流程。

  • 请在服务端下发合法的 data 与 dbAuthorization 后调用。

调用方式

异步 API

requestOrder(params: RequestOrderParams): Promise<RequestOrderResult>

入参

名称类型必填默认值约束说明
datastring是--下单参数 JSON 字符串。

该字段必须由业务服务端按支付接入协议构造并返回,前端应原样透传,不要在客户端自行拼装。
JSON 必填字段包括 `skuList`、`outOrderNo`、`merchantUid`、`totalAmount`、`orderName` 和
`orderDesc`;可选字段包括 `currency`、`payExpireSeconds` 和 `payNotifyUrl`。

`skuList` 每项必填 `skuId`、`price`、`quantity`、`title` 和 `totalAmount`。
金额单位由 `currency` 决定;当前 `CNY` 使用分。`outOrderNo` 不超过 64 字节,
`quantity` 取值范围为 1 到 100,`title` 不超过 256 字节。
`payExpireSeconds` 不传或传 0 时使用 300 秒,最长不超过 48 小时;
`payNotifyUrl` 必须是 HTTPS 地址。
dbAuthorizationstring是--`data` 对应的请求签名。

该字段必须由业务服务端使用已配置的证书生成并返回,前端应原样透传。

调用示例

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

// 业务方自行实现:从业务服务端获取预下单参数和签名;该函数不是 SDK API。
declare function getOrderParamsFromBusinessServer(): Promise<RequestOrderParams>;

const orderParams = await getOrderParamsFromBusinessServer();
const { orderId, logId } = await requestOrder(orderParams);

console.log(orderId, logId);

成功返回

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

返回示例

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

错误处理

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

错误码

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

已知限制与注意事项

  • 失败结果不会作为 await 的返回值,需通过 catch 捕获并从错误对象的 data 字段读取 errNo、errMsg、errLogId。