主题
Stripe 配置（含 webhook）
一句话
拿三个值（Publishable key / Secret key / Webhook 密钥），填进后台，用测试卡走一遍。
界面会变，功能不会
Stripe 后台每年都在调整。下面写的是要找什么，不是"点第几个按钮"。 菜单名对不上时按功能找同义词。
你要拿的三个值
| 后台字段 | 长什么样 | 在 Stripe 哪里 |
|---|---|---|
| 可发布密钥 Publishable key | pk_test_... / pk_live_... | Developers → API keys |
| 密钥 Secret key | sk_test_... / sk_live_... | 同上 |
| Webhook 签名密钥 | whsec_... | Developers → Webhooks → 添加端点之后才有 |
前两个和第三个不在同一个地方
很多人在 API keys 页面上找不到 whsec_，以为哪里出错了。
它不在那儿 —— Webhook 密钥要先「添加一个端点」，然后在那个端点的详情页里 才能看到（通常要点一下「Reveal」/「显示」）。
第 1 步：注册并切到测试模式
- 注册 https://stripe.com
- 后台右上角有一个 Test mode / 测试模式 开关 —— 先打开它
测试模式和正式模式的密钥完全独立
测试模式下拿到的是 pk_test_ / sk_test_，只能用测试卡； 正式模式下是 pk_live_ / sk_live_，会真的扣钱。
两套 webhook 也是独立的，要各配一次。
第 2 步：拿 API keys
Developers → API keys
- Publishable key 直接可见，复制
- Secret key 要点「Reveal」才显示，复制
Secret key 泄露 = 别人能动你的钱
它能创建收款、发起退款、读取所有交易。 不要贴到聊天工具里，不要截图发出去。系统会加密存库，后台读取时只返回掩码。
第 3 步：先在后台把通道建出来
顺序不能反
Webhook 地址里带着通道 ID，而 ID 是保存之后才有的。 所以先建通道（Webhook 密钥那一格先留空），保存，再回 Stripe 配 webhook。
新建弹窗里那一块会提示「回调地址要保存之后才有」，那是正常的，不是漏了什么。
后台 → 站点管理 → 支付通道 → Stripe 那一行的「新增」
| 字段 | 填什么 |
|---|---|
| 环境 | 沙箱 |
| 可发布密钥 | pk_test_... |
| 密钥 | sk_test_... |
| Webhook 签名密钥 | 先留空，第 5 步再填 |
| 前台展示名 | 留空即可（显示 Stripe） |
| 启用 | 打开 |
保存时会要求输验证器上的 6 位码（见 支付通道总览）。
保存后，通道列表里那一行会出现**「回调地址（webhook）」列， 后面有个复制**按钮 —— 下一步要用的就是它。
第 4 步：在 Stripe 添加 webhook 端点
Developers → Webhooks → Add endpoint
Endpoint URL 填 —— 回后台支付通道列表，点那一行的复制按钮，直接粘过来。
地址长这样（别手打，用复制按钮）：
https://jdz.io/api/open/payment/callback/stripe/3也可以在配置弹窗里拿
点「配置密钥」打开弹窗，「密钥」那一段上面就有同一个地址和复制按钮 —— 你正好要在那儿填 Webhook 密钥，不用来回切页面。
要监听的事件（Select events），至少选这几个：
charge.refunded
charge.refund.updated
payment_intent.canceled
payment_intent.payment_failed
payment_intent.succeeded
refund.failed不要图省事选「所有事件」
选全部的话，Stripe 会把几百种事件都推给你，绝大多数我们不处理 —— 它们会在回调日志里堆成一片，真出问题时反而找不到。
第 5 步：拿 Webhook 密钥填回去
端点创建完，点进那个端点的详情页，找 Signing secret， 点「Reveal」，复制那串 whsec_...。
回后台 → 支付通道 → 编辑刚才那个 Stripe 通道 → 把 Webhook 签名密钥 填上 → 保存 （又要输一次 6 位码）。
这一步漏了会怎样
所有回调都会被判为伪造并拒绝，Stripe 那边看到的是 401。 表现和"完全没配 webhook"一样：买家付了钱订单还是待付款。
第 6 步：用测试卡走一遍
Stripe 的测试卡号：
| 卡号 | 结果 |
|---|---|
4242 4242 4242 4242 | 支付成功 |
4000 0000 0000 0002 | 卡被拒 |
4000 0025 0000 3155 | 需要 3D 验证 |
有效期填任意未来日期（如 12/34），CVC 任意三位（如 123），邮编任意。
要走完整条：
加购 → 结算 → 选 Stripe → 用 4242 卡付款 → 跳回来
→ 订单几秒内变成「已付款」→ 收到订单确认邮件顺便验一下失败的情况
用 4000 0000 0000 0002 付一次，确认订单没有变成已付款， 而且页面给出了能看懂的提示。
第 7 步：切正式环境
不要新建第二条通道
系统里一个支付方式只能有一条通道（再建会报「已配置过 stripe」）。 「沙箱 / 生产」是这一条通道上的一个开关，不是两套配置 —— 切换时看到的密钥框内容是一样的，这是正常的。
好消息：回调地址从头到尾不变（地址里的数字是通道 ID）。
沙箱全部跑通之后：
- Stripe 后台关掉测试模式，拿
pk_live_/sk_live_ - Stripe 正式模式下 → Developers → Webhooks → 再添加一次端点， 地址填同一个（就是你沙箱阶段用的那个），拿到新的
whsec_ - 回后台打开这条通道 → 环境切到「生产」 → 三个密钥框会自动清空并弹红色提示，把 live 的值填进去 → 保存（要过 TOTP）
- 点「测试连接」确认
- 清掉测试订单
为什么切环境会清空密钥
不清空的话会出现一种界面上看不出来的错配：框里显示 ••••••1234 掩码， 看着是填好的，而系统对密钥的规则是「空或掩码 = 不修改」—— 于是通道标着生产、握着测试密钥，每一笔真实付款都失败而后台一切正常。 前后端都做了强制：换环境不继承旧密钥。
第 2 步最容易漏
测试模式下配过 webhook 就以为完事了 —— 但正式模式是完全独立的一套， 端点要在正式模式下再加一次（地址一样，但生成的 whsec_ 是新的）。
漏了的话：上线后买家付了钱，订单全是「待付款」，半小时后被自动关单。
常见问题
结算页选 Stripe 之后一直转圈
浏览器控制台（F12）看有没有报错。最常见是 Publishable key 填错 （填成了 secret key，或者沙箱通道里填了 live 的 key）。
Stripe 回调日志显示 401
Webhook 签名密钥不对。注意：
- 它是
whsec_开头，不是sk_ - 删了端点重建的话，密钥会变，要回后台更新
- 沙箱和正式的
whsec_不一样，别搞混
Stripe 回调日志显示 404
基本都是地址手拼错了。回后台用那一行的「复制」按钮重新取一次， 覆盖掉 Stripe 端点里的地址。
复制来的也 404 的话，检查后台地址栏里的域名是不是能从公网访问的正式域名。
退款失败
- 那笔订单是用这个通道收的吗 —— 换过收款账号的话， 老订单要用老通道退（所以通道只停用不删）
- Stripe 余额够吗 —— 余额不足时退款会失败
- 后台的售后页面会显示 Stripe 返回的原文，照着它查