Integrate Stripe Payments and Subscriptions

This skill covers robust, PCI-compliant Stripe payment integration across checkout, subscriptions, webhooks, and refunds. It explains three payment-flow options: hosted Checkout Sessions (Stripe-hosted page, minimal PCI burden, fastest to implement, supports one-time and recurring), custom Payment Intents (full UI control via Stripe.js, more implementation work), and Setup Intents (collecting a payment method without charging, for future/subscription billing). It lists the critical webhook events to handle (payment_intent.succeeded, payment_intent.payment_failed, customer.subscription.updated/.deleted, charge.refunded, invoice.payment_succeeded) and the subscription object model (Product, Price, Subscription, Invoice). Working code patterns cover a one-time-payment hosted Checkout Session with metadata linking to an internal order/user ID, a custom Payment Intent flow paired with frontend stripe.confirmCardPayment, subscription creation with payment_behavior='default_incomplete' returning a client secret for 3D Secure confirmation, and a Customer Portal session for self-service subscription management. Webhook handling code verifies the Stripe-Signature header via stripe.Webhook.construct_event, dispatches on event type to handler functions, and demonstrates idempotent processing (checking whether an event ID was already processed before handling it, since Stripe retries failed webhooks). Customer management covers creating a Stripe Customer with a default payment method, attaching additional payment methods, and listing a customer's saved cards. Refund handling covers full or partial refunds with a reason code (duplicate/fraudulent/requested_by_customer) and updating a dispute with evidence fields. A testing section lists Stripe's standard test card numbers (success, declined, 3D Secure required, insufficient funds) and a full test-mode payment flow assertion. Best practices: always rely on webhooks rather than client-side confirmation alone, process webhooks idempotently, handle all Stripe errors gracefully, test thoroughly with test-mode keys before production, use metadata to link Stripe objects to your own database records, monitor payment success rates, never handle raw card data server-side, and implement SCA/3D Secure for European payments. Common pitfalls flagged: skipping webhook signature verification, missing relevant webhook event types, hardcoding amounts instead of using the smallest currency unit (cents), no retry logic for API calls, and skipping test-mode edge cases.

Use it when implementing payment processing in web/mobile apps, setting up subscription billing, handling one-time or recurring charges, processing refunds and disputes, managing customer payment methods, implementing SCA for European payments, or building Stripe Connect marketplace flows. It is not appropriate for unrelated tasks or domains outside Stripe payment integration.

Inputs: a Stripe secret/webhook API key and the specific payment flow needed (one-time checkout, custom payment intent, subscription, refund, or customer management).
Outputs: working Python/Stripe SDK code for the requested flow (checkout session, payment intent, subscription, webhook handler, refund, or customer/payment-method operation), plus test-mode verification code.

session = stripe.checkout.Session.create(
    payment_method_types=['card'],
    line_items=[{'price_data': {'currency': 'usd', 'product_data': {'name': 'Premium Subscription'},
                                  'unit_amount': 2000, 'recurring': {'interval': 'month'}}, 'quantity': 1}],
    mode='subscription',
    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url='https://yourdomain.com/cancel',
)

Developers implementing Stripe payment processing - checkout, subscriptions, webhooks, refunds, or customer management - who need correct, PCI-compliant, idempotent integration code rather than assembling it from scattered docs.