应用服务
收款与权益
让接入 CZL Connect 的应用向自己的终端用户收费:出售套餐 (个人或组织)、套餐加购项 (加席位、加容量) 与一次性商品,CZL Connect 负责下单、验签、维护订阅状态与权益,并把状态变化推给你的后端。钱直接进你自己的支付宝、微信支付或 Stripe 账户,CZL Connect 不经手资金、不抽成;退款、税务与发票责任也由你承担。
各渠道可单独或同时使用,结账页列出全部可用方式:
| 渠道 | 你提供 | 支付方式 |
|---|---|---|
| 支付宝开放平台直连 | 自己应用的 APPID 与密钥 | 当面付扫码、电脑网站、手机网站 (一次性付款) |
| 微信支付商户直连 (APIv3) | 自己的商户号、AppID、APIv3 密钥、商户 API 证书与微信支付公钥 (或平台证书) | Native 扫码、H5 (手机浏览器拉起微信),一次性付款 |
| Stripe Connect | 经 OAuth 授权你的 Stripe 账户 (Standard),CZL Connect 不保存你的密钥 | 「Stripe 自动续费」(开通套餐,每期自动扣款) 与「Stripe 一次性付款」;具体付款方式由你的 Stripe 账户开通的决定 |
开通
支付宝
- 在 支付宝开放平台 创建应用,签约「当面付」「电脑网站支付」「手机网站支付」中需要的一种或几种,接口加签方式选 RSA2,公钥模式或公钥证书模式均可。建议单独建一个应用给 CZL Connect 用
- 在 CZL Connect「账户设置 → 集成 → 收款账户」添加:APPID、应用私钥、支付宝公钥 (或应用公钥证书、支付宝公钥证书、支付宝根证书)。并勾选已签约的产品 (至少一种,只改勾选不用重填密钥)。保存时会调用交易查询接口做连通校验 (不依赖签约哪种产品),失败不保存;凭据加密存储,从不回显。结账页与目录的
methods只提供已勾选产品对应的方式:当面付 →alipay_qr,电脑网站支付 →alipay_page,手机网站支付 →alipay_wap。托管结账页在电脑上提供扫码 (当面付) 与网页收银台 (电脑网站支付),都没签约时退回手机网站支付;在手机上依次优先手机网站支付、电脑网站支付、扫码 - 应用详情「收款 → 设置」选用该收款账户并开通。收款需要你的 CZL Connect 套餐为 Plus 及以上 (Plus 每月 300 笔成功订单、Pro 3000 笔、Enterprise 不限;续费不受额度限制)
- 「收款 → 套餐」新建套餐,「商品」新建一次性商品
不需要在支付宝后台配置通知地址:下单时 CZL Connect 会随请求带上 https://connect.czl.net/api/pay/notify/alipay/{收款账户 ID}。
微信支付
- 在 微信支付商户平台 开通「Native 支付」(手机浏览器付款另开通「H5 支付」,并在「产品中心 → 开发配置」登记 H5 支付域名
connect.czl.net),并在「账户中心 → API 安全」设置 APIv3 密钥 (32 位)、申请商户 API 证书 (得到apiclient_key.pem与证书序列号)、获取微信支付公钥与公钥 ID (PUB_KEY_ID_开头;老商户也可以用平台证书)。下单用的 AppID 须是与商户号绑定的公众号、小程序或开放平台应用 - 在「账户设置 → 集成 → 收款账户」点「添加微信支付账户」,填商户号、AppID、APIv3 密钥、商户 API 私钥与证书序列号、微信支付公钥与公钥 ID (或平台证书),并勾选已开通的产品 (Native 支付 →
wxpay_native、H5 支付 →wxpay_h5;H5 未登记域名时付款页会报「商家参数格式有误」)。保存需要通行密钥验证,会查一笔不存在的订单做连通校验 (商户号、私钥、证书序列号、微信支付公钥都对时才通过),失败不保存;密钥加密存储、从不回显,只显示证书序列号与公钥 ID 的首尾几位供核对。AppID 是否与商户号绑定在第一次下单时校验,APIv3 密钥在第一次收到回调时校验 (填错时回调验签失败、订单靠轮询查询入账)。老商户申请微信支付公钥后,微信可能仍用平台证书签名,CZL Connect 会用 APIv3 密钥自动下载平台证书验签,照常填公钥即可 - 应用详情「收款 → 设置」选用该账户 (可与支付宝、Stripe 同时选用) 并开通
微信支付只收人民币,订单号为去掉连字符的订单 ID (32 位)。不需要在商户平台配置回调地址:下单与退款时随请求带上 https://connect.czl.net/api/pay/notify/wxpay/{收款账户 ID}。退款是异步的:渠道受理即记为已退款,结果以退款回调为准 (渠道最终退款失败时只记日志,请到商户平台处理);订单在商户平台已部分退款后,再从 CZL Connect 退款会被渠道拒绝;在商户平台直接退款也会同步,累计退满后订单按退款处理。
Stripe
- 在「账户设置 → 集成 → 收款账户」点「连接 Stripe」(需通行密钥验证),在 Stripe 页面登录并授权;授权完成后回到账户设置,收款账户即添加。一个 Stripe 账户只能连接到一个 CZL Connect 账户
- 应用详情「收款 → 设置」选用该 Stripe 账户 (可与支付宝账户同时选用) 并开通
- 套餐价格为人民币,需要你的 Stripe 账户支持人民币收款。在你自己的 Stripe 后台「设置 → 付款方式」开通想提供的方式 (支付宝、微信支付、Apple Pay、Google Pay、Link 等):结账用 Stripe 的动态付款方式,会话建在你的账户上,列出的方式取你账户自己的付款方式设置,再按币种、顾客所在地与付款类型筛选——「Stripe 自动续费」只出能自动续费的方式 (银行卡、Apple Pay、Google Pay、Link 等),支付宝、微信支付等只出现在「Stripe 一次性付款」里。平台给连接账户的默认设置只对没自己改过的账户生效;某种方式在你的账户上不可用时 Stripe 不列出它,不会报错
- 建议在 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 (同 OIDCsub/ userinfoid)。浏览器里登着别的 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} = 期末取消 |
下单 (当面付)
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同此
{
"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 是补差价金额。
权益
{
"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;桌面端在回到前台或付款完成后重新拉取
兑换码
POST /api/oauth2/billing/redeem
{"code": "ABCD-EFGH-JKLM-NPQR", "subject": "user"}套餐型兑换码叠加天数到当前订阅 (当前套餐更便宜时切到兑换的套餐,没有订阅时新开一段);商品型生成一笔零元已付款订单并发出 order.paid。每个码只能用一次,同一用户连续失败 10 次锁定 1 小时。
应用级 API
用 API key (czlc_live_…) 从你的后端调用,详见 应用级 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) 幂等:
{"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 项
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。
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,内网地址会被拒绝
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 | 支付渠道暂时不可用或拒绝了凭据 |