software-payments

支付与账单工程

使用此技能来设计、实现和调试生产环境中的支付集成：结账流程、订阅生命周期处理、账单门户、权益门控、Webhook、区域定价和支付测试策略。

快速参考

需求	默认方案	例外情况	参考
标准 SaaS 订阅结账	Stripe Checkout 或 Payment Links	如果必须使用带品牌风格的自定义 UI，则使用 Payment Element 和 Express Checkout Element	references/stripe-patterns.md
商家记录方（托管税务／销售记录）	Paddle 或 LemonSqueezy	查看卖家所在地、产品税码、账户资格和支持的界面后，再通过其资格页面评估 Stripe Managed Payments	references/platform-comparison.md
高交易量或企业级多方式处理	Adyen	—	references/platform-comparison.md
英国或欧盟银行借记和本地支付方式	GoCardless、Mollie 或开放银行服务提供商	取决于代码库：现有资料中没有能根据具体情况区分这三者的来源；保留现有集成使用的方案即可	references/uk-eu-payments-guide.md
按使用量计量或代币计费	Stripe Billing Meters 或 Lago	—	references/subscription-lifecycle.md
复杂的合同、席位或收入确认计费	在处理器之上使用 Chargebee 或 Recurly	—	references/subscription-lifecycle.md
Webhook 可靠性	验证签名并进行幂等处理	—	references/webhook-reliability-patterns.md
权益和功能门控	注册表加 API 强制执行，再加 UI 付费墙	—	references/feature-gating-patterns.md
iOS 原生应用内购买	使用 StoreKit 2 和后端 JWS 验证	只有当跨平台权益同步确实值得投入时，才添加 RevenueCat	references/storekit2-native-patterns.md
结账和 Webhook 测试	Stripe CLI 加端到端自动化	—	references/testing-patterns.md
AI Agent 发起购买	限定范围、限次使用的支付凭证，加上卖家侧审批	高风险操作需要人工确认	references/agentic-commerce.md

何时使用此技能

在主要工作涉及以下内容时使用此技能：

• 选择支付处理商、名义商户层或计费技术栈
• 实施托管式或自定义结账
• 设计订阅生命周期和 webhook 处理
• 构建功能门控和账单门户流程
• 处理区域定价、对税务敏感的平台选择或本地支付方式
• 测试和运营结账或计费工作流

如果主要任务属于以下内容，请转到其他技能：

需求	改用
支付以外的一般后端实现	../software-backend/SKILL.md
不涉及计费的 API 契约设计	../dev-api-design/SKILL.md
定价策略和套餐设计	startup-business-models
结账转化优化	marketing-cro
应用安全审查	../software-security-appsec/SKILL.md
围绕应用商店计费实现原生应用	../software-mobile/SKILL.md
钱包、加密货币结算或链上资金转移	../software-crypto-web3/SKILL.md
Stripe 特定的产品/API 指导或账户工具	可用的 Stripe 维护技能/插件；通过 Stripe 的 Agent 指南 查找，然后遵循运行时的安装和权限政策

默认选项

• 对大多数 SaaS 和产品团队而言，默认支付处理商是 Stripe。
• 除非品牌化自定义 UI 是硬性要求，否则默认从托管式结账开始。
• 经验证的 webhook 会触发状态同步；请根据服务商的当前对象进行对账，因为消息可能重复送达或乱序送达。
• 延迟初始化服务商客户端；导入时缺少密钥不应导致构建失败。
• 除非有意限制可用支付方式，否则省略 payment_method_types。
• 确保每个 webhook 处理程序都经过签名验证且具备幂等性。
• 在三个位置实施功能门控：注册表、API 边界和 UI 付费墙。
• 将平台可用性、API 版本、预览功能和税务行为视为易变事项，并在给出最终建议前进行核实。

工作流

1. 明确资金流转、服务商、客户和账本边界，然后对业务模式分类：
   • 一次性购买
   • 订阅
   • 按使用量计费
   • 市场或多方流程（在选择资金流模型或设计支付前，先加载 references/marketplace-payouts.md）
   • 移动应用内购买（IAP）或 Web 与应用混合计费
2. 选择技术栈：
   • 支付处理商
   • 如有需要，选择名义商户层
   • 只有生命周期复杂度足以支撑时，才使用计费编排器
3. 选择结账界面：
   • 追求速度时使用 Checkout 或 Payment Links
   • 需要自定义 UX 时使用 Payment Element
4. 实施运营核心：
   • webhook 验证
   • 幂等处理
   • 账单门户或自助管理
   • 权益同步和功能门控
5. 对服务商余额或结算报告、账本条目和权益进行对账；为未匹配记录指定负责人。
6. 测试成功、拒绝、重复、超时、退款和重试路径；在将集成视为可投入生产之前，添加可观测性和事件处理机制。

有关不同情境的平台默认选项，请参阅上方的快速参考表；详细权衡请参阅 references/platform-comparison.md 和 references/uk-eu-payments-guide.md。移动订阅的默认方案：将 StoreKit 2 或 Play Billing 作为商店记录系统；仅当跨平台权益同步、实验或 Web 与商店协调确实有此需要时，才添加 RevenueCat。

已知陷阱

• 混合移动端计费却没有统一的权益注册表。如果 App Store、Play Billing 和网页订阅都能授予访问权限，应在上线前定义唯一的规范权益状态和冲突解决规则。
• 将结账成功后的重定向视为购买凭证。重定向仅用于改善用户体验；只有在验证 webhook 或商店服务器通知流程后，才能开通服务。
• 混淆移动端数字商品政策边界与网页 SaaS 计费假设。Apple 和 Google 对应用内数字商品的政策处理方式变化频繁，在提供最终实施建议前必须重新核实。
• 未根据 App Store storefront 判断，就在 iOS 上显示指向网页结账的链接或按钮。外部链接许可、权益和条款取决于 storefront 和应用类别。请根据 Storefront.current 分支处理，并在发布前重新阅读适用的指南和地区条款。参见 references/storekit2-native-patterns.md。
• 假设 RevenueCat 默认适用于所有移动订阅技术栈。它是一个协调层，并非必需，还会增加自身的运维负担。
• 用同一个 webhook 消费者处理互不相关的计费副作用，却没有幂等边界。权益、开票、CRM 同步和分析扇出需要各自独立的重试与重放行为。
• 等到结账流程构建完成后才决定税务、名义商户和发票开具方。这些选择会影响产品目录、法律实体风险、退款和支持流程。

常见反模式

• 使用违反适用 storefront 购买政策和外部链接政策的原生数字商品结账方式；在选择结账界面前核实这些政策。
• 在网页、移动端和计费系统中分别创建产品或价格目录，却没有同步约定。
• 将服务商对象 ID 作为唯一的权益键，而非使用稳定的内部订阅或账户标识。
• 上线计费门户前，未测试降级、取消、退款和宽限期政策。
• 任由定价页面、结账文案、权益规则和 CRM 生命周期各自演变。
• 将收入分析事件视为访问控制的业务事实来源。

Stripe 集成默认设置

如果选择 Stripe 作为处理商，请应用以上通用默认设置，以及以下 Stripe 专属默认设置：

• 谨慎存储内部用户和层级元数据，并在用于数据库操作前进行验证
• 对预先计划的计费变更使用订阅计划
• 保持计费门户启用，以便用户自助进行变更
• 产品打包方式经常变化时使用权益，但仍须在自有 API 中执行授权

API 版本说明、webhook 映射和迁移详情请参阅 references/stripe-patterns.md。

Agent 商务

当 AI Agent 代表用户购买，或卖家接受由 Agent 发起的订单时，只向 Agent 提供按单交易的凭证，并将其绑定到卖家、货币、最高金额和到期时间。通过代码强制执行支出限额；要求卖家根据最终总额批准或拒绝；确保每个步骤在 Agent 重试时都具有幂等性；对于周期性扣费或新商户等高风险操作，要求人工确认；并保留同意记录，作为争议证据。参见 references/agentic-commerce.md，其中包含 Stripe 共享支付令牌说明。

生产就绪检查清单

对账关卡。

定义一条与支付服务商无关的资金记录，涵盖预期金额、币种、费用、税款、结算、退款、争议和当前权益。按计划将 Webhook 以及支付服务商的余额或结算报告与该记录进行对账，并设置异常队列和负责人。成功的结账重定向或 Webhook 只是事件证据；两者都不能证明现金、会计状态和访问权限彼此一致。

• 每个处理程序都在处理前验证 Webhook 签名
• 所有 Webhook 处理程序都具备幂等性（可以安全地重放同一事件）
• 明确记录结账创建失败和 Webhook 失败
• 为乱序或失败事件定义死信或重试策略
• 将 Stripe CLI（或同类工具）接入本地和 CI 测试流程
• 测试覆盖成功、拒绝以及 3DS / 加强验证流程
• 编写针对结账返回 500、身份验证失败和策略拒绝的事件处理手册
• 在开始构建结账功能前敲定税务和登记商户决策
• 在三个位置强制执行功能门控：注册表、API 边界和 UI 付费墙

常见错误：

错误	后果
将客户端重定向视为购买证明	在 Webhook 验证前就开通权限，导致用户未付款即可访问
在代码中硬编码价格或套餐逻辑	目录信息不一致，且调价受部署限制
不必要地设置 payment_method_types	无意中限制可用的支付方式
Webhook 失败时不重试而是静默忽略	权益无声丢失或订阅未清理
认为 Apple/Google 的政策在各次发布之间保持不变	应用被商店拒绝或被迫重新设计

参见：references/testing-patterns.md、references/webhook-reliability-patterns.md、references/feature-gating-patterns.md、references/ops-runbook-checkout-errors.md

导航

核心

• references/stripe-patterns.md
• references/platform-comparison.md
• references/subscription-lifecycle.md
• references/feature-gating-patterns.md

区域与运营

• references/uk-eu-payments-guide.md
• references/regional-pricing-guide.md
• references/webhook-reliability-patterns.md
• references/ops-runbook-checkout-errors.md

移动端与应用内购买

• references/storekit2-native-patterns.md

Agent 商务

• references/agentic-commerce.md

市场平台付款

• references/marketplace-payouts.md

测试与迁移

• references/testing-patterns.md
• references/in-app-browser-checkout-contract.md
• assets/template-checkout-entrypoint-propagation-checklist.md
• data/sources.json

监管与卡组织规则陷阱

该领域的阈值、日期和立法状态经常变化。每次都应查阅原始来源；本节仅保留工程控制措施。

• 3DS 测试覆盖：CI 应测试挑战流程、无摩擦流程、非现场交易需要身份验证、身份验证后拒付以及不支持 3DS 的路径。编写测试时，请从 Stripe 测试文档（docs.stripe.com/testing）或 stripe:test-cards 获取卡号；不要凭记忆抄写。
• MIT 的 SCA 豁免：商户发起的扣款（续费、扣取已保存卡片的款项）需要 off_session: true，并且必须在用户在线设置时取得所需的同意／授权；在需要时还要进行身份验证。缺少标记可能导致续费意外被拒。使用已发布或草案中的规范功能前，请先查看 EMVCo 和服务提供商的支持情况。
• 欧盟 PSD3 / PSR：在将某项规定视为具有约束力之前，应通过合格的欧盟监管法律顾问核实其发布情况、生效日期和适用范围。现在应纳入架构设计考量的风险包括：开放银行 API 性能标准、修订后的 SCA 豁免、更严格的 APP 欺诈责任，以及单边跨境交易的适用范围。
• 欧盟即时支付法规：即时 SEPA 收款／付款和收款人验证义务将按欧元区及非欧元区成员国分阶段实施。在向客户承诺实施日期之前，应从法规原文或合格的欧盟监管法律顾问处确认日期。
• Visa VAMP：该比率会将欺诈报告（TC40）与争议（TC15）合并计算，因此一笔既有争议又被报告的交易可能被计算两次。主要的工程杠杆是排除路径：在争议前解决的争议（RDR／CDRN 类服务）以及通过有力证据 3.0 获胜的案件，不会计入该比率。商户和收单机构的阈值请以 Visa 当前的 VAMP 说明文件为准。
• Mastercard ECP：根据滚动周期内的拒付数量和比率划分等级，并逐步提高费用，还可能被列入 MATCH。向商户报价前，请以 Mastercard 当前规则手册为准，确认等级和费用表。若商户接近任一卡组织的阈值，应触发专家审核，而不是自行计算。
• PCI DSS v4.0.1：带有未来生效日期的 v4.0 要求现已成为基准要求，其中包括支付页面脚本控制措施（6.4.3、11.6.1）。本技能涵盖结账界面的范围缩减（SAQ A 与 SAQ D；参见 references/stripe-patterns.md）；完整的范围界定应交由安全／合规专家处理。
• Stripe Managed Payments（记录商户）：资格受企业所在地、数字产品、仅限直接集成（不支持 Connect）以及 Checkout Session 或 Payment Link 界面等条件限制。在确定 MoR 架构前，请查看 Stripe 的资格页面，确认卖家所在地、账户审核、产品税务代码和受支持的界面。
• 英国规则：英国 SCA（经修订的 PSRs 2017）、强制性 APP 欺诈赔付以及 FCA 延期付款信贷（BNPL）制度均不同于欧盟规则。规则状态和适用范围应交由合格的英国监管法律顾问确认；不要假设英国和欧盟的消费者责任规则相同。
• 附加费：欧盟和英国禁止对消费者银行卡交易收取附加费。任何涉及银行卡的费用转嫁功能上线前，都应核实当地规则。

经验反馈循环

如果以往的决策或陷阱与当前情况相关，请在 learnings.consolidated.md 存在时查阅；只有在需要查看历史记录或将其作为可用的备选资料时，才使用 learnings.md。否则跳过这两个文件。

应用经验后，如果你遇到了值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目。不要修改 SKILL.md 本身。