Skip to navigation

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.

StateWhat it meansWhat to do
ProvisioningTruemed still needs to save a card. The timing depends on the capture mode and the sales channel configuration.Wait for payment_token_updated. A charge returns 400 SessionPending during setup.
ActiveThe token is chargeable. It stays chargeable if the first order is later voided, canceled, or expires.Charge it each billing period.
Needs customer actionA charge came back 422 with a next_action.Send the customer to the redirect_url, then wait for payment_token_updated.
DeletedYou called delete_payment_token.Nothing—this is terminal. Charging returns NotFound.

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.

Charge outcomeHTTP responsenext_actionToken state
Charge accepted200 with the payment session idomittedActive
Card expired or declined422UpdatePaymentMethodNeeds customer action
Cart contains ineligible items with no backup card422UpdatePaymentMethodNeeds customer action
Items changed beyond what the LMN covers422TakeHealthSurveyNeeds customer action
The LMN on file has expired422TakeHealthSurveyNeeds customer action
Token is not ready yet400 SessionPending—Provisioning
Token was deleted404 NotFound—Deleted

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:

{
"id": "c51f5d44-9f8d-4e9f-bc5f-929a6f9f2f51",
"redirect_url": "https://app.truemed.com/...",
"next_action": "UpdatePaymentMethod"
}

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.

next_actionSuggested subjectSuggested body
UpdatePaymentMethodUpdate your payment methodYour HSA/FSA card couldn’t be charged for this month’s order. Update your card to keep your subscription active.
TakeHealthSurveyRequalify to keep using HSA/FSA fundsYour Letter of Medical Necessity no longer covers your subscription. Take a short health survey to requalify.

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

1

The charge returns 422

Read next_action and redirect_url from the response body, and store the id of the failed payment session.

2

Send the customer to the redirect_url

Either inline or by email, depending on whether they’re on your site—see below.

3

The customer resolves the block

They update their card or retake the survey on Truemed’s hosted pages.

4

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.

5

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.

Updating Payment Method Flow
Updating Payment Method Flow

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, using next_action to 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 422 every time until the customer acts.
Re-qualification Flow
Re-qualification Flow

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.

1

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.

curl --get "https://api.truemed.com/api/v1/payment_tokens" \
--data-urlencode "email=alex@example.com" \
--data "page_size=100" \
--data "page=1" \
-H "x-truemed-api-key: $TRUEMED_API_KEY"
2

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.

curl --get "https://api.truemed.com/payments/v1/payment_sessions" \
--data-urlencode "payment_token=$PAYMENT_TOKEN" \
--data-urlencode "search=$PAYMENT_SESSION_ID" \
-H "x-truemed-api-key: $TRUEMED_API_KEY"

Leave filter_voided at its default of false so the response includes the original session after you void it.

3

Select the token when exactly one candidate matches

If exactly one candidate lists the original checkout ID, select its payment_token for future charges.

4

Stop if you cannot confirm one token

If the original checkout ID is missing, leave the token unselected. Do the same if zero or several candidates match that ID. Wait for payment_token_updated if setup is still pending.

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.

CauseWhat it means
Setup is still pendingTruemed has yet to save a card. The customer can have a pending LMN, or the channel can require capture before Truemed saves the card. On channels that save cards at approval, Truemed can still be retrying the card save.
The order closed before letter approvalYou voided the order, or its hold expired, before Truemed approved a required LMN. Truemed does not save a card for this checkout. Stop waiting for its payment_token_updated webhook.
No matchThe search used a different account email or a key for another sales channel.
The token was deletedYou called delete_payment_token. Deletion is final.

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.

NeedRead this
Charge a token on your billing scheduleRecurring Charges
Let a customer change their card or itemsUpdate a Subscription
Monitor expirations and cancel subscriptionsPartner Operations
Every payment session statusPayment Lifecycle
Webhook verification and retriesWebhooks
Test the failure and recovery pathsTesting