> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Implementation readiness checklist

> A pre-launch checklist covering checkout, fulfillment, webhooks, and reconciliation for your Truemed integration.

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`](/api-reference/payment-tokens/payment-token-updated-webhook) 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. See
  [Subscriptions testing](/guides/setup/api/subscriptions/testing).
* [ ] **Expiration monitoring is scheduled.** A recurring job filters
  [`list_payment_token`](/api-reference/payment-tokens/list-payment-token) by `lmn_expires_before` and
  `card_expires_before` and prompts customers before their next charge. Nothing warns you
  automatically.
* [ ] **Token recovery clears its own messaging.** When
  [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) arrives, any
  banner or email sequence you raised for that token is stood down.

## Related guides

| Need                                 | Guide                                                                                         |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| Build the first payment flow         | [Accept your first payment](/guides/setup/api/payment-sessions/accept-your-first-payment)     |
| Handle webhook fulfillment correctly | [Webhooks and fulfillment](/guides/setup/api/payment-sessions/webhooks-and-fulfillment)       |
| Pass fees and discounts correctly    | [Itemized fees and discounts](/guides/setup/api/payment-sessions/itemized-fees-and-discounts) |
| Validate refunds, cancels, and voids | [Refunds, cancels, and voids](/guides/setup/api/payment-sessions/refunds-cancels-and-voids)   |
| Reconcile payouts and transactions   | [Reconciliations](/guides/setup/api/reconciliations/overview)                                 |
| Build subscription flows             | [Subscriptions](/guides/setup/api/subscriptions/overview)                                     |
| Recover a blocked subscription       | [Token lifecycle](/guides/setup/api/subscriptions/token-lifecycle)                            |