在沙箱中端到端测试支付/结账流程（Stripe 为主，含…

用 PSP 沙箱和测试卡验证支付成功/拒付/3DS 挑战/订阅续费/Webhook 签名与幂等/退款对账，避免真实卡与客户端伪造成功。

适用场景

解决思路

1. 先检查项目根目录的 .agents/qa-project-context.md，跳过其中已说明的 PSP、技术栈、测试框架和现有 fixture，再澄清：用哪个 PSP（默认 Stripe）、一次性支付还是订阅、是否涉及 SCA/3DS、当前是在 webhook 还是 redirect 上履约、webhook handler 在测试中运行在本地还是已部署的预览环境。
2. 绝不使用真实卡号或 live key：测试环境只用 pk_test_/sk_test_ 与 Stripe 公布的测试卡；对真实 PAN 做掩码或加密不算修复，必须移除，并从仓库和 git 历史中清除、轮换已暴露的密钥。
3. 金额只以服务端确认为准：不要在 redirect、onApprove 回调或 ?status=success 查询参数上标记订单已支付；只在签名验证通过的 payment_intent.succeeded webhook 之后，再用 API retrieve 复核，才执行履约。
4. 在解析 body 之前先验证签名：webhook 路由挂载 express.raw 以保留原始字节，constructEvent 需要原始 body；全局 express.json() 必须放在 webhook 路由之后；伪造或篡改的事件返回 400，不要手写 === 字符串比较。
5. 把计费时间当作服务端构造：客户端伪造时钟（jest.useFakeTimers、sinon、mock Date）对 Stripe 计费引擎无效，必须使用 Stripe test clock。
6. 假设每个 webhook 都会被投递多次：以 event.id 在持久化存储中做幂等（UNIQUE 约束），内存 Set 不算幂等；重复投递返回 200 并只履约一次。
7. 用确定性测试卡驱动各结果：4242424242424242 成功；4000000000000002 拒付 card_declined（generic_decline）；4000000000009995 拒付 insufficient_funds；4000000000003220 总是触发 3DS 挑战；4000000000000341 可附加但后续扣款失败。不要用 4111111111111111（那是 Braintree/PayPal 时代的通用 Luhn 号，不是 Stripe 测试卡，不会确定性拒付）。
8. 卡号输入框位于跨域 Stripe iframe 中，必须通过 frameLocator 填写，不能用 page.locator 直接定位；结果可在 UI 文案上做冒烟断言，更稳健的是从 paymentIntents.retrieve 读取服务端 last_payment_error.decline_code 断言。
9. 处理 3DS/SCA 嵌套 iframe：Stripe 3DS 挑战是嵌套在 Stripe modal frame 内部的 frame，单个 frameLocator 无法到达；链式调用 frameLocator 外层 → 内层，再点击 Complete authentication；不要用 page.frames()[1] 按索引选帧，按稳定名称前缀（如 iframe[name^="__privateStripeFrame"]）匹配；不要用 waitForTimeout 猜挑战时长，改为等待元素可见。
10. 3DS 测试示例：用 4000000000003220 填卡号，点击支付按钮，然后用 page.frameLocator('iframe[name^="__privateStripeFrame"]').frameLocator('iframe#challengeFrame, iframe[name="acsFrame"]') 定位内层，点击 /complete authentication|complete|authorize/i，最后断言跳转到 /success 且出现 payment succeeded 文案；setup-intent/首次使用流程可用 4000002760003184 作为替代 SCA 卡。
11. 用 test clock 测试订阅续费：在 frozen_time 创建 clock，并在创建 customer 时通过 test_clock: clock.id 附加（事后无法附加已有 customer）；advance 只能向前，不能回退，每次最多推进两个计费周期；推进后轮询 clock 到 ready，再断言续费 invoice 和 webhook。
12. 本地接收 webhook 用 stripe listen --forward-to localhost:3000/webhooks（启动时只打印一次 whsec_…），用 stripe trigger payment_intent.succeeded 按需触发；把 whsec_… 写入 STRIPE_WEBHOOK_SECRET，注意它是签名密钥，与 STRIPE_SECRET_KEY（sk_test_…）不同，不要混淆；不要用 ngrok 暴露端点，也不要轮询 API 查状态。
13. 幂等实现示例：INSERT INTO processed_events (id) VALUES ($1) ON CONFLICT (id) DO NOTHING RETURNING id，若 rowCount === 0 则返回 200 表示重复已忽略；请求侧 idempotency key 不能去重入站 webhook。
14. 测试失败续费与退款：用 4000000000000341（SDK token pm_card_chargeCustomerFail）订阅，它会附加到 customer 但在后续扣款时失败；在 test clock 上推进过续费日，断言 invoice.payment_failed 和订阅变为 past_due；用 refunds.create 发起退款（触发 charge.refunded）来解决，不要通过删除订阅来“修复”。
15. 对账测试：断言 redirect 之后订单仍为 pending，只有在签名验证通过的 payment_intent.succeeded webhook 之后（并用 paymentIntents.retrieve 复核 status === 'succeeded' 且 amount_received 符合预期）才变为 paid。
16. 多 PSP 时移植结构而非测试值：Stripe 测试卡在其他 PSP 上无效，Adyen 用自己的测试卡（如 4212345678910014 用于 3DS2），很多拒付由交易金额驱动（.13 拒绝、.51 转介），事件为 HMAC 签名通知；PayPal 用 sandbox buyer 账号登录，服务端通过 Orders API/webhook 确认；Braintree 用自有 sandbox 测试卡，金额决定交易结果、卡号决定验证结果；共同点是独立测试凭据、不用真实卡、在服务端验证事件后履约。
17. 验证清单：stripe listen 打印 whsec_… 且 stripe trigger 能看到事件到达；3DS 测试用 4000000000003220 能到达并点击 Complete authentication（找不到嵌套 frame 时应显式失败而非静默通过）；篡改 Stripe-Signature 返回 400，generateTestHeaderString 生成的 header 返回 200；同一 event.id 投递两次只履约一次；对测试套件运行 grep -rE 'pk_live|sk_live|4111111111111111' 应无结果（不要用裸 [0-9]{16} 扫描，会误报所有合法测试卡）。

适用边界 · 注意事项

• 非支付端点的通用 API 契约测试——应使用 api-testing。
• PCI-DSS/合规监管审计——应使用 compliance-testing。
• 需要真实卡或 live key 的生产验证场景——本技能明确不适用。