For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
This guide walks you through installing and configuring Truemed on your WooCommerce store. Once complete, “Pay with HSA/FSA (Truemed)” appears as a payment option at checkout, alongside your existing payment methods.
The full setup takes most merchants about an hour, plus time for testing.
Prerequisites
Before you begin, make sure you have:
Confirmation from your Truemed contact that you’re cleared to begin installation
Your sandbox and production API keys (you’ll generate these during setup)
WordPress admin access with permissions to install plugins
Your WooCommerce store running on a publicly accessible domain (required for webhooks)
Step 1: Install the Truemed Plugin
The Truemed Payments plugin is published in the WordPress Plugin Directory. You can install it directly from your WordPress admin or download the zip and upload it manually.
Option A: Install from WordPress admin (recommended)
In WordPress, go to WooCommerce → Settings → Payments
Find Truemed Payments in the list and click Manage
Paste your sandbox API key into the Truemed API Key field
Check the Enable Test Mode box
Click Save changes
Test mode only works with a sandbox API key. Mixing a sandbox key with test mode disabled (or a production key with test mode enabled) will cause transactions to fail.
Step 3: Configure the Webhook URL
The plugin generates a webhook URL specific to your store. Register that URL in your Truemed admin so Truemed can notify your store when an LMN is approved or a payment status changes.
On the same Truemed plugin settings page, copy the Webhook URL shown
Add the webhook URL you copied from the WooCommerce plugin page under Endpoint URL
Choose Unsigned under Payload Signing
Choose payment_session.updated under Events
Check the I understand the endpoint could not be verified. Save anyway. box
Save
You’ll repeat this step with your production webhook URL when you go live (Step 7).
Step 4: Enable Truemed at Checkout
On the Truemed plugin settings page, click the Enable toggle
Save changes
Truemed now appears as a payment option on your checkout page. In sandbox mode, only test transactions will work.
Step 5: Add the Product Page Widget
The product page widget educates shoppers about HSA/FSA eligibility right where purchase intent is highest. It signals that the product may qualify for HSA/FSA reimbursement and links to a “Learn how” explainer.
Get your Public Qualification ID
Find your Public Qualification ID in your integration guide or ask your Truemed contact.
Add the widget code
Paste this snippet into your product page template, replacing YOUR_PUBLIC_QUALIFICATION_ID:
Place a small live order from your storefront to confirm the production flow works end to end
Truemed is now live for your customers.
Don’t skip the live test order. Sandbox and production are separate environments, and a webhook misconfigured in production will leave real customer orders stuck in Pending Payment.
Step 8: Handle Subscriptions (If Applicable)
The Truemed WooCommerce plugin does not currently support subscription products at checkout. Subscription customers can still get an LMN through Truemed, but the flow happens after purchase.
Surface a Truemed reimbursement link on your order confirmation page and in your order confirmation email. After purchasing, the customer clicks the link, completes the Truemed clinical intake form, and if an independent licensed practitioner determines medical necessity, an LMN is issued for the customer to submit to their HSA/FSA administrator.
Get your reimbursement link
Find your Qualification Link in your integration guide or ask your Truemed contact.
Add the link to your order confirmation page
Add a snippet like this to your WooCommerce Thank You page (typically via the woocommerce_thankyou hook in your theme’s functions.php or through a code snippets plugin):
1
<p>This order may be eligible for HSA/FSA reimbursement. <a href="YOUR_QUALIFICATION_LINK?source=order_confirm">Get reimbursed with Truemed</a>.</p>
Add the link to your order confirmation email
In WordPress, go to WooCommerce → Settings → Emails
Find Processing order (or Completed order, depending on your fulfillment flow) and click Manage
Add the same snippet to the Additional content field, or override the email template in your theme
Verify Your Setup
After completing setup, run through this checklist:
Truemed is set to Enabled in WooCommerce → Settings → Payments
If you sell subscriptions, the reimbursement link appears on the order confirmation page and email
Managing Orders
Once Truemed is live, you’ll manage Truemed orders directly from the standard WooCommerce orders dashboard.
Order statuses
Status
Meaning
Pending Payment
Customer has not completed Truemed checkout
On Hold
Customer has completed checkout and is waiting on LMN approval or rejection
Processing
LMN approved and payment authorized; order is ready to fulfill
Expired
The authorization hold expired before capture; the order can no longer be charged
Truemed authorization holds are valid for 6.95 days. If an order isn’t captured within that window, the auth expires and Truemed does not re-authorize. Capture orders promptly to avoid expirations.
Order actions
From any Truemed order, you can:
Cancel an order before capture
Refund an order after capture (full or partial)
Capture an order manually (if manual capture is enabled)
Manual capture
By default, Truemed captures payment automatically once the LMN is approved. If you’d prefer to capture manually (for example, on ship), enable it in the Truemed plugin settings under Capture Method. With manual capture enabled, approved orders sit in On Hold until you trigger the capture from the order dashboard.
Need Help?
Implementation questions: Reach out to your Truemed implementation contact
