Flex Checkout Quick Start
Flex Checkout is our low-code integration to accept HSA/FSA payments.
At this point you should have a flex account, access to the partner dashboard, and have gone through the onboarding process of adding your payout information with Stripe.
Below we walk through a full example of how to integrate Flex Checkout into your checkout flow.
Create an API Key in the partner dashboard
In the partner dashboard, navigate to the Developers section. Here we will find an API Keys tab where you can create an API Key to interact with Flex.
Select the New API Key button and give your API Key a name. With this key we can now interact with
the Flex API.
Define a product to sell
Always keep sensitive information about your product inventory, such as price and availability, on your server to prevent customer manipulation from the client. Define product information when you create the Checkout Session using predefined price IDs or on the fly with price_data.
For this example we've created a product that is eligible via a letter of medical necessity. To learn more about creating products and their eligibility review the Product docs or Product API.
curl --request POST \
--url https://api-stg.withflex.com/v1/products \
--header 'authorization: Bearer fsk_MzkxYzU2MTAtZGYxOC00OWUyLThlODQtYTA0ODMwNjhiYmVm' \
--header 'content-type: application/json' \
--data '{"product": {"name": "Test Product","description": "Test Product Description","visit_type": "gym","hsa_fsa_eligibility": "letter_of_medical_necessity"}}'The response we get back is:
{
"product": {
"product_id": "fprod_01HW5MXAPBE79RHMMJJGB4ACAB",
"name": "Test Product",
"description": "Test Product Description",
"created_at": "2024-04-23T14:14:16.029253Z",
"visit_type": "gym",
"active": true,
"upc_code": null,
"gtin": null,
"hsa_fsa_eligibility": "letter_of_medical_necessity"
}
}Define the price for our product
Given the product_id that was returned to in the previous payload we'll define a one time price for $50.99.
curl --request POST \
--url https://api-stg.withflex.com/v1/prices \
--header 'authorization: Bearer fsk_MzkxYzU2MTAtZGYxOC00OWUyLThlODQtYTA0ODMwNjhiYmVm' \
--header 'content-type: application/json' \
--data '{"price": {"product": "fprod_01HW5MXAPBE79RHMMJJGB4ACAB","description": "Our awesome new price","unit_amount": 5099}}'The response we get back is:
{
"price": {
"price_id": "fprice_01HW5NTAB88NK7HPD0H688EPG9",
"description": "Our awesome new price",
"unit_amount": 5099,
"recurring": null,
"active": true,
"product": "fprod_01HW5MXAPBE79RHMMJJGB4ACAB",
"created_at": "2024-04-23T14:30:05.943282Z",
"type": "one_time",
"metadata": null
}
}
Choose the mode
Checkout has two modes: payment or subscription. Use payment mode for one-time purchases.
Learn more about subscription and setup modes in the docs.
Supply success and cancel URLs
Specify URLs for success and cancel pages—make sure they’re publicly accessible so Flex can redirect customers to them. You can also handle both the success and canceled states with the same URL.
success_url: https://withflex.com/thank-you?success=true
cancel_url: https://withflex.com/thank-you?canceled=true
Build your checkout
On your site you should have an order preview page. On the order preview page you will add a button that will trigger your server to generate a checkout session.
Generate a checkout session
On the server you will generate a checkout session.
curl --request POST \
--url https://api-stg.withflex.com/v1/checkout/sessions \
--header 'authorization: Bearer fsk_MzkxYzU2MTAtZGYxOC00OWUyLThlODQtYTA0ODMwNjhiYmVm' \
--header 'content-type: application/json' \
--data '{"checkout_session": {"line_items": [{"price": "fprice_01HW5NTAB88NK7HPD0H688EPG9","quantity": 1}],"success_url": "https://withflex.com/thank-you?success=true","mode": "payment","cancel_url": "https://withflex.com/thank-you?canceled=true",}}'Redirect users to checkout
The response we got back looks like:
{
"checkout_session": {
"allow_promotion_codes": false,
"amount_total": 5099,
"amount_subtotal": 5099,
"cancel_url": "https://withflex.com/thank-you?canceled=true",
"capture_method": "automatic",
"checkout_session_id": "fcs_01HW5Q2A08N6A0YGZ6T1KARN8S",
"created_at": 1713883916,
"customer": null,
"customer_email": null,
"expires_at": 1713887516,
"invoice_id": null,
"hsa_fsa_eligible": true,
"letter_of_medical_necessity_required": true,
"metadata": null,
"mode": "payment",
"multiple_subscriptions": false,
"payment_intent_id": null,
"redirect_url": "https://checkout.withflex.com/pay/c/fcs_01HW5Q2A08N6A0YGZ6T1KARN8S",
"setup_intent": null,
"shipping_options": null,
"shipping_address_collection": false,
"shipping_details": null,
"status": "open",
"success_url": "https://withflex.com/thank-you?success=true",
"subscription": null,
"tax_rate": null,
"test_mode": false,
"total_details": {
"amount_discount": 0,
"amount_tax": null,
"amount_shipping": null
},
"visit_type": "gym"
}
}Try it out
Navigate to the redirect_url and use any of these tests cards to simulate a payment.
Payment succeeds: 4242424242424242
Payment is decline: 4000000000009995
Congratulations!
You have a basic checkout integration working!
Next Steps
Fulfillment
Set up a webhook to fulfill orders after a payment succeeds.
Explore checkout sesession scenarios
Depending on your setup/business you may want to rely on additional parameters that are avaialable as part of the Checkout Session API. Some of the common scenarios, can be found here.