<< All versions
Skill v1.0.1
currentAutomated scan100/100rmyndharis/antigravity-skills/stripe-integration
2 files
──Details
PublishedMay 23, 2026 at 09:51 PM
Content Hashsha256:1b3e05635fa50328...
Git SHA4f9110cbfca4
Bump Typepatch
──Files
Files (1 file, 13.1 KB)
SKILL.md13.1 KBactive
SKILL.md · 456 lines · 13.1 KB
version: "1.0.1" name: stripe-integration description: 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.
Stripe Integration
Master Stripe payment processing integration for robust, PCI-compliant payment flows including checkout, subscriptions, webhooks, and refunds.
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.
- If detailed examples are required, open
resources/implementation-playbook.md.
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
- Minimal PCI compliance burden
- Fastest implementation
- Supports one-time and recurring payments
Payment Intents (Custom UI)
- Full control over payment UI
- Requires Stripe.js for PCI compliance
- 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 completedpayment_intent.payment_failed: Payment failedcustomer.subscription.updated: Subscription changedcustomer.subscription.deleted: Subscription canceledcharge.refunded: Refund processedinvoice.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
python
import stripestripe.api_key = "sk_test_..."# Create a checkout sessionsession = stripe.checkout.Session.create(payment_method_types=['card'],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.urlprint(session.url)
Payment Implementation Patterns
Pattern 1: One-Time Payment (Hosted Checkout)
python
def create_checkout_session(amount, currency='usd'):"""Create a one-time payment checkout session."""try:session = stripe.checkout.Session.create(payment_method_types=['card'],line_items=[{'price_data': {'currency': currency,'product_data': {'name': 'Purchase','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 sessionexcept stripe.error.StripeError as e:# Handle errorprint(f"Stripe error: {e.user_message}")raise
Pattern 2: Custom Payment Intent Flow
python
def create_payment_intent(amount, currency='usd', customer_id=None):"""Create a payment intent for custom checkout UI."""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# Frontend (JavaScript)"""const stripe = Stripe('pk_test_...');const elements = stripe.elements();const cardElement = elements.create('card');cardElement.mount('#card-element');const {error, paymentIntent} = await stripe.confirmCardPayment(clientSecret,{payment_method: {card: cardElement,billing_details: {name: 'Customer Name'}}});if (error) {// Handle error} else if (paymentIntent.status === 'succeeded') {// Payment successful}"""
Pattern 3: Subscription Creation
python
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 4: Customer Portal
python
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
python
from flask import Flask, requestimport stripeapp = Flask(__name__)endpoint_secret = 'whsec_...'@app.route('/webhook', methods=['POST'])def webhook():payload = request.datasig_header = request.headers.get('Stripe-Signature')try:event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)except ValueError:# Invalid payloadreturn 'Invalid payload', 400except stripe.error.SignatureVerificationError:# Invalid signaturereturn 'Invalid signature', 400# Handle the eventif 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', 200def 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 orderprint(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 statusdef handle_subscription_canceled(subscription):"""Handle subscription cancellation."""customer_id = subscription['customer']# Update user access# Send cancellation emailprint(f"Subscription canceled: {subscription['id']}")
Webhook Best Practices
python
import hashlibimport hmacdef 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 processedif is_event_processed(event_id):return# Process eventtry:handler()mark_event_processed(event_id)except Exception as e:log_error(e)# Stripe will retry failed webhooksraise
Customer Management
python
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 customerdef 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 defaultstripe.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
python
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 refundif reason:refund_params['reason'] = reason # 'duplicate', 'fraudulent', 'requested_by_customer'refund = stripe.Refund.create(**refund_params)return refunddef 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
python
# Use test mode keysstripe.api_key = "sk_test_..."# Test card numbersTEST_CARDS = {'success': '4242424242424242','declined': '4000000000000002','3d_secure': '4000002500003155','insufficient_funds': '4000000000009995'}def test_payment_flow():"""Test complete payment flow."""# Create test customercustomer = stripe.Customer.create(email="test@example.com")# Create payment intentintent = stripe.PaymentIntent.create(amount=1000,currency='usd',customer=customer.id,payment_method_types=['card'])# Confirm with test cardconfirmed = stripe.PaymentIntent.confirm(intent.id,payment_method='pm_card_visa' # Test payment method)assert confirmed.status == 'succeeded'
Resources
- references/checkout-flows.md: Detailed checkout implementation
- references/webhook-handling.md: Webhook security and processing
- references/subscription-management.md: Subscription lifecycle
- references/customer-management.md: Customer and payment method handling
- references/invoice-generation.md: Invoicing and billing
- assets/stripe-client.py: Production-ready Stripe client wrapper
- assets/webhook-handler.py: Complete webhook processor
- assets/checkout-config.json: Checkout configuration templates
Best Practices
- Always Use Webhooks: Don't rely solely on client-side confirmation
- Idempotency: Handle webhook events idempotently
- Error Handling: Gracefully handle all Stripe errors
- Test Mode: Thoroughly test with test keys before production
- Metadata: Use metadata to link Stripe objects to your database
- Monitoring: Track payment success rates and errors
- PCI Compliance: Never handle raw card data on your server
- 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