stripe-handler

name	stripe-handler
description	Handle Stripe payments, custom checkouts, and webhook fulfillment outside of standard plans/credits.
deps	["plans-handler","credits-handler","inngest-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:
  1. Extract metadata from the event object.
  2. Check if metadata.type matches your custom feature.
  3. If yes: Run your fulfillment logic.
     • Simple Logic: Update DB directly.
     • Heavy Logic: Dispatch an Inngest event to handle it in the background.
  4. If no: Let the function fall through to standard plan/credit handling.

4. Background Processing (Inngest)

Recommended for production: If your fulfillment logic involves multiple DB calls, external APIs, or could timeout (Stripe expects a response in < 3s):

• Use inngest-handler to create a new function.
• In the webhook, just dispatch the event:

  await inngest.send({ name: "app/payment.custom_succeeded", data: { sessionId: object.id, metadata } });
  

• Handle the actual logic in src/inngest/functions/....

5. Database Updates

• If the purchase grants access to a resource, update the corresponding schema (e.g., orders, courses).
• Ensure the fulfillment is idempotent (handle duplicate webhook events gracefully).

6. Frontend Integration

• Use a simple Button or Form to call your API/Action.
• Redirect the user to the returned url (Stripe Checkout).

Best Practices

• Idempotency: Webhooks can fire multiple times. Ensure your logic checks if the order is already fulfilled.
• Metadata: Rely on metadata, not just product IDs, for cleaner logic separation.
• Timeouts: Stripe webhooks must respond quickly. Use Inngest for anything taking > 2 seconds.
• Testing: Use stripe listen to test webhooks locally.

Reference

See reference.md for code snippets on creating sessions, handling webhooks, and using Inngest.