Implementation Readiness Checklist

Use this checklist before launch to confirm your Truemed integration is correct, production-ready, and resilient to common checkout, fulfillment, and reconciliation issues.

Customer experience

• HSA/FSA messaging appears before checkout. Show Truemed messaging on product pages where the item may qualify for HSA/FSA spending or reimbursement. This helps customers understand the option before they reach checkout.
• Truemed appears as a checkout payment option. Surface a clear “Pay with HSA/FSA” option alongside your other payment methods so the customer explicitly chooses the Truemed flow.
• Return pages set the right expectation. Use success_url for customer-facing confirmation or pending messaging, and failure_url to return customers to checkout when they cannot complete payment.

Payment session creation

• Cart changes generate a new idempotency key. Regenerate the idempotency_key whenever cart inputs change, including items, quantities, pricing, shipping, taxes, or discounts. This prevents duplicate or stale payment sessions.
• Fees and discounts are represented correctly. Pass shipping, taxes, and discounts through amount_details, not as product line items. Test promo patterns like gift-with-purchase and buy-one-get-one discounts.
• Metadata supports support and reconciliation. Include useful metadata such as order ID, customer ID, or cart reference in create_payment_session so you can connect Truemed activity to your own order and reporting systems.

Webhooks and fulfillment

• Order completion is driven by webhooks. Treat Truemed webhooks as the source of truth for payment status. Do not fulfill from success_url alone.
• Fulfillment is gated on the right status. For immediate capture, fulfill only after payment_session_complete sends status: captured. For manual capture, wait for status: authorized, capture the payment, then fulfill after the capture succeeds.
• Approval and rejection paths are tested. Test both approved and rejected flows end to end so your customer messaging, order state, and cancellation behavior are correct.
• Webhook retries are idempotent. Ensure repeated webhook deliveries do not duplicate shipments, emails, refunds, credits, or capture attempts.

Operations

• Refunds are validated before launch. Process at least one refund through the Truemed API or dashboard so your team understands refund mechanics and operational handoffs.
• Reconciliation data is consumed. Use payout and transaction reconciliation endpoints to match bank deposits, refunds, fees, disputes, and orders back to your internal ledger.
• Support workflows can find payments. Your support team can search by order ID, customer, payment session ID, and any metadata sent to Truemed.

Subscriptions and payment tokens

• Payment-token webhooks are handled. If you use subscriptions, listen for payment_token_updated before charging future orders with a token.
• Customer next actions are surfaced. When a token charge returns next_action and redirect_url, send the customer to that URL so they can update their payment method or retake the health survey.
• Recurring-order failure paths are tested. Test expired payment methods, expired LMNs, rejected LMNs, free trials, and cart changes before launch.

Related guides