Integrate Stripe

First: detect the existing integration

• 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.

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.

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.

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.

Verification and output