> ## 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 Custom Payment Methods Overview

> Learn how to integrate Flex as a Stripe custom payment method alongside traditional payment options.

## What are Stripe Custom Payment Methods?

Stripe Custom Payment Methods allow you to display your own payment options alongside Stripe's 50+ preset payment methods through a single Payment Element integration. This enables you to offer Flex as a payment option while maintaining a unified checkout experience with traditional payment methods like credit cards, Apple Pay, and Google Pay.

## How Flex Integrates with Stripe

Flex appears as a custom payment method within Stripe's Payment Element, allowing customers to choose between:

* **Traditional payment methods** (handled by Stripe): Credit cards, debit cards, Apple Pay, Google Pay, etc.
* **Flex** (handled by Flex API): HSA/FSA payment processing with eligibility verification

When a customer selects Flex, they are redirected to Flex's hosted checkout page to complete their payment. For traditional payment methods, the payment is processed inline using Stripe's embedded elements.

## Benefits of This Integration

### Unified Checkout Experience

* Single Payment Element displays all payment options
* Consistent UI/UX across payment methods
* Reduced development complexity

### Flexible Payment Routing

* Automatically route payments to the appropriate processor based on customer selection
* No need for separate checkout flows or conditional rendering logic
* Seamless handling of both embedded (Stripe) and redirect (Flex) payment models

### Reporting and Reconciliation

* Optionally record Flex transactions in Stripe using the Payment Records API
* Unified reporting across all payment methods
* Simplified back-office workflows

## Architecture Overview

### Payment Flow Models

**Stripe (Embedded Model)**

1. Customer enters payment details directly in the Payment Element
2. Payment is confirmed inline using Stripe.js
3. Customer remains on your domain throughout the process
4. Stripe handles 3D Secure authentication via modals

**Flex (Redirect Model)**

1. Customer selects Flex from the Payment Element
2. Your backend creates a Flex checkout session
3. Customer is redirected to Flex's hosted checkout page
4. After payment, Flex redirects back to your success page

### Integration Components

```mermaid theme={null}
flowchart TD
    A["Your Checkout Page"] --> B["Stripe Payment Element<br/>○ Credit Card<br/>○ Apple Pay<br/>○ Google Pay<br/>○ Flex (Custom Payment Method)"]
    B --> C["Customer Info Form"]
    C --> D["Submit Payment Button"]

    D --> E{"Payment Method<br/>Selected?"}

    E -->|"Flex Selected"| F["Create Flex<br/>Checkout Session"]
    E -->|"Other Methods"| G["Create Stripe<br/>Payment Intent"]

    F --> H["Redirect to Flex<br/>Hosted Checkout"]
    G --> I["Confirm Payment<br/>Inline (Stripe.js)"]

    H --> J["Return to Success Page"]
    I --> J

    style E fill:#e1f5ff
    style F fill:#fff4e6
    style G fill:#fff4e6
    style J fill:#e8f5e9
```

## When to Use This Integration

This integration is ideal if you:

* Already use Stripe for traditional payment processing
* Want to add Flex (HSA/FSA) as an additional payment option
* Need a unified checkout experience across multiple payment methods
* Want to minimize frontend complexity by leveraging Stripe's Payment Element
* Need to support both embedded and redirect payment flows

## Next Steps

<Steps>
  <Step title="Set up your Stripe account">
    Ensure you have a Stripe account with the Payment Element integration enabled.
  </Step>

  <Step title="Configure the custom payment method">
    Create a custom payment method in the Stripe Dashboard and obtain your custom payment method ID.
  </Step>

  <Step title="Install and configure">
    Follow the [installation guide](/developer-guides/integration/stripe/installation) to set up the required dependencies and environment variables.
  </Step>

  <Step title="Implement the integration">
    Follow the [custom payment methods guide](/developer-guides/integration/stripe/custom-payment-methods) for step-by-step implementation instructions with code examples.
  </Step>
</Steps>

## Support

If you need assistance with this integration:

* Review the [Stripe Custom Payment Methods documentation](https://docs.stripe.com/payments/payment-element/custom-payment-methods)
* Check the Flex API documentation
* Contact Flex support for help with your integration