Stripe Agent

This skill enables Claude to interact with Stripe's API for complete payment and subscription management.

Prerequisites

Ensure STRIPE_SECRET_KEY environment variable is set. For webhook handling, also set STRIPE_WEBHOOK_SECRET.

export STRIPE_SECRET_KEY="sk_test_..."
export STRIPE_WEBHOOK_SECRET="whsec_..."

Install the Stripe SDK (use a virtual environment for isolation):

pip install stripe

Core Workflows

1. Customer Management

Create and manage customers before any payment operation.

import stripe
import os

stripe.api_key = os.environ.get("STRIPE_SECRET_KEY")

# Create customer
customer = stripe.Customer.create(
    email="user@example.com",
    name="John Doe",
    metadata={"user_id": "your_app_user_id"}
)

# Retrieve / Update / List
customer = stripe.Customer.retrieve("cus_xxx")
stripe.Customer.modify("cus_xxx", metadata={"plan": "premium"})
customers = stripe.Customer.list(limit=10, email="user@example.com")

2. Products and Prices

Always create Products first, then attach Prices. Use lookup_key for easy price retrieval.

product = stripe.Product.create(
    name="Pro Plan",
    description="Full access to all features",
    metadata={"tier": "pro"}
)

# Recurring price (subscription)
price = stripe.Price.create(
    product=product.id,
    unit_amount=1999,  # Amount in cents
    currency="eur",
    recurring={"interval": "month"},
    lookup_key="pro_monthly"
)

# One-time price
one_time_price = stripe.Price.create(
    product=product.id,
    unit_amount=9999,
    currency="eur",
    lookup_key="pro_lifetime"
)

3. Checkout Sessions (Recommended for Web)

Use Checkout Sessions for secure, hosted payment pages.

session = stripe.checkout.Session.create(
    customer="cus_xxx",
    mode="subscription",
    line_items=[{"price": "price_xxx", "quantity": 1}],
    success_url="https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}",
    cancel_url="https://yourapp.com/cancel",
    metadata={"user_id": "123"}
)
# Redirect user to: session.url

4. Subscription Management

# Create subscription directly (when you have payment method)
subscription = stripe.Subscription.create(
    customer="cus_xxx",
    items=[{"price": "price_xxx"}],
    payment_behavior="default_incomplete",
    expand=["latest_invoice.payment_intent"]
)

# Update subscription (change plan)
stripe.Subscription.modify(
    "sub_xxx",
    items=[{"id": sub["items"]["data"][0].id, "price": "price_new_xxx"}],
    proration_behavior="create_prorations"
)

# Cancel subscription
stripe.Subscription.cancel("sub_xxx")  # Immediate
stripe.Subscription.modify("sub_xxx", cancel_at_period_end=True)  # At period end

5. Payment Intents (Custom Integration)

Use when you need full control over the payment flow.

intent = stripe.PaymentIntent.create(
    amount=2000,
    currency="eur",
    customer="cus_xxx",
    metadata={"order_id": "order_123"}
)
# Return intent.client_secret to frontend

6. Webhook Handling

Critical for subscription lifecycle. Key events to handle:

checkout.session.completed - Payment successful
customer.subscription.created - New subscription
customer.subscription.updated - Plan changes
customer.subscription.deleted - Cancellation
invoice.paid - Successful renewal
invoice.payment_failed - Failed payment

def handle_webhook(payload, sig_header):
    endpoint_secret = os.environ.get("STRIPE_WEBHOOK_SECRET")
    event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)

    if event["type"] == "checkout.session.completed":
        session = event["data"]["object"]
        # Fulfill order, activate subscription
    elif event["type"] == "invoice.payment_failed":
        invoice = event["data"]["object"]
        # Notify user, handle dunning
    return {"status": "success"}

Firebase Integration Pattern

For Firebase + Stripe integration, see references/firebase-integration.md.

Quick setup:

Store Stripe customer_id in Firestore user document
Sync subscription status via webhooks to Firestore
Use Firebase Security Rules to check subscription status

Common Operations Quick Reference

Task	Method
Create customer	`stripe.Customer.create()`
Start subscription	`stripe.checkout.Session.create(mode="subscription")`
Cancel subscription	`stripe.Subscription.cancel()`
Change plan	`stripe.Subscription.modify()`
Refund payment	`stripe.Refund.create(payment_intent="pi_xxx")`
Get invoices	`stripe.Invoice.list(customer="cus_xxx")`
Create portal session	`stripe.billing_portal.Session.create()`

Customer Portal (Self-Service)

portal_session = stripe.billing_portal.Session.create(
    customer="cus_xxx",
    return_url="https://yourapp.com/account"
)
# Redirect to: portal_session.url

Payment Links (No-Code Payments)

payment_link = stripe.PaymentLink.create(
    line_items=[{"price": "price_xxx", "quantity": 1}],
    after_completion={"type": "redirect", "redirect": {"url": "https://yourapp.com/thanks"}}
)
# Share: payment_link.url

Testing

Use test mode keys (sk_test_...) and test card numbers:

4242424242424242 - Successful payment
4000000000000002 - Declined
4000002500003155 - Requires 3D Secure

Error Handling

try:
    # Stripe operation
except stripe.error.CardError as e:
    print(f"Card error: {e.user_message}")
except stripe.error.InvalidRequestError as e:
    print(f"Invalid request: {e}")
except stripe.error.AuthenticationError:
    pass  # Invalid API key
except stripe.error.StripeError as e:
    pass  # Generic Stripe error

Advanced Features

For detailed code examples of the following, see references/stripe-patterns.md:

Metered and usage-based billing - API calls, seats, tiered pricing
Stripe Connect (Marketplaces) - Connected accounts, platform fees, transfers
Tax Calculation (Stripe Tax) - Automatic tax in checkout
3D Secure and SCA Compliance - Strong Customer Authentication (EU/UK)
Fraud Prevention (Stripe Radar) - Risk assessment, custom rules
Dispute Handling - Chargebacks, evidence submission
Idempotency - Preventing duplicate operations

Scripts Reference

scripts/setup_products.py - Create products and prices
scripts/webhook_handler.py - Flask webhook endpoint
scripts/sync_subscriptions.py - Sync subscriptions to database
scripts/stripe_utils.py - Common utility functions

References

references/stripe-patterns.md - Metered billing, Connect, tax, 3DS, Radar, disputes, idempotency patterns
references/firebase-integration.md - Firebase + Firestore integration
references/api-cheatsheet.md - Quick API reference

stripe-agent