Docs
Payments
Stripe Integration

Stripe Payment Setup Guide

Overview

This guide provides a detailed walkthrough for setting up Stripe payments in your application. It covers everything from account creation to webhook configuration, ensuring a smooth integration process for both test and live environments.

Table of Contents

  1. Set Up Stripe Account
  2. Create Product
  3. Webhook and Stripe Environment Variables Setup
  4. Supabase Environment Variables Setup
  5. Payment Settings in settings.js

Set Up Stripe Account

  1. Sign up for Stripe

    • Begin by signing up on Stripe and creating a new account. Provide your business name and country of operation.
    stripe_pic1

  2. Complete Your Profile

    • Fill out your profile details in Stripe, including bank payout information. When setting up payouts, you can choose a schedule that suits your needs (e.g., weekly on Mondays).
    stripe_pic2

  3. Account Verification

    • The approval and verification process for your Stripe account might take a few days. Subsequent accounts for new startups usually get approved much faster.
    • We recommend making new accounts for every new startup that you launch.

  4. Public Business Details

    • Navigate to Settings > Business > Public details
    • Fill in customer support email, support URL, website, privacy policy URL, and terms of service URL.
    stripe_pic5

  5. Branding

    • Customize your branding by going to Settings > Business > Branding.
    • Add your company icon and logo.
    • Ensure the logo and icon have transparent backgrounds to look professional across various Stripe-hosted pages.
    • Set your brand and accent colors to match your website.
    stripe_pic6

  6. Customer Emails

    • In Settings > Business > Customer emails, enable emails for successful payments & refunds.
    stripe_pic7

  7. Subscriptions and Emails

    • Under Settings -> Billing -> Subscriptions and Emails, select "Send emails about upcoming renewals" and "Send emails about expiring cards".
    stripe_pic8
    • Optionally, it is recommended to enable 3D Secure for billing payments that match Radar rules.
    stripe_pic9

  8. Customer Portal

    • Activate the Customer Portal by going to Settings > Billing > Customer Portal.
    • Click on "Activate Link"
    stripe_pic10
    • Customer Portal activation must be repeated separately for both test and live modes since the activation is independent for each environment.

  9. Fraud Prevention

    • Go to Settings > Radar and enable Radar for Fraud Teams. This is recommended to prevent fraudulent transactions, though it may slightly reduce conversion rates. Radar services will cost a few cents per transaction.
    stripe_pic11
    • Additionally, under Radar > Rules, you can enable the recommended 3D Secure rules:
      • First Rule: Request 3DS if 3D Secure is recommended for card. Enabling this rule is advisable.
      • Second Rule: Request 3DS if 3D Secure is supported for card. While optional, enabling this rule can reduce fraud, though it may slightly lower the conversion rate.
    stripe_pic12
    • Ensure that the following Block Rules are enabled:
      • Block if :risk_level: = 'highest'
      • Block if payment matches one or more values in default Stripe block lists
      • Block if CVC verification fails
    stripe_pic13

Create Product

Test mode

Test mode allows you to simulate transactions during the development phase. You can test all features before going live.

  1. Toggle test mode on

    stripe_pic14

  2. Go to Product catalog and click "Add Product"

  3. Fill in product details

    • Fill in the required information: Name, Description, Payment Mode (Recurring or One-off), and Amount
    stripe_pic15
    • Recurring payment is for subscription models. Set the billing period (e.g., monthly, yearly) according to your needs.

  4. Copy the price-id from the product page

    • Inside the product, click on the price to view the price-id. Copy the price-id.
    stripe_pic16

Live Mode

This is the mode you want to use in production. Follow the same steps as Test Mode, but with test mode toggled off.

Webhook and Stripe Environment Variables Setup

Test mode

  1. Set environment variables

    • Open the .env.local file in your project's root folder. If it doesn't exist, rename .env.example to .env.local.
    • In Stripe, ensure Test Mode is on. Navigate to Developers > API Keys and copy the Publishable Key and Secret Key.
    stripe_pic17
    • Set the keys in .env.local as follows:
      • STRIPE_PUBLIC_KEY: Publishable Key from Stripe
      • STRIPE_SECRET_KEY: Secret Key from Stripe
    • If you're working in a live test server, you might configure this key differently, such as within the server's environment variable settings.

  2. Set up webhooks:

    • Configure Webhooks in Stripe by going to Developers > Webhooks. Webhooks listen to Stripe events like checkout completions and invoice payments.

    • You can listen to Stripe events in two ways while in test mode: a. Using Stripe CLI:

      • Click on "Test in a local environment"
      stripe_pic18
      • Download and install Stripe CLI following this tutorial: Stripe CLI Documentation (opens in a new tab).
      • Run stripe login in your terminal (on Mac) or PowerShell (on Windows).
      • Forward events to your webhook by using the following command: stripe listen --forward-to localhost:3000/api/payments/stripe/webhook
      • Set STRIPE_WEBHOOK_SECRET in .env.local as the value of the endpoint_secret in the sample endpoint.
      stripe_pic19
      • Keep the terminal or PowerShell open so it can listen for Stripe events.

      b. Using a live endpoint:

      • Click "Add an endpoint" and type your endpoint URL (https://www.yourdomain.com/api/payments/stripe/webhook).
      stripe_pic20
      • Click on "Select Events" to choose the events you want to listen to.
      • Select all checkout events, customer events, and invoice events, then click "Add Events."
      stripe_pic21
      • Then click "Add Endpoint." Click "Reveal" to view your signing secret.
      stripe_pic22
      • Set STRIPE_WEBHOOK_SECRET in .env.local as the signing secret. If you're working in a live test server, you might configure this key differently, such as within the server's environment variable settings.
      • Now, Stripe events for payments will be listened to by the above endpoint. Make sure your website is deployed at https://www.yourdomain.com (opens in a new tab).

Live Mode

  • Toggle Test Mode off in Stripe.
  • Repeat the process above with your live keys and endpoints.

  1. Set environment variables

    • Navigate to Developers > API Keys and copy the Publishable Key and Secret Key.
    stripe_pic23
    • Set the keys in .env.local as follows:
      • STRIPE_PUBLIC_KEY: Publishable Key from Stripe
      • STRIPE_SECRET_KEY: Secret Key from Stripe
    • If you're working in a live server, you might configure this key differently, such as within the server's environment variable settings.

  2. Set up webhooks:

    • Configure Webhooks in Stripe by going to Developers > Webhooks. Webhooks listen to Stripe events like checkout completions and invoice payments.
    • Click "Add an endpoint" and type your endpoint URL (https://www.yourdomain.com/api/payments/stripe/webhook).
    stripe_pic20
    • Click on "Select Events" to choose the events you want to listen to.
    • Select all checkout events, customer events, and invoice events, then click "Add Events."
    stripe_pic21
    • Then click "Add Endpoint." Click "Reveal" to view your signing secret.
    stripe_pic22
    • Set STRIPE_WEBHOOK_SECRET in .env.local as the signing secret. If you're working in a live server, you might configure this key differently, such as within the server's environment variable settings.
    • Now, Stripe events for payments will be listened to by the above endpoint. Make sure your website is deployed at https://www.yourdomain.com (opens in a new tab).

Supabase Environment Variables Setup

We use Supabase to store customer information. Ensure the following keys are configured:

  • NEXT_PUBLIC_SUPABASE_URL: Your Supabase project URL
  • SUPABASE_SERVICE_ROLE_KEY: Your Supabase service role key

For more details, refer to the Supabase setup guide: Supabase Setup Guide.

Supabase Configuration

  • To enable Webhooks, we need to create tables to manage customer data, set up essential RPC functions, and configure triggers to handle payments and subscriptions.
  • For detailed instructions, refer to the Supabase configuration guide: Supabase Configuration Guide.

Payment Settings in settings.js

The settings.js file, located at /settings.js is the central configuration file for your StartupBolt application. This file contains various settings that control different aspects of your app, allowing for easy customization and management of your project's core parameters. It is important to update these configuration values as per your product or service.

  1. PAYMENT_PROVIDER
  • Set this to Stripe: 
    const PAYMENT_PROVIDER = "Stripe";
  1. NO_AUTH_CHECKOUT
  • Set this to true if you want to enable checkout for users who are not authenticated (i.e., not signed in).
  • Enabling checkout without authentication is usually recommended, as it reduces the number of steps users need to take to purchase your product. However, the decision is yours.
  • If you prefer to collect emails from users before they proceed to checkout, this can be a good strategy, though it may lower your conversion rate. 
    const NO_AUTH_CHECKOUT = true; // Enable checkout without authentication
// or
const NO_AUTH_CHECKOUT = false; // Require authentication for checkout
  1. PLAN_DETAILS
  • This is where you configure the various payment plans.
   const PLAN_DETAILS = [
     {
       name: "Plan Name",
       price: 147,
       anchorPrice: 197,
       currency: "USD",
       pricePeriod: "monthly", // Leave empty for one-off payments
       description: "Product Description",
       features: [
         { name: "Feature 1", hasFeature: true },
         // ... more features
       ],
       payment: {
         id: "stripe_price_id",
         credits: 100, // Default is 100, can be changed
         rollover: false, // Credits are refilled, not rolled over
         mode: "payment", // Use "subscription" for recurring payments
         couponId: "stripe_coupon_id",
       },
       isPopular: true
     },
     // ... more plans
   ];
  • Credits: Set to any number (default 100). Access to the product is granted if credits are greater than 0.
  • Rollover:
    • false: Credits are refilled on payment, access lost if subscription lapses.
    • true: Unused credits carry over, access maintained until credits are depleted.
  • Mode: Use "payment" for one-off payments, "subscription" for recurring payments.
  • CouponId:
    • Create coupons in Product Catalog > Coupons (separate for test and live modes).
    • If you don't include a couponId, customers can apply their own coupon codes. For more details, refer to the Coupons Documentation
  • You can also send the PLAN_DETAILS array as a prop to the PricingTable module. Feel free to refer to the PricingTable Module Documentation for more details.
  • Also, you can pass a single object from the PLAN_DETAILS array as a prop to the PayButton module. Feel free to refer to the PayButton Module Documentation for more details.

By following this guide, you'll have a comprehensive Stripe payment setup integrated into your application, covering both test and live environments.

IconsLemonSqueezy Integration