交易接入 / 操作与配置
Stripe:获取两项密钥并配置 Checkout
从 Stripe 官方后台取得 Secret Key 和本应用 Webhook 的 Signing Secret,配好通知地址和两个事件,再在 ZOO 验证生效。
01 / 准备条件
02 / 分步操作
03 / 结果检查
使用前准备
- 已有符合 Stripe 支持地区/主体要求的账户;正式收款前完成官方激活和银行资料审核。
- 有查看 API keys 与管理 Webhook 的权限。
- ZOO 应用已允许“[官方] Stripe Checkout”。
01从准备到结果确认
查看这段动画的完整步骤
- 选择环境
Sandbox / Live:同一账户,参数成套。
两项密钥来自同一账户、同一环境。
- 取得 API 密钥
Secret Key:sk_test_… / sk_live_… 占位。
Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- 核对地址
当前应用 Webhook:使用 ZOO 生成 URL。
ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 配置事件
Checkout 快照事件:completed / expired。
正式收款前另用 Live 整套配置验收。
- 取得签名密钥
Signing secret:当前端点 whsec_… 占位。
正式收款前另用 Live 整套配置验收。
- 配置验收
测试订单与回调:先测试,再切正式环境。
正式收款前另用 Live 整套配置验收。
02第一步:选对 ZOO 应用与测试环境
查看这段动画的完整步骤
- 登录你自己的 ZOO 站点
登录你自己的 ZOO 站点。示例为分站 https://s.198600.xyz,示例应用名为 vpnceshi。这里的应用名可以换成你的实际业务名。
两项密钥来自同一账户、同一环境。
- 打开左侧“商户应用”
打开左侧“商户应用”,找到 vpnceshi,确认所属商户是自己。检查“默认支付范围”是否包含本教程渠道;管理员可点“编辑”调整,普通商户看不到编辑按钮时联系管理员。
Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- 打开左侧“系统设置”
打开左侧“系统设置”。管理员先在“选择商户应用”中选 vpnceshi,不要误选“平台默认配置”。普通商户选择自己的应用,不能配置别人的应用。
ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 列表已有“Stripe”时点该行“编辑”
列表已有“Stripe”时点该行“编辑”;没有时点“新增配置”,在“支付平台”选“Stripe”。本教程只处理这一个配置组。
正式收款前另用 Live 整套配置验收。
03第二步:取得 Secret Key
查看这段动画的完整步骤
- 自己登录 Stripe 管理平台 ↗
自己登录 Stripe 管理平台 ↗,先检查当前账户及顶部 Sandbox/测试或 Live 环境。
两项密钥来自同一账户、同一环境。
- 也可使用官方 API keys 入口 ↗
打开“开发者/Developers”或“Workbench”中的“API keys”,也可使用官方 API keys 入口 ↗。不同版本名称略有差异,找的是 API keys。
Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- 操作 3
在“Standard keys”找到“Secret key”,点“Reveal/显示”或按官方提示创建并查看密钥。测试环境以 sk_test_ 开头,正式环境以 sk_live_ 开头。正式密钥可能只显示一次,自己妥善保管。
ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 把它填到 ZOO 的 Secret Key
把它填到 ZOO 的 Secret Key。不要复制 pk_ 开头 Publishable key;本系统当前验证要求 sk_,不要按别的教程填 rk_ 受限密钥。此页面不用填写 Publishable key。
正式收款前另用 Live 整套配置验收。
04第四步:在 Workbench 创建事件接收端
查看这段动画的完整步骤
- 操作 1
仍在同一 Stripe 账户、同一 Sandbox/Live 环境。打开 Workbench → Webhooks ↗,点“创建事件接收端/Create an event destination”(旧界面可能写“Add endpoint”)。
两项密钥来自同一账户、同一环境。
- 操作 2
来源选“你的账户/Your account”;不要选 Connected accounts 或另一个组织的账号。事件类型使用快照事件/Snapshot events,本系统处理完整 Checkout Session,不要选 Thin 精简事件。
Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- 操作 3
API 版本以当前 ZOO 发布版本的兼容设置为准;本教程核对的 beta.15 使用 2026-02-25.clover,界面可选时选择对应版本,不能照抄通用教程随意换成未来版本。
ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 操作 4
只勾选 checkout.session.completed 和 checkout.session.expired。当前 ZOO 只处理这两个事件,不勾“全部事件”、payment_intent.succeeded、invoice.paid 或异步支付事件。
正式收款前另用 Live 整套配置验收。
- 点“继续/Continue”
点“继续/Continue”,接收端类型选“Webhook endpoint”。再次继续,把上一步的完整 URL 粘到“Endpoint URL”,描述可写“ZOO 我的应用 Stripe 回调”,完成创建。
正式收款前另用 Live 整套配置验收。
- 进入这个端点的详情
进入这个端点的详情,在“Signing secret/签名密钥”点“Reveal/显示”,复制以 whsec_ 开头的完整值。这是当前 URL、账户和环境独有的密钥,不从另一端点或 Stripe CLI 复制。
正式收款前另用 Live 整套配置验收。
05第五步:把两项参数填回 ZOO
查看这段动画的完整步骤
- 按字段表填入自己取得的资料
按字段表填入自己取得的资料。 保存过的私密字段不会回显;编辑时留空保留原值,填写新值会覆盖旧值。不要把星号或示例文字粘进去。
两项密钥来自同一账户、同一环境。
- 点击“验证配置”
点击“验证配置”,阅读提示。验证失败时先按本页排错表修正,不要反复点击保存。验证主要检查凭据、格式或接口连通性,不能证明每种支付产品、到账和回调都已完成。
Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- 点击“保存草稿”
点击“保存草稿”。若弹出安全确认,按页面要求在自己的浏览器完成邮箱或双因素验证,勿将验证码发给他人。草稿保存后回到配置列表。
ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 再点击这一行“生效”
复核当前选中的应用、测试/正式环境和回调地址,再点击这一行“生效”。确认状态变为“已生效”。生效影响该应用之后的支付,请在业务允许的时间操作。
正式收款前另用 Live 整套配置验收。
- 从已接入的测试商店或面板生成一笔新订单
从已接入的测试商店或面板生成一笔新订单,选择本教程渠道。不要重新使用过期订单,也不要把“返回成功页面”当成到账。检查 ZOO“支付订单”、服务商交易记录和“商户回调”。
正式收款前另用 Live 整套配置验收。
06第六步:先验收测试订单,再切正式
查看这段动画的完整步骤
- 从你的测试商店/面板发起一笔新订单
从你的测试商店/面板发起一笔新订单,选择 Stripe Checkout,确认跳转到 Stripe 托管页面。在 Sandbox 只使用 官方测试卡 ↗,例如测试卡 4242 4242 4242 4242 配未来有效日期与测试 CVC;不要在沙箱输入自己的真实卡。
两项密钥来自同一账户、同一环境。
- 支付完成后
支付完成后,在 Workbench 的这个 Webhook → “事件投递/Event deliveries”找到这笔 checkout.session.completed,检查 Delivered/2xx;再检查 ZOO 订单 SUCCESS 与业务端回调。
Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- 不能代替 ZOO 发起的完整订单验收
官方“发送测试事件”可能是没有 ZOO 订单关联的样例,不能代替 ZOO 发起的完整订单验收。测试卡付款也不代表正式账户已能收款。
ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 需要正式收款时
需要正式收款时,确认 Stripe 账户已可收款;在 Live 环境取得新的 sk_live_ 和当前 URL 的 Live whsec_,按同样两个事件配置,填回 ZOO 验证、保存、生效,再由本人完成合法小额验收。
正式收款前另用 Live 整套配置验收。
- 操作 5
金额和币种须符合 Stripe 当前 最低收款金额 ↗。不要固定用人民币 1 元测试所有 Stripe 币种。当前 ZOO 为卡支付托管 Checkout,不是直接嵌入卡表单;钱包是否显示由 Stripe 账户、设备和条件决定。
正式收款前另用 Live 整套配置验收。
详细操作与条件
第一步:选对 ZOO 应用与测试环境
- 登录你自己的 ZOO 站点。示例为分站
https://s.198600.xyz,示例应用名为vpnceshi。这里的应用名可以换成你的实际业务名。 - 打开左侧“商户应用”,找到
vpnceshi,确认所属商户是自己。检查“默认支付范围”是否包含本教程渠道;管理员可点“编辑”调整,普通商户看不到编辑按钮时联系管理员。 - 打开左侧“系统设置”。管理员先在“选择商户应用”中选
vpnceshi,不要误选“平台默认配置”。普通商户选择自己的应用,不能配置别人的应用。 - 列表已有“Stripe”时点该行“编辑”;没有时点“新增配置”,在“支付平台”选“Stripe”。本教程只处理这一个配置组。
有香港银行卡不等于自动取得 Stripe 收款资格,以 Stripe 支持地区 ↗ 及官方账户审核为准。第一次先使用 Sandbox/测试模式的整套参数和测试订单;正式前换成 Live 整套参数。
第二步:取得 Secret Key
- 自己登录 Stripe 管理平台 ↗,先检查当前账户及顶部 Sandbox/测试或 Live 环境。
- 打开“开发者/Developers”或“Workbench”中的“API keys”,也可使用官方 API keys 入口 ↗。不同版本名称略有差异,找的是 API keys。
- 在“Standard keys”找到“Secret key”,点“Reveal/显示”或按官方提示创建并查看密钥。测试环境以
sk_test_开头,正式环境以sk_live_开头。正式密钥可能只显示一次,自己妥善保管。 - 把它填到 ZOO 的 Secret Key。不要复制
pk_开头 Publishable key;本系统当前验证要求sk_,不要按别的教程填rk_受限密钥。此页面不用填写 Publishable key。
第三步:先拿到正确的 Webhook URL
服务商 → ZOO:在当前应用配置列表复制“回调地址”。分站应用通常为 https://s.198600.xyz/api/v1/notify/stripe/你的ZOO应用ID;平台默认地址没有应用 ID 后缀。以后台生成地址为准,不照抄占位文本。
ZOO → 你的商店:在商店插件或面板设置 ZOO 的商户回调地址,应用“回调 Origin 白名单”仅填写它的 https://域名(不含路径)。这两个方向不能互换。
- 在 ZOO 当前应用的 Stripe 配置列表复制“回调地址”。还未保存配置时可按后文先填两项并保存草稿,再从列表复核地址。为首次创建 Webhook,可先以本站域名和当前 ZOO App ID 组成应用地址,创建后再逐字符核对后台地址。
- 分站应用示意:
https://s.198600.xyz/api/v1/notify/stripe/你的ZOO应用ID。这里需要 ZOO 商户应用 ID,不是 Stripe 账户编号,也不是商户用户名。其它站点换成自己的域名。 - Webhook 是服务端 POST 接口,不能填
/settings、商店成功页面或管理员私有登录入口。用浏览器直接打开它显示不支持 GET,并不能证明回调坏了。
第四步:在 Workbench 创建事件接收端
- 仍在同一 Stripe 账户、同一 Sandbox/Live 环境。打开 Workbench → Webhooks ↗,点“创建事件接收端/Create an event destination”(旧界面可能写“Add endpoint”)。
- 来源选“你的账户/Your account”;不要选 Connected accounts 或另一个组织的账号。事件类型使用快照事件/Snapshot events,本系统处理完整 Checkout Session,不要选 Thin 精简事件。
- API 版本以当前 ZOO 发布版本的兼容设置为准;本教程核对的 beta.15 使用
2026-02-25.clover,界面可选时选择对应版本,不能照抄通用教程随意换成未来版本。 - 只勾选
checkout.session.completed和checkout.session.expired。当前 ZOO 只处理这两个事件,不勾“全部事件”、payment_intent.succeeded、invoice.paid或异步支付事件。 - 点“继续/Continue”,接收端类型选“Webhook endpoint”。再次继续,把上一步的完整 URL 粘到“Endpoint URL”,描述可写“ZOO 我的应用 Stripe 回调”,完成创建。
- 进入这个端点的详情,在“Signing secret/签名密钥”点“Reveal/显示”,复制以
whsec_开头的完整值。这是当前 URL、账户和环境独有的密钥,不从另一端点或 Stripe CLI 复制。
Secret Key 在 API keys;Signing Secret 在这个 Webhook 详情页。它们不是同一种密钥。以后修改 URL、切换环境或轮换 Webhook 密钥后,必须同步更新正确 ZOO 应用的 Signing Secret。
第五步:把两项参数填回 ZOO
| ZOO 字段 | 来源 | 检查方法 |
|---|---|---|
| Secret Key(STRIPE_SECRET_KEY) | 同一环境 API keys → Secret key | 测试 sk_test_;正式 sk_live_;不能填 pk_ |
| Webhook Signing Secret(STRIPE_WEBHOOK_SECRET) | 当前应用 Webhook 详情 → Signing secret | whsec_ 开头,与上面 API key 同账户同环境 |
- 按字段表填入自己取得的资料。 保存过的私密字段不会回显;编辑时留空保留原值,填写新值会覆盖旧值。不要把星号或示例文字粘进去。
- 点击“验证配置”,阅读提示。验证失败时先按本页排错表修正,不要反复点击保存。验证主要检查凭据、格式或接口连通性,不能证明每种支付产品、到账和回调都已完成。
- 点击“保存草稿”。若弹出安全确认,按页面要求在自己的浏览器完成邮箱或双因素验证,勿将验证码发给他人。草稿保存后回到配置列表。
- 复核当前选中的应用、测试/正式环境和回调地址,再点击这一行“生效”。确认状态变为“已生效”。生效影响该应用之后的支付,请在业务允许的时间操作。
- 从已接入的测试商店或面板生成一笔新订单,选择本教程渠道。不要重新使用过期订单,也不要把“返回成功页面”当成到账。检查 ZOO“支付订单”、服务商交易记录和“商户回调”。
Stripe 在线验证检查密钥格式并调用余额接口;whsec_ 的前缀正确不代表它一定属于这个端点。必须用这个 ZOO 应用产生的测试 Checkout 订单验证真实回调。
第六步:先验收测试订单,再切正式
- 从你的测试商店/面板发起一笔新订单,选择 Stripe Checkout,确认跳转到 Stripe 托管页面。在 Sandbox 只使用 官方测试卡 ↗,例如测试卡
4242 4242 4242 4242配未来有效日期与测试 CVC;不要在沙箱输入自己的真实卡。 - 支付完成后,在 Workbench 的这个 Webhook → “事件投递/Event deliveries”找到这笔
checkout.session.completed,检查 Delivered/2xx;再检查 ZOO 订单 SUCCESS 与业务端回调。 - 官方“发送测试事件”可能是没有 ZOO 订单关联的样例,不能代替 ZOO 发起的完整订单验收。测试卡付款也不代表正式账户已能收款。
- 需要正式收款时,确认 Stripe 账户已可收款;在 Live 环境取得新的
sk_live_和当前 URL 的 Livewhsec_,按同样两个事件配置,填回 ZOO 验证、保存、生效,再由本人完成合法小额验收。 - 金额和币种须符合 Stripe 当前 最低收款金额 ↗。不要固定用人民币 1 元测试所有 Stripe 币种。当前 ZOO 为卡支付托管 Checkout,不是直接嵌入卡表单;钱包是否显示由 Stripe 账户、设备和条件决定。
常见错误:从这里开始检查
| 现象 | 检查与处理 |
|---|---|
| Invalid API Key / 验证失败 | 是否复制 Secret key,是否已撤销/轮换,测试与正式是否一致,服务器能否访问 Stripe |
| Webhook signature verification failed | whsec_ 是否来自当前 URL 的同一账户同一环境;不要使用 CLI 临时密钥 |
| Webhook 404 / 302 / 403 | 完整应用后缀及域名;是否误填网页、被登录页面重定向或有访问验证拦截,请站点管理员处理 |
| unsupported stripe event type | 只订阅 completed 和 expired 两种 Checkout Session 快照事件 |
| No such checkout.session | 可能涉及会话 ID、账号/环境或订单信息,需要管理员根据具体订单排查;别把它等同于金额太低,也别反复付款 |
| 支付成功但没发货/充值 | 先核对 Stripe 实收和 ZOO SUCCESS,再查 ZOO 商户回调及业务端响应 |
官方资料
资料核对:2026-10-03。本文按 ZOO 当前字段整理,未复制真实账号凭据。服务商的资格、费率和审核结果由服务商决定。
操作结果确认
- 两项密钥来自同一账户、同一环境。
- Webhook URL 与 ZOO 应用地址一致,只有两个支持的快照事件。
- ZOO 发起的测试订单已收到回调并更新状态,业务端结果已验收。
- 正式收款前另用 Live 整套配置验收。
本页操作视频
与本页主动画使用同一分镜。视频按 1.5× 导出,32 秒;付款与凭据操作由本人完成。
常见问题
要在 Stripe 先创建商品和 Price ID 吗?
这个 ZOO 配置弹窗不要求 Price ID,也不是创建 Stripe 订阅计划的教程。业务订单由 ZOO 的 Checkout 适配器创建。
两个应用用同一 Stripe 账户如何配置?
为各自 ZOO 应用使用对应回调 URL,取得各自端点的 whsec_;不要把一个端点签名密钥盲目填到另一个应用。
要把所有事件全勾上吗?
不要。当前只支持 checkout.session.completed 与 checkout.session.expired。
保存之后怎么还是旧配置?
保存草稿不会启用新配置;确认选对应用,再点对应行“生效”,用新订单测试。
编辑时密钥输入框空着,是不是丢了?
私密字段保存后不会回显。已配置字段留空保留原值;重新输入会覆盖。首次新增仍需填写必要参数。
我没有申请到官方账号,可以先照抄教程参数吗?
不能。示例和图中的值都不可用于支付。必须取得自己有权使用的账户和参数;未开通的产品先不要启用。