Back to Details

integrate-stripe

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Integrate Stripe

集成Stripe

Build Stripe integrations that match the existing application, business model, currency, countries, and ownership of payments. Always inspect the project before planning or writing Stripe code.
构建与现有应用程序、业务模式、货币、适用国家以及支付所有权相匹配的Stripe集成。在规划或编写Stripe代码前，务必先检查项目情况。

First: detect the existing integration

第一步：检测现有集成

Search the repository for Stripe packages, imports, configuration, environment-variable names, API clients, Checkout or PaymentIntent creation, webhook routes, database fields, migrations, tests, and frontend Stripe.js usage. Inspect package manifests and lockfiles to determine the installed Stripe SDK version. Identify any pinned account, request, or webhook API version without exposing secret values.
  • If Stripe already exists, trace the complete payment flow and preserve compatible architecture. Find incomplete, outdated, insecure, or broken behavior and make the smallest safe fixes. Do not create a second Stripe client, webhook endpoint, Customer model, or payment flow without a clear reason.
  • If Stripe does not exist, design the integration from scratch using the project's existing language, framework, database, validation, error handling, logging, and testing patterns.
  • If the SDK or API version is old, check the official changelog and migration guide first. Upgrade deliberately with tests; never change a Stripe version silently during unrelated work.
Because Stripe changes over time, verify API choices against current official Stripe documentation before writing code. Prefer the latest supported SDK and API version unless the project is intentionally pinned; plan and test upgrades instead of silently changing versions.
在代码仓库中搜索Stripe包、导入语句、配置、环境变量名称、API客户端、Checkout或PaymentIntent创建逻辑、webhook路由、数据库字段、迁移脚本、测试以及前端Stripe.js的使用情况。检查包清单和锁定文件以确定已安装的Stripe SDK版本。识别任何固定的账户、请求或webhook API版本，但不要暴露密钥值。
  • 如果已存在Stripe集成，追踪完整的支付流程并保留兼容的架构。找出不完整、过时、不安全或存在故障的行为，并进行最小化的安全修复。除非有明确理由，否则不要创建第二个Stripe客户端、webhook端点、Customer模型或支付流程。
  • 如果不存在Stripe集成，则使用项目现有的语言、框架、数据库、验证、错误处理、日志记录和测试模式从头设计集成。
  • 如果SDK或API版本较旧，请先查看官方变更日志和迁移指南。通过测试谨慎进行升级；切勿在无关工作中静默更改Stripe版本。
由于Stripe会不断更新，在编写代码前请对照当前官方Stripe文档验证API选择。除非项目有意固定版本，否则优先使用最新的受支持SDK和API版本；规划并测试升级，而非静默更改版本。

Workflow

工作流程

  1. Report whether an existing Stripe integration was found and list its relevant SDK/API versions and implemented flows.
  2. Define whether the product needs one-time purchases, subscriptions, usage billing, invoices, saved methods, marketplace payments, or a combination.
  3. Establish who is merchant of record, who owns the customer relationship, where funds settle, who handles disputes, and whether a platform fee applies.
  4. Choose the simplest suitable surface: Payment Links for no-code sales, Checkout Sessions for most integrations, Checkout Sessions with Payment Element for embedded UI, or PaymentIntents only for bespoke payment-state control.
  5. Make the server authoritative for products, Price IDs, amounts, currency, discounts, tax behavior, identity, entitlements, destinations, and fees. Never trust these values from the client.
  6. Persist an internal pending order or subscription before redirecting to payment. Link Stripe objects with non-sensitive metadata.
  7. Treat verified webhooks as the source of truth. Make fulfillment and state changes idempotent and safe for retries or out-of-order events.
  8. Implement failure, cancellation, retry, refund, dispute, and reconciliation paths—not only success.
  9. Test in a sandbox, exercise authentication and failure cases, replay webhooks, and complete a go-live review.
  1. 报告是否发现现有Stripe集成，并列出其相关的SDK/API版本以及已实现的流程。
  2. 明确产品是否需要一次性购买、订阅、用量计费、发票、已保存支付方式、交易市场支付，或是多种组合。
  3. 确定谁是记录商户、谁拥有客户关系、资金结算地点、谁处理争议，以及是否适用平台费用。
  4. 选择最合适的简化界面：无需代码的销售使用Payment Links，大多数集成使用Checkout Sessions，嵌入UI使用带Payment Element的Checkout Sessions，或是仅使用PaymentIntents实现定制化支付状态控制。
  5. 让服务器作为产品、Price IDs、金额、货币、折扣、税务行为、身份、权益、收款方和费用的权威来源。绝不要信任客户端传来的这些值。
  6. 在重定向至支付页面之前，持久化内部待处理订单或订阅信息。使用非敏感元数据关联Stripe对象。
  7. 将已验证的webhooks视为事实来源。确保履约和状态变更具有幂等性，可安全重试或处理乱序事件。
  8. 实现失败、取消、重试、退款、争议和对账流程——不要只处理成功场景。
  9. 在沙箱中进行测试，验证身份验证和故障场景，重放webhooks，并完成上线前审查。

Non-negotiable rules

不可协商的规则

  • Never expose secret, restricted, or webhook keys in source, clients, logs, errors, or examples. Prefer least-privilege restricted keys per service.
  • Never handle raw card numbers server-side unless the business has completed the required PCI process. Use Checkout or Stripe.js Elements.
  • Never fulfill from a success redirect or client-reported status.
  • Verify webhook signatures against the unmodified raw request body.
  • Deduplicate event IDs with a unique constraint and make mutations transactional where possible.
  • Use stable idempotency keys for retried financial POST operations.
  • Do not use legacy Charges, Sources, Tokens, Plans, or Card Element for new work.
  • Omit 
    payment_method_types
    for dynamic payment methods except where current official Terminal guidance explicitly requires it.
  • Never perform live charges, refunds, transfers, or account changes without explicit approval.
  • 切勿在源代码、客户端、日志、错误信息或示例中暴露密钥、受限密钥或webhook密钥。优先为每个服务使用权限最小的受限密钥。
  • 除非企业已完成所需的PCI流程，否则切勿在服务器端处理原始卡号。使用Checkout或Stripe.js Elements。
  • 切勿根据成功重定向或客户端报告的状态进行履约。
  • 针对未修改的原始请求体验证webhook签名。
  • 使用唯一约束对事件ID进行去重，并尽可能使变更操作具有事务性。
  • 对重试的金融POST操作使用稳定的幂等键。
  • 新开发工作中不要使用旧版Charges、Sources、Tokens、Plans或Card Element。
  • 除当前官方Terminal指南明确要求的情况外，为动态支付方式省略
    payment_method_types
    。
  • 未经明确批准，切勿执行实时扣费、退款、转账或账户变更操作。

Reference routing

参考路由

  • Read references/payments.md for Checkout, Payment Element, PaymentIntents, SetupIntents, customers, refunds, disputes, SCA, and testing.
  • Read references/billing.md for subscriptions, invoices, trials, proration, customer portal, usage billing, and entitlements.
  • Read references/webhooks.md before implementing or reviewing a webhook endpoint.
  • Read references/connect.md for platforms, marketplaces, connected accounts, onboarding, fees, charge patterns, and liability.
  • Read references/security-and-production.md for keys, PCI scope, financial integrity, observability, reconciliation, migrations, and go-live.
  • Read references/implementation-patterns.md for adaptable implementation examples.
  • Read references/source.md for the upstream skill credited as the foundation of this expanded skill.
  • 阅读references/payments.md了解Checkout、Payment Element、PaymentIntents、SetupIntents、客户、退款、争议、SCA和测试相关内容。
  • 阅读references/billing.md了解订阅、发票、试用、prorating、客户门户、用量计费和权益相关内容。
  • 在实现或审查webhook端点前，阅读references/webhooks.md。
  • 阅读references/connect.md了解平台、交易市场、关联账户、入驻流程、费用、收费模式和责任相关内容。
  • 阅读references/security-and-production.md了解密钥、PCI范围、财务完整性、可观测性、对账、迁移和上线相关内容。
  • 阅读references/implementation-patterns.md获取可适配的实现示例。
  • 阅读references/source.md了解作为本扩展技能基础的上游技能。

Verification and output

验证与输出

Run relevant formatting, linting, type checking, and tests. State whether Stripe was repaired or added from scratch, which versions were inspected or changed, which Stripe objects and webhook events were chosen, how internal state maps to Stripe, how duplicates are prevented, and which Dashboard setup remains. Separate sandbox validation from live verification.
运行相关的格式化、代码检查、类型检查和测试。说明是修复了现有Stripe集成还是从头添加了集成，检查或更改了哪些版本，选择了哪些Stripe对象和webhook事件，内部状态如何映射到Stripe，如何防止重复，以及仍需在控制台中完成哪些设置。区分沙箱验证和实时环境验证。