收款与权益

应用服务

收款与权益

本页目录

让接入 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. 在 支付宝开放平台 创建应用,签约「当面付」「电脑网站支付」「手机网站支付」中需要的一种或几种,接口加签方式选 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. 在 微信支付商户平台 开通「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 <access_token>) 调用,应用由令牌决定。

方法路径说明
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。

scope方法路径说明
billing:readGET/api/v1/app/users/{userId}/entitlements用户权益,结构同上
billing:readGET/api/v1/app/orgs/{orgId}/entitlements组织权益,结构同上面 orgs[] 的一项 (不含 role);组织不存在 404 org_not_found
billing:readGET/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:readGET/api/v1/app/billing/orders/{orderId}按订单号查询 (补偿发放用)
billing:writePOST/api/v1/app/subscriptions/import导入存量订阅
billing:catalogPUT/api/v1/app/billing/catalog同步套餐、商品、加购项目录
billing:catalog 或 billing:readGET/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支付渠道暂时不可用或拒绝了凭据