Stripe

核心用法

Stripe Skill 是 Maton 平台提供的官方支付网关代理，允许用户通过统一的 API 密钥访问 Stripe 的全套 REST API。核心工作流程包括：

1. 认证流程：获取 Maton API Key → 创建 Stripe 连接 → 完成 OAuth 授权 → 通过 gateway.maton.ai/stripe 代理访问原生 API
2. 连接管理：支持多账户连接，可通过 Maton-Connection 头部指定特定连接，默认使用最早创建的活跃连接
3. 完整 API 覆盖：涵盖 Customers、Products、Prices、Subscriptions、Invoices、Charges、Payment Intents、Balance、Events 等 Stripe 核心资源

显著优点

• 托管 OAuth：无需自行处理 Stripe 复杂的 OAuth 流程，Maton 自动管理令牌刷新
• 统一入口：单一 Maton API Key 访问多个 Stripe 账户，简化密钥管理
• 原生兼容：完整保留 Stripe API 语义，支持 expand[]、分页、form-urlencoded 等原生特性
• 多语言示例：提供 Python、JavaScript、Bash 等即开即用的代码模板

潜在局限

• 网关依赖：所有请求需经过 Maton 中转，存在单点故障和额外延迟
• 速率限制：每账户 10 req/sec 的限制可能无法满足高并发场景
• 数据隐私：敏感的支付数据流经第三方网关，需评估合规风险
• 功能滞后：新 Stripe API 特性可能无法及时同步到网关

适合人群

• SaaS 创业者需快速集成订阅计费系统
• 开发者希望避免直接管理 Stripe OAuth 认证
• 多 Stripe 账户企业需集中化管理方案
• 原型验证阶段需低代码接入支付能力

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 密钥泄露 | MATON_API_KEY 泄露可导致账户被滥用 | 使用环境变量，定期轮换，避免硬编码 |

| 连接状态异常 | OAuth 令牌过期或 revoked 导致 400 错误 | 监控连接状态，建立自动重连机制 |

| 金额单位混淆 | Stripe 使用「分」为单位，易误操作 | 封装金额转换层，添加前置校验 |

| 数据残留 | 删除连接后网关可能保留日志 | 查阅 Maton 数据保留政策，必要时申请清除 |

核心用法

Stripe Skill 是 Maton 提供的托管式 Stripe API 代理服务，通过统一的网关接口 (gateway.maton.ai/stripe) 实现对 Stripe 原生 API 的完整封装。用户仅需持有 Maton API Key，即可调用客户管理、产品定价、订阅生命周期、发票开具、支付意图等 Stripe 核心功能，无需直接处理 Stripe 密钥的存储与轮换。

连接采用 OAuth 托管模式：用户在 ctrl.maton.ai 创建连接后，通过浏览器完成 Stripe 授权，Maton 代为保管访问令牌。多连接场景下可通过 Maton-Connection 头部指定目标账户。API 路径与 Stripe 官方文档保持 1:1 映射，支持 expand[] 参数展开关联对象，金额单位为美分，ID 前缀遵循 Stripe 规范（cus_、sub_、prod_ 等）。

显著优点

• 密钥托管安全：Stripe 访问令牌由 Maton 加密存储，本地仅需管理单一 Maton API Key，降低密钥泄露风险与运维复杂度。
• 多租户支持：通过连接 ID 切换不同 Stripe 账户，适合代运营、SaaS 多商户等场景。
• 协议兼容：完整保留 Stripe API 语义，支持 x-www-form-urlencoded 提交、分页游标、幂等性请求等原生特性，迁移成本低。
• 生态整合：与 Maton 其他技能（如 api-gateway）形成统一接口层，便于构建跨平台财务自动化流程。

潜在缺点与局限性

• 网络依赖：所有流量经 Maton 网关中转，若网关服务不可用将导致支付链路中断，存在单点依赖风险。
• 速率限制：默认 10 req/sec 的账户级限流，高并发场景需额外申请配额或实施客户端缓存。
• 功能时滞：Stripe 新 API 或 Beta 功能需等待 Maton 网关同步更新，可能错过官方最新特性。
• 调试透明度：错误堆栈经网关层封装，复杂问题定位需协调 Maton 与 Stripe 双方日志。

适合人群

• 快速验证 MVP 的初创团队，希望零配置接入收款系统
• 已使用 Maton 生态的开发者，追求技术栈统一
• 需管理多个 Stripe 账户的 SaaS 平台或代运营机构
• 对 PCI DSS 合规有顾虑、希望减少敏感凭证本地接触面的企业

常规风险

1. 令牌生命周期：OAuth 连接可能因 Stripe 侧刷新策略或用户撤销授权而失效，需实现连接状态监控与异常重连机制。
2. 金额精度：Stripe 以整数美分存储金额，浮点运算易引入精度误差，建议全程使用整数运算或货币专用库。
3. 幂等性控制：重复提交可能产生重复资源（如客户、发票），生产环境务必使用 Idempotency-Key 头部。
4. Webhook 缺失：当前 Skill 聚焦主动 API 调用，若需实时事件响应（支付成功、订阅到期），需额外配置 Stripe 原生 Webhook 或等待 Maton 事件推送能力。