> ## Documentation Index > Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt > Use this file to discover all available pages before exploring further. # 创建交易单 > 创建交易单 ## OpenAPI ````yaml openapi/v1-zh.yaml POST /api/v1/trades openapi: 3.0.3 info: title: Subotiz API description: Subotiz OpenAPI version: 1.0.0 servers: - url: https://{api}.subotiz.com variables: api: default: api security: - sec0: [] tags: - name: 折扣 description: 折扣 - name: 发票 description: 发票 - name: 退款 description: 退款 - name: 商品管理 description: 商品管理 - name: 订阅 description: 订阅 - name: 商品定价 description: 商品定价方案 - name: 交易单 description: 交易单 - name: 支付流水 description: 支付流水 - name: 结账会话 description: 结账会话 - name: 顾客 description: 顾客 - name: 顾客门户 description: 顾客门户 - name: Webhook description: Webhook - name: 争议 description: 争议订单 paths: /api/v1/trades: post: tags: - 交易单 summary: 创建交易单 description: 创建交易单 operationId: v1-trade-create-trade parameters: - $ref: '#/components/parameters/HeaderRequestID' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTradeRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateTradeResponse' components: parameters: HeaderRequestID: name: Request-Id in: header description: 请求的唯一标识符 required: true schema: type: string default: 008e3967-a1b5-48bb-be14-d5bff5092e61 schemas: CreateTradeRequest: required: - order_id - txn_time - server_name - payment_mode - amount - currency type: object properties: amount: type: string description: 支付金额，金额必须大于0，只有使用 subscription 支付方式时可出现0。截取两位小数 currency: type: string description: 金额对应的交易币种，编码遵照ISO4217 customer_id: type: string description: >- Subotiz 顾客 id，关联 Subotiz 中已有顾客，与 customer_data 字段二选一，在需要关联已有顾客的场景选择使用该字段 customer_data: allOf: - $ref: '#/components/schemas/CustomerData' description: 顾客数据，在 Subotiz 创建顾客对象，与 customer_id 字段二选一，在需要创建新顾客的场景选择使用该字段。 metadata: type: object description: 一组可附加到对象上的键值对，允许您以结构化格式存储附加信息。 order_id: type: string description: 接入方订单 ID payment_mode: type: string description: >- 支付业务模式： - onetime_payment：一次性支付，需要收集顾客支付信息，传入 payment_method_data 字段 - subscription：首次订阅支付，需要收集顾客支付信息，传入 payment_method_data 字段，支付成功时会返回 payment_token 用于后续订阅续费 - recurring_payment：订阅续订支付，需要传入 payment_token 完成支付，无需收集用户支付信息 payment_token: type: string description: 顾客支付 token，用于订阅续订，使用 recurring_payment 支付方式时必传。 return_url: type: string description: 在类似 3DS 跳转支付场景时，支付渠道受理成功后重定向的页面 txn_time: type: string description: 交易发起时间，UTC格式，示例：2025-07-02T15:04:05Z server_name: type: string description: '客户端域名信息，固定值: checkout.subotiz.com' payment_method_data: allOf: - $ref: '#/components/schemas/PaymentMethodData' description: 顾客支付信息，首次订阅支付，使用 subscription 支付方式时必传 summary: type: string description: 交易摘要信息，如果渠道接口支持，该字段会传递给渠道。当前仅支持自有支付的非0元支付 refer_info: allOf: - $ref: '#/components/schemas/RequestReferInfo' description: 客户的来源信息 CreateTradeResponse: type: object properties: code: type: string description: error code message: type: string description: error message data: $ref: '#/components/schemas/CreateTradeResponse_Data' description: 通过order_id查询交易单响应 CustomerData: type: object properties: email: type: string description: 顾客的邮箱 phone: type: string description: 顾客的手机号码 name: type: string description: 顾客的姓名 address: type: string description: 顾客的详细地址 PaymentMethodData: type: object properties: type: type: string description: |- 支付方式类型： - card：卡支付 card: allOf: - $ref: '#/components/schemas/PaymentMethodDataCard' description: 银行卡信息，type为card时必填。 RequestReferInfo: type: object properties: source_ip: type: string description: 客户的 IP 地址 source_user_agent: type: string description: 客户的用户代理 CreateTradeResponse_Data: type: object properties: trade_id: type: string description: 交易单ID access_no: type: string description: 接入方编号 merchant_id: type: string description: 商户ID amount: type: string description: 支付金额，截取两位小数 currency: type: string description: 币种 customer_id: type: string description: 平台顾客 ID callback_url: type: string description: webhook 通知回调地址 metadata: type: object additionalProperties: type: string description: 透传的元数据，key 长度不超过 40 字节，value 长度不超过 500 字节，JSON编码后 ≤ 1024字节 last_payment_error: allOf: - $ref: '#/components/schemas/LastPaymentError' description: 最后一次支付错误信息，如果该字段有值，则表示支付失败。 next_action: allOf: - $ref: '#/components/schemas/NextAction' description: 下一步操作 order_id: type: string description: 接入方订单号 last_trans_id: type: string description: 订单流水ID。 paid_at: type: string description: 支付成功时间 payment_mode: type: string description: >- 支付业务模式： - subscription：首次订阅支付，需要收集顾客支付信息，传入 payment_method_data 字段，支付成功时会返回 payment_token 用于后续订阅续费 - recurring_payment：订阅续订支付，需要传入 payment_token 完成支付，无需收集用户支付信息 payment_token: type: string description: 订阅支付时，返回的支付凭证，用于后续订阅续费 payment_method: type: string description: 支付方式 payment_channel: type: string description: 支付渠道 return_url: type: string description: 在类似 3DS 跳转支付场景时，支付渠道受理成功后重定向的页面 trade_status: type: string description: >- 交易单状态： - requires_payment_method：待支付。交易单初始状态，顾客尚未完成付款（可能尚未发起或正在支付中），或订阅续订扣费已发起但尚未返回结果。 - payment_failed：支付失败。支付请求被渠道拒绝，例如余额不足、卡验证失败或风控拦截。顾客可再次发起支付。 - processing：支付处理中。顾客已完成支付操作，支付渠道正在处理支付请求，但支付结果暂未确认，可能处于风控核验、银行处理中或延迟清算流程中。 - succeeded：支付成功。支付已被渠道确认成功，款项已入账。 - closed：已关闭。订阅续订失败（多次重试后仍失败）或超过7天无支付结果返回等状态基本不会再正向变化时，交易单轮转为已关闭。 txn_time: type: string description: 交易发起时间，客户端发起接口的时间 created_at: type: string description: 创建时间 refund_status: type: string description: |- 退款状态： - no_refund：无退款 - partially_refunded：部分退款。已成功退款部分金额，退款成功金额小于交易单总金额。 - refunded：全额退款。已成功退款全部交易单金额。 total_refunded_amount: type: string description: 退款金额，截取两位小数 session_id: type: string description: Session 唯一标识 session_url: type: string description: Session 的访问地址 refer_info: allOf: - $ref: '#/components/schemas/ReferInfo' description: 顾客的来源信息 order_type: type: string description: |- 在不同采购或计费场景下生成的订单类型： - onetime_payment: 一次性付款请求创建的交易订单 - subscription: 发起订阅付款请求创建的交易订单 - recurring_payment: Subotiz订阅续订服务创建的交易订单 - token_payment: 商家使用现有订阅合同令牌向客户扣款时创建的交易订单 tax_amount: type: string description: 税费总额 description: 通过order_id查询交易单响应 PaymentMethodDataCard: type: object properties: number: type: string description: 卡号，示例：4761739012345611 exp_month: type: string description: 过期月份，示例：11 exp_year: type: string description: 过期年份，示例：2025 secure_code: type: string description: 安全码（cvv/cvc） first_name: type: string description: 持卡人名 last_name: type: string description: 持卡人姓 LastPaymentError: type: object properties: code: type: string description: 系统返回交易返回码 message: type: string description: 系统返回交易返回说明 NextAction: type: object properties: type: type: string description: |- 客户端下一步需要操作的类型： - redirect：重定向 redirect: allOf: - $ref: '#/components/schemas/NextActionRedirect' description: 重定向信息 client: allOf: - $ref: '#/components/schemas/NextActionClient' description: 客户端操作信息 description: NextAction ReferInfo: type: object properties: country_code: type: string description: 客户下单时的国家 (ISO 2格式) ip: type: string description: 客户下单时的 IP device: type: string description: |- 客户设备的类型 - pc：指个人电脑设备类型，包括台式机和笔记本电脑。 - mobile：指移动端设备类型，包括智能手机和平板电脑。 user_agent: type: string description: 客户端的 user agent description: ReferInfo NextActionRedirect: type: object properties: url: type: string description: 重定向 URL NextActionClient: type: object properties: confirm_url: type: string description: 确认支付 URL apple_pay_session: type: string description: ApplePay 创建使用的数据 securitySchemes: sec0: type: http description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}' scheme: bearer ````