Payment SessionsGet started

Before You Begin

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.

New to HSA/FSA payments? Read 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 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.

EnvironmentBase API URLDashboard
Dev (sandbox)https://dev-api.truemed.com/payments/v1/dev.truemed.com/developers
Productionhttps://api.truemed.com/payments/v1/app.truemed.com/developers

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.

$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, 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.

Next steps

How Truemed Checkout Works

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

Accept Your First Payment

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