Set up Truemed (HSA/FSA) payments
Truemed lets your customers pay for eligible products with money from their Health Savings Account (HSA) or Flexible Spending Account (FSA). At checkout the customer chooses Truemed (HSA/FSA), answers a short health survey on Truemed's site, and pays with their HSA or FSA card. When a product needs a Letter of Medical Necessity (LMN), Truemed arranges it with a practitioner, so you don't have to.
Because Truemed may review the payment before it collects the money, a Truemed order waits in Pending Clearance until Truemed captures it. How Truemed orders work explains that part. This page covers setup.
Before you start
You need a Truemed merchant account, with the products you sell classified for HSA/FSA eligibility in Truemed's dashboard. Each product's SKU in Truemed must be the same as its item ID in UltraCart, because that is how UltraCart matches Truemed's decisions to your items. Truemed matches SKUs exactly, including upper and lower case, so type each SKU the way the item ID appears in UltraCart. A GTIN is optional. You also need access to the Developers section of that dashboard, where you create an API key and a webhook. If you don't see it, ask Truemed to enable it for your account.
Truemed has two separate environments, each with its own dashboard. Sandbox is for testing and Production takes real payments. Keys from one don't work in the other, so set up Sandbox first, then repeat the API key and webhook steps in the Production dashboard when you go live.
- Sandbox dashboard: dev.truemed.com/developers
- Production dashboard: app.truemed.com/developers
Turn on Truemed and add your API key
Truemed is configured on the payments page, under its own Truemed (HSA/FSA) section.
- Go to Configuration → Checkout → Payments.
- Scroll to Truemed (HSA/FSA) and turn on the toggle.
- Click Settings to open Truemed Settings.
- Set Truemed Environment to Sandbox while you test, or Production for live payments.
- In the Truemed dashboard for the same environment, open Developers → API Keys, create a key, and paste it into Truemed API Key.
- Close the dialog and click Save at the bottom of the page.
Saving with Truemed turned on creates your webhook URL, which you need for the next step. It appears in Truemed Settings once the page reloads after the save.
Connect the Truemed webhook
Truemed tells UltraCart when a payment is captured or rejected by sending a signed webhook to a URL that belongs to your account. Without it, orders still clear, but only when UltraCart checks with Truemed on its own schedule.
- On Configuration → Checkout → Payments, open Truemed (HSA/FSA) → Settings again.
- Next to Webhook URL, click Copy.
- In the Truemed dashboard for the same environment, open Developers → Webhooks and add a webhook. Paste the URL you copied.
- Set Payload Signing to Signed. UltraCart only accepts signed webhooks.
- Select all the events, then click Create. UltraCart acts on payment session updates and item eligibility updates, and records the other events in its Truemed integration log, so subscribing to every event is safe.
- Truemed shows the webhook's signing secret once you click Create. Copy it.
- Back in Truemed Settings, paste it into Webhook Signing Secret.
- Close the dialog and click Save.
Saved keys are shown masked. Leave a masked value as it is to keep the stored key, or paste a new one to replace it.
Keep the webhook URL private, and don't turn Truemed off while orders are waiting for review. Turning Truemed off removes its settings. Turning it back on creates a new webhook URL, and you must update the webhook in Truemed's dashboard and paste a new signing secret.
UltraCart only offers Truemed at checkout once Truemed Environment, Truemed API Key and Webhook Signing Secret are all set, and only for carts that contain an HSA/FSA eligible item.
Choose which carts can use Truemed
Two more options in Truemed Settings control which carts are offered Truemed. Both start turned off. Change them, close the dialog and click Save.
| Setting | When it's on | When it's off |
|---|---|---|
| Subscriptions: My Truemed account supports payment tokens | Carts with an auto order item or an auto order upsell can pay with Truemed, and each rebill is charged through Truemed. See Subscriptions (auto orders). | Truemed isn't offered for those carts. Carts without auto order items aren't affected. |
| Eligibility: Only offer Truemed when every item is HSA/FSA eligible | Every paid item in the cart must be Eligible or Eligible with LMN. Free items and a kit's $0 components don't count, so a kit is judged by the kit item. | One eligible item is enough. Truemed asks the customer for a regular card for the part that isn't eligible. |
Truemed's payment tokens must be turned on for your Truemed account before subscriptions can work, and Truemed has no way for UltraCart to check. Ask Truemed to confirm that tokenization is enabled, then turn on Subscriptions. Until then, leave it off so customers with a subscription in their cart choose another payment method instead of reaching an error at Truemed.
Developers can set these through the REST API as subscriptions_enabled and require_all_items_eligible on the Truemed payments configuration.
Mark which products are HSA/FSA eligible
Truemed only makes sense for a cart that HSA/FSA funds can pay for, so UltraCart shows Truemed at checkout only when at least one item in the cart is HSA/FSA eligible. Each item records its eligibility in the HSA/FSA Eligibility setting in the item editor, in the Advanced section of the Item tab:
| Value | Meaning |
|---|---|
| Unknown | Not reviewed yet. Counts as not eligible, which matches Truemed: it treats products it hasn't reviewed as ineligible. |
| Eligible | Customers can pay for it with HSA/FSA funds. |
| Eligible with LMN | Customers can pay with HSA/FSA funds once they have a Letter of Medical Necessity (LMN), which Truemed arranges during checkout. |
| Not eligible | HSA/FSA funds can't pay for it. |
You normally don't set this yourself. When Truemed finishes reviewing a product in your Truemed catalog, it sends a webhook, and UltraCart updates the item whose item ID matches the product's SKU. Each update is recorded in the Truemed integration log with the old and new value. A product whose SKU doesn't match an UltraCart item ID is logged and skipped.
Set it by hand when Truemed's webhook can't do it for you:
- Products Truemed reviewed before you connected the webhook. Truemed only sends the webhook when a review finishes, so UltraCart never heard about those. Set them in the item editor, or in bulk with an item import using the
hsaFsaEligibilitycolumn (eligible,eligible_with_lmnorineligible; leave it blank for Unknown). Developers can setpayment_processing.hsa_fsa_eligibilitythrough the REST API. - Products you sell but haven't sent to Truemed. They stay Unknown, so they don't make a cart eligible.
A value you set by hand stays until Truemed reviews that product again, then Truemed's answer replaces it.
Kits are matched by the kit's own item ID. At checkout UltraCart sends a kit to Truemed as one line at the kit price, so add the kit's item ID to your Truemed catalog. Its components don't need to be there. Truemed's clinical team classifies each product, and a kit sold as one item is usually approved as eligible when its main device is.
Offer Truemed in your StoreFront checkout
Once it is configured, Truemed appears in the checkout payment method element of a StoreFront Visual Builder checkout, shown with the Truemed logo and the text "Pay with HSA/FSA". Customers who choose it are sent to Truemed when they submit the order.
To change the wording or hide the option on a particular checkout, edit the checkout payment method element in StoreFront Visual Builder:
- To change the text under the option, edit Truemed Details in the element's Text settings. Keep it within Truemed's messaging rules for HSA/FSA claims.
- To hide Truemed from that checkout, open Payment Method: Truemed (HSA/FSA) and set Omit to Yes.
- To show other elements on the page while Truemed is selected, add them to Show Content in the same group.
To promote HSA/FSA payment on product pages, wrap a badge or message in an item condition element set to hsa/fsa eligible, so it shows only on eligible products. Use hsa/fsa eligible with lmn for products that need a Letter of Medical Necessity. In the cart and checkout item list, the checkout item condition element offers the same pair as item hsa/fsa eligible and item hsa/fsa eligible with lmn.
A checkout that submits the order in one step (the checkout form action Finalize Order) needs nothing more. If your payment step instead saves and routes the customer onward, with the checkout form's After Submit set to Go to URL (Conditional), add a condition slot set to Truemed Handoff ahead of Default. That condition needs no URL. Without it, choosing Truemed on that step won't send the customer to Truemed.
Test with Sandbox
Place a test order with Truemed Environment set to Sandbox before you take real payments.
- Make sure your test product is approved in the Sandbox catalog and shows Eligible under HSA/FSA Eligibility in the item editor. Without an eligible item in the cart, Truemed doesn't appear at checkout.
- In a StoreFront checkout, choose the Truemed option and submit the order.
- Complete Truemed's sandbox survey and payment with the test card
4242 4242 4242 4242, any future expiry date, and any CVC and ZIP. Truemed returns you to the store. - In Operations → Order Management → Order Life Cycle → Pending Clearance, confirm the order is there, unless Truemed captured it straight away.
- In the Sandbox dashboard's Payments tab, use the payment's Actions menu to approve or reject the LMN, and confirm the order leaves Pending Clearance on its own.
When it works, switch Truemed Environment to Production, paste an API key from your Production Truemed dashboard, and create the same webhook there (same URL, Payload Signing set to Signed, all events). Paste its signing secret into Webhook Signing Secret and click Save. Production is a separate catalog, so check that your products' eligibility in UltraCart reflects the Production review.
Related
- How Truemed orders work: who can choose Truemed, the review period, refunds and reporting.
- Payments: every payment method on Configuration → Checkout → Payments.
- Pending Clearance: where orders wait while a payment is reviewed.