技能介绍

支付集成的三类常见坑

把支付接进业务系统，真正的成本不在调通一个接口，而在三处容易被忽略的细节：

支付意图与认证：PaymentIntent 的状态机（requires_payment_method、requires_action 等）需要在前端确认与后端落库之间保持一致，SCA 合规要求 3D Secure 不能绕过。
异步事件：Webhook 会重复投递，签名不对就会被伪造事件；没有幂等处理就会出现重复发货或重复扣款。
生命周期：订阅不是创建完就结束，试用期、升降级、催收（Dunning）、取消限制都要有明确的数据模型支撑。

这个技能做了什么

它把 Stripe 的官方优选实践整理成一套可执行的工作流，按六个步骤推进：

规划：确定支付模式（一次性 / 订阅 / 分账 / 混合）、目标市场、集成方式（Payment Elements / Checkout Session / 原生 SDK），以及 PCI DSS 的合规范围。
支付流程：服务端创建 PaymentIntent，设置金额、货币与 metadata；前端用 Stripe.js 收集卡信息，卡号绝不经过自有服务器。
订阅管理：产品与价格定义、按比例计算的升降级、续费失败重试、Customer Portal 自助门户。
Webhook 处理：签名验证、基于事件 ID 的幂等去重、事件路由与失败重试。
退款与争议：全额/部分退款、争议证据提交、Radar 防欺诈规则配置。
国内适配：把 Stripe 替换为微信支付（JSAPI/Native/APP）、支付宝（电脑网站/手机网站/APP）或银联全渠道，通过统一抽象层保持上层业务代码不变。

同时内置一套边界约束，避免脏数据进入交易链路：低于或高于阈值的订单直接拒绝，重复订单返回错误，已完成订单不可取消，试用期或已激活的订阅不可取消，已完成订单不可退款，只处理白名单内的 Webhook 事件类型。错误处理覆盖 API 认证失败、接口限流、响应超时、权限不足等常见情况，并给出原因与恢复策略。

适用边界

不覆盖数字货币 / 区块链支付、P2P 转账、线下 POS 收款，也不对接银行核心清算系统。
跨境资金合规咨询需要专业法律或财务顾问，技能只负责支付网关层面的实现。
风控只基于支付平台自身规则（如 Radar），不做独立的信用评分建模。
属于 MD+EXEC 类别，环境需要 Node.js 18+ 或 Python 3.10+ 来运行 SDK 与测试；API Key 必须放在环境变量或密钥管理服务中，不能硬编码进源码。