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

💡

If you're just getting started, be sure to create an API Key in test mode to safely distinguish between testing and production.

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.withflex.com/v1/products \
  --header 'authorization: Bearer fsk_test_YzNiYjdhNWItN2FkOS00ZTMyLWE5MmQtZTdhNzMzYzE2NTIy' \
  --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.withflex.com/v1/prices \
  --header 'authorization: Bearer fsk_test_YzNiYjdhNWItN2FkOS00ZTMyLWE5MmQtZTdhNzMzYzE2NTIy' \
  --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.withflex.com/v1/checkout/sessions \
  --header 'authorization: Bearer fsk_test_YzNiYjdhNWItN2FkOS00ZTMyLWE5MmQtZTdhNzMzYzE2NTIy' \
  --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.

How Checkout Works Fulfillment