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

# API

## Docs

- [Setup guide (API)](https://developers.truemed.com/v-1/guides/setup/api/setup-guide.md): Implement Truemed directly via the API for custom and non-standard commerce platforms.
- [Before you begin](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/before-you-begin.md): What you need — an API key, a server, and a webhook endpoint — before building with the Payment Sessions API.
- [How Truemed checkout works](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/how-truemed-checkout-works.md): The end-to-end Truemed checkout flow — create a payment session, redirect the customer, and fulfill from the webhook.
- [Accept your first payment](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/accept-your-first-payment.md): The shortest path to a working Truemed payment — create a session, redirect the customer, and fulfill from the webhook.
- [Webhooks and fulfillment](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/webhooks-and-fulfillment.md): How to use the payment session webhook as the fulfillment boundary, and keep fulfillment idempotent across retries.
- [Payment lifecycle](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/payment-lifecycle.md): Every payment session status, what it means, and what to do next.
- [Manual and delayed capture](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/manual-delayed-capture.md): How to authorize a payment at checkout and capture it later, when you're ready to fulfill.
- [Itemized fees and discounts](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/itemized-fees-and-discounts.md): How to pass itemized fees, discounts, and taxes to create_payment_session so Truemed can show a full breakdown at checkout.
- [Refunds, cancels, and voids](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/refunds-cancels-and-voids.md): How to cancel, void, or refund a Truemed payment session depending on where it is in the payment lifecycle.
- [Embedded checkout (iFrame)](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/i-frame-payment-session.md): How to render the Truemed payment session inline with an iFrame instead of redirecting the customer to a hosted page.
- [Testing](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/testing.md): How to test the full Truemed payment flow in the sandbox before going live.
- [Implementation readiness checklist](https://developers.truemed.com/v-1/guides/setup/api/payment-sessions/implementation-readiness-checklist.md): A pre-launch checklist covering checkout, fulfillment, webhooks, and reconciliation for your Truemed integration.
- [Overview](https://developers.truemed.com/v-1/guides/setup/api/product-catalog/overview.md): How the Product Catalog API classifies your SKUs for HSA/FSA eligibility and powers storefront integrations.
- [Build HSA/FSA-eligible collections](https://developers.truemed.com/v-1/guides/setup/api/product-catalog/use-cases/build-hsa-fsa-eligible-collections.md): How to use Truemed's eligibility data to build a dedicated HSA/FSA-eligible collection on your storefront.
- [Conditionally show the PDP widget](https://developers.truemed.com/v-1/guides/setup/api/product-catalog/use-cases/conditionally-show-the-pdp-widget.md): How to conditionally render Truemed's HSA/FSA widget on product pages based on real eligibility data.
- [Checkout page messaging](https://developers.truemed.com/v-1/guides/setup/api/product-catalog/use-cases/checkout-page-messaging.md): How to show HSA/FSA checkout messaging only when the customer's cart contains eligible items.
- [Managing your catalog](https://developers.truemed.com/v-1/guides/setup/api/product-catalog/managing-your-catalog.md): How to add, update, and look up products in the Truemed product catalog using the API.
- [How subscriptions work](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/overview.md): How Truemed payment tokens let you bill HSA/FSA subscriptions on your own schedule.
- [Create a subscription (new subscriber)](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/create-a-subscription-new-subscriber.md): Provision a payment token and take the first payment in a single flow.
- [Create a subscription (existing subscriber)](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/create-a-subscription-existing-subscriber.md): Qualify a customer who already subscribes with you, and store their HSA/FSA card without charging them.
- [Recurring charges](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/subsequent-billing-periods.md): Charge a stored payment token on your own billing schedule, and keep tokens chargeable over time.
- [Token lifecycle](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/token-lifecycle.md): What each payment token state means, and how to get a customer back to a chargeable token.
- [Update an active subscription](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/update-an-active-subscription.md): Let customers change their card on file or their subscribed items without breaking eligibility.
- [Partner operations](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/partner-administrative-operations.md): List subscriptions, monitor expirations, and cancel tokens — the operational surface behind your subscriptions.
- [Testing](https://developers.truemed.com/v-1/guides/setup/api/subscriptions/testing.md): Run a full token lifecycle in the sandbox — provision, charge, break, and recover — before going live.
- [Update a qualification session](https://developers.truemed.com/v-1/guides/setup/api/qualification-sessions/update-a-qualification-session.md): How to attach a user_id, update metadata, or adjust redirect URLs on an existing qualification session.
- [Overview](https://developers.truemed.com/v-1/guides/setup/api/reconciliations/overview.md): How to use the Reconciliations API to tie Truemed payouts and transactions back to your own ledger.
- [Overview](https://developers.truemed.com/v-1/guides/setup/api/disputes/overview.md): How Truemed's Disputes API lets merchants list, respond to, and resolve chargebacks from their own systems.
- [List and retrieve disputes](https://developers.truemed.com/v-1/guides/setup/api/disputes/list-and-retrieve.md): How to list, filter, and retrieve disputes, and update their metadata, scoped to your sales channel.
- [Response payloads](https://developers.truemed.com/v-1/guides/setup/api/disputes/payloads.md): A fully-populated look at the detail and list shapes the Disputes API returns, so you can model your integration against the complete response.
- [Respond with evidence](https://developers.truemed.com/v-1/guides/setup/api/disputes/respond-with-evidence.md): How to draft, autosave, and submit dispute evidence through the counter lifecycle.
- [Upload evidence files](https://developers.truemed.com/v-1/guides/setup/api/disputes/upload-evidence-files.md): How to upload dispute evidence files through the Files API and reference them from a counter.
- [Accept a dispute](https://developers.truemed.com/v-1/guides/setup/api/disputes/accept-a-dispute.md): How to concede a dispute loss without contesting it, and what states allow accepting.
- [Webhooks and polling](https://developers.truemed.com/v-1/guides/setup/api/disputes/webhooks.md): How Truemed notifies you of dispute activity in real time, and the recommended notify-then-fetch pattern.
- [Webhooks](https://developers.truemed.com/v-1/guides/setup/api/resources/webhooks.md): How Truemed delivers webhook events — signed vs. unsigned authentication methods, envelope format, and signature verification.
- [Developer tools](https://developers.truemed.com/v-1/guides/setup/api/resources/developer-tools.md): Download the Truemed OpenAPI specification for use with API clients, SDK generators, and offline reference.