## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.withflex.com/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:

- A Stripe account with access to the Dashboard
- A Flex account with API credentials
- Node.js 18.17.1 or higher (for JavaScript/TypeScript implementations)
- An existing web application or checkout flow

## Step 1: Create Custom Payment Method in Stripe

1. Navigate to the Stripe Dashboard

Log in to your [Stripe Dashboard](https://dashboard.stripe.com/) and navigate to **Settings → Payments → Custom Payment Methods**.

2. Create a new custom payment method

Click **Add custom payment method** and configure:

- **Display Name**: Enter “Flex”
   - **Logo**: Upload the Flex logo
     - Ensure the logo is visible against light and dark backgrounds
     - Recommended size: At least 32x32 pixels
     - Include rounded corners if using a filled background
     - For transparent backgrounds, consider the background color for visibility

3. 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):

```bash
# 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:

```typescript
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:

```json
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:

```typescript
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:

```typescript
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:

- [ ] Custom payment method created in Stripe Dashboard
- [ ] Custom payment method ID saved in constants file
- [ ] Dependencies installed
- [ ] Environment variables configured
- [ ] Stripe server and client instances created
- [ ] Product/pricing data configured

## Troubleshooting

### Custom payment method not showing in Payment Element

- Verify the custom payment method ID is correct
- Ensure the ID is properly passed to the Elements configuration
- Check that the custom payment method is enabled in your Stripe Dashboard

### Environment variables not loading

- Restart your development server after adding environment variables
- Verify the variable names match exactly (including prefixes)
- For Next.js, ensure `.env.local` is in your project root

### Stripe.js not loading

- Check your browser console for errors
- Verify your publishable key is correct
- Ensure you’re using the correct environment key (test vs. production)