How subscriptions work

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.

New to HSA/FSA payments? Read Core Concepts first, and build the one-time payment flow in Payment Sessions before adding subscriptions—the token flow builds directly on it.

What you’ll need

A working Payment Sessions integration. Subscriptions reuse 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 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.

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` with `tokenize: true`	One flow: survey, card entry, and the first charge together	New Subscriber
The customer already subscribes with you and is switching to HSA/FSA	`create_payment_token`	Survey and card entry only—nothing is charged	Existing Subscriber

Free trials use the first path with total_amount: 0. See New Subscriber.

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.

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

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

Existing Subscriber

Qualify a customer who already subscribes, without charging them.