Stripe Custom Payment Methods Overview - Flex Documentation
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)
- Customer enters payment details directly in the Payment Element
- Payment is confirmed inline using Stripe.js
- Customer remains on your domain throughout the process
- Stripe handles 3D Secure authentication via modals
Flex (Redirect Model)
- Customer selects Flex from the Payment Element
- Your backend creates a Flex checkout session
- Customer is redirected to Flex’s hosted checkout page
- After payment, Flex redirects back to your success page
Integration Components
| Flex Selected | Other Methods | Your Checkout Page |
|---|---|---|
| Credit Card | ||
| Apple Pay | ||
| Google Pay | ||
| Flex (Custom Payment Method) | ||
| Customer Info Form | Submit Payment Button | Payment Method |
| Selected? | Create Flex Checkout Session | Create Stripe Payment Intent |
| Redirect to Flex Hosted Checkout | Confirm Payment Inline (Stripe.js) | Return to Success Page |
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
- Set up your Stripe account
- Ensure you have a Stripe account with the Payment Element integration enabled.
- Configure the custom payment method
- Create a custom payment method in the Stripe Dashboard and obtain your custom payment method ID.
- Install and configure
- Follow the installation guide to set up the required dependencies and environment variables.
- Implement the integration
- Follow the custom payment methods guide for step-by-step implementation instructions with code examples.
Support
If you need assistance with this integration:
- Review the Stripe Custom Payment Methods documentation
- Check the Flex API documentation
- Contact Flex support for help with your integration.