Stripe Integration

Master Stripe payment processing integration for robust, PCI-compliant payment flows including checkout, subscriptions, webhooks, and refunds.

When to Use This Skill

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 Sessions

Recommended for most integrations

Supports all UI paths:

Stripe-hosted checkout page

Embedded checkout form

Custom UI with Elements (Payment Element, Express Checkout Element) using

ui_mode='custom'

Provides built-in checkout capabilities (line items, discounts, tax, shipping, address collection, saved payment methods, and checkout lifecycle events)

Lower integration and maintenance burden than Payment Intents

Payment Intents (Bespoke control)

You calculate the final amount with taxes, discounts, subscriptions, and currency conversion yourself.

More complex implementation and long-term maintenance burden

Requires Stripe.js for PCI compliance

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 Quick Start import stripe stripe . api_key = "sk_test_..."

Create a checkout session

session

stripe . checkout . Session . create ( line_items = [ { 'price_data' : { 'currency' : 'usd' , 'product_data' : { 'name' : 'Premium Subscription' , } , 'unit_amount' : 2000 ,

$20.00

'recurring' : { 'interval' : 'month' , } , } , 'quantity' : 1 , } ] , mode = 'subscription' , success_url = 'https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}' , cancel_url = 'https://yourdomain.com/cancel' )

Redirect user to session.url

print ( session . url ) Payment Implementation Patterns Pattern 1: One-Time Payment (Hosted Checkout) def create_checkout_session ( amount , currency = 'usd' ) : """Create a one-time payment checkout session.""" try : session = stripe . checkout . Session . create ( line_items = [ { 'price_data' : { 'currency' : currency , 'product_data' : { 'name' : 'Blue T-shirt' , 'images' : [ 'https://example.com/product.jpg' ] , } , 'unit_amount' : amount ,

Amount in cents

} , 'quantity' : 1 , } ] , mode = 'payment' , success_url = 'https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}' , cancel_url = 'https://yourdomain.com/cancel' , metadata = { 'order_id' : 'order_123' , 'user_id' : 'user_456' } ) return session except stripe . error . StripeError as e :

Handle error

print ( f"Stripe error: { e . user_message } " ) raise Pattern 2: Elements with Checkout Sessions def create_checkout_session_for_elements ( amount , currency = 'usd' ) : """Create a checkout session configured for Payment Element.""" session = stripe . checkout . Session . create ( mode = 'payment' , ui_mode = 'custom' , line_items = [ { 'price_data' : { 'currency' : currency , 'product_data' : { 'name' : 'Blue T-shirt' } , 'unit_amount' : amount , } , 'quantity' : 1 , } ] , return_url = 'https://yourdomain.com/complete?session_id={CHECKOUT_SESSION_ID}' ) return session . client_secret

Send to frontend

const stripe = Stripe ( "pk_test_..." ) ; const appearance = { theme : "stripe" } ; const checkout = stripe . initCheckout ( { clientSecret , elementsOptions : { appearance } , } ) ; const loadActionsResult = await checkout . loadActions ( ) ; if ( loadActionsResult . type === "success" ) { const { actions } = loadActionsResult ; const session = actions . getSession ( ) ; const button = document . getElementById ( "pay-button" ) ; const checkoutContainer = document . getElementById ( "checkout-container" ) ; const emailInput = document . getElementById ( "email" ) ; const emailErrors = document . getElementById ( "email-errors" ) ; const errors = document . getElementById ( "confirm-errors" ) ; // Display a formatted string representing the total amount checkoutContainer . append ( Total: ${ session . total . total . amount } ) ; // Mount Payment Element const paymentElement = checkout . createPaymentElement ( ) ; paymentElement . mount ( "#payment-element" ) ; // Store email for submission emailInput . addEventListener ( "blur" , ( ) => { actions . updateEmail ( emailInput . value ) . then ( ( result ) => { if ( result . error ) emailErrors . textContent = result . error . message ; } ) ; } ) ; // Handle form submission button . addEventListener ( "click" , ( ) => { actions . confirm ( ) . then ( ( result ) => { if ( result . type === "error" ) errors . textContent = result . error . message ; } ) ; } ) ; } Pattern 3: Elements with Payment Intents Pattern 2 (Elements with Checkout Sessions) is Stripe's recommended approach, but you can also use Payment Intents as an alternative. def create_payment_intent ( amount , currency = 'usd' , customer_id = None ) : """Create a payment intent for bespoke checkout UI with Payment Element.""" intent = stripe . PaymentIntent . create ( amount = amount , currency = currency , customer = customer_id , automatic_payment_methods = { 'enabled' : True , } , metadata = { 'integration_check' : 'accept_a_payment' } ) return intent . client_secret

Send to frontend

// Mount Payment Element and confirm via Payment Intents const stripe = Stripe ( "pk_test_..." ) ; const appearance = { theme : "stripe" } ; const elements = stripe . elements ( { appearance , clientSecret } ) ; const paymentElement = elements . create ( "payment" ) ; paymentElement . mount ( "#payment-element" ) ; document . getElementById ( "pay-button" ) . addEventListener ( "click" , async ( ) => { const { error } = await stripe . confirmPayment ( { elements , confirmParams : { return_url : "https://yourdomain.com/complete" , } , } ) ; if ( error ) { document . getElementById ( "errors" ) . textContent = error . message ; } } ) ; Pattern 4: Subscription Creation def create_subscription ( customer_id , price_id ) : """Create a subscription for a customer.""" try : subscription = stripe . Subscription . create ( customer = customer_id , items = [ { 'price' : price_id } ] , payment_behavior = 'default_incomplete' , payment_settings = { 'save_default_payment_method' : 'on_subscription' } , expand = [ 'latest_invoice.payment_intent' ] , ) return { 'subscription_id' : subscription . id , 'client_secret' : subscription . latest_invoice . payment_intent . client_secret } except stripe . error . StripeError as e : print ( f"Subscription creation failed: { e } " ) raise Pattern 5: Customer Portal def create_customer_portal_session ( customer_id ) : """Create a portal session for customers to manage subscriptions.""" session = stripe . billing_portal . Session . create ( customer = customer_id , return_url = 'https://yourdomain.com/account' , ) return session . url

Redirect customer here

Webhook Handling Secure Webhook Endpoint from flask import Flask , request import stripe app = Flask ( name ) endpoint_secret = 'whsec_...' @app . route ( '/webhook' , methods = [ 'POST' ] ) def webhook ( ) : payload = request . data sig_header = request . headers . get ( 'Stripe-Signature' ) try : event = stripe . Webhook . construct_event ( payload , sig_header , endpoint_secret ) except ValueError :

Invalid payload

return 'Invalid payload' , 400 except stripe . error . SignatureVerificationError :

Invalid signature

return 'Invalid signature' , 400

Handle the event

if event [ 'type' ] == 'payment_intent.succeeded' : payment_intent = event [ 'data' ] [ 'object' ] handle_successful_payment ( payment_intent ) elif event [ 'type' ] == 'payment_intent.payment_failed' : payment_intent = event [ 'data' ] [ 'object' ] handle_failed_payment ( payment_intent ) elif event [ 'type' ] == 'customer.subscription.deleted' : subscription = event [ 'data' ] [ 'object' ] handle_subscription_canceled ( subscription ) return 'Success' , 200 def handle_successful_payment ( payment_intent ) : """Process successful payment.""" customer_id = payment_intent . get ( 'customer' ) amount = payment_intent [ 'amount' ] metadata = payment_intent . get ( 'metadata' , { } )

Update your database

Send confirmation email

Fulfill order

print ( f"Payment succeeded: { payment_intent [ 'id' ] } " ) def handle_failed_payment ( payment_intent ) : """Handle failed payment.""" error = payment_intent . get ( 'last_payment_error' , { } ) print ( f"Payment failed: { error . get ( 'message' ) } " )

Notify customer

Update order status

def handle_subscription_canceled ( subscription ) : """Handle subscription cancellation.""" customer_id = subscription [ 'customer' ]

Update user access

Send cancellation email

print ( f"Subscription canceled: { subscription [ 'id' ] } " ) Webhook Best Practices import hashlib import hmac def verify_webhook_signature ( payload , signature , secret ) : """Manually verify webhook signature.""" expected_sig = hmac . new ( secret . encode ( 'utf-8' ) , payload , hashlib . sha256 ) . hexdigest ( ) return hmac . compare_digest ( signature , expected_sig ) def handle_webhook_idempotently ( event_id , handler ) : """Ensure webhook is processed exactly once."""

Check if event already processed

if is_event_processed ( event_id ) : return

Process event

try : handler ( ) mark_event_processed ( event_id ) except Exception as e : log_error ( e )

Stripe will retry failed webhooks

raise Customer Management def create_customer ( email , name , payment_method_id = None ) : """Create a Stripe customer.""" customer = stripe . Customer . create ( email = email , name = name , payment_method = payment_method_id , invoice_settings = { 'default_payment_method' : payment_method_id } if payment_method_id else None , metadata = { 'user_id' : '12345' } ) return customer def attach_payment_method ( customer_id , payment_method_id ) : """Attach a payment method to a customer.""" stripe . PaymentMethod . attach ( payment_method_id , customer = customer_id )

Set as default

stripe . Customer . modify ( customer_id , invoice_settings = { 'default_payment_method' : payment_method_id } ) def list_customer_payment_methods ( customer_id ) : """List all payment methods for a customer.""" payment_methods = stripe . PaymentMethod . list ( customer = customer_id , type = 'card' ) return payment_methods . data Refund Handling def create_refund ( payment_intent_id , amount = None , reason = None ) : """Create a refund.""" refund_params = { 'payment_intent' : payment_intent_id } if amount : refund_params [ 'amount' ] = amount

Partial refund

if reason : refund_params [ 'reason' ] = reason

'duplicate', 'fraudulent', 'requested_by_customer'

refund

stripe . Refund . create ( ** refund_params ) return refund def handle_dispute ( charge_id , evidence ) : """Update dispute with evidence.""" stripe . Dispute . modify ( charge_id , evidence = { 'customer_name' : evidence . get ( 'customer_name' ) , 'customer_email_address' : evidence . get ( 'customer_email' ) , 'shipping_documentation' : evidence . get ( 'shipping_proof' ) , 'customer_communication' : evidence . get ( 'communication' ) , } ) Testing

Use test mode keys

stripe . api_key = "sk_test_..."

Test card numbers

TEST_CARDS

{ 'success' : '4242424242424242' , 'declined' : '4000000000000002' , '3d_secure' : '4000002500003155' , 'insufficient_funds' : '4000000000009995' } def test_payment_flow ( ) : """Test complete payment flow."""

Create test customer

customer

stripe . Customer . create ( email = "test@example.com" )

Create payment intent

intent

stripe . PaymentIntent . create ( amount = 1000 , automatic_payment_methods = { 'enabled' : True } , currency = 'usd' , customer = customer . id )

Confirm with test card

confirmed

stripe . PaymentIntent . confirm ( intent . id , payment_method = 'pm_card_visa'

Test payment method

) assert confirmed . status == 'succeeded'