> ## 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/session 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/session: post: tags: - 结账会话 summary: 创建结账会话 description: 创建结账会话 operationId: v1-checkout-session-create-checkout-session parameters: - $ref: '#/components/parameters/HeaderRequestID' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionResponse' components: parameters: HeaderRequestID: name: Request-Id in: header description: 请求的唯一标识符 required: true schema: type: string default: 008e3967-a1b5-48bb-be14-d5bff5092e61 schemas: CreateCheckoutSessionRequest: required: - order_id - line_items type: object properties: order_id: type: string description: 接入方订单号 customer_id: type: string description: >- Subotiz 平台顾客唯一标识，需提前在 Subotiz 创建。payer_id 、customer_id 和 email 必须存在其一 email: type: string description: 顾客邮箱 line_items: type: array items: $ref: '#/components/schemas/CheckoutSessionLineItem' description: 本次结账包含的商品定价数组（目前仅支持一个 lineItem） return_url: type: string description: 顾客支付成功之后跳转的 URL。若调用时传入了 URL，则优先使用传入值。若未传入，则自动使用开发者信息中的默认配置。 cancel_url: type: string description: 顾客取消支付之后跳转的 URL。若调用时传入了 URL，则优先使用传入值。若未传入，则自动使用开发者信息中的默认配置。 mode: type: string description: |- 支付模式，用于判断是否校验商品信息： - checkout：校验商品数据，默认值 - payment：不校验商品数据 payer_id: type: string description: 接入方的顾客 ID，如果传入的 ID 不存在与 Subotiz 系统中，那么会自动创建顾客，每个商户下的 payer_id 是唯一的。 integration_method: type: string description: |- 集成模式： - hosted：托管式，默认为该模式 - embedded ：嵌入式集成 total_amount: type: string description: 支付金额，当 mode 选择 payment 模式时必填金额。 redirect_on_completion: type: string description: |- 嵌入式ui模式的重定向行为 - always： 支付成功后，会自动重定向到 return_url - if_required： 仅在有重定向的付款方式才会重定向到return_url locale: type: string description: |- 指定结账会话所使用的语言,默认根据浏览器语言确定。
可选值： - **ar-SA**：阿拉伯语（沙特阿拉伯） - **de-DE**：德语（德国） - **en-US**：英语（美国） - **es-ES**：西班牙语（西班牙） - **fr-FR**：法语（法国） - **id-ID**：印尼语（印度尼西亚） - **it-IT**：意大利语（意大利） - **ja-JP**：日语（日本） - **ko-KR**：韩语（韩国） - **nl-NL**：荷兰语（荷兰） - **pl-PL**：波兰语（波兰） - **pt-PT**：葡萄牙语（葡萄牙） - **ru-RU**：俄语（俄罗斯） - **th-TH**：泰语（泰国） - **zh-CN**：中文（中国大陆） - **zh-TW**：中文（中国台湾） target_currency: type: string description: >- 指定结账会话的订单结算币种，传入平台支持的 ISO 4217 货币代码，如 USD、CNY。系统会以店铺主货币为基准，将订单金额换算为该币种进行展示与计价；未传 merchant_rate 时，系统默认按当日实时汇率完成换算。 merchant_rate: type: string description: >- 指定店铺主货币兑换 target_currency 的自定义汇率，传入值须为大于 0 的数字，且必须与 target_currency 同时传入。该字段仅在订单结算币种与店铺主货币不一致时使用。汇率方向为“1 单位店铺主货币可兑换的 target_currency 金额”。例如：店铺主货币为 USD，target_currency 为 CNY，传入 7.999 表示 1 USD = 7.999 CNY，系统将按该汇率计算订单金额。 metadata: type: object description: 一组可附加到对象上的键值对，允许您以结构化格式存储附加信息。 subscription_data: allOf: - $ref: '#/components/schemas/SubscriptionData' description: 传递给结账会话中订阅创建的子集参数 trade_data: allOf: - $ref: '#/components/schemas/TradeData' description: 传递给结账会话中交易创建的子集参数 source_channel: type: string description: 首次交易来源渠道识别，用于交易归因统计，长度限制为 50 个字符。 billing_address_data: allOf: - $ref: '#/components/schemas/BillingAddressData' description: 账单地址信息 payment_mode: type: string description: |- 支付业务模式： - `onetime_payment`：一次性支付模式。仅处理单次支付交易，不创建任何重复支付令牌。 - `subscription`：订阅支付模式。处理初始支付，并生成用于自动重复支付的支付令牌。后续的续费费用将根据订阅计划配置使用此令牌进行处理。 once_trial: type: integer description: '试用期定价限制试用 1 次. 1: 不限制, 2:限制试用一次, 3: 跳过试用期' format: int32 fixed_term: type: integer description: 订阅固定期限，取值正整数 format: int32 is_renewable: type: boolean description: 是否支持固定期限转为持续订阅 description: 创建 checkout session 的请求 CreateCheckoutSessionResponse: type: object properties: code: type: string description: error code message: type: string description: error message data: $ref: '#/components/schemas/CreateCheckoutSessionResponse_Data' CheckoutSessionLineItem: type: object properties: price_id: type: string description: 商品定价的唯一标识 quantity: type: string description: 商品数量 description: LineItem 结构 SubscriptionData: type: object properties: metadata: type: object description: 一组可附加到对象上的键值对，允许您以结构化格式存储附加信息。 TradeData: type: object properties: metadata: type: object description: 一组可附加到对象上的键值对，允许您以结构化格式存储附加信息。 BillingAddressData: type: object properties: name: type: string description: '收件人全名 (例如: John Smith)' address_line1: type: string description: '地址行1，主要街道地址 (例如: 123 Main Street, Apt 4B)' address_line2: type: string description: '地址行2，附加地址信息 (例如: Building C, Floor 5)' country_code: type: string description: '国家代码，ISO2格式 (例如: US, GB, CN)' province_code: type: string description: '省/州代码 (例如: CA代表加利福尼亚州, ON代表安大略省)' city: type: string description: '城市名称 (例如: New York, London, Tokyo)' area: type: string description: 区域/区/县名称，用于更精细的地址定位 postal_code: type: string description: '邮政编码/邮编，格式因国家而异 (例如: 美国: 12345, 英国: SW1A 1AA, 加拿大: K1A 0B1)' phone: type: string description: '不含国家代码的电话号码 (例如: 5551234567)' phone_area_code: type: string description: '电话国家代码 (例如: +1, +44, +86)' email: type: string description: '用于账单通知和联系的电子邮件地址 (例如: user@example.com)' description: 账单地址信息 CreateCheckoutSessionResponse_Data: type: object properties: session_id: type: string description: Checkout Session 唯一标识 session_url: type: string description: Subotiz 结账页 URL，可直接将 客户重定向到该 URL 上。仅 hosted 集成模式返回 securitySchemes: sec0: type: http description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}' scheme: bearer ````