Token lifecycle
A payment token is either chargeable or blocked on something the customer has to do. When it’s blocked, Truemed tells you which action is needed and where to send the customer. Your job is to relay that action and wait for the token to come back.
This page is the reference for every way a token can stop working and how to recover it. For the happy path, see Recurring Charges.
Token states
These state names are a model for reasoning about tokens, not values returned by the API. There is no
status field on a payment token—you infer the state from your charge results and the
payment_token_updated webhook.
How a charge maps to token state
One table for the whole picture: what you get back from
create_payment_session when charging a
token, and what it tells you about the token.
SessionPending is not permanent. It means the token is not ready, so Truemed has no payment method
to charge yet. Retry the charge once payment_token_updated arrives.
When you create a token with tokenize: true, it becomes ready after Truemed saves the card.
- With automatic capture, Truemed saves the card when it captures the first payment.
- With manual capture (
kind: authorization), you can recover the token before capture if your sales channel saves cards at approval. Truemed waits for the card issuer to approve the hold and for approval of any required Letter of Medical Necessity (LMN). If your channel saves cards at capture, lookup can find the token after you capture the first payment.
On channels that save cards at approval, Truemed sends payment_token_updated with the original
payment_session_id once it saves the card. If the card save needs a retry, the approval notification
can arrive before the token is ready. Truemed sends the token update once the card save succeeds.
A later capture does not send a second setup notification.
A token that became usable stays usable if the first order is later voided, canceled, or expires.
Only delete_payment_token ends it.
A 200 means the charge was accepted for processing—it does not mean funds are secured. Fulfill only
after the payment_session_complete webhook reports status: captured, exactly as with a one-time
payment. See Payment Lifecycle.
Manual multi-capture orders
Multi-capture collects an authorization in parts while the order stays open.
An enabled channel can combine request_multicapture: true with initial tokenize: true or a later payment_token.
Both combinations require kind: "authorization" and a positive, non-trial amount.
Automatic-capture or trial combinations return 400 InvalidRequestParameter, and disabled required features return 400 FeatureNotEnabled.
After authorization, read multicapture_available through
session retrieval or payment_session_complete webhooks.
The create response omits it.
Every card funding the order must support multi-capture, and a card saved with a $0 order share does not affect availability.
Successful non-final captures leave the session partially_captured and open for later captures.
Final capture or void releases unused holds, including verification holds on saved cards.
Read Manual and Delayed Capture for capture deadlines and refunds against individual captures.
The 422 response
The body of a 422 is the same shape as a successful create_payment_session response, with
next_action and redirect_url populated:
Read next_action to decide what to tell the customer, and redirect_url to decide where to send
them. Store the id—it’s the payment session that failed, and it comes back to you as
failed_payment_session_id when the customer resolves the block.
Why a charge fails
Two next_action values cover every recoverable failure.
UpdatePaymentMethod
The customer’s card can no longer cover the charge.
Common causes
- The HSA/FSA card on file has expired.
- The card was declined.
- The cart contains ineligible items and there’s no credit or debit card on file to cover them.
What the customer must do. Visit the redirect_url and enter current card details. If the charge
failed because of ineligible items, they’ll be asked for a regular credit or debit card as a backup
alongside their HSA/FSA card.
Suggested message. “Your payment method needs updating to keep your subscription active.”
TakeHealthSurvey
The customer’s Letter of Medical Necessity no longer covers what they’re buying.
Common causes
- The items in the subscription changed and fall outside the existing LMN.
- The existing LMN has expired.
- Truemed has determined the customer needs to retake the survey for another reason.
What the customer must do. Visit the redirect_url and complete the health survey again. A new
LMN is issued if they still qualify.
Suggested message. “Requalify with Truemed to keep using your HSA/FSA funds.”
What to tell the customer
Truemed doesn’t email your customers—you do. Adapt this copy to your voice; it’s a starting point, not a requirement.
Include the redirect_url as the call to action in both cases. The link is specific to this customer
and this failure—don’t reuse one across customers.
Recover the subscription
The charge returns 422
Read next_action and redirect_url from the response body, and store the id of the failed
payment session.
Send the customer to the redirect_url
Either inline or by email, depending on whether they’re on your site—see below.
The customer resolves the block
They update their card or retake the survey on Truemed’s hosted pages.
Wait for payment_token_updated
The webhook carries the payment_token and the failed_payment_session_id of the charge that
triggered the recovery, so you can match it back to the billing period you were retrying.
Resubmit the charge
Resend the same create_payment_session call with the same idempotency_key. Truemed charges the
failed payment session and returns the same id. If the order changed since the failure, send it with
a new idempotency_key instead, then cancel the failed session with
Cancel Payment Session.
Retrying the charge before payment_token_updated arrives returns the same 422. The webhook is the
signal that the customer’s action actually landed.
A customer can also resolve a block without ever touching your app—for instance by following a link
from an older email. Treat payment_token_updated as a stand-down signal: when it arrives, clear any
banner, dashboard warning, or scheduled reminder you raised for that token. Otherwise you’ll keep
chasing customers who already fixed the problem.
If the customer is on your site
Surface the redirect_url immediately, inside the flow they’re already in. This applies when the
charge was triggered by something the customer just did—changing their plan, adding an item, or
checking out. Send them straight to Truemed and bring them back to your success_url.
This is also the right path for a subscription-management dashboard. See Update an active subscription for generating an update link on demand rather than waiting for a charge to fail.

If the customer is not on your site
This is the recurring-charge case, and the one most integrations need to get right: the charge runs on your billing schedule, so by definition the customer isn’t present.
- Email the
redirect_url, usingnext_actionto pick the message. - Don’t re-drive the charge on a timer. Wait for
payment_token_updated, then charge. - If you retry on a schedule anyway, expect the same
422every time until the customer acts.

Most of these failures are avoidable. See Prevent failures before they happen for the monitoring job that catches expiring cards and LMNs before a charge breaks.
Recover a token after a missed webhook
If you miss the payment_token_updated webhook for a checkout with tokenize: true, use these steps
to recover its token without charging the customer.
You need the email on the customer’s Truemed account and the id that
create_payment_session returned for the
original checkout. You can use the email you sent as customer_email if it matches the account email.
Use the API key for the sales channel that created the original checkout.
List the tokens for the account email
Call list_payment_token with the account
email in email. Start at page=1 and set page_size=100. Request each page through
pagination.last_page. Keep each distinct payment_token as a candidate. A token can appear on
two pages if a new token arrives between your requests, so count it once.
Check each candidate for the original checkout ID
For each candidate, call the list payment sessions
endpoint. Set payment_token to the candidate. Set search to the original checkout ID. Compare
that ID with each id in the payment_sessions array.
Leave filter_voided at its default of false so the response includes the original session
after you void it.
Even a single result needs the original checkout ID check. The list can show an older token while
setup for the new token is pending. The response customer_email can be a separate delivery address.
An empty result from list_payment_token can mean one of four things. The response does not say which.
If the customer never finished setup, see When no webhook ever arrives.
After Truemed saves the card, you can still recover the active token if you void the original order or the order expires.
When no webhook ever arrives
Provisioning a token can fail silently from your side: you call create_payment_session with
tokenize: true, the customer is redirected, and no payment_token_updated ever comes.
That means one of:
- The customer abandoned the health survey.
- The customer never entered card details.
- The customer didn’t qualify for the items in their cart, so no LMN was issued.
This isn’t specific to subscriptions—the same thing happens with any payment session where the customer doesn’t finish. Don’t hold a subscription open indefinitely waiting for the webhook. Time it out and prompt the customer to start over.
If a token exists but its payment_token_updated webhook never arrived, see
Recover a token after a missed webhook.