How Truemed orders work
A Truemed order is different from a card order in one way that matters: when the customer finishes checkout, Truemed may not have collected the money yet. Truemed often reviews an HSA/FSA payment first, for example while a practitioner issues a Letter of Medical Necessity (LMN). UltraCart therefore places the order straight away but holds it in Pending Clearance, and only releases it for fulfillment once Truemed captures the payment.
To set Truemed up, see Set up Truemed (HSA/FSA) payments.
Which customers can choose Truemed
Truemed appears at checkout only for carts it can pay for. UltraCart shows the option when all of these are true:
- Truemed is turned on and has its environment, API key and webhook signing secret saved.
- At least one item in the cart is HSA/FSA eligible (Eligible or Eligible with LMN in the item editor), or every paid item is when you've turned on the Eligibility setting. A kit counts by the kit item itself, not its components. See Mark which products are HSA/FSA eligible.
- The cart has no auto order item or auto order upsell, unless you've turned on the Subscriptions setting. See Choose which carts can use Truemed.
- The cart is in U.S. dollars. HSA and FSA funds can only be used in the United States.
- The customer is in the United States. The checkout hides Truemed once the shipping country, or the billing country when nothing ships, is known and isn't the United States.
- The cart has no digital items, unless your account allows every payment method for digital delivery.
- No item is priced through a make-an-offer price.
- Any rules you set with the Restrictions button in the Truemed (HSA/FSA) section allow it.
Truemed is offered in StoreFront Visual Builder checkouts. The older built-in checkout pages don't offer it.
If the cart changes after the checkout page loaded and nothing eligible is left, a customer who still picks Truemed is sent back to checkout with "Nothing in your cart can be paid for with HSA/FSA funds. Please choose another payment method." If the cart still has an eligible item but your settings rule it out (a subscription without the Subscriptions setting, or an ineligible item with the Eligibility setting on), the message is "HSA/FSA payment isn't available for the items in your cart. Please choose another payment method."
What the customer sees
The customer chooses Truemed, submits the order, and goes to Truemed's site. There they answer a short health survey and pay with their HSA or FSA card. If part of the cart isn't eligible, Truemed asks for a regular card for that part.
Truemed's page lists the items, shipping, tax and discounts from the cart, so the total matches what the customer saw in your store. A gift certificate or other credit applied to the cart appears as a discount.
When the customer finishes, Truemed sends them back to your store and UltraCart places the order. If the customer doesn't qualify, cancels, or the card fails in a way Truemed can't recover from, they return to your checkout with a message such as "Your HSA/FSA payment through Truemed was not completed. Please choose another payment method."
Why the order waits in Pending Clearance
A Truemed order waits in Pending Clearance until Truemed captures the payment, so you never ship an order that isn't paid. The order gets a merchant note saying it is waiting on the Truemed (HSA/FSA) review. If Truemed captured the payment before the customer came back, the order skips Pending Clearance and continues like any paid order. The exception is the first order of a subscription, which waits for Truemed's payment token (see Subscriptions).
The order leaves Pending Clearance on its own, in one of two ways:
- Truemed captures the payment. UltraCart records the capture and releases the order to the rest of your order flow, including fraud review if you use it, then shipping.
- Truemed rejects or cancels the payment. UltraCart moves the order to Accounts Receivable, marks the payment declined, and adds the note "Truemed (HSA/FSA) payment rejected. Moved automatically from Pending Clearance to Accounts Receivable." UltraCart doesn't email the customer about it, so contact them yourself.
UltraCart learns about the outcome from Truemed's webhook, usually within a few minutes. It also checks recent Pending Clearance orders with Truemed on a schedule, which catches anything a webhook missed. That scheduled check covers orders paid in the last 14 days. For an older order, check its payment from the order's page in Pending Clearance, which asks Truemed for the current status and shows it.
Rejecting a Truemed order from Pending Clearance rejects it in UltraCart only. If Truemed has already taken payment, cancel or refund it in Truemed's dashboard. The rejected order's merchant note reminds you.
If Truemed's amount doesn't match the order total, the order stays in Pending Clearance with a note asking you to check the payment in Truemed before releasing it.
Orders that paid on Truemed but never came back
If a customer pays on Truemed but closes the browser before returning to your store, no order is placed. UltraCart still receives Truemed's webhook for that payment and records a warning in the Truemed integration log, with the cart id, so you can follow up. See Integrations Reports for where to find integration logs.
Refunds
You refund a Truemed order from the usual refund screen, and UltraCart sends the refund to Truemed. Full and partial refunds both work. See How do I perform a Refund for the screen itself.
A Truemed order can be refunded only after Truemed has captured the payment. While the order is in Pending Clearance, or after a rejection, there is nothing to refund and UltraCart doesn't offer the refund.
When you refund specific items, UltraCart passes them to Truemed so the refund appears against those lines on the customer's receipt. Truemed decides how much goes back to the HSA/FSA card and how much to any regular card the customer used.
If Truemed refuses a refund, UltraCart shows Truemed's reason, for example "Truemed refund failed: ChargeDisputed" when the customer has an open dispute. If you refund a Truemed order directly in Truemed's dashboard, record it in UltraCart as a manual refund so your order totals stay right.
Subscriptions (auto orders)
Customers can pay for an auto order with HSA/FSA funds once Truemed has enabled payment tokens on your Truemed account and you've turned on the Subscriptions setting in Truemed Settings (see Choose which carts can use Truemed). When the cart has an auto order item or an auto order upsell, Truemed also saves a reusable payment token for the customer, and UltraCart charges that token for each rebill.
- The first order waits for the token. It stays in Pending Clearance, even if Truemed captured the payment straight away, until Truemed sends the token. That usually takes a few minutes. If the token hasn't arrived after 24 hours, UltraCart releases the order anyway and adds a merchant note that its rebills can't be charged through Truemed.
- Each rebill waits for Truemed too. Truemed accepts the charge when the rebill runs and reports the outcome a few minutes later, so every rebill order goes through Pending Clearance the same way a checkout order does. A rebill Truemed rejects moves to Accounts Receivable.
- Truemed checks eligibility on every rebill, against the items on that rebill. If the customer needs to act first, for example to retake the health survey because their Letter of Medical Necessity expired or the items changed, or to update their HSA/FSA card, the rebill is held. UltraCart emails the customer Truemed's link once, notifies your users who get auto order notifications, and shows the link in the auto order's failure reason. It then tries the rebill again every day and charges it as soon as the customer has fixed it. These retries don't count toward the auto order's failed-attempt limit.
The customer email isn't sent if you've turned off auto order problem notices. Your notified users can then send the link themselves.
A subscription leaves HSA/FSA only when its own payment details change:
- A new card entered for the subscription (by the customer on the subscription's update billing page, through the REST API, or by you changing the payment method on the order editor's Billing tab) moves it to that card. UltraCart deletes the Truemed token, so going back to HSA/FSA means a new checkout with Truemed.
- Updating a saved card in My Account doesn't touch HSA/FSA subscriptions. They keep paying through Truemed.
- A cancelled HSA/FSA subscription keeps its token, so you can reactivate it later.
The virtual terminal can't charge a Truemed order. Change the payment method first if you need to take a card payment.
Upsells
Truemed takes one payment per order, so customers who pay with Truemed don't see post-purchase upsells.
Disputes
If a customer disputes a Truemed payment, Truemed tells UltraCart, and the order gets a red Truemed Dispute field with the dispute id, its state and, while it's open, the date you must respond by.
When a dispute opens, UltraCart:
- adds a refund block to the order, so you don't refund a payment that may already be taken back;
- holds any shipment that hasn't been sent to your fulfillment center yet. Release the hold yourself if you decide to ship;
- adds a merchant note with the reason, amount and respond-by date.
Further notes record each change of state and the outcome when the dispute closes. Inquiries, which come before a formal dispute, show up the same way, so you can respond early.
You respond to the dispute in Truemed's dashboard, under Disputes, by searching for the dispute id. UltraCart doesn't send evidence or responses. A lost dispute is taken from your next Truemed payout, not through UltraCart.
Sales reports
Truemed orders appear under their own Truemed payment method in sales reports such as the Period Sales report. An order counts as a sale from the date it was placed, including while it waits in Pending Clearance, the same as e-check orders. If Truemed rejects the payment, the order drops out of the sales figures.
Related
- Set up Truemed (HSA/FSA) payments: API key, webhook and checkout setup.
- Pending Clearance: the holding area for orders whose payment hasn't settled.
- How do I perform a Refund: the refund screen.