Skip to main content
POST
创建结账会话

授权

Authorization
string
header
必填

Bearer API Key 鉴权。格式:Authorization: Bearer {your_api_key}

请求头

Request-Id
string
默认值:008e3967-a1b5-48bb-be14-d5bff5092e61
必填

请求的唯一标识符

请求体

application/json

创建 checkout session 的请求

order_id
string
必填

接入方订单号

line_items
object[]
必填

本次结账包含的商品定价数组(目前仅支持一个 lineItem)

customer_id
string

Subotiz 平台顾客唯一标识,需提前在 Subotiz 创建。payer_id 、customer_id 和 email 必须存在其一

email
string

顾客邮箱

return_url
string

顾客支付成功之后跳转的 URL。若调用时传入了 URL,则优先使用传入值。若未传入,则自动使用开发者信息中的默认配置。

cancel_url
string

顾客取消支付之后跳转的 URL。若调用时传入了 URL,则优先使用传入值。若未传入,则自动使用开发者信息中的默认配置。

mode
string

支付模式,用于判断是否校验商品信息:

  • checkout:校验商品数据,默认值
  • payment:不校验商品数据
payer_id
string

接入方的顾客 ID,如果传入的 ID 不存在与 Subotiz 系统中,那么会自动创建顾客,每个商户下的 payer_id 是唯一的。

integration_method
string

集成模式:

  • hosted:托管式,默认为该模式
  • embedded :嵌入式集成
total_amount
string

支付金额,当 mode 选择 payment 模式时必填金额。

redirect_on_completion
string

嵌入式ui模式的重定向行为

  • always: 支付成功后,会自动重定向到 return_url
  • if_required: 仅在有重定向的付款方式才会重定向到return_url
locale
string

指定结账会话所使用的语言,默认根据浏览器语言确定。
可选值:

  • 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
string

指定结账会话的订单结算币种,传入平台支持的 ISO 4217 货币代码,如 USD、CNY。系统会以店铺主货币为基准,将订单金额换算为该币种进行展示与计价;未传 merchant_rate 时,系统默认按当日实时汇率完成换算。

merchant_rate
string

指定店铺主货币兑换 target_currency 的自定义汇率,传入值须为大于 0 的数字,且必须与 target_currency 同时传入。该字段仅在订单结算币种与店铺主货币不一致时使用。汇率方向为“1 单位店铺主货币可兑换的 target_currency 金额”。例如:店铺主货币为 USD,target_currency 为 CNY,传入 7.999 表示 1 USD = 7.999 CNY,系统将按该汇率计算订单金额。

metadata
object

一组可附加到对象上的键值对,允许您以结构化格式存储附加信息。

subscription_data
object

传递给结账会话中订阅创建的子集参数

trade_data
object

传递给结账会话中交易创建的子集参数

source_channel
string

首次交易来源渠道识别,用于交易归因统计,长度限制为 50 个字符。

billing_address_data
object

账单地址信息

payment_mode
string

支付业务模式:

  • onetime_payment:一次性支付模式。仅处理单次支付交易,不创建任何重复支付令牌。
  • subscription:订阅支付模式。处理初始支付,并生成用于自动重复支付的支付令牌。后续的续费费用将根据订阅计划配置使用此令牌进行处理。
once_trial
integer<int32>

试用期定价限制试用 1 次. 1: 不限制, 2:限制试用一次, 3: 跳过试用期

fixed_term
integer<int32>

订阅固定期限,取值正整数

is_renewable
boolean

是否支持固定期限转为持续订阅

tax_category
string

订单应税分类。仅 mode=payment 时生效,可选。

  • Software as a service (SaaS):通过互联网提供软件服务的模式,用户可按需订阅,无需本地安装或维护。
  • Software:可下载/授权独立软件:需要本地安装的独立软件(如安装包、许可证密钥)。
  • Online Video Content:视频内容:通过流媒体或下载提供的视频内容(如课程、影片、直播流)。
  • Information Service:数字数据/报告:提供数据、新闻或分析的数字产品(如数据库、行业报告)。
  • eBook:电子书/数字出版物:可在电子设备上阅读的数字化图书或出版物。
  • Digital Graphic / Template:可编辑数字模板:可编辑的数字设计素材(如PSD模板、PowerPoint模板)。
  • Video Game:数字游戏:交互式数字游戏,包括下载、内购或订阅服务(如Xbox Game Pass)。
  • Blockchain Digital Products:加密数字资产:基于区块链的唯一数字资产(如NFT艺术品、虚拟房产)。
  • Other Digital Products:其他虚拟商品:未涵盖的其他虚拟商品(如活动门票)。 未传或传入值不在上述范围时按未传处理(回落到商户默认税码),不报错、不阻断结账会话创建
terms_data
object

结账页展示的商户自有条款链接,可选。两个 URL 各自可空; 必须 https 绝对 URL 且长度 <= 512,否则 400

响应

200 - application/json

OK

code
string

error code

message
string

error message

data
object