stripe-integration

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<br>
# 或<br>
npm install stripe  # Node.js<br>
```<br>
3. 测试环境的 API Key(从 Stripe Dashboard → Developers → API keys 获取,记得切到 Test mode)。<br>
4. 安装 Stripe CLI(用于本地测试 Webhook):<br>
```bash<br>
# macOS<br>
brew install stripe/stripe-cli/stripe<br>
# Windows<br>
scoop install stripe<br>
```<br>
5. Clone 仓库:<br>
```bash<br>
git clone https://github.com/stripe/agent-skills.git<br>
```<br>
6. 软链 Skill:<br>
```bash<br>
ln -s agent-skills/skills/stripe-integration ~/.claude/skills/stripe-integration<br>
```<br>
## 3 步快速上手<br>
### 第 1 步:环境配置<br>
```bash<br>
# .env (本地开发,绝对不要 commit!)<br>
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx<br>
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx<br>
```<br>
### 第 2 步:验证安装<br>
向 AI 发送请求:
> "用 stripe-integration 给我一段创建 PaymentIntent 的 Python 代码,要求带幂等键。"

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

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

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

```python

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 挂了还是自己的代码。

参考链接

• stripe-integration Skill 仓库

• Stripe 官方文档

• Stripe Webhook 签名验证

• Stripe 测试卡号

• Stripe CLI

• Stripe Status