Stripe Handler

Stripe Handler

Use this skill when you need to implement payment logic using Stripe, specifically for use cases that are NOT standard SaaS subscription plans or standard Credit packages (which are handled by plans-handler and credits-handler respectively).

When to use

• Implementing "Buy One-time Product" flows (e.g., Courses, Digital Goods).
• Creating custom "Service" payments.
• Handling checkout.session.completed for custom metadata.
• Customizing src/app/api/webhooks/stripe/route.ts for non-standard events.
• Offloading heavy webhook processing to background tasks (via Inngest).

Process

1. Identify Payment Type

Before writing code, determine the nature of the payment:

• Is it a Subscription Plan? -> Use plans-handler.
• Is it a Credit Package? -> Use credits-handler.
• Is it a Custom One-time or Recurring Product? -> Continue with this skill.

2. Create Checkout Session (API/Action)

You need a server-side endpoint to create the Stripe Checkout Session.

• File: Create a new route (e.g., src/app/api/app/orders/create/route.ts) or Server Action.
• Import: import stripe from "@/lib/stripe";
• Metadata: CRITICAL. Always attach metadata to the session to identify the purchase type in the webhook.

  metadata: {
    type: "my_custom_feature",
    userId: user.id,
    customId: "..."
  }
  

• URLs: Use the standard success/error pages or custom ones if needed.
  • Success: ${process.env.NEXT_PUBLIC_APP_URL}/app/subscribe/success?session_id={CHECKOUT_SESSION_ID}
  • Error: ${process.env.NEXT_PUBLIC_APP_URL}/app/subscribe/error

3. Handle Webhook Fulfillment

All Stripe events go to src/app/api/webhooks/stripe/route.ts.

• File: src/app/api/webhooks/stripe/route.ts
• Locate: onCheckoutSessionCompleted (for one-time) or handleOutsidePlanManagementProductInvoicePaid (for invoices).
• Implement: