Stripe Installation and Setup - Flex Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

This guide will walk you through setting up Flex as a Stripe custom payment method in your application.

Prerequisites

Before you begin, ensure you have:

Step 1: Create Custom Payment Method in Stripe

  1. Navigate to the Stripe Dashboard

Log in to your Stripe Dashboard and navigate to Settings → Payments → Custom Payment Methods.

  1. Create a new custom payment method

Click Add custom payment method and configure:

  1. Save and copy the Custom Payment Method ID

After creating the custom payment method, Stripe will generate a unique ID starting with cpmt_. Copy this ID - you’ll need it for your integration. Example ID format: cpmt_1RFYhqIVh7O1TOu8IP4pAWbm

The custom payment method ID is different from your Stripe API keys. Store it as a constant in your application code.

Step 2: Install Required Dependencies

For JavaScript/TypeScript Projects

Install the Stripe client libraries:

npm install @stripe/stripe-js @stripe/react-stripe-js stripe

Or using yarn:

yarn add @stripe/stripe-js @stripe/react-stripe-js stripe

Or using pnpm:

pnpm add @stripe/stripe-js @stripe/react-stripe-js stripe

Additional Dependencies (Optional)

For form validation and schema management:

npm install react-hook-form zod @hookform/resolvers

For UUID generation (used in order tracking):

npm install uuid

Step 3: Configure Environment Variables

Create or update your environment configuration file (.env.local for Next.js or .env for other frameworks):

# Stripe Configuration
STRIPE_SECRET_KEY=sk_test_... # Your Stripe secret key (server-side only)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_... # Your Stripe publishable key

# Flex Configuration
FLEX_SECRET_KEY=your_flex_secret_key # Your Flex API secret key (server-side only)

# Application Configuration
NEXT_PUBLIC_BASE_URL=http://localhost:3000 # Your application base URL

Security Best Practice: Never expose secret keys to the client side. Only keys prefixed with NEXT_PUBLIC_ (or your framework’s equivalent) should be accessible in the browser.

Step 4: Create Constants File

Create a file to store your custom payment method ID and other constants:

export const CURRENCY = "usd";
export const FLEX_CUSTOM_PAYMENT_METHOD_ID = "cpmt_1RFYhqIVh7O1TOu8IP4pAWbm"; // Replace with your ID

Replace the FLEX_CUSTOM_PAYMENT_METHOD_ID with the ID you copied from the Stripe Dashboard in Step 1.

Step 5: Configure Product and Pricing Data

Example structure - This shows one way to organize product data. Your structure may differ based on your needs:

data.json
{
  "plans": [
    {
      "name": "monthly",
      "price": 2999,
      "plan_id": "plan_monthly_001",
      "flex_price_id": "fprice_01js70gpb0m40qd316gwp9e6g0"
    },
    {
      "name": "annual",
      "price": 29900,
      "plan_id": "plan_annual_001",
      "flex_price_id": "fprice_01js70j4gqjqbgre2r08xb7j1n"
    }
  ]
}

What you actually need: Data to create Flex checkout sessions. This requires Flex price IDs (from your Flex Dashboard) and product information. Structure this data however works best for your application - JSON file, database, CMS, etc. Flex supports both one-time and recurring payments.

Step 6: Set Up Stripe Server Instance

Create a server-side Stripe instance for backend operations:

import "server-only"; // Prevents accidental client-side imports
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  appInfo: {
    name: "your-app-name",
  },
});

The "server-only" import ensures this module can never be accidentally imported in client-side code, protecting your secret keys.

Step 7: Set Up Stripe.js Client Instance

Create a client-side Stripe.js instance:

import { loadStripe, Stripe } from "@stripe/stripe-js";

let stripePromise: Promise<Stripe | null>;

export default function getStripe(): Promise<Stripe | null> {
  if (!stripePromise) {
    stripePromise = loadStripe(
      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY as string
    );
  }
  return stripePromise;
}

This singleton pattern ensures Stripe.js is only loaded once, improving performance.

Verification

After completing these steps, verify your setup:

Troubleshooting

Custom payment method not showing in Payment Element

Environment variables not loading

Stripe.js not loading