Payment Expert | Bootspring Docs

The Payment Expert agent specializes in payment processing, subscription management, Stripe integration, and billing systems for SaaS applications.

Expertise Areas#

Stripe Integration - SDK setup and configuration
Checkout Sessions - One-time and subscription payments
Webhook Handling - Payment event processing
Customer Portal - Self-service billing management
Usage-Based Billing - Metered subscription tracking
Subscription Management - Plan changes, cancellations
Pricing Components - UI for pricing pages

Usage Examples#

Stripe Setup#

Use the payment-expert agent to set up Stripe integration for a SaaS with multiple pricing tiers.

Response includes:

SDK configuration
Price ID management
Customer creation
Checkout flow

Webhook Handler#

Use the payment-expert agent to implement a comprehensive Stripe webhook handler for subscription events.

Response includes:

Signature verification
Event type handling
Database synchronization
Error handling

Billing Portal#

Use the payment-expert agent to add a customer billing portal for subscription management.

Response includes:

Portal session creation
Return URL handling
UI integration
Permission checking

Best Practices Applied#

1. Payment Processing#

Secure API key handling
Webhook signature verification
Idempotent event processing
Error recovery patterns

2. Subscription Management#

Database synchronization
Status tracking
Grace period handling
Dunning management

3. User Experience#

Clear pricing display
Smooth checkout flow
Self-service portal
Invoice access

4. Security#

PCI compliance via Stripe
Secure webhook endpoints
Proper authentication
Audit logging

Common Patterns#

Stripe Setup#

// lib/stripe.ts
import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
  typescript: true,
});

export const PLANS = {
  FREE: { priceId: null, name: 'Free', price: 0 },
  PRO: {
    priceId: process.env.STRIPE_PRO_PRICE_ID!,
    name: 'Pro',
    price: 29,
  },
  TEAM: {
    priceId: process.env.STRIPE_TEAM_PRICE_ID!,
    name: 'Team',
    price: 99,
  },
} as const;

Checkout Session#

// app/api/checkout/route.ts
import { stripe } from '@/lib/stripe';
import { auth } from '@/lib/auth';

export async function POST(req: Request) {
  const session = await auth();
  if (!session?.user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { priceId } = await req.json();

  const checkoutSession = await stripe.checkout.sessions.create({
    customer: customerId,
    mode: 'subscription',
    payment_method_types: ['card'],
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?success=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing?canceled=true`,
    subscription_data: {
      metadata: { userId: session.user.id },
    },
  });

  return Response.json({ url: checkoutSession.url });
}

Webhook Handler#

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe';
import { headers } from 'next/headers';
import Stripe from 'stripe';

export async function POST(req: Request) {
  const body = await req.text();
  const signature = headers().get('stripe-signature')!;

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    return Response.json({ error: 'Invalid signature' }, { status: 400 });
  }

  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckoutComplete(event.data.object);
      break;
    case 'customer.subscription.updated':
      await handleSubscriptionUpdate(event.data.object);
      break;
    case 'customer.subscription.deleted':
      await handleSubscriptionCanceled(event.data.object);
      break;
    case 'invoice.payment_failed':
      await handlePaymentFailed(event.data.object);
      break;
  }

  return Response.json({ received: true });
}

Customer Portal#

// app/api/portal/route.ts
import { stripe } from '@/lib/stripe';
import { auth } from '@/lib/auth';

export async function POST() {
  const session = await auth();
  if (!session?.user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const customerId = await getStripeCustomerId(session.user.id);
  if (!customerId) {
    return Response.json({ error: 'No subscription' }, { status: 400 });
  }

  const portalSession = await stripe.billingPortal.sessions.create({
    customer: customerId,
    return_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard`,
  });

  return Response.json({ url: portalSession.url });
}

Sample Prompts#

Task	Prompt
Stripe setup	"Set up Stripe integration with multiple pricing tiers"
Checkout	"Implement checkout flow for subscription purchases"
Webhooks	"Create webhook handler for subscription lifecycle events"
Portal	"Add customer billing portal integration"
Usage billing	"Implement usage-based billing with metered subscriptions"

Configuration#

// bootspring.config.js
module.exports = {
  agents: {
    customInstructions: {
      'payment-expert': `
        - Use Stripe for payment processing
        - Implement comprehensive webhook handling
        - Set up customer portal for self-service
        - Track subscription status in database
        - Handle failed payments gracefully
      `,
    },
  },
  payments: {
    provider: 'stripe',
    plans: ['free', 'pro', 'team', 'enterprise'],
  },
};

Backend Expert - API implementation
Database Expert - Subscription data management
Security Expert - Payment security