> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Before you begin

> What you need — an API key, a server, and a webhook endpoint — before building with the Payment Sessions API.

The Payment Sessions API lets you accept HSA/FSA payments in your own checkout. You create a payment
session from your server, redirect the customer to Truemed to verify eligibility and pay, and
receive the final result by webhook. This page covers what to have in hand before you write any code.

> **Note**
>
> New to HSA/FSA payments? Read **[Core Concepts](/guides/overview/core-concepts)** first—it explains
> how a payment session works and the key terms used throughout these guides.

## What you'll need

* [ ] **An API key.** Sign in at [dev.truemed.com](https://dev.truemed.com/developers/api-keys) and
  create a sandbox key to build and test, then switch to a production key to go live.
* [ ] **A server to call the API.** Create payment sessions from your backend, never from the
  browser—your API key is a secret and must not be exposed client-side.
* [ ] **A webhook endpoint.** A publicly reachable URL on your server that receives
  `payment_session_complete` events. This is how you learn the final payment result and decide when
  to fulfill.
* [ ] **A way to redirect the customer.** Your checkout sends the customer to the Truemed-hosted
  `redirect_url` and provides a `success_url` and `failure_url` to return them to your site.

## Environments

Build and test against dev with a sandbox key, then switch to production for live payments. The
request and response shapes are identical across environments.

| Environment   | Base API URL                               | Dashboard                                                                 |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
| Dev (sandbox) | `https://dev-api.truemed.com/payments/v1/` | [dev.truemed.com/developers](https://dev.truemed.com/developers/api-keys) |
| Production    | `https://api.truemed.com/payments/v1/`     | [app.truemed.com/developers](https://app.truemed.com/developers/api-keys) |

## Authentication

Every API request is authenticated with your Truemed API key, passed in the `x-truemed-api-key`
header. Keep the key in an environment variable or secrets manager—never hard-code it or commit it
to source control.

```bash
curl https://dev-api.truemed.com/payments/v1/create_payment_session \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
  -d '{ ... }'
```

A sandbox key only works against the dev base URL, and a production key only works against
production. Switching environments means swapping both the base URL and the key.

## Set up your webhook

Truemed reports the final payment result by webhook, not in the API response. The minimum setup:

1. In the [Developer Dashboard](https://dev.truemed.com/developers/webhooks), create a webhook
   pointing at your endpoint URL.
2. Subscribe it to the `payment_session_complete` event.
3. Save the signing secret (signed webhooks, recommended) so you can verify inbound requests.

That's enough to receive payment results. For signature verification, retries, unsigned webhooks,
and the full event catalog, see the [Webhooks guide](/guides/setup/api/resources/webhooks).

## Next steps

#### [How Truemed Checkout Works](/guides/setup/api/payment-sessions/how-truemed-checkout-works)

See the full flow end to end—create, redirect, return, and confirm by webhook.

#### [Accept Your First Payment](/guides/setup/api/payment-sessions/accept-your-first-payment)

The shortest path to a working payment, with copy-paste request examples.