> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withflex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Installation and Setup

> Set up Flex as a Stripe custom payment method in your application.

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

<Steps>
  <Step title="Navigate to the Stripe Dashboard">
    Log in to your [Stripe Dashboard](https://dashboard.stripe.com) and navigate to **Settings → Payments → Custom Payment Methods**.
  </Step>

  <Step title="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
  </Step>

  <Step title="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`
  </Step>
</Steps>

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

## Step 2: Install Required Dependencies

### For JavaScript/TypeScript Projects

Install the Stripe client libraries:

```bash theme={null}
npm install @stripe/stripe-js @stripe/react-stripe-js stripe
```

Or using yarn:

```bash theme={null}
yarn add @stripe/stripe-js @stripe/react-stripe-js stripe
```

Or using pnpm:

```bash theme={null}
pnpm add @stripe/stripe-js @stripe/react-stripe-js stripe
```

### Additional Dependencies (Optional)

For form validation and schema management:

```bash theme={null}
npm install react-hook-form zod @hookform/resolvers
```

For UUID generation (used in order tracking):

```bash theme={null}
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 .env.local theme={null}
# 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
```

<Warning>
  **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.
</Warning>

## Step 4: Create Constants File

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

```typescript lib/constants.ts theme={null}
export const CURRENCY = "usd";
export const FLEX_CUSTOM_PAYMENT_METHOD_ID = "cpmt_1RFYhqIVh7O1TOu8IP4pAWbm"; // Replace with your ID
```

<Info>
  Replace the `FLEX_CUSTOM_PAYMENT_METHOD_ID` with the ID you copied from the Stripe Dashboard in Step 1.
</Info>

## 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 theme={null}
{
  "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"
    }
  ]
}
```

<Note>
  **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.
</Note>

## Step 6: Set Up Stripe Server Instance

Create a server-side Stripe instance for backend operations:

```typescript lib/stripe.ts theme={null}
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",
  },
});
```

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

## Step 7: Set Up Stripe.js Client Instance

Create a client-side Stripe.js instance:

```typescript lib/get-stripejs.ts theme={null}
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

## Next Steps

With your environment configured, you're ready to implement the payment flow. Continue to the [Custom Payment Methods guide](/developer-guides/integration/stripe/custom-payment-methods) for detailed implementation instructions.

## 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)