Skip to main content
How-to

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. You also need access to the Developers area 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. 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 with your Production keys when you go live.

Turn on Truemed and add your API key​

Truemed is configured on the payments page, under its own Truemed (HSA/FSA) section.

  1. Go to Configuration → Checkout → Payments.
  2. Scroll to Truemed (HSA/FSA) and turn on the toggle.
  3. Click Settings to open Truemed Settings.
  4. Set Truemed Environment to Sandbox while you test, or Production for live payments.
  5. Paste the API key from the Developers area of your Truemed dashboard into Truemed API Key.
  6. 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.

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.

  1. On Configuration → Checkout → Payments, open Truemed (HSA/FSA) → Settings again.
  2. Next to Webhook URL, click Copy.
  3. In the Truemed dashboard, go to Developers → Webhooks and add a webhook with that URL. Choose the signed delivery method. UltraCart only accepts signed webhooks.
  4. Copy the signing secret Truemed shows for the new webhook.
  5. Back in Truemed Settings, paste it into Webhook Signing Secret.
  6. 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.

warning

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.

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.

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.

  1. In a StoreFront checkout, choose the Truemed option and submit the order.
  2. Complete Truemed's sandbox survey and payment. Truemed returns you to the store.
  3. In Operations → Order Management → Order Life Cycle → Pending Clearance, confirm the order is there, unless Truemed captured it straight away.
  4. Once the sandbox payment is captured, confirm the order leaves Pending Clearance on its own.

When it works, switch Truemed Environment to Production, paste your Production API key, and add the same webhook URL as a signed webhook in your Production Truemed dashboard with its own signing secret.

Was this page helpful?