stripe-payments

stripe-payments Skill 多维度简评

类别: 后端开发 / 支付集成 来源: stripe/skills（Stripe 官方 Agent Skills） 定位: Stripe 支付集成——PaymentIntents 支付意图、Subscriptions 订阅管理、Connect 平台支付、Tax 自动税务、webhook 签名验证。

一、核心定位与价值

Stripe 是全球最大的支付基础设施平台之一，其 API 覆盖从在线支付、订阅计费、平台支付（Connect）到税务自动化（Tax）、发票（Invoicing）、发卡（Issuing）等完整支付生态。

核心价值: Stripe Skills 将 Stripe 的支付平台专业知识打包为可复用的 Agent Skill，让 AI 编程助手生成符合当前 API 版本的 Stripe 集成代码，而非依赖模型训练数据中的过时模式。

Stripe 产品矩阵

二、核心能力清单

三、5 大实战场景

场景 1: 标准调用——集成 Stripe Checkout

提示词:
使用 stripe-payments Skill，为我的 Next.js SaaS 应用集成 Stripe Checkout：
1. 创建产品（Product + Price）→ 生成 Checkout Session
2. 用户支付成功后跳转到成功页
3. 通过 webhook 监听 checkout.session.completed 事件
4. webhook 需要签名验证

Skill 执行流程:

1. 加载 Stripe Skill，识别为 Checkout 集成场景
2. 生成 stripe SDK 初始化代码（TypeScript，最新 API 版本）
3. 编写 POST /api/create-checkout-session 路由
4. 编写 webhook handler，含 stripe.webhooks.constructEvent() 签名验证
5. 提示测试方式：stripe listen --forward-to localhost:3000/api/webhook

场景 2: 订阅管理——SaaS 计费

提示词:
为我的 SaaS 产品实现订阅系统：
- 3 个套餐：Free, Pro ($29/月), Enterprise ($99/月)
- 支持试用期 14 天
- 用户可升级/降级，按比例计费
- 使用 Customer Portal 让用户自助管理

关键技术点:

• Stripe Billing 的 Subscription 对象跟踪每个客户的订阅状态
• 升级/降级自动按比例计费（proration_behavior: 'always_invoice'）
• Customer Portal 是零代码的自助管理界面，配置后生成链接即可
• 关键 webhook 事件: customer.subscription.updated, invoice.payment_failed, invoice.payment_succeeded

场景 3: CI 集成——Stripe CLI 本地测试

# 启动 Stripe webhook 转发（本地测试）
stripe listen --forward-to localhost:3000/api/webhook

# 触发测试事件
stripe trigger checkout.session.completed
stripe trigger invoice.payment_succeeded

# 查看 webhook 日志
stripe logs tail

# .github/workflows/stripe-test.yml
name: Stripe Integration Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Run Stripe tests (test mode)
        env:
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_TEST_KEY }}
          STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_WEBHOOK_SECRET }}
        run: npm test

场景 4: 与其他 Skill 链式调用

1. 用 brainstorming 设计支付架构
2. 用 stripe-payments 实现 Checkout + Webhook + Subscription
3. 用 playwright 编写支付流程 E2E 测试（使用 Stripe 测试卡号）
4. 用 verification-before-completion 验证 webhook 链路完整
5. 用 doc-coauthoring 沉淀支付系统运维文档

场景 5: 定制化——Connect 平台支付

提示词:
stripe-payments Skill，我需要实现 Connect 平台支付：
- 商家入驻（Express Account）
- 用户付款时自动分账（Application Fee）
- 商家提现到银行账户（Payouts）
- 类型: 市场平台（如 Uber、Airbnb 模式）
- 给出完整的 Connect 集成代码

四、内部 SKILL.md 工作流揭秘

Stripe Skills 是面向 AI Coding Agent 的参考 Skill。其核心策略是让 LLM 生成符合 Stripe 最新 API 版本的代码。

核心设计原则

Stripe Skills 工作流:
1. 识别场景: Checkout? Subscription? Connect? Tax?
2. 检索最新 API 版本: 从 docs.stripe.com 获取当前 API 签名
3. 遵循 Stripe 最佳实践:
   - 始终验证 webhook 签名（防止伪造事件）
   - 使用 idempotency key 防止重复扣款
   - 在 webhook handler 中先返回 2xx，再处理业务逻辑
   - 使用 test mode 充分测试
4. 生成代码: TypeScript SDK + 最新 API 版本
5. 给出测试指令: stripe listen / stripe trigger

Webhook 签名验证（关键安全步骤）

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get('stripe-signature')!;

  let event: Stripe.Event;
  try {
    // 签名验证——防止伪造的 webhook 请求
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
  } catch (err) {
    return new Response(`Webhook Error: ${(err as Error).message}`, { status: 400 });
  }

  // 先返回 2xx，再处理业务逻辑（Stripe 要求快速响应）
  // 业务逻辑处理...
  switch (event.type) {
    case 'checkout.session.completed':
      const session = event.data.object;
      // 处理支付成功逻辑
      break;
    case 'customer.subscription.updated':
      const subscription = event.data.object;
      // 处理订阅变更
      break;
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

五、反合理化（8 大常见偷懒）

六、基于官方文档的典型使用场景

以下场景基于 Stripe 官方文档和公开资料整理。

场景: SaaS 订阅计费

• 需求: 实现多档订阅、试用期、升级/降级
• 核心对象: Product → Price → Subscription
• 关键点:
  • Subscription 状态机从 incomplete → active → past_due → canceled
  • invoice.payment_failed webhook 触发催款（dunning）或暂停服务
  • Customer Portal 零代码让用户自助升级/降级/取消

场景: 平台支付（Connect）

• 需求: 类似 Uber 的平台，用户付款给平台，平台分账给服务提供者
• 核心对象: Connect Account → PaymentIntent + application_fee_amount
• 关键点:
  • 三种收费模式：目的地收费（Destination）、直接收费（Direct）、独立收费（Separate）
  • Transfer 对象处理分账和提现
  • 平台需处理 Connect Account 入驻（Onboarding）流程

场景: 跨境税务合规

• 需求: 向全球客户销售，自动计算并申报各地税费
• 核心对象: Tax.Calculation, Tax.Transaction
• 关键点:
  • Stripe Tax 自动根据客户位置确定税率
  • 与 PaymentIntents 和 Checkout 原生集成
  • 2025 年起支持 PaymentIntents 自动提交税务交易（Tax Association）

场景: Webhook 事件驱动的订单系统

• 需求: 支付成功后自动发货、发邮件、更新数据库
• 核心事件: checkout.session.completed, payment_intent.succeeded
• 关键点:
  • 最多可创建 16 个 webhook endpoint
  • 支持发送到 Amazon EventBridge 或 Azure Event Grid
  • 本地测试使用 stripe listen --forward-to

七、性能 & 限制

八、与其他 Skill 的协同矩阵

九、安装与配置

基础安装

# 方式 1: npx skills CLI
npx skills add stripe/skills --skill stripe-payments

# 方式 2: 手动克隆
git clone https://github.com/stripe/skills
cp -r skills/stripe-payments ~/.claude/skills/

# 方式 3: 本地软链
ln -s "$PWD/stripe-payments" ~/.claude/skills/stripe-payments

Stripe CLI（本地测试必备）

# macOS
brew install stripe/stripe-cli/stripe

# Windows (Scoop)
scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
scoop install stripe

# 登录并开始测试
stripe login
stripe listen --forward-to localhost:3000/api/webhook

在 CLAUDE.md 中启用

# CLAUDE.md
skills:
  - stripe-payments

auto_invoke:
  - when: "支付|Stripe|订阅|Checkout|webhook|Connect"
    skill: stripe-payments

十、5 大 Q&A

Q: Stripe Skill 和直接看 Stripe 文档有什么区别？ A: Stripe Skill 封装了支付安全最佳实践——如 webhook 签名验证、idempotency key、状态机处理等。LLM 原生回答可能忽略这些关键安全点。Skill 确保生成的代码始终包含这些防护。

Q: 能离线用吗？ A: Stripe API 调用和 Stripe CLI 都需要联网。但 Skill 本身可离线加载，只在需要 Stripe 集成时触发。

Q: 支持哪些编程语言？ A: Stripe 官方 SDK 支持 Node.js、Python、Ruby、PHP、Java、Go、.NET。Skill 默认生成 TypeScript 代码。

Q: 测试的时候会真的扣钱吗？ A: 不会。使用 test mode API key（sk_test_...）时，所有操作都在沙盒中运行。Stripe 还提供测试卡号（如 4242 4242 4242 4242）用于模拟各种支付场景。

Q: webhook 签名验证有多重要？ A: 非常重要——没有签名验证，攻击者可以伪造 webhook 事件发送到你的端点，导致虚假订单、非法激活订阅等安全问题。这是 Stripe 官方文档再三强调的安全要求。

十一、参考资料

1. Stripe 官方文档 —— 完整 API 参考、指南、最佳实践
2. Stripe API 参考 —— REST API 对象详解
3. Stripe Payments 文档 —— 支付集成入口
4. Stripe PaymentIntents API —— PaymentIntents 完整 API
5. Stripe Billing / Subscriptions —— 订阅计费文档
6. Stripe Connect 文档 —— 平台支付文档
7. Stripe Tax 文档 —— 自动税务文档
8. Stripe Webhooks 文档 —— Webhook 配置与签名验证
9. Stripe CLI 文档 —— 本地测试工具
10. stripe/skills GitHub —— Stripe 官方 Agent Skills 仓库
11. Stripe Skills 第三方概述 —— Stripe Skills 功能介绍
12. Stripe 开发环境搭建指南 —— 快速入门
13. Awesome Agent Skills —— Agent Skills 精选列表
14. Agent Skills 开放标准 —— Agent Skills 规范
15. Anthropic Skills 文档 —— Claude Code Skills 官方文档

十二、总结

核心价值:

• PaymentIntents——状态机模式，完整控制支付生命周期
• Checkout——预构建托管页面，快速上线
• Subscriptions——SaaS 订阅、试用期、按比例计费、Customer Portal
• Connect——平台支付、分账、商家入驻
• Tax——自动税务计算与申报
• Webhooks——事件驱动架构 + HMAC 签名验证确保安全

适用人群:

• 后端开发 / 全栈工程师 / SaaS 创业者 / 支付系统开发者

投入产出比: ⭐⭐⭐⭐ —— 对于需要集成支付的团队强烈推荐。Stripe 本身是支付基础设施领导者，其 Agent Skill 帮助 LLM 生成符合最新 API 版本和安全最佳实践的代码。

最后: 本文基于 Stripe 官方文档和公开资料整理。Stripe Skills 专注于让 AI 编程助手生成正确的 Stripe 集成代码——包含签名验证、幂等键、状态机处理等关键安全实践，避免因 LLM 训练数据过时而产生的集成缺陷。

基于官方文档和公开资料整理，包含 15 条可验证的参考链接。