从后端发起购买流

购买流端点让自建的活动网站卖出与平台相同的内容——票、加购、捆绑、兑换码，免费与付费——底层仍由 orriven 处理它一直在做的事：容量占位、Stripe 收款、webhook 结算、履约为报名与权益，以及发给买家的票务邮件。

在这个调用面上，路径永远是买家 → 前端 → 后端（持 API 密钥）→ orriven。密钥可读写整个业务单元，不能下发到浏览器。后端必须只把该登录买家的订单与报名返回给本人。买家账号体系由接入方自建：orriven 不托管任何参会者登录，仅以邮箱识别买家。站点没有后端时，同样的结账会话可以用公开密钥从浏览器直接创建。见 Storefront API。

两条路

	结账会话（推荐）	直接下单 / 确认
后端发送	所选项目、已知的买家信息、`returnUrl`	邮箱、姓名、项目、表单答案——整张订单
orriven 的托管页面负责	补齐信息、占位、收款、展示结果、送回买家	仅收款（Stripe）；若未传自己的回跳地址，还负责展示订单结果
适用于	买家身份、报名表单与支付都交给平台处理	每一步都由接入方渲染，只需平台完成结算

结账会话

展示在售内容

用 GET …/ticket-types（票名、价格、售卖窗口、状态）、…/availability（实时剩余数字）、…/addons、…/bundles、…/venues、…/sessions（议程）、…/speakers（讲者）渲染活动页。买家输入兑换码时，先用 GET …/redemption-codes/lookup?code= 预览——解锁的票（隐藏票也在内）、附带的权益、折后价，在下单之前即可展示。

创建会话并跳转

curl -s -X POST "$BASE/v1/events/$EVENT/checkout-sessions" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "itemType": "registration_type", "itemId": "…", "quantity": 1 },
      { "itemType": "addon",             "itemId": "…", "quantity": 2 }
    ],
    "email": "ada@example.com",
    "name": "Ada",
    "redemptionCode": "VIP2026",
    "returnUrl": "https://tickets.example.com/thanks"
  }'

201 返回 { "id", "url", "expiresAt" }。把买家送到 url —— orriven 的托管结账页。请求体中除 items 外均为可选：未提供的信息（邮箱、姓名、票种的报名表单答案、加购）由页面向买家询问。预填的邮箱以打码形式展示，买家不能修改。会话有效 24 小时且不占位。占位从买家在会话中下单时开始。GET …/checkout-sessions/{id} 可查询它是否已产生订单（orderId）。

接回买家

付款完成（免费单则立即）后，买家看到托管订单页及其**「返回主办方」**按钮，按钮跳转到 returnUrl 并附加 ?order=<orderNumber>&status=<status>。status=paid 表示座位、权益与入场凭证均已存在。其他值（expired、cancelled）表示买家中途离开。未提供 returnUrl 时，按钮使用控制台中设置的活动页面地址。

在后端核对

后端可随时读取订单：GET …/orders（或按 id）给出 status、履约后的 registrationId、orderUrl（其托管页面），订单仍开放时还有 checkoutUrl。付费单的结算由平台的 Stripe webhook 完成，而不是经这次调用。需要在服务端据此动作时，请轮询直到 paid。

直接下单与确认

完全由接入方渲染的结账流程，仍沿用三步：

下单

curl -s -X POST "$BASE/v1/events/$EVENT/orders" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada",
    "items": [
      { "itemType": "registration_type", "itemId": "…", "quantity": 1 },
      { "itemType": "addon",             "itemId": "…", "quantity": 2 }
    ],
    "redemptionCode": "VIP2026",
    "returnUrl": "https://tickets.example.com/thanks"
  }'

201 返回待确认订单。它会占位 15 分钟，并带 orderUrl：托管订单页，可直接交给买家完成核对与付款。已在该活动报过名的买家得到 200 和 alreadyRegistered: true：被确认，绝不重复占位。票已满则 412。

确认——免费当场结清，付费拿 Stripe 支付页

curl -s -X POST "$BASE/v1/events/$EVENT/orders/$ORDER_NUMBER/confirm" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "successUrl": "https://tickets.example.com/thanks?order='"$ORDER_NUMBER"'",
    "cancelUrl":  "https://tickets.example.com/checkout?order='"$ORDER_NUMBER"'"
  }'

免费订单（总额 0）当场结清：{"status":"paid", "registration":{…}, "created":true}。不经过 Stripe。
付费订单返回 {"status":"awaiting_payment", "paymentUrl":"https://checkout.stripe.com/…"}。将买家重定向过去。successUrl/cancelUrl 为可选：传入时 Stripe 把买家直接送回接入方的页面（仅限 https——本地开发允许 http://localhost）；不传时买家落在托管订单页，再由它送回订单的 returnUrl。

等待结算

付款经平台的 Stripe webhook 结算，而不是经这次调用。轮询 GET …/orders/{orderId} 直到 status 变为 paid 且 registrationId 已填。那一刻，座位、权益、签到码都已存在。

在站点里做「我的票」

平台会给每位已确认的买家发送入场凭证链接——托管页面，包含其签到二维码、钱包通行证、证书与问卷。它对持有链接且输入买家邮箱的人开放，因此可以放心地在自定义网站里再次展示。请在服务端按后端已认证的人过滤后构建页面：

报名（GET …/registrations?email=）——按邮箱精确过滤。每条带 status、票种、自行渲染二维码时用的 checkinCode，以及 passUrl ——可直接链接的托管入场凭证页。
重新生成链接（POST …/registrations/{id}/rotate-access-token）——此前的全部地址立即失效。响应携带新的 passUrl。链接被转发到不该去的地方时使用。
权益（GET …/registrations/{id}/perks）——票种 ∪ 兑换码 ∪ 个人授予的生效并集。
签到记录（GET …/checkins?registrationId=）——使用历史。
订单——购买历史，各带 orderUrl。

约束

一单一座。 报名模型是一人一活动一报名，一张订单最多承载一个票座（超出 412）。替朋友买票时，每人一单、各用各的邮箱。加购数量不受此限。
在这个调用面上，订单号就是订单的凭证。 在服务端像对待该买家的会话令牌一样保管它。托管页面还会额外要求买家输入订单邮箱。
待确认订单占位 15 分钟。 付费单确认后占位拉长到 35 分钟。用 POST …/orders/{orderNumber}/cancel 提前释放。重复取消只被确认。
结账会话不占位，直到买家从中下单；24 小时后过期。过期会话与从不存在的会话返回同一个 404。
重新生成凭证链接不可撤销。 之后请重新发送票务邮件（或在站点里展示新的 passUrl）。
业务单元未配置收款（未完成 Stripe 入驻）时，付费下单返回 412。免费路径不受影响。
自动化与票务邮件和平台自己的结账完全同源 ——下单/过期/取消与报名类触发器行为一致。

端点参考

会话、place、confirm、cancel 的结构。

订单（控制台视角）

主办方如何查看同一批订单。

开始使用

参考

接口

Storefront 接口

两条路

结账会话

直接下单与确认

在站点里做「我的票」

约束

相关页面

端点参考

订单（控制台视角）

​两条路

​结账会话

​直接下单与确认

​在站点里做「我的票」

​约束

​相关页面

端点参考

订单（控制台视角）

两条路

结账会话

直接下单与确认

在站点里做「我的票」

约束

相关页面