Recurring charges
Once you have a payment_token, each billing period is a normal create_payment_session call with
the token attached. The customer isn’t present and there’s no redirect—Truemed charges the card on
file.
Your system decides when to charge. Truemed decides whether the charge is allowed.
Charge a stored token
Pass payment_token instead of collecting customer details. Amounts are integers in cents.
A 200 means the charge was accepted, not that funds are secured. Use a distinct idempotency_key
per billing period so a retried request doesn’t double-charge.
order_items must match what you’re actually billing for on this charge. Unlike a normal card
payment, where only the amount matters, Truemed re-checks eligibility against the items on every
charge. The customer’s LMN covers specific items—anything outside it is blocked with a 422 and
next_action: "TakeHealthSurvey", and the billing period fails.
This catches people out in two ways:
- Reusing a hardcoded or stale
order_itemspayload across billing periods. It works until the subscription changes, then silently starts failing. - Changing the subscription in your system without telling Truemed. Call
update_payment_tokenat the moment items change, not at charge time—see Update a Subscription.
Authorize a renewal for multi-capture
Manual multi-capture reserves funds on saved cards and lets you collect each shipment separately.
For a paid renewal, add kind: "authorization" and request_multicapture: true to the request with payment_token.
The customer can remain absent, and you do not set tokenize: true again.
Your channel must support saved cards and multi-capture.
The combination requires a positive, non-trial amount and manual capture.
Automatic-capture or trial combinations return 400 InvalidRequestParameter.
A disabled required feature returns 400 FeatureNotEnabled.
Only requests that neither save nor reuse cards ignore the flag with automatic capture.
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, including a backup that covers a shortfall.
A card with a $0 order share does not affect availability.
If multicapture_available is true, send non-final captures with final: false until the last capture.
The session reports partially_captured while open.
Final capture or void releases unused holds, and earlier captures remain collected.
Read authorization_expires_at through session retrieval for the latest capture time.
Use Manual and Delayed Capture for recovery limits and refunds against each capture.
For create retries, token mode means saving cards, reusing a token, or neither.
If either request combines saved cards with multi-capture, keep the same token mode and multi-capture intent.
The supplied token identity must also match, and a mismatch returns 400 IdempotencyViolation, including after capture.
Requests that neither save nor reuse cards retain their existing retry behavior.
Fulfillment rules
Fulfill from the payment_session_complete webhook, exactly as with a one-time payment. A stored-token
charge returns no redirect_url—the field appears only on a 422, where it’s where you send the
customer to resolve the block.
Make fulfillment idempotent—webhooks are at-least-once, so the same status can arrive more than once. See Webhooks and Fulfillment for the full handler checklist.
Prevent failures before they happen
Truemed does not warn you before a token stops working, and does not email your customers. Catching expirations ahead of the charge is your job, and it’s the difference between a customer who renews and one who churns.
- Store expiration dates on every token. Keep
lmn_expires_atand the cardexpirationfromretrieve_payment_tokenalongside your subscription record. - Run a daily expiration sweep. Query
list_payment_tokenwithlmn_expires_beforeandcard_expires_beforeset about 30 days out.lmn_expires_beforeonly returns LMNs expiring between today and that date—already-lapsed ones are excluded, which is why you keep your own copy oflmn_expires_at. See Partner Operations. - Prompt those customers before their next charge. Email them a link generated with
update_payment_token, escalating as the date gets closer. For an expiring card sendupdate_card_info: true; for an expiring LMN sendrenew_eligibility: truewith the subscription’s currentorder_items, or the response comes backnext_action: "None"with nothing to link to. See Renew eligibility before the LMN expires. - Call
update_payment_tokenwhenever subscription items change—at the moment of the change, not at charge time. A cart change that falls outside the existing LMN blocks the next charge. See Update a Subscription.
When a charge fails
A blocked charge returns 422 with a next_action telling you what the customer has to do, and a
redirect_url to send them to. The customer isn’t present, so you’ll relay this by email and wait for
payment_token_updated before charging again.
Token Lifecycle covers every failure cause, the recovery loop, and suggested customer messaging.