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

# How subscriptions work

> How Truemed payment tokens let you bill HSA/FSA subscriptions on your own schedule.

A payment token is a stored, reusable authorization to charge a customer's HSA/FSA funds. You
provision it once while the customer is present to qualify and enter their card, then charge it on
your own billing schedule without them.

Truemed doesn't manage plans, invoices, proration, or retries—your system owns the subscription and
the schedule. Truemed owns one thing: whether this customer can pay for these items with HSA/FSA
funds right now.

> **Note**
>
> New to HSA/FSA payments? Read **[Core Concepts](/guides/overview/core-concepts)** first, and build the
> one-time payment flow in [Payment Sessions](/guides/setup/api/payment-sessions/before-you-begin)
> before adding subscriptions—the token flow builds directly on it.

## What you'll need

* [ ] **A working Payment Sessions integration.** Subscriptions reuse
  [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) and the same
  fulfillment rules. Get one-time payments working first.
* [ ] **A webhook endpoint subscribed to two events.** `payment_session_complete` tells you whether a
  charge cleared;
  [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) tells you
  when a token is usable. You need both.
* [ ] **Somewhere to store a token per customer.** One `payment_token` per subscription, alongside
  your own record of the billing schedule.
* [ ] **A way to act on `next_action`.** When a charge fails, Truemed returns an action and a URL. You
  need a path to get that in front of the customer—usually email plus a dashboard banner.

## Vocabulary

| Term                         | What it is                                                                                                                                                                                                                                                                         |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_token`              | The reusable authorization to charge HSA/FSA funds. Formatted `{environment}_token_{uuid}` — `tm_token_...` in production, `dev_tm_token_...` in sandbox.                                                                                                                          |
| `provision_token_request_id` | Returned when you provision a token for an existing subscriber. Identifies the setup request, not the token.                                                                                                                                                                       |
| `payment_session_id`         | A single charge. Every billing period creates a new one.                                                                                                                                                                                                                           |
| `failed_payment_session_id`  | On `payment_token_updated`, the charge that triggered a recovery—so you can match the webhook to the billing period you were retrying.                                                                                                                                             |
| `next_action`                | What the customer must do before the token can be charged: `UpdatePaymentMethod` or `TakeHealthSurvey`. `update_payment_token` always returns the field, using the string `"None"` when nothing is needed; `create_payment_session` omits the key entirely on a successful charge. |
| LMN                          | Letter of Medical Necessity. The clinical approval that makes items HSA/FSA-eligible. Expires, and is scoped to specific items. See the [glossary](/guides/overview/glossary).                                                                                                     |

## Choose your provisioning path

There are two ways to get a token, depending on where the customer is coming from.

| Your situation                                                       | Call                                                                                                     | What the customer sees                                      | Guide                                                                                            |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| The customer is subscribing and paying now                           | [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) with `tokenize: true` | One flow: survey, card entry, and the first charge together | [New Subscriber](/guides/setup/api/subscriptions/create-a-subscription-new-subscriber)           |
| The customer already subscribes with you and is switching to HSA/FSA | [`create_payment_token`](/api-reference/payment-tokens/create-payment-token)                             | Survey and card entry only—nothing is charged               | [Existing Subscriber](/guides/setup/api/subscriptions/create-a-subscription-existing-subscriber) |

Free trials use the first path with `total_amount: 0`. See
[New Subscriber](/guides/setup/api/subscriptions/create-a-subscription-new-subscriber#free-trials).

## How the flow works

#### Provision the token

Call one of the two endpoints above and redirect the customer to the `redirect_url` in the
response. The customer has to be present—this is where they qualify and enter their card.

#### The customer completes the survey and enters their card

Truemed runs the clinical intake and collects HSA/FSA card details, then returns the customer to
your `success_url`.

#### Wait for payment_token_updated

The webhook carries the `payment_token`—for example
`dev_tm_token_8a1f0c2e-77b4-4f0a-9c31-2f5c7a9d4e10`. Store it against the customer. Until it
arrives, you have no token. When you provision with `tokenize: true`, the same value also appears
on the `captured` `payment_session_complete` event, so you can correlate the two.

#### Charge on your schedule

Each billing period, call `create_payment_session` with the `payment_token`. No customer, no
redirect. Fulfill when `payment_session_complete` reports `status: captured`.

> **Warning**
>
> A token doesn't exist until `payment_token_updated` arrives. If the customer abandons the flow, or no
> LMN is issued, the webhook never fires and no token is ever provisioned. Don't treat a successful
> return to your `success_url`—or the `postMessage` in an embedded flow—as confirmation.

## Next steps

#### [New Subscriber](/guides/setup/api/subscriptions/create-a-subscription-new-subscriber)

Provision a token and take the first payment in one flow.

#### [Existing Subscriber](/guides/setup/api/subscriptions/create-a-subscription-existing-subscriber)

Qualify a customer who already subscribes, without charging them.