# 收款与权益 让接入 CZL Connect 的应用向自己的终端用户收费:出售套餐 (个人或组织)、套餐加购项 (加席位、加容量) 与一次性商品,CZL Connect 负责下单、验签、维护订阅状态与权益,并把状态变化推给你的后端。**钱直接进你自己的支付宝、微信支付或 Stripe 账户**,CZL Connect 不经手资金、不抽成;退款、税务与发票责任也由你承担。 各渠道可单独或同时使用,结账页列出全部可用方式: | 渠道 | 你提供 | 支付方式 | |---|---|---| | 支付宝开放平台直连 | 自己应用的 APPID 与密钥 | 当面付扫码、电脑网站、手机网站 (一次性付款) | | 微信支付商户直连 (APIv3) | 自己的商户号、AppID、APIv3 密钥、商户 API 证书与微信支付公钥 (或平台证书) | Native 扫码、H5 (手机浏览器拉起微信),一次性付款 | | Stripe Connect | 经 OAuth 授权你的 Stripe 账户 (Standard),CZL Connect 不保存你的密钥 | 「Stripe 自动续费」(开通套餐,每期自动扣款) 与「Stripe 一次性付款」;具体付款方式由你的 Stripe 账户开通的决定 | ## 开通 ### 支付宝 1. 在 [支付宝开放平台](https://open.alipay.com) 创建应用,签约「当面付」「电脑网站支付」「手机网站支付」中需要的一种或几种,接口加签方式选 **RSA2**,公钥模式或公钥证书模式均可。建议单独建一个应用给 CZL Connect 用 2. 在 CZL Connect「账户设置 → 集成 → 收款账户」添加:APPID、应用私钥、支付宝公钥 (或应用公钥证书、支付宝公钥证书、支付宝根证书)。并勾选已签约的产品 (至少一种,只改勾选不用重填密钥)。保存时会调用交易查询接口做连通校验 (不依赖签约哪种产品),失败不保存;凭据加密存储,从不回显。结账页与目录的 `methods` 只提供已勾选产品对应的方式:当面付 → `alipay_qr`,电脑网站支付 → `alipay_page`,手机网站支付 → `alipay_wap`。托管结账页在电脑上提供扫码 (当面付) 与网页收银台 (电脑网站支付),都没签约时退回手机网站支付;在手机上依次优先手机网站支付、电脑网站支付、扫码 3. 应用详情「收款 → 设置」选用该收款账户并开通。收款需要你的 CZL Connect 套餐为 Plus 及以上 (Plus 每月 300 笔成功订单、Pro 3000 笔、Enterprise 不限;续费不受额度限制) 4. 「收款 → 套餐」新建套餐,「商品」新建一次性商品 不需要在支付宝后台配置通知地址:下单时 CZL Connect 会随请求带上 `https://connect.czl.net/api/pay/notify/alipay/{收款账户 ID}`。 ### 微信支付 1. 在 [微信支付商户平台](https://pay.weixin.qq.com) 开通「Native 支付」(手机浏览器付款另开通「H5 支付」,并在「产品中心 → 开发配置」登记 H5 支付域名 `connect.czl.net`),并在「账户中心 → API 安全」设置 **APIv3 密钥** (32 位)、申请**商户 API 证书** (得到 `apiclient_key.pem` 与证书序列号)、获取**微信支付公钥**与公钥 ID (`PUB_KEY_ID_` 开头;老商户也可以用平台证书)。下单用的 AppID 须是与商户号绑定的公众号、小程序或开放平台应用 2. 在「账户设置 → 集成 → 收款账户」点「添加微信支付账户」,填商户号、AppID、APIv3 密钥、商户 API 私钥与证书序列号、微信支付公钥与公钥 ID (或平台证书),并勾选已开通的产品 (Native 支付 → `wxpay_native`、H5 支付 → `wxpay_h5`;H5 未登记域名时付款页会报「商家参数格式有误」)。保存需要通行密钥验证,会查一笔不存在的订单做连通校验 (商户号、私钥、证书序列号、微信支付公钥都对时才通过),失败不保存;密钥加密存储、从不回显,只显示证书序列号与公钥 ID 的首尾几位供核对。AppID 是否与商户号绑定在第一次下单时校验,APIv3 密钥在第一次收到回调时校验 (填错时回调验签失败、订单靠轮询查询入账)。老商户申请微信支付公钥后,微信可能仍用平台证书签名,CZL Connect 会用 APIv3 密钥自动下载平台证书验签,照常填公钥即可 3. 应用详情「收款 → 设置」选用该账户 (可与支付宝、Stripe 同时选用) 并开通 微信支付只收人民币,订单号为去掉连字符的订单 ID (32 位)。不需要在商户平台配置回调地址:下单与退款时随请求带上 `https://connect.czl.net/api/pay/notify/wxpay/{收款账户 ID}`。退款是异步的:渠道受理即记为已退款,结果以退款回调为准 (渠道最终退款失败时只记日志,请到商户平台处理);订单在商户平台已部分退款后,再从 CZL Connect 退款会被渠道拒绝;在商户平台直接退款也会同步,累计退满后订单按退款处理。 ### Stripe 1. 在「账户设置 → 集成 → 收款账户」点「连接 Stripe」(需通行密钥验证),在 Stripe 页面登录并授权;授权完成后回到账户设置,收款账户即添加。一个 Stripe 账户只能连接到一个 CZL Connect 账户 2. 应用详情「收款 → 设置」选用该 Stripe 账户 (可与支付宝账户同时选用) 并开通 3. 套餐价格为人民币,需要你的 Stripe 账户支持人民币收款。在你自己的 Stripe 后台「设置 → 付款方式」开通想提供的方式 (支付宝、微信支付、Apple Pay、Google Pay、Link 等):结账用 Stripe 的动态付款方式,会话建在你的账户上,列出的方式取你账户自己的付款方式设置,再按币种、顾客所在地与付款类型筛选——「Stripe 自动续费」只出能自动续费的方式 (银行卡、Apple Pay、Google Pay、Link 等),支付宝、微信支付等只出现在「Stripe 一次性付款」里。平台给连接账户的默认设置只对没自己改过的账户生效;某种方式在你的账户上不可用时 Stripe 不列出它,不会报错 4. 建议在 Stripe 后台关闭自带的收据邮件,CZL Connect 会以应用名义发付款与续费邮件 不需要在 Stripe 配置 webhook:Connect 平台统一接收你账户上的事件。CZL Connect 在你的账户上创建的结账、订阅、价格与付款都带 `metadata.app=czlconnect`、`app_id`、`order`、`subject`、`plan`,你自己的其它业务不受影响;套餐首次以自动续费售出时,会在你的账户上按套餐建 Product 与 Price (改价时新建 Price,不改旧的)。在「收款账户」删除 Stripe 账户会同时解除授权;仍有应用在用或还有自动续费订阅时不能删除。你在 Stripe 后台撤销授权后,该账户标为「已断开」,使用它的应用停止接受 Stripe 新订单。 ## 概念 | 概念 | 说明 | |---|---| | 套餐 | `code` (客户端识别用,建好不能改)、价格 (分)、多周期选项 `multiPeriods` (一次买 2~12 个周期及各自折扣,如 3 年 8 折)、周期 (年 / 月 / 固定天数 / 永久 `lifetime`)、主体 (`user` 个人 / `org` 组织)、席位 (组织套餐)、`quotas` 与 `features` (开放键值,原样下发)、试用天数 | | 加购项 | 加到套餐上的份数 (如 1 席位 / 10 GB):每份单价 (按套餐一个周期计)、每份数量、作用目标 (`seats` 或套餐 `quotas` 的某个键)、最多份数、可加购的套餐 | | 商品 | 一次性购买 (加油包等),`payload` 开放键值随 `order.paid` 交给你的后端发放;`kind: "topup"` 为按金额充值 (见下) | | 优惠券 | 券码 (不区分大小写)、固定金额或百分比 (1~99%)、总使用次数 (1 = 一次性,0 = 不限)、每主体可用次数、最低消费 (按优惠前金额)、开始 / 结束时间、适用范围 (全部,或指定的套餐 / 商品 / 加购项 code) | | 订阅 | 每个主体 (用户或组织) 在应用里一条,状态 `trialing` / `active` / `past_due` / `grace` / `expired` / `canceled` / `refunded` | | 订单 | 每次下单一笔,`pending` / `paid` / `closed` / `refunded`;类型 `plan` / `upgrade` / `addon` / `product`;订单号即支付宝商户订单号 (微信支付为去掉连字符的订单号) | 改价、改周期或改主体会归档原套餐、同 `code` 新建一行:已有订阅保持原价,续费按新价。下架即归档,已有订阅到期为止权益照常。加购项改单价、每份数量或作用目标会归档原行、同 `code` 新建;已买的份数沿用购买时的价格,一次性订阅续费时按在售行计价。下架加购项或换到不允许它的套餐后,已付费的当前周期照常,下个周期起不再生效、续费也不再计费 (自动续费订阅上的订阅项随即从 Stripe 移除,不按比例)。 ## 币种与充值 - **币种**:套餐、商品 (含充值)、加购项与固定金额优惠券可按人民币 `CNY` 或美元 `USD` 标价。Stripe 直接按标价币种收;支付宝与微信支付只收人民币,美元标价按「收款 → 设置 → 美元汇率」折成人民币下单 (四舍五入到分),未设汇率时返回 400 与 `"code": 40027`。订单同时记两种金额:`amountCents` / `currency` 为渠道实收,`listAmountCents` / `listCurrency` 为标价 (已扣优惠),`exchangeRate` 为下单时的汇率;退款按实收原路退回。加购项须与套餐同币种;周期内不能在币种不同的套餐之间升级或降级 - **手续费**:owner 可在「收款 → 设置 → 手续费」按收款方式 (支付宝 / 微信支付 / Stripe) 设比例与固定金额 (按实收币种),下单时加到渠道实收上:`amountCents` 含手续费,`feeCents` 单列 (订单、预览带 `method` 时、`order.paid` 等 webhook 的 `order` 都带,未加收时省略);`listAmountCents` 不含手续费。零元订单与 Stripe 自动续费不加收;退款按实收 (含手续费) 原路退回 - **按金额充值** (商品 `kind: "topup"`):owner 设最小、最大金额与步长 (标价币种),可选档位折扣 (到账金额达到门槛时少付一定比例,取达到的最高档)。用户下单时用 `amountCents` 填到账金额,订单的 `creditCents` 为到账金额、`listAmountCents` 为实付。CZL Connect 不维护余额:`order.paid` 带 `creditCents` 与实付,由你的后端入账。金额不在范围或不按步长返回 400;折算后低于渠道最低收款额返回 400 与 `"code": 40026`。充值商品不能生成兑换码 ## 购买规则 - **一次性付款** (支付宝直连、微信支付直连、Stripe 一次性付款):不自动续费,到期前 7 天、1 天邮件提醒;续费同套餐在原到期日上顺延,金额为套餐 + 下个周期的加购份数 - **Stripe 自动续费**:主体当前没有生效中的已付费订阅时,开通套餐可选「Stripe 自动续费」,周期以 Stripe 为准,到期自动扣款 (套餐 + 加购);年付在扣款前 7 天邮件提醒。扣款失败进 `past_due`,宽限天数内权益照常,Stripe 补扣成功即恢复,宽限期满或 Stripe 终止订阅后 `expired`。用户可在「我的订阅」关闭自动续费 (期末取消,可用到当前周期结束) 或恢复。自动续费订阅不能再用一次性付款续费;一次性订阅仍在有效期内时,到期后才能改为自动续费 - **升级** (同周期、更贵的套餐):一次性订阅的差价 = (新价 − 旧价) × 剩余天数 / 周期天数,至少 1 分,付款后立即切换;自动续费订阅直接从订阅的付款方式按比例扣差价 (扣款失败即报错、订阅不变)。两者到期日都不变 - **降级** (更便宜的套餐):一次性订阅付款后在当前周期结束时生效;自动续费订阅暂不支持降级,先关闭自动续费,到期后再购买 - **多周期购买**:套餐设了 `multiPeriods` (如 `[{"periods": 3, "percentOff": 20}]`) 时,开通、续费与降级可带 `periods` 一次买多个周期,套餐价 = 单价 × 周期数 × (1 − 折扣),续费时的加购份数按周期数原价计;有效期按周期数顺延,订单 `quantity` 即周期数。只能一次性付款 (不提供 Stripe 自动续费);升级按剩余时间补差价 (差价按单个周期折算,剩余时间可超过一个周期),不能同时带 `periods`。未开放的周期数返回 400 与 `"code": 40028` - **永久套餐** (`periodUnit: "lifetime"`):一次买断,无到期、不续费、不能加购,权益里 `periodEnd` 为 `null`、`lifetime` 为 `true`;只能一次性付款 (支付宝、微信支付、Stripe 一次性付款,不提供 Stripe 自动续费)。已有周期订阅时购买永久套餐按原价立即生效、替换当前订阅 (剩余时间不折算,自动续费订阅随即在 Stripe 取消);已拥有永久套餐时不能再购买或更换为其它套餐 (从永久套餐升级暂不支持),返回 400 与 `"code": 40025`。退款一律立即结束;兑换码与订阅导入指向永久套餐时不看天数 / `periodEnd` - 到期后有宽限天数 (应用设置,默认 3 天),宽限期内权益照常,之后 `expired` - **一次加购多项**:同一笔订单可带多个加购项与各自份数,每项分别按剩余周期折算,订单金额为合计,最低收款额按合计判断;退款按整笔订单退并回收这笔里的全部份数。只覆盖部分加购项的优惠券不能用于这笔订单 - **开通套餐随单加购**:开通套餐 (没有订阅、已到期、试用中或宽限期内) 时可带 `addons`,每项按「单价 × 份数 × 周期数」计入订单,与套餐同一天到期、续费时按份数一起续;Stripe 自动续费时加购作为订阅的其它项每期一起扣款。订阅生效中续费、升级或降级不能附带 (返回 400),请单独加购;永久套餐不支持加购。付款到账时订阅已被别的订单开通 (这笔变成顺延续费) 或加购已不适用的,整笔原路退款 - **加购**:只有订阅生效中的主体可以加购当前套餐允许的加购项;价格 = 每份单价 × 份数 × 剩余天数 / 套餐周期天数 (至少 1 分),立即生效、与套餐同一天到期。自动续费订阅的加购直接从订阅的付款方式按比例扣款,之后随订阅续费。减少份数在当前周期结束后生效 (调用「调整加购份数」);重新开通已到期的订阅时,上一段的加购不延续。剩余时间太短、折算金额低于最低收款额 (支付宝与微信支付 ¥1、Stripe ¥4) 时拒绝下单,返回 400 与 `"code": 40021`,请续费后再加购。一次性付款到账时订阅已失效、套餐已不允许该加购项或份数已满的,订单自动原路退款 - 为组织购买须是组织的 `owner` 或 `admin`;组织有有效订阅时,席位 = 套餐的 `seats` (未设则取应用组织设置的默认席位) + 加购的席位,否则取默认席位。成员数超过席位时组织转只读 (不移除成员),续费、升级、加席位或减员后恢复 - **优惠券**:下单、预览与托管结账页都可带券码;套餐券对开通、续费、升级补差价都适用。使用次数按带券的订单计 (待支付、已付款、已退款):未付款关闭的订单退还次数,**整单退款不退还**。同一用户重复下单会复用自己带券的待支付订单;换了数量或支付方式时先关掉旧的那笔,每人同一张券只保留一笔待支付订单。券码连续 10 次不存在会锁定该用户 1 小时 (429)。优惠后金额至少 1 分且不低于该支付方式的最低收款额 (支付宝与微信支付 ¥1、Stripe ¥4),否则返回 400 与 `"code": 40024`;券无效、未生效、已过期、已停用、已用完、不适用或未达最低消费返回 400 与 `"code": 40023`。不能用于 Stripe 自动续费 (含已是自动续费订阅的升级与加购) - 自助退款:应用可设置「付款后 N 小时内、每个周期 M 次」;退款后订阅立即结束 (自动续费订阅同时在 Stripe 取消)。owner 后台退款不受时间窗口限制,可选立即结束或保留到期末 (自动续费订阅改为期末取消);退加购订单只退掉对应份数。在 Stripe 后台直接退款也会同步到订单与订阅 ## 托管结账页 没有自建界面时,在系统浏览器打开: ``` https://connect.czl.net/pay/{应用 ID}/{套餐或商品 code}?user={用户 ID}&subject=org:{组织 ID}&periods={周期数}&addons={加购项 code}:{份数}&coupon={券码}&return={回跳地址} https://connect.czl.net/pay/{应用 ID}?user={用户 ID}&addons={加购项 code}:{份数},{加购项 code}:{份数}&subject=org:{组织 ID}&return={回跳地址} ``` - `user` 建议总是带上:应用里当前登录用户的 ID (同 OIDC `sub` / userinfo `id`)。浏览器里登着别的 Connect 账户时页面不让付款,提示「切换账户」(退出后重新登录再回到本页),避免订阅开到应用找不到的账户上。它只用来核对、不改变付款人,所以不需要签名;下单接口同样接受 `user`,不一致返回 409 与 `"code": 40029` - `addons`:`code:份数` 以逗号分隔 (份数缺省 1)。路径是套餐 code 时为开通套餐随单加购 (见「加购」);不带套餐 code 时为单独加购,可一次加多项,页面上可调份数。旧写法 `?addon={code}&qty={份数}` 仍可用 - `subject` 省略即为个人购买;组织套餐不带时页面让用户选择自己管理的组织;加购时页面让用户在本人与自己管理的组织之间选择 - `coupon` 可预填优惠券码,用户也可在页面输入 - `return` 须与应用登记的回调地址或「收款 → 设置 → 回跳地址」同协议、同域名、同路径 (查询参数可不同),可以是自定义协议 (如 `myapp://billing/done`);不符合时忽略 - 支付宝:电脑上提供扫码与网页收银台,手机上跳转支付宝;微信支付:电脑与微信内置浏览器展示 Native 二维码,手机浏览器开通了 H5 时直接跳转微信付款、付完回到结果页;Stripe:跳转 Stripe 收银台。付款完成后进入结果页,再由「返回应用」带回 `return` 用户可在「账户设置 → 我的订阅」(`https://connect.czl.net/profile/subscriptions`,应用里的「管理订阅」直接链到这里) 查看订阅与加购、续费、开关自动续费、继续加购与申请退款。 ## 用户令牌接口 客户端用 OAuth2 访问令牌 (`Authorization: Bearer `) 调用,应用由令牌决定。 | 方法 | 路径 | 说明 | |---|---|---| | GET | `/api/oauth2/billing/catalog?subject=` | 在售套餐、商品、可用支付方式,以及 `subject` (默认本人) 当前套餐可加购的项 | | GET | `/api/oauth2/billing/entitlements` | 本人与所属各组织的权益 | | POST | `/api/oauth2/billing/orders` | 下单 | | POST | `/api/oauth2/billing/order-preview` | 下单前算价并校验优惠券 (参数同下单,`method` 可选;带上时按该方式检查最低收款额),返回 `originalCents`、`discountCents`、`amountCents` (标价币种)、`creditCents` (充值)、带 `method` 时另有 `chargeCents` (含手续费) / `chargeCurrency` / `exchangeRate` / `feeCents`、`coupon` | | GET | `/api/oauth2/billing/orders` | 我的订单 | | GET | `/api/oauth2/billing/orders/{orderId}` | 订单状态 (轮询用,待支付时服务端会主动向渠道查询兜底) | | POST | `/api/oauth2/billing/orders/{orderId}/refund` | 自助退款 | | POST | `/api/oauth2/billing/redeem` | 兑换码 | | POST | `/api/oauth2/billing/trials` | 开始试用 (`{"plan": "...", "subject": "..."}`) | | POST | `/api/oauth2/billing/addon-quantity` | 调整加购份数 (只能调低,下个周期生效;传当前份数即撤回调低):`{"subject": "user", "addon": "seat", "quantity": 1}` | | POST | `/api/oauth2/billing/subscriptions/{subscriptionId}/auto-renew` | 开关自动续费:`{"enabled": false}` = 期末取消 | ### 下单 (当面付) ```http POST /api/oauth2/billing/orders Content-Type: application/json {"plan": "team", "subject": "org:0192f3a0-...", "method": "alipay_qr", "returnUrl": "myapp://billing/done"} ``` - `plan`、`product`、加购三选一 (填 code);商品可带 `quantity` (1 到 99) - `addons`:加购多项 `[{"code": "storage10", "quantity": 2}, {"code": "seat", "quantity": 1}]`。不带 `plan` 时为单独加购 (旧写法 `addon` + `quantity` 仍可用,二者只能用一种);带 `plan` 时为开通套餐随单加购 - `user`:可选,应用视角的用户 ID;与令牌对应的用户不一致时返回 409 与 `"code": 40029`。目录的 `me.id` 为当前用户 ID (托管页另带昵称与邮箱用于提示) - `subject`:`user` 或 `org:{组织 ID}` - `amountCents`:充值商品的到账金额 (标价币种,分) - `periods`:套餐一次购买的周期数 (默认 1,须是套餐 `multiPeriods` 里开放的) - `coupon`:优惠券码 (可选);订单返回 `discountCents` 与 `couponCode`,`amountCents` 为优惠后实收 - `method`:`alipay_qr` (当面付,返回二维码内容) / `wxpay_native` (微信支付 Native,返回二维码内容 `weixin://...`) / `wxpay_h5` (微信支付 H5,返回跳转地址,只能在手机浏览器打开、微信内置浏览器不可用;按调用方请求的 IP 下单,须由用户设备直接调用) / `alipay_page` (电脑网站支付,返回跳转地址) / `alipay_wap` (手机网站支付) / `stripe_recurring` (Stripe 自动续费,只用于可开通自动续费的套餐订单,否则报错) / `stripe_once` (Stripe 一次性付款,套餐、加购、商品都可用);后两者返回 Stripe 收银台地址 `payUrl`。可用方式见目录的 `methods` (支付宝、微信支付按收款账户已签约 / 已开通的产品列出),传了账户没有的方式返回 400 与 `"code": 40022`。旧值 `stripe_card` (可自动续费时等同 `stripe_recurring`,否则 `stripe_once`) 与 `stripe_alipay` (等同 `stripe_once`) 仍接受,订单里按实际方式记录 - Stripe 一次性付款选了支付宝、微信支付这类异步确认的方式时,用户提交后订单仍是 `pending`,渠道确认后才变为 `paid`;最终失败则 `closed`,可重新下单 - 主体已是自动续费订阅时,升级与加购不经收银台:直接扣款并返回 `status: "paid"` 的订单,扣款失败返回 402;一次加购多项只开一张账单 - 订单与预览带 `addons` 明细 (`code`、`name`、`quantity`、`amountCents` 为该项优惠前的标价金额),`order.paid` 等 webhook 的 `order.addons` 同此 ```json { "id": "0192f3b1-7c2e-7a10-9d55-0f1c2b3a4d5e", "kind": "plan", "itemCode": "team", "amountCents": 14900, "status": "pending", "qrCode": "https://qr.alipay.com/bax0...", "expiresAt": "2026-11-20T10:15:00Z", "refundable": false } ``` 加购示例:`{"addon": "storage10", "quantity": 2, "subject": "user", "method": "alipay_qr"}`,`kind` 为 `addon`,`amountCents` 为按剩余天数折算后的金额。目录里每个加购项带 `currentQuantity` (当前份数)、`maxUnits`、`priceCents` (每份每周期) 与 `proratedUnitCents` (本期每份折算价)。 桌面端把 `qrCode` (支付宝或微信支付) 渲染成二维码,每 2 秒轮询 `GET /orders/{id}`,`status` 变为 `paid` 后刷新权益。二维码 15 分钟内有效,超时后订单关闭。网站支付返回 `payUrl`,用浏览器打开即可。同一内容在有效期内重复下单会返回同一笔订单。`kind` 为 `upgrade` 时 `amountCents` 是补差价金额。 ### 权益 ```json { "personal": { "subscriptionId": "0192...", "active": true, "plan": "personal", "planName": "个人同步", "status": "active", "periodStart": "2026-11-20T10:00:00Z", "periodEnd": "2027-11-20T10:00:00Z", "lifetime": false, "graceUntil": null, "cancelAtPeriodEnd": false, "seats": 0, "quotas": {"syncStorageGB": 25}, "features": {}, "addons": [ {"code": "storage10", "name": "加 10 GB 存储", "target": "syncStorageGB", "unitAmount": 10, "quantity": 2, "amount": 20, "pendingQuantity": null, "pendingEffectiveAt": null} ], "provider": "stripe_connect", "autoRenew": true }, "orgs": [ {"orgId": "0192...", "name": "外贸一组", "role": "member", "orgStatus": "active", "seats": 5, "memberCount": 3, "entitlement": {"plan": "team", "active": true, "...": "..."}} ] } ``` - 永久套餐的 `periodEnd` 为 `null`、`lifetime` 为 `true` (出站 webhook 的 `currentPeriodEnd` 同样为 `null` 并带 `lifetime`) - 没订阅过时 `personal` / `entitlement` 为 `null`;`active` 为 `false` 时 `seats`、`quotas`、`features`、`addons` 为空 - `seats` 与 `quotas` 是套餐与加购的**合计** (上例为套餐 5 GB + 加购 2 × 10 GB),直接按它判定即可;`addons` 是明细,`pendingQuantity` 出现时表示下个周期的份数 - `autoRenew` 为 `true` 表示 Stripe 自动续费订阅,`cancelAtPeriodEnd` 为 `true` 表示已关闭自动续费 - 状态按当前时间推算,不依赖定时任务落库 - `pendingPlan` 出现时表示已付款的降级,当前周期结束后生效 - 权益不放进 ID Token;桌面端在回到前台或付款完成后重新拉取 ### 兑换码 ```http POST /api/oauth2/billing/redeem {"code": "ABCD-EFGH-JKLM-NPQR", "subject": "user"} ``` 套餐型兑换码叠加天数到当前订阅 (当前套餐更便宜时切到兑换的套餐,没有订阅时新开一段);商品型生成一笔零元已付款订单并发出 `order.paid`。每个码只能用一次,同一用户连续失败 10 次锁定 1 小时。 ## 应用级 API 用 API key (`czlc_live_…`) 从你的后端调用,详见 [应用级 API](/docs/app-api)。 | scope | 方法 | 路径 | 说明 | |---|---|---|---| | `billing:read` | GET | `/api/v1/app/users/{userId}/entitlements` | 用户权益,结构同上 | | `billing:read` | GET | `/api/v1/app/orgs/{orgId}/entitlements` | 组织权益,结构同上面 `orgs[]` 的一项 (不含 `role`);组织不存在 404 `org_not_found` | | `billing:read` | GET | `/api/v1/app/billing/orders` | 订单列表,按更新时间升序增量拉取 (对账用):`since` (RFC 3339,只列此后更新的)、`status` (逗号分隔,`pending` / `paid` / `closed` / `refunded`)、`limit` (1~100,默认 50)、`cursor` (上一页的 `nextCursor`);返回 `items` (结构同 webhook 的 `order`)、`nextCursor`、`hasMore`。订单之后再更新 (付款、退款) 会在后面的页里再次出现,按订单号幂等处理。只列 30 秒前更新的;`nextCursor` 最后一页也有,存下来下次接着拉 | | `billing:read` | GET | `/api/v1/app/billing/orders/{orderId}` | 按订单号查询 (补偿发放用) | | `billing:write` | POST | `/api/v1/app/subscriptions/import` | 导入存量订阅 | | `billing:catalog` | PUT | `/api/v1/app/billing/catalog` | 同步套餐、商品、加购项目录 | | `billing:catalog` 或 `billing:read` | GET | `/api/v1/app/billing/catalog` | 导出目录 (`?includeArchived=1` 含已下架项) | ### 导入存量订阅 迁移已有付费用户 (一次性付款或其它渠道),记为 `manual` 订阅,不发邮件,按 (主体, `externalId`) 幂等: ```json {"items": [ {"externalId": "legacy-123", "userId": "0192...", "plan": "personal", "periodEnd": "2027-03-01T00:00:00+08:00", "note": "旧系统迁移"}, {"externalId": "legacy-456", "orgId": "0192...", "plan": "team", "periodEnd": "2027-01-01T00:00:00+08:00"} ]} ``` 每条可带 `addons` (如 `[{"code": "storage10", "quantity": 1}]`,用于赠送「套餐 + 加容量」):导入后该订阅上这些加购项设为给定份数 (不叠加),与套餐同一天到期、续费时按份数一起续;订阅被重新开始时不带上一段的加购。主体的订阅仍按别的套餐生效或是 Stripe 自动续费时,带 `addons` 的条目报错。 返回逐条 `status`:`created` / `exists` / `error` (附 `error`)。每次 1 到 500 条。 ### 同步套餐目录 接入方在自己后台维护套餐时,把目录推过来即可,不必在 CZL Connect 后台手工建。按 `code` 幂等,规则与后台一致: - 没有同 `code` 的在售项 → 新建 (`created`) - 价格、周期、主体 (加购项为单价、每份数量、作用目标) 变化 → 归档原行、同 `code` 新建 (`repriced`),已有订阅保持原价、续费按新价 - 其它字段 (名称、额度、功能、席位、排序等) 变化 → 原地修改 (`updated`);内容没变 → `unchanged`,可以反复推送 - `status: "archived"` → 下架 (`archived`);`prune: true` 时把本次没出现的在售项一并下架 - 套餐先于加购项处理;逐项独立,单项出错报 `error` 不影响其它项。每次最多 200 项 ```http PUT /api/v1/app/billing/catalog Authorization: Bearer czlc_live_... {"plans": [{"code": "pro-1y", "nameZh": "专业版 1 年", "priceCents": 19900, "periodUnit": "year", "periodCount": 1, "subjectType": "user", "quotas": {"storageGB": 100}, "features": {"group": "pro"}}], "products": [{"code": "pack-10g", "nameZh": "10 GB 流量包", "priceCents": 990, "payload": {"trafficGB": 10}}], "addons": [], "prune": false} ``` 返回 `{"items": [{"type": "plan", "code": "pro-1y", "result": "created", "id": "0192..."}, ...]}`。字段同后台表单 (套餐:`code`、`nameZh`、`nameEn`、`priceCents`、`periodUnit`、`periodCount`、`subjectType`、`seats`、`quotas`、`features`、`trialDays`、`sortOrder`;商品:`payload` 等;加购项:`unitAmount`、`target`、`maxUnits`、`planCodes`)。`GET` 导出同一结构 (每项另带 `id` 与 `status`),改完可原样推回。 ## 出站 webhook 在「收款 → Webhook」添加 https 地址 (每应用最多 5 个,可按事件过滤)。事件: `subscription.activated` · `subscription.renewed` · `subscription.upgraded` · `subscription.past_due` · `subscription.expired` · `subscription.canceled` · `subscription.refunded` · `subscription.addons_changed` · `order.paid` · `order.refunded` · `org.member_added` · `org.member_removed` `subscription.addons_changed` 在加购、调低份数与退掉加购时发出,收到后重新拉取权益;自动续费每期扣款成功发 `order.paid` + `subscription.renewed`,扣款失败发 `subscription.past_due`。 ```http POST https://api.example.com/czl/webhook Content-Type: application/json X-CZL-Event-Id: 0192f3c4-... X-CZL-Event-Type: order.paid X-CZL-Signature: t=1795000000,v1=5f0c... {"id": "0192f3c4-...", "type": "order.paid", "createdAt": "2026-11-20T10:01:02Z", "data": {"order": {"id": "0192...", "kind": "product", "itemCode": "chars-1m", "quantity": 1, "amountCents": 990, "discountCents": 0, "couponCode": "", "listAmountCents": 990, "listCurrency": "CNY", "creditCents": 0, "exchangeRate": "", "status": "paid", "subject": {"type": "user", "userId": "0192..."}, "payerUserId": "0192...", "payload": {"chars": 1000000}}}} ``` - 签名:`v1 = hex(HMAC-SHA256(签名密钥, t + "." + 原始请求体))`,校验 `t` 在 5 分钟内,用常量时间比较 - 按 `id` 去重:同一事件可能重复投递 - 返回 2xx 即成功;否则按 1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时、24 小时重试,用尽后标记失败,可在投递记录里手动重新投递 - 地址须为公网 https,内网地址会被拒绝 ```go func verify(secret, header string, body []byte) bool { var ts, sig string for _, p := range strings.Split(header, ",") { k, v, _ := strings.Cut(p, "=") if k == "t" { ts = v } else if k == "v1" { sig = v } } t, _ := strconv.ParseInt(ts, 10, 64) if time.Since(time.Unix(t, 0)).Abs() > 5*time.Minute { return false } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(ts + "." + string(body))) return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(sig)) } ``` ## 邮件与通知 付款成功、一次性订阅到期前 7 天 / 1 天、自动续费扣款前 7 天 (年付)、自动续费成功、自动续费失败 (附 Stripe 账单付款链接,可更换付款方式补缴)、已到期、退款完成以应用名义发出 (发件人「应用名(经 CZL Connect)」),同时写入用户的通知中心;组织订阅另抄送组织所有者。这些是交易类邮件,用户不能退订,也不计入你的群发额度。收款账户凭据被支付宝或微信支付拒绝、Stripe 账户被撤销授权时通知账户所有者。 ## 错误 接口错误为 `{"error": "人话说明"}`,按请求语言返回中文或英文;应用级 API 为 `{"error": "snake_case 码", "message": "说明"}`。常见状态码: | 状态 | 含义 | |---|---| | 400 | 参数不对、主体不符、不满足退款条件等;加购金额低于最低收款额时另带 `"code": 40021`,所选支付方式收款账户未开通时另带 `"code": 40022`,优惠券不可用时另带 `"code": 40023`,用券后低于最低收款额时另带 `"code": 40024`,已拥有永久套餐再购买或更换时另带 `"code": 40025`,充值金额低于渠道最低收款额时另带 `"code": 40026`,美元标价但应用未设汇率时另带 `"code": 40027`,套餐未开放所选周期数时另带 `"code": 40028` | | 402 | 自动续费订阅的升级 / 加购扣款失败 | | 403 | 应用未开通收款、为组织购买但不是 owner / admin、自助退款不允许 | | 404 | 套餐 / 商品 / 加购项 / 订单 / 订阅不存在 | | 409 | 带了 `user` 但与当前登录账户不一致 (`"code": 40029`),请让用户切换账户 | | 429 | 兑换失败次数过多 | | 502 | 支付渠道暂时不可用或拒绝了凭据 |