> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# How Truemed checkout works

> The end-to-end Truemed checkout flow — create a payment session, redirect the customer, and fulfill from the webhook.

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

| Integration piece                                                                               | What it does                                                           |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`create_payment_session`](/api-reference/payment-sessions/create-payment-session)              | Creates the hosted Truemed checkout session.                           |
| `redirect_url`                                                                                  | Sends the customer to Truemed to verify eligibility and pay.           |
| `success_url`                                                                                   | Returns the customer to your confirmation page after checkout.         |
| `failure_url`                                                                                   | Returns the customer to your checkout if they cannot complete payment. |
| [`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) | Tells your server when the payment status changes.                     |

> **Warning**
>
> 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`:

| Where it appears                        | Field name               |
| --------------------------------------- | ------------------------ |
| `create_payment_session` response       | `id`                     |
| Capture, void, cancel, and status paths | `{business_id}`          |
| `payment_session_complete` webhook      | `payment_id`             |
| `success_url` / `failure_url` templates | `{{payment_session_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.

> **Note**
>
> Don't confuse the payment session `id` with the `payment_token` (`tm_token_...`) in the same response. The
> token is a separate identifier for [recurring billing](/guides/setup/api/subscriptions/overview)—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`](/api-reference/payment-sessions/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)](/guides/setup/api/payment-sessions/i-frame-payment-session).

#### 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.

#### Confirm the result by webhook

Truemed sends `payment_session_complete` whenever the payment session status changes. Your
backend should update the order based on the webhook status.

#### Fulfill only after capture

For the default one-time payment flow, fulfill the order when the webhook sends
`status: captured`. If the webhook sends `status: rejected`, cancel the order and notify the
customer.

## First payment vs. full lifecycle

Start with the smallest working path, then add deeper payment behavior when your checkout needs it.

| If you need to...                                   | Read this                                                                                                   |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Build the first working payment flow                | [Accept Your First Payment](/guides/setup/api/payment-sessions/accept-your-first-payment)                   |
| Validate launch readiness                           | [Implementation Readiness Checklist](/guides/setup/api/payment-sessions/implementation-readiness-checklist) |
| Handle webhook verification and fulfillment         | [Webhooks and Fulfillment](/guides/setup/api/payment-sessions/webhooks-and-fulfillment)                     |
| Understand all payment statuses                     | [Payment Lifecycle](/guides/setup/api/payment-sessions/payment-lifecycle)                                   |
| Authorize now and capture later                     | [Manual/Delayed Capture](/guides/setup/api/payment-sessions/manual-delayed-capture)                         |
| Show fees, discounts, shipping, and tax in checkout | [Itemized Fees and Discounts](/guides/setup/api/payment-sessions/itemized-fees-and-discounts)               |
| Refund, cancel, or void a payment                   | [Refunds, Cancels, and Voids](/guides/setup/api/payment-sessions/refunds-cancels-and-voids)                 |