omnipay轻量可控，payum自带状态机但学习成本高，stripe官方sdk最灵活却易踩坑；应通过symfony服务容器管理网关实例，webhook必须用signing secret校验签名，paymentintent需分清confirm与capture时机，customer和paymentmethod id须持久化存储。
Omnipay 是更轻、更可控的选择，Payum 则自带状态机和存储抽象，但学习成本高；直接用 Stripe 官方 SDK（如 stripe-php）最灵活，也最容易踩坑——比如 PaymentIntent 状态未校验、webhook 签名验证漏掉、测试密钥混入生产环境。
为什么别直接在 Controller 里 new Omnipay::create('Stripe')
每次调用都新建网关实例，会导致连接复用失效、配置硬编码、无法统一处理重试或日志。Symfony 的依赖注入容器本就是为这事设计的。
正确做法是把网关注册为服务：
- 在
config/services.yaml中定义服务，传入stripe_secret_key和test_mode参数 - 用工厂类封装
Omnipay::create('Stripe')+setApiKey()+setTestMode() - 控制器中只接收
PaymentService类型依赖，不碰Omnipay全局函数
否则你很快会发现：测试环境能付，生产环境报 AuthenticationError，因为 env('STRIPE_SECRET_KEY') 没加载进服务定义里。
Webhook 处理必须验证签名，不能只靠 route path
Stripe 发来的 webhook 请求，URL 可被伪造，仅靠匹配 /stripe/webhook 路由完全不安全。官方要求必须用 Stripe\Webhook::constructEvent() 校验 Stripe-Signature header。
常见疏漏点：
- 没从原始 request body 读取数据（用了
$request->getContent()但中间件已解析过 JSON，body 变空） - 用错密钥：验证用的是
webhook signing secret，不是secret_key，两者在 Stripe 后台位置不同 - 没设置合理 tolerance（默认 5 分钟），服务器时间偏差大时校验失败，返回 400 导致 Stripe 重试堆积
示例关键行：$event = \Stripe\Webhook::constructEvent($payload, $sigHeader, $webhookSecret, 300);
PaymentIntent 的 confirm vs capture 时机要分清
用户填卡后前端调 stripe.confirmCardPayment()，后端只需创建 PaymentIntent 并返回 client_secret；真正扣款发生在前端 confirm 成功之后，后端无需再调 capture ——除非你用了 manual confirmation 模式。
容易混淆的场景：
- 误在后端重复调
$intent->confirm()，触发InvalidRequestError: This PaymentIntent could not be confirmed because it has already been confirmed - 对 3D Secure 支付，前端 confirm 返回
requires_action，后端却没监听payment_intent.requires_actionwebhook 去触发下一步挑战流程 - 退款时直接调
$intent->refund()，但没检查 intent 状态是否为succeeded，导致InvalidRequestError: You cannot refund this PaymentIntent because it is not in succeeded state
Symfony 中的 Customer 和 PaymentMethod 绑定要持久化
首次支付后，Stripe 会返回 customer ID 和 payment_method ID。如果只是临时存 session 或没写入 Doctrine 实体，下次订阅或重复扣款就找不到凭据。
必须做的事：
- 在
payment_intent.succeededwebhook 中，提取data.object.customer和data.object.payment_method - 将这两个 ID 存到你自己的
User或CustomerProfile实体中，字段类型用string，别用整数（Stripe ID 是字母数字混合） - 后续创建 Subscription 时，直接传
customerID 和default_payment_method，别再走卡号流程
否则你会遇到：用户第二次下单报错 No such customer: cus_XXX，因为上次的 customer ID 没保存。
最常被跳过的一步是 webhook 签名验证的完整链路测试——本地用 stripe-cli 模拟事件时，header 里的 signature 和 payload 必须严格匹配，少一个换行或空格都会失败。别信“先跑通再说”，这个环节一旦上线就只能靠日志盲猜。
