Stripe Payment

BuilderKit provides a seamless integration with Stripe for handling payments and subscriptions. This documentation will guide you through the process of setting up and using Stripe payment functionality in your application.

Prerequisites

Before proceeding with the Stripe integration, ensure that you have the following:

A Stripe (opens in a new tab) account with API keys (publishable key and secret key)
Stripe webhook secret for handling subscription events

You can obtain the API keys and webhook secret from your Stripe dashboard. Check the Stripe documentation (opens in a new tab) for more information on how to obtain these credentials.

Configuration

Set the required environment variables in your .env file:

Replace the placeholder values with your actual Stripe credentials:

.env

STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

Update the src/config.ts with your Stripe configuration details:

src/config.ts

const config = {
  // ...
  stripe: {
    baseUrl: "https://buy.stripe.com",
    emailParam: "prefilled_email",
    discountParam: "prefilled_promo_code",
    variant: {
      standard: {
        monthly: "test_bIY6rO5L4cb3dPi6oo",
        annually: "test_cN25nKddwcb3fXqaEF",
      },
      premium: {
        monthly: "test_28o7vSa1kdf7dPicMO",
        annually: "test_fZe3fCflEfnf8uYfZ1",
      },
    },
    plan: {
      prod_PuuU0reuFt6y8W: "standard",
      prod_P0jB4G8yniRIE2: "standard",
      prod_PuuWeAnbhCqCe2: "premium",
      prod_PuuVeP4vko8uhg: "premium",
    },
  },
  // ...
};

baseUrl: The base URL for Stripe checkout sessions.
emailParam: The parameter used to prefill the email input in the checkout form.
discountParam: The parameter used to prefill a promo code in the checkout form (optional).
variant: The mapping of subscription plans to their corresponding Stripe price IDs.
plan: The mapping of Stripe product IDs to subscription types.

Adjust the variant and plan mappings based on your Stripe product setup.

Webhook Handling

BuilderKit includes a webhook handler for processing Stripe subscription events. The webhook route is defined in src/app/api/webhooks/stripe/route.ts.

src/app/api/webhooks/stripe/route.ts

import config from '@/config';
import { EnumSubscriptionBillingCycle } from '@/types/types';
import { supabaseAdmin } from '@/utils/supabase/admin';
import { headers } from 'next/headers';
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
 
// Environment variables for Stripe API key and webhook secret.
const SECRET_KEY = process.env.STRIPE_SECRET_KEY;
const WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET;
 
// Stripe object initialization with TypeScript support enabled
const stripe = new Stripe(SECRET_KEY!, {
  typescript: true,
});
 
// Main function to handle POST requests from Stripe webhooks
export async function POST(req: NextRequest): Promise<NextResponse> {
  // ... Webhook handling logic ...
}
 
// Handles 'customer.subscription.created' event: Activates a subscription and updates the database.
async function handleSubscriptionCreated(subscription: Stripe.Subscription) {
  // ... Subscription creation handling logic ...
}
 
// Handles 'customer.subscription.updated' event: Updates the status of a subscription in the database.
async function handleSubscriptionUpdated(subscription: Stripe.Subscription) {
  // ... Subscription update handling logic ...
}

The webhook handler listens for the following events:

customer.subscription.created: Triggered when a new subscription is created. It activates the subscription and updates the corresponding details in the Supabase database.
customer.subscription.updated: Triggered when a subscription is updated. It updates the subscription status in the Supabase database.

Make sure to configure the webhook endpoint in your Stripe dashboard to point to the appropriate URL (e.g., https://your-domain.com/api/webhooks/stripe).

Payment Button Component

BuilderKit provides a reusable payment button component (ButtonPayment) that handles the payment flow for different subscription plans and frequencies.

The ButtonPayment component takes the following props:

provider: The payment gateway provider (e.g., 'stripe').
tier: The subscription plan (e.g., 'standard', 'premium').
frequency: The subscription billing frequency (e.g., 'monthly', 'annually').

Use the ButtonPayment component in your desired location, passing the required props:

<ButtonPayment provider="stripe" tier="standard" frequency="monthly" />

This will render a payment button that initiates the Stripe checkout process for the specified plan and frequency.

When the payment button is clicked, it checks the user's authentication status. If the user is not logged in, they are redirected to the login page. Otherwise, the payment URL is constructed based on the selected provider, plan, and frequency, with potential discounts applied for annual subscriptions via Stripe.

Conclusion

That's it! You now have Stripe payment integration set up in your BuilderKit application. Users can select a subscription plan, choose a billing frequency, and proceed with the payment using Stripe. The webhook handler will process the subscription events and update the corresponding details in the Supabase database.

Pinecone Lemon Squeezy