Comprehensive Stripe integration agent for payments, subscriptions, billing, and marketplace management. Use when Claude needs to work with Stripe API for creating customers, managing subscriptions, processing payments, handling checkout sessions, setting up products/prices, managing webhooks, Connect marketplaces, metered billing, tax calculation, fraud prevention, or any payment-related task. Triggers on mentions of Stripe, payments, subscriptions, billing, checkout, invoices, payment intents, recurring payments, Connect, marketplace, SCA, 3D Secure, or disputes.
This skill enables Claude to interact with Stripe's API for complete payment and subscription management.
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:
pip install stripe --break-system-packages
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="[email protected]",
name="John Doe",
metadata={"user_id": "your_app_user_id"}
)
# Retrieve customer
customer = stripe.Customer.retrieve("cus_xxx")
# Update customer
stripe.Customer.modify("cus_xxx", metadata={"plan": "premium"})
# List customers
customers = stripe.Customer.list(limit=10, email="[email protected]")
Always create Products first, then attach Prices. Use lookup_key for easy price retrieval.
# Create product
product = stripe.Product.create(
name="Pro Plan",
description="Full access to all features",
metadata={"tier": "pro"}
)
# Create recurring price (subscription)
price = stripe.Price.create(
product=product.id,
unit_amount=1999, # Amount in cents (€19.99)
currency="eur",
recurring={"interval": "month"},
lookup_key="pro_monthly"
)
# Create one-time price
one_time_price = stripe.Price.create(
product=product.id,
unit_amount=9999,
currency="eur",
lookup_key="pro_lifetime"
)
# Retrieve price by lookup_key
prices = stripe.Price.list(lookup_keys=["pro_monthly"])
Use Checkout Sessions for secure, hosted payment pages.
# Subscription checkout
session = stripe.checkout.Session.create(
customer="cus_xxx", # Optional: attach to existing customer
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
# One-time payment checkout
session = stripe.checkout.Session.create(
mode="payment",
line_items=[{"price": "price_xxx", "quantity": 1}],
success_url="https://yourapp.com/success",
cancel_url="https://yourapp.com/cancel"
)
# 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"]
)
# Retrieve subscription
sub = stripe.Subscription.retrieve("sub_xxx")
# 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
# Or cancel at period end:
stripe.Subscription.modify("sub_xxx", cancel_at_period_end=True)
Use when you need full control over the payment flow.
# Create payment intent
intent = stripe.PaymentIntent.create(
amount=2000,
currency="eur",
customer="cus_xxx",
metadata={"order_id": "order_123"}
)
# Return intent.client_secret to frontend
# Confirm payment (server-side)
stripe.PaymentIntent.confirm(
"pi_xxx",
payment_method="pm_xxx"
)
Critical for subscription lifecycle. See scripts/webhook_handler.py for complete implementation.
Key events to handle:
checkout.session.completed - Payment successfulcustomer.subscription.created - New subscriptioncustomer.subscription.updated - Plan changescustomer.subscription.deleted - Cancellationinvoice.paid - Successful renewalinvoice.payment_failed - Failed paymentimport stripe
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"}
For Firebase + Stripe integration, see references/firebase-integration.md.
Quick setup:
| 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() |
Let customers manage their own subscriptions:
portal_session = stripe.billing_portal.Session.create(
customer="cus_xxx",
return_url="https://yourapp.com/account"
)
# Redirect to: portal_session.url
Use test mode keys (sk_test_...) and test card numbers:
4242424242424242 - Successful payment4000000000000002 - Declined4000002500003155 - Requires 3D Secure