AI Agent for Stripe: Payment Processing, Subscription Management, and Invoicing

Why Build AI Agents for Stripe

Payment operations involve complex decision-making: handling failed payments, managing subscription upgrades and downgrades, issuing refunds, detecting fraud patterns, and resolving billing disputes. An AI agent connected to Stripe can automate these decisions with business context, reducing manual intervention while maintaining the careful judgment that financial operations require.

The Stripe API is well-designed for programmatic access, and its webhook system provides real-time event notifications that serve as natural triggers for agent actions.

Setting Up the Stripe Client

Stripe's official Python library handles authentication, retries, and serialization. Wrap it in a service class for your agent.

import stripe
from dataclasses import dataclass

stripe.api_key = "sk_live_your-key"  # Use env variables in production

@dataclass
class PaymentResult:
    success: bool
    payment_intent_id: str
    status: str
    error_message: str = None

class StripeService:
    async def create_payment_intent(
        self, amount_cents: int, currency: str,
        customer_id: str, metadata: dict = None,
    ) -> PaymentResult:
        try:
            intent = stripe.PaymentIntent.create(
                amount=amount_cents,
                currency=currency,
                customer=customer_id,
                metadata=metadata or {},
                automatic_payment_methods={"enabled": True},
            )
            return PaymentResult(
                success=True,
                payment_intent_id=intent.id,
                status=intent.status,
            )
        except stripe.error.CardError as e:
            return PaymentResult(
                success=False,
                payment_intent_id="",
                status="failed",
                error_message=e.user_message,
            )
        except stripe.error.StripeError as e:
            return PaymentResult(
                success=False,
                payment_intent_id="",
                status="error",
                error_message=str(e),
            )

    def get_customer_subscriptions(self, customer_id: str) -> list:
        subscriptions = stripe.Subscription.list(
            customer=customer_id,
            status="all",
            limit=10,
        )
        return subscriptions.data

Webhook Event Processing

Stripe webhooks notify your agent of payment events in real time. Always verify the webhook signature to prevent spoofing.

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
STRIPE_WEBHOOK_SECRET = "whsec_your-webhook-secret"

@app.post("/stripe/webhook")
async def handle_stripe_webhook(request: Request):
    payload = await request.body()
    sig_header = request.headers.get("Stripe-Signature")

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, STRIPE_WEBHOOK_SECRET
        )
    except stripe.error.SignatureVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    event_handlers = {
        "invoice.payment_failed": handle_payment_failed,
        "customer.subscription.updated": handle_subscription_change,
        "charge.dispute.created": handle_dispute,
        "invoice.paid": handle_invoice_paid,
    }

    handler = event_handlers.get(event["type"])
    if handler:
        await handler(event["data"]["object"])

    return {"status": "ok"}

Intelligent Failed Payment Recovery

When a payment fails, the agent analyzes the failure reason and decides the recovery strategy.

async def handle_payment_failed(invoice: dict):
    customer_id = invoice["customer"]
    amount = invoice["amount_due"] / 100
    failure_code = invoice.get("last_finalization_error", {}).get("code")
    attempt_count = invoice.get("attempt_count", 0)

    customer = stripe.Customer.retrieve(customer_id)
    payment_history = stripe.PaymentIntent.list(
        customer=customer_id, limit=10
    )
    recent_failures = sum(
        1 for pi in payment_history.data
        if pi.status == "requires_payment_method"
    )

    decision = await agent.run(
        prompt=(
            f"A payment of ${amount:.2f} failed for customer "
            f"{customer.email}.\n"
            f"Failure code: {failure_code}\n"
            f"Attempt #{attempt_count}\n"
            f"Recent failures in last 10 payments: {recent_failures}\n\n"
            f"Decide the recovery action:\n"
            f"1. retry_immediately - transient error, retry now\n"
            f"2. notify_customer - ask to update payment method\n"
            f"3. apply_grace_period - give 7 days before suspension\n"
            f"4. escalate_to_support - needs human review"
        )
    )

    if decision.action == "retry_immediately":
        stripe.Invoice.pay(invoice["id"])
    elif decision.action == "notify_customer":
        await send_payment_update_email(customer.email, amount)
    elif decision.action == "apply_grace_period":
        stripe.Subscription.modify(
            invoice["subscription"],
            metadata={"grace_period_until": "2026-03-24"},
        )
    elif decision.action == "escalate_to_support":
        await create_support_ticket(customer, invoice)

Subscription Lifecycle Management

Let the agent handle upgrade, downgrade, and cancellation logic with business rules.

class SubscriptionAgent:
    def __init__(self, stripe_service: StripeService, agent):
        self.stripe = stripe_service
        self.agent = agent

    async def handle_change_request(
        self, customer_id: str, requested_action: str
    ) -> dict:
        current_subs = self.stripe.get_customer_subscriptions(customer_id)
        active_sub = next(
            (s for s in current_subs if s.status == "active"), None
        )

        if not active_sub:
            return {"error": "No active subscription found"}

        current_plan = active_sub.items.data[0].price.id
        current_amount = active_sub.items.data[0].price.unit_amount / 100

        decision = await self.agent.run(
            prompt=(
                f"Customer wants to: {requested_action}\n"
                f"Current plan: {current_plan} (${current_amount}/mo)\n"
                f"Subscription started: {active_sub.start_date}\n\n"
                f"Available plans: basic ($29), pro ($79), enterprise ($199)\n"
                f"Determine the target plan and proration behavior."
            )
        )

        if decision.action == "upgrade":
            updated = stripe.Subscription.modify(
                active_sub.id,
                items=[{
                    "id": active_sub.items.data[0].id,
                    "price": decision.target_price_id,
                }],
                proration_behavior="create_prorations",
            )
            return {"status": "upgraded", "new_plan": decision.target_price_id}

        elif decision.action == "downgrade":
            updated = stripe.Subscription.modify(
                active_sub.id,
                items=[{
                    "id": active_sub.items.data[0].id,
                    "price": decision.target_price_id,
                }],
                proration_behavior="none",
                # Apply at end of billing period
                billing_cycle_anchor="unchanged",
            )
            return {"status": "downgrade_scheduled"}

        return {"status": decision.action, "details": decision.reason}

FAQ

How do I test Stripe integrations without processing real payments?

Use Stripe's test mode with test API keys (prefixed with sk_test_). Stripe provides test card numbers like 4242424242424242 for successful payments and 4000000000000002 for declines. Use the Stripe CLI (stripe listen --forward-to localhost:8000/stripe/webhook) to forward test webhook events to your local development server.

Should the AI agent process refunds automatically?

For small refunds below a threshold (e.g., under $50), automated refunds can be safe with proper logging. For larger amounts, the agent should create a refund request that a human approves. Always log the agent's reasoning for audit purposes. Use Stripe's metadata field to record why the refund was issued and which agent decision triggered it.

How do I handle idempotency for Stripe API calls from the agent?

Pass an idempotency_key parameter with every Stripe API call that creates or modifies resources. Use a deterministic key derived from the event that triggered the action — for example, hash the webhook event ID. This prevents duplicate charges or refunds if your agent processes the same event twice due to webhook retries.

---

#Stripe #PaymentProcessing #Subscriptions #AIAgents #FinTech #AgenticAI #LearnAI #AIEngineering