Stripe Integration

1---
2name: stripe-integration
3description: Implement Stripe payment processing for robust, PCI-compliant payment flows including checkout, subscriptions, and webhooks. Use when integrating Stripe payments, building subscription systems, or implementing secure checkout flows.
4---
5 
6# Stripe Integration
7 
8Master Stripe payment processing integration for robust, PCI-compliant payment flows including checkout, subscriptions, webhooks, and refunds.
9 
10## Do not use this skill when
11 
12- The task is unrelated to stripe integration
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Implementing payment processing in web/mobile applications
25- Setting up subscription billing systems
26- Handling one-time payments and recurring charges
27- Processing refunds and disputes
28- Managing customer payment methods
29- Implementing SCA (Strong Customer Authentication) for European payments
30- Building marketplace payment flows with Stripe Connect
31 
32## Core Concepts
33 
34### 1. Payment Flows
35**Checkout Session (Hosted)**
36- Stripe-hosted payment page
37- Minimal PCI compliance burden
38- Fastest implementation
39- Supports one-time and recurring payments
40 
41**Payment Intents (Custom UI)**
42- Full control over payment UI
43- Requires Stripe.js for PCI compliance
44- More complex implementation
45- Better customization options
46 
47**Setup Intents (Save Payment Methods)**
48- Collect payment method without charging
49- Used for subscriptions and future payments
50- Requires customer confirmation
51 
52### 2. Webhooks
53**Critical Events:**
54- `payment_intent.succeeded`: Payment completed
55- `payment_intent.payment_failed`: Payment failed
56- `customer.subscription.updated`: Subscription changed
57- `customer.subscription.deleted`: Subscription canceled
58- `charge.refunded`: Refund processed
59- `invoice.payment_succeeded`: Subscription payment successful
60 
61### 3. Subscriptions
62**Components:**
63- **Product**: What you're selling
64- **Price**: How much and how often
65- **Subscription**: Customer's recurring payment
66- **Invoice**: Generated for each billing cycle
67 
68### 4. Customer Management
69- Create and manage customer records
70- Store multiple payment methods
71- Track customer metadata
72- Manage billing details
73 
74## Quick Start
75 
76```python
77import stripe
78 
79stripe.api_key = "sk_test_..."
80 
81# Create a checkout session
82session = stripe.checkout.Session.create(
83    payment_method_types=['card'],
84    line_items=[{
85        'price_data': {
86            'currency': 'usd',
87            'product_data': {
88                'name': 'Premium Subscription',
89            },
90            'unit_amount': 2000,  # $20.00
91            'recurring': {
92                'interval': 'month',
93            },
94        },
95        'quantity': 1,
96    }],
97    mode='subscription',
98    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
99    cancel_url='https://yourdomain.com/cancel',
100)
101 
102# Redirect user to session.url
103print(session.url)
104```
105 
106## Payment Implementation Patterns
107 
108### Pattern 1: One-Time Payment (Hosted Checkout)
109```python
110def create_checkout_session(amount, currency='usd'):
111    """Create a one-time payment checkout session."""
112    try:
113        session = stripe.checkout.Session.create(
114            payment_method_types=['card'],
115            line_items=[{
116                'price_data': {
117                    'currency': currency,
118                    'product_data': {
119                        'name': 'Purchase',
120                        'images': ['https://example.com/product.jpg'],
121                    },
122                    'unit_amount': amount,  # Amount in cents
123                },
124                'quantity': 1,
125            }],
126            mode='payment',
127            success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
128            cancel_url='https://yourdomain.com/cancel',
129            metadata={
130                'order_id': 'order_123',
131                'user_id': 'user_456'
132            }
133        )
134        return session
135    except stripe.error.StripeError as e:
136        # Handle error
137        print(f"Stripe error: {e.user_message}")
138        raise
139```
140 
141### Pattern 2: Custom Payment Intent Flow
142```python
143def create_payment_intent(amount, currency='usd', customer_id=None):
144    """Create a payment intent for custom checkout UI."""
145    intent = stripe.PaymentIntent.create(
146        amount=amount,
147        currency=currency,
148        customer=customer_id,
149        automatic_payment_methods={
150            'enabled': True,
151        },
152        metadata={
153            'integration_check': 'accept_a_payment'
154        }
155    )
156    return intent.client_secret  # Send to frontend
157 
158# Frontend (JavaScript)
159"""
160const stripe = Stripe('pk_test_...');
161const elements = stripe.elements();
162const cardElement = elements.create('card');
163cardElement.mount('#card-element');
164 
165const {error, paymentIntent} = await stripe.confirmCardPayment(
166    clientSecret,
167    {
168        payment_method: {
169            card: cardElement,
170            billing_details: {
171                name: 'Customer Name'
172            }
173        }
174    }
175);
176 
177if (error) {
178    // Handle error
179} else if (paymentIntent.status === 'succeeded') {
180    // Payment successful
181}
182"""
183```
184 
185### Pattern 3: Subscription Creation
186```python
187def create_subscription(customer_id, price_id):
188    """Create a subscription for a customer."""
189    try:
190        subscription = stripe.Subscription.create(
191            customer=customer_id,
192            items=[{'price': price_id}],
193            payment_behavior='default_incomplete',
194            payment_settings={'save_default_payment_method': 'on_subscription'},
195            expand=['latest_invoice.payment_intent'],
196        )
197 
198        return {
199            'subscription_id': subscription.id,
200            'client_secret': subscription.latest_invoice.payment_intent.client_secret
201        }
202    except stripe.error.StripeError as e:
203        print(f"Subscription creation failed: {e}")
204        raise
205```
206 
207### Pattern 4: Customer Portal
208```python
209def create_customer_portal_session(customer_id):
210    """Create a portal session for customers to manage subscriptions."""
211    session = stripe.billing_portal.Session.create(
212        customer=customer_id,
213        return_url='https://yourdomain.com/account',
214    )
215    return session.url  # Redirect customer here
216```
217 
218## Webhook Handling
219 
220### Secure Webhook Endpoint
221```python
222from flask import Flask, request
223import stripe
224 
225app = Flask(__name__)
226 
227endpoint_secret = 'whsec_...'
228 
229@app.route('/webhook', methods=['POST'])
230def webhook():
231    payload = request.data
232    sig_header = request.headers.get('Stripe-Signature')
233 
234    try:
235        event = stripe.Webhook.construct_event(
236            payload, sig_header, endpoint_secret
237        )
238    except ValueError:
239        # Invalid payload
240        return 'Invalid payload', 400
241    except stripe.error.SignatureVerificationError:
242        # Invalid signature
243        return 'Invalid signature', 400
244 
245    # Handle the event
246    if event['type'] == 'payment_intent.succeeded':
247        payment_intent = event['data']['object']
248        handle_successful_payment(payment_intent)
249    elif event['type'] == 'payment_intent.payment_failed':
250        payment_intent = event['data']['object']
251        handle_failed_payment(payment_intent)
252    elif event['type'] == 'customer.subscription.deleted':
253        subscription = event['data']['object']
254        handle_subscription_canceled(subscription)
255 
256    return 'Success', 200
257 
258def handle_successful_payment(payment_intent):
259    """Process successful payment."""
260    customer_id = payment_intent.get('customer')
261    amount = payment_intent['amount']
262    metadata = payment_intent.get('metadata', {})
263 
264    # Update your database
265    # Send confirmation email
266    # Fulfill order
267    print(f"Payment succeeded: {payment_intent['id']}")
268 
269def handle_failed_payment(payment_intent):
270    """Handle failed payment."""
271    error = payment_intent.get('last_payment_error', {})
272    print(f"Payment failed: {error.get('message')}")
273    # Notify customer
274    # Update order status
275 
276def handle_subscription_canceled(subscription):
277    """Handle subscription cancellation."""
278    customer_id = subscription['customer']
279    # Update user access
280    # Send cancellation email
281    print(f"Subscription canceled: {subscription['id']}")
282```
283 
284### Webhook Best Practices
285```python
286import hashlib
287import hmac
288 
289def verify_webhook_signature(payload, signature, secret):
290    """Manually verify webhook signature."""
291    expected_sig = hmac.new(
292        secret.encode('utf-8'),
293        payload,
294        hashlib.sha256
295    ).hexdigest()
296 
297    return hmac.compare_digest(signature, expected_sig)
298 
299def handle_webhook_idempotently(event_id, handler):
300    """Ensure webhook is processed exactly once."""
301    # Check if event already processed
302    if is_event_processed(event_id):
303        return
304 
305    # Process event
306    try:
307        handler()
308        mark_event_processed(event_id)
309    except Exception as e:
310        log_error(e)
311        # Stripe will retry failed webhooks
312        raise
313```
314 
315## Customer Management
316 
317```python
318def create_customer(email, name, payment_method_id=None):
319    """Create a Stripe customer."""
320    customer = stripe.Customer.create(
321        email=email,
322        name=name,
323        payment_method=payment_method_id,
324        invoice_settings={
325            'default_payment_method': payment_method_id
326        } if payment_method_id else None,
327        metadata={
328            'user_id': '12345'
329        }
330    )
331    return customer
332 
333def attach_payment_method(customer_id, payment_method_id):
334    """Attach a payment method to a customer."""
335    stripe.PaymentMethod.attach(
336        payment_method_id,
337        customer=customer_id
338    )
339 
340    # Set as default
341    stripe.Customer.modify(
342        customer_id,
343        invoice_settings={
344            'default_payment_method': payment_method_id
345        }
346    )
347 
348def list_customer_payment_methods(customer_id):
349    """List all payment methods for a customer."""
350    payment_methods = stripe.PaymentMethod.list(
351        customer=customer_id,
352        type='card'
353    )
354    return payment_methods.data
355```
356 
357## Refund Handling
358 
359```python
360def create_refund(payment_intent_id, amount=None, reason=None):
361    """Create a refund."""
362    refund_params = {
363        'payment_intent': payment_intent_id
364    }
365 
366    if amount:
367        refund_params['amount'] = amount  # Partial refund
368 
369    if reason:
370        refund_params['reason'] = reason  # 'duplicate', 'fraudulent', 'requested_by_customer'
371 
372    refund = stripe.Refund.create(**refund_params)
373    return refund
374 
375def handle_dispute(charge_id, evidence):
376    """Update dispute with evidence."""
377    stripe.Dispute.modify(
378        charge_id,
379        evidence={
380            'customer_name': evidence.get('customer_name'),
381            'customer_email_address': evidence.get('customer_email'),
382            'shipping_documentation': evidence.get('shipping_proof'),
383            'customer_communication': evidence.get('communication'),
384        }
385    )
386```
387 
388## Testing
389 
390```python
391# Use test mode keys
392stripe.api_key = "sk_test_..."
393 
394# Test card numbers
395TEST_CARDS = {
396    'success': '4242424242424242',
397    'declined': '4000000000000002',
398    '3d_secure': '4000002500003155',
399    'insufficient_funds': '4000000000009995'
400}
401 
402def test_payment_flow():
403    """Test complete payment flow."""
404    # Create test customer
405    customer = stripe.Customer.create(
406        email="test@example.com"
407    )
408 
409    # Create payment intent
410    intent = stripe.PaymentIntent.create(
411        amount=1000,
412        currency='usd',
413        customer=customer.id,
414        payment_method_types=['card']
415    )
416 
417    # Confirm with test card
418    confirmed = stripe.PaymentIntent.confirm(
419        intent.id,
420        payment_method='pm_card_visa'  # Test payment method
421    )
422 
423    assert confirmed.status == 'succeeded'
424```
425 
426## Resources
427 
428- **references/checkout-flows.md**: Detailed checkout implementation
429- **references/webhook-handling.md**: Webhook security and processing
430- **references/subscription-management.md**: Subscription lifecycle
431- **references/customer-management.md**: Customer and payment method handling
432- **references/invoice-generation.md**: Invoicing and billing
433- **assets/stripe-client.py**: Production-ready Stripe client wrapper
434- **assets/webhook-handler.py**: Complete webhook processor
435- **assets/checkout-config.json**: Checkout configuration templates
436 
437## Best Practices
438 
4391. **Always Use Webhooks**: Don't rely solely on client-side confirmation
4402. **Idempotency**: Handle webhook events idempotently
4413. **Error Handling**: Gracefully handle all Stripe errors
4424. **Test Mode**: Thoroughly test with test keys before production
4435. **Metadata**: Use metadata to link Stripe objects to your database
4446. **Monitoring**: Track payment success rates and errors
4457. **PCI Compliance**: Never handle raw card data on your server
4468. **SCA Ready**: Implement 3D Secure for European payments
447 
448## Common Pitfalls
449 
450- **Not Verifying Webhooks**: Always verify webhook signatures
451- **Missing Webhook Events**: Handle all relevant webhook events
452- **Hardcoded Amounts**: Use cents/smallest currency unit
453- **No Retry Logic**: Implement retries for API calls
454- **Ignoring Test Mode**: Test all edge cases with test cards
455