stripe-integration 快速入门

Stripe 官方出的”支付集成安全清单”Skill,帮你在写支付代码时避开所有已知坑。

这是什么?解决什么问题?

stripe-integration 是 Stripe 官方在 stripe/agent-skills 仓库下提供的一个 Skill,和 stripe-payments 是配对关系:stripe-payments 偏”业务流”(Webhook / 退款 / 对账),stripe-integration 偏”代码级安全”(签名验证 / 幂等性 / 测试模式 / 异常处理)。

它解决的问题,是 Stripe 集成代码里最容易出问题的几个”安全细节”:

• Webhook 签名没验证:任何人都可以伪造回调,直接薅羊毛。
• 没有幂等键:重复扣款,用户炸了。
• API Key 写死在代码里:一泄露资金直接暴露。
• 生产环境用测试 Key:钱收了但进 Stripe 沙盒。
• 没处理 3D Secure:欧洲用户支付失败率高。
• 测试覆盖不全:很多边界场景没在测试模式验证过。

这个 Skill 沉淀的”集成清单”包括:

• 签名验证:Webhook 必须用 stripe.Webhook.construct_event 验签。
• 幂等性:所有创建/扣款操作必须带 idempotency_key。
• 环境隔离:开发用 sk_test_,生产用 sk_live_,通过环境变量管理。
• 测试模式:用 4242 4242 4242 4242 等测试卡号,触发各种失败场景。
• 异常处理:捕获 CardError、RateLimitError、APIConnectionError 等。
• PCI 合规:不接触原始卡号,所有敏感数据交给 Stripe 处理。

它适合的场景:第一次集成 Stripe、给现有支付代码做安全 review、写支付模块的单元测试、Code Review 时检查支付代码质量。

准备工作

1. Stripe 账号(测试模式即可,https://dashboard.stripe.com/register)。
2. Stripe SDK:

   pip install stripe  # Python
   # 或
   npm install stripe  # Node.js
   

3. 测试环境的 API Key(从 Stripe Dashboard → Developers → API keys 获取,记得切到 Test mode)。
4. 安装 Stripe CLI(用于本地测试 Webhook):

   # macOS
   brew install stripe/stripe-cli/stripe
   # Windows
   scoop install stripe
   

5. Clone 仓库:

   git clone https://github.com/stripe/agent-skills.git
   

6. 软链 Skill:

   ln -s agent-skills/skills/stripe-integration ~/.claude/skills/stripe-integration
   

3 步快速上手

第 1 步:环境配置

# .env (本地开发,绝对不要 commit!)
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

第 2 步:验证安装

向 AI 发送请求:

“用 stripe-integration 给我一段创建 PaymentIntent 的 Python 代码,要求带幂等键。”

如果返回的代码里有 idempotency_key= 参数,异常处理用 stripe.error.CardError 捕获,说明 Skill 加载成功。

第 3 步:用 stripe-integration 跑第一个真实任务

任务 1:创建带幂等键的 PaymentIntent

import stripe
import os
import uuid

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

def create_payment_intent(amount_cents: int, customer_email: str):
    try:
        intent = stripe.PaymentIntent.create(
            amount=amount_cents,
            currency="usd",
            receipt_email=customer_email,
            # 幂等键:同一订单重试时不会重复创建 PaymentIntent
            idempotency_key=str(uuid.uuid4()),
            payment_method_types=["card"],
        )
        return intent
    except stripe.error.CardError as e:
        # 卡被拒
        return {"error": "card_declined", "message": e.user_message}
    except stripe.error.RateLimitError:
        # Stripe 限流
        return {"error": "rate_limited"}
    except stripe.error.APIConnectionError:
        # 网络问题
        return {"error": "network_error"}
    except stripe.error.StripeError as e:
        # 其他 Stripe 错误
        return {"error": "stripe_error", "message": str(e)}

Skill 会主动提醒 AI:

• 幂等键用 UUID,不要复用(否则第二次调用直接返回第一次的结果)。
• 异常要分门别类捕获,不要一个 except Exception 兜底。
• amount 是最小货币单位(美分),不是美元。

任务 2:Webhook 签名验证

from flask import Flask, request, abort
import stripe

app = Flask(__name__)
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]
endpoint_secret = os.environ["STRIPE_WEBHOOK_SECRET"]

@app.post("/webhook")
def webhook():
    payload = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, endpoint_secret
        )
    except ValueError:
        abort(400)  # payload 格式错
    except stripe.error.SignatureVerificationError:
        abort(400)  # 签名错(可能是伪造回调)

    if event["type"] == "payment_intent.succeeded":
        payment_intent = event["data"]["object"]
        # 业务处理
        fulfill_order(payment_intent["metadata"]["order_id"])

    return "", 200

任务 3:本地测试 Webhook

# 终端 1:起本地服务
flask run

# 终端 2:起 Stripe CLI 监听
stripe listen --forward-to localhost:5000/webhook

# 终端 3:触发测试事件
stripe trigger payment_intent.succeeded

常见踩坑

1. Webhook 没验签。直接 request.json() 读 event.data.object 是高危操作,任何人都可以伪造。
2. 没带幂等键。网络抖动 Stripe 自动重试,导致用户被扣两次款。
3. API Key 写死在代码里。git push 后被扫描机器人拿到,直接被攻击。
4. 测试模式用错卡号。用真实卡号在 sk_test_ 模式下测试,会被拒。要用 4242 4242 4242 4242。
5. 没处理 3D Secure。欧洲用户支付时强制要求 3DS,没配置好支付成功率掉 30%。
6. 没保存 charge.id。后续退款、对账都查不到,Skill 建议把 charge.id 存到本地订单表。

初级用法

用法 1:首次集成 Stripe。让 AI 按 Skill 帮你从环境配置到第一个 PaymentIntent 走通,包括签名验证。

用法 2:给老代码加幂等。把现有支付代码贴给 AI,让它按 Skill 加幂等键 + 异常分类处理。

用法 3:Webhook 单元测试。让 AI 按 Skill 帮你写 Webhook 签名验证的单元测试,模拟伪造请求和正常请求。

高级玩法

玩法 1:多 Payment Method 适配。让 AI 帮你接入 iDEAL(Klarna)(欧洲)、Alipay/WeChat Pay(中国)、SEPA Direct Debit(欧洲银行转账)。

玩法 2:订阅生命周期 webhook。监听 customer.subscription.created/updated/deleted,管理 SaaS 用户的订阅状态。

玩法 3:对账系统。每日拉取 BalanceTransaction 列表,和本地订单表 left join,差异项入”对账异常”工单。

小技巧

1. 测试卡号大全。4242 4242 4242 4242 成功;4000 0000 0000 9995 卡余额不足;4000 0000 0000 0341 触发 3DS;完整列表在 https://docs.stripe.com/testing。
2. 保存原始 API 响应。Stripe API 响应里很多字段后续会用,存 JSON 到数据库,避免再调 API。
3. 用 expand 字段预加载。stripe.PaymentIntent.retrieve(id, expand=["customer", "charge"]) 一次拿到完整对象,省 N+1 查询。
4. 金额用整数 cents。amount=1000 是 $10.00,不要用浮点数 amount=10.00(精度问题)。
5. 监控 Stripe Status。https://status.stripe.com/,集成事故时第一时间知道是 Stripe 挂了还是自己的代码。

常见问题 FAQ

Q1: 这个 Skill 跟 stripe-integration 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: stripe-integration 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 stripe-integration 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 stripe-integration,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/stripe/agent-skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• stripe-integration Skill 仓库:https://github.com/stripe/agent-skills
• Stripe 官方文档:https://docs.stripe.com/
• Stripe Webhook 签名验证:https://docs.stripe.com/webhooks/signatures
• Stripe 测试卡号:https://docs.stripe.com/testing
• Stripe CLI:https://docs.stripe.com/stripe-cli
• Stripe Status:https://status.stripe.com/

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。