Stripe Agent

2. Products and Prices

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"])

3. Checkout Sessions (Recommended for Web)

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"
)

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"]
)

# 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)

5. Payment Intents (Custom Integration)

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"
)

6. Webhook Handling

Critical for subscription lifecycle. See scripts/webhook_handler.py for complete implementation.

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

import 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"}

Firebase Integration Pattern

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

Quick setup:

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

Common Operations Quick Reference

Customer Portal (Self-Service)

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

Testing

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

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

Error Handling