Introduction to the Flex API

The Flex API allows you to integrate HSA/FSA payment capabilities directly into your application. This guide covers the basics of how to get started with the API, authentication, and core concepts.

​

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

​

Base URL

All API requests should be made to the following base URL:

https://api.withflex.com/v1

​

Content type

API requests with a request body should specify the content type:

Content-Type: application/json

​

Test mode

Flex provides a test mode environment that allows you to test your integration without processing real payments. Test mode API keys start with fsk_test_, while production API keys start with fsk_.

​

API response format

All API responses are returned in JSON format. Successful responses will include the requested resource(s), while error responses will include an error code and message.

Example successful response:

{
  "checkout_session": {
    "checkout_session_id": "fcs_01HW5KTQQAAQ66WV19MFW4DTT4",
    "status": "complete",
    "amount_total": 4999,
    "redirect_url": "https://checkout.withflex.com/pay/c/fcs_01HW5KTQQAAQ66WV19MFW4DTT4",
    "mode": "payment"
    // ...other properties
  }
}

Example error response:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: price"
  }
}

​

Rate limits

The Flex API enforces rate limits to ensure stability. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. The response headers will include information about when you can retry.

​

Core resources

The Flex API is organized around these core resources:

​

Next steps

Explore these guides to learn more about specific aspects of the Flex API:

For a complete reference of all API endpoints, see the API Reference section.