Implement and verify Stripe checkout, subscriptions, webhooks and refunds with explicit server-side authorization and retry boundaries.

Stripe Integration Implement and verify Stripe checkout, subscriptions, webhooks and refunds with explicit server side authorization and retry boundaries. Do not use this skill when The task is unrelated to stripe integration You need a different domain or tool outside this scope Instructions Clarify goals, constraints, and required inputs. Apply relevant best practices and validate outcomes. Provide actionable steps and verification. Inspect the installed Stripe SDK and pinned API/webhook version. This single file skill has no bundled playbook or production wrapper. Use this skill when Implementing payment processing in web/mobile applications Setting up subscription billing systems Handling one time payments and recurring charges Processing refunds and disputes Managing customer payment methods Implementing SCA (Strong Customer Authentication) for European payments Building marketplace payment flows with Stripe Connect Core Concepts 1. Payment Flows Checkout Session (Hosted) Stripe hosted payment page Reduced direct card data handling Fastest implementation Supports one time and recurring payments Payment Intents (Custom UI) Full control over payment UI Uses Stripe.js/Elements to avoid handling raw card data directly More complex implementation Better customization options Setup Intents (Save Payment Methods) Collect payment method without charging Used for subscriptions and future payments Requires customer confirmation 2. Webhooks Critical Events: payment intent.succeeded : Payment completed payment intent.payment failed : Payment failed customer.subscription.updated : Subscription changed customer.subscription.deleted : Subscription canceled charge.refunded : Refund processed invoice.payment succeeded : Subscription payment successful 3. Subscriptions Components: Product : What you're selling Price : How much and how often Subscription : Customer's recurring payment Invoice : Generated for each billing cycle 4. Customer Management Create and manage customer records Store multiple payment methods Track customer metadata Manage billing details Inputs and safety boundary Use an explicitly authorized Stripe test account/sandbox, server owned order and customer records, the installed SDK/API version and expected webhook types. Amounts, currencies, price/customer IDs and refund permissions must come from authenticated server policy, not arbitrary client parameters. Checkout/Elements can reduce card data exposure; they do not establish PCI compliance by themselves. The snippets are integration sketches. Test secret keys and webhook signing secrets are different; load them from the project secret mechanism and never print them. No live payment, refund, customer update or account configuration is authorized merely by reading this skill. Quick Start Payment Implementation Patterns Pattern 1: One Time Payment (Hosted Checkout) Pattern 2: Custom Payment Intent Flow Pattern 3: Subscription creation contract Use the flow documented for the account’s pinned API version. Do not assume latest invoice.payment intent exists in every version or that every invoice has an immediately confirmable payment. Resolve an authorized customer and allowed price, create the incomplete subscription with an idempotency key, and handle the returned confirmation state through that version’s API. Grant access from verified subscription/invoice state; test trials, zero amount invoices, delayed payments, cancellation and retries. See [Stripe subscription integration](https://docs.stripe.com/billing/subscriptions/build subscriptions). The customer portal below also requires ownership checks before accepting a customer ID. Pattern 4: Customer Portal Webhook Handling Secure Webhook Endpoint Signature, duplication and fulfillment Use stripe.Webhook.construct event with the raw bytes, full Stripe Signature header and correct endpoint secret. A bare HMAC over the body does not implement Stripe’s timestamped header format or replay tolerance. Keep the SDK’s timestamp check and verify both invalid and stale signatures. See [Stripe webhook documentation](https://docs.stripe.com/webhooks). A check then handle then mark sequence is not atomic and does not provide exactly once effects. Events can arrive out of order. The sample Flask handlers above are placeholders, not a complete durable processor; do not deploy them as fulfillment. Checkout success redirects are UI signals, not proof of payment. Consult [fulfillment guidance](https://docs.stripe.com/checkout/fulfillment) and [request idempotency](https://docs.stripe.com/api/idempotent requests). Customer Management Refund Handling Testing Worked verification case For an authorized test order, deliver the same valid payment event twice and concurrently, then a stale/invalid signature and an older out of order state event. Expected: one durable fulfillment, rejected invalid signatures, and no rollback of a newer state. Simulate a storage failure before inbox commit; it must not return a success that loses the event. Assert a zero amount refund is rejected rather than silently becoming a full refund. These are acceptance checks to implement in the project. This skill records no live transaction result and includes no hidden client wrapper or extra reference files. Best Practices 1. Always Use Webhooks : Don't rely solely on client side confirmation 2. Idempotency : Handle webhook events idempotently 3. Error Handling : Gracefully handle all Stripe errors 4. Test Mode : Thoroughly test with test keys before production 5. Metadata : Use metadata to link Stripe objects to your database 6. Monitoring : Track payment success rates and errors 7. PCI Compliance : Never handle raw card data on your server 8. SCA Ready : Implement 3D Secure for European payments Common Pitfalls Not Verifying Webhooks : Always verify webhook signatures Missing Webhook Events : Handle all relevant webhook events Hardcoded Amounts : Use cents/smallest currency unit No Retry Logic : Implement retries for API calls Ignoring Test Mode : Test all edge cases with test cards Limitations API versions, event payloads and SDK exception namespaces differ; verify the installed version rather than combining examples from different releases. Request idempotency keys must stay bound to the same logical operation and parameters; a new key on every retry can duplicate a charge or refund. Webhook deduplication alone does not prevent duplicate business effects from different events. Client success, test card success and a signature check do not establish full fulfillment, tax, compliance or subscription correctness. Customer, payment method, dispute and refund mutations require server side ownership/role checks and explicit task authorization.

stripe-integration