How Truemed Checkout Works
Truemed Checkout lets customers pay with HSA/FSA funds through a hosted payment flow. You create a payment session from your server, redirect the customer to Truemed, and receive the final payment result by webhook.
The key integration pattern is simple: use the redirect for the customer experience, and use the webhook for fulfillment decisions.
The integration surface
Do not fulfill from the success_url redirect alone. Fulfill only after the
payment_session_complete webhook sends status: captured.
One ID, several field names
A payment session has a single identifier—the id returned when you create it. The same value
reappears under different field names depending on where you encounter it, but it is always that one
id:
Store the id on your order when you create the session. You will use it to match the webhook, call
capture/void/cancel, and reconcile later.
Don’t confuse the payment session id with the payment_token (pt_...) in the same response. The
token is a separate identifier for recurring billing—not for
managing this payment session.
How the flow works
Create a payment session
When the customer chooses Truemed at checkout, call
create_payment_session from your
server with the cart total, order items, customer details, success_url, and failure_url.
Redirect the customer to Truemed
Send the customer to the redirect_url returned in the response. Truemed collects the health
survey details and HSA/FSA card information needed to process the payment. Prefer to keep
customers on your site? Render the same flow inline with
Embedded Checkout (iFrame).
Return the customer to your site
Truemed redirects the customer to your success_url or failure_url so your site can show the
right customer-facing message.
First payment vs. full lifecycle
Start with the smallest working path, then add deeper payment behavior when your checkout needs it.