Skip to navigation

The first order charges as soon as the customer places it. Truemed sends a payment token the moment the customer enters both cards, and you charge that order the same way you charge every later one. An independent licensed practitioner reviews the case after the first charge, and Truemed settles the order when the practitioner decides.

How the first order flows

Every call below belongs to one example customer, Jamie Rivera (your customer ID 84213), whose first box has two eligible meals and a dessert that is not. Payloads are trimmed; the full versions are in API calls. A dotted underline in the progress bar marks a step that Truemed runs.

1. Jamie chooses to pay with HSA/FSA

1Opt in—2Survey & cards—3Pick meals—4Charge—5Review—6Settle
Payment page with Pay with HSA/FSA selected

Your page

What the customer sees

Jamie picks a plan, enters delivery details, and selects Pay with HSA/FSA at payment.

What you do

Call Create Payment Token, store the returned provision_token_request_id on Jamie’s record (it is how you match the decision back later), then open redirect_url in an iframe.

POST /api/v1/payment_tokens/create returns:

{
"provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
"redirect_url": "https://app.truemed.com/survey/6c2d9e41-7b83-4f52-a0d1-3ea95c6b8f27"
}

2. Jamie completes the survey and enters both cards

✓Opt in—2Survey & cards—3Pick meals—4Charge—5Review—6Settle
HSA/FSA card and personal card entry forms

Truemed-hosted

What the customer sees

Truemed’s health survey, then a form for an HSA/FSA card and a personal card, all inside your iframe. Card data never reaches your servers.

What you do

Close the frame when it reports that it is done, and send Jamie to the menu. Truemed sends the payment token at the same time.

The frame posts { success: true } to your page when Jamie finishes. See Embedded checkout.

Truemed then sends payment_token.updated:

{
"event_type": "payment_token.updated",
"data": {
"payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42",
"provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
"payment_session_id": null,
"eligibility_status": "pending",
"lmn_expires_at": null
}
}

Store payment_token on Jamie’s record. Every order, the first one included, charges against it. pending means the practitioner has not reviewed the case yet. The review starts when you charge the first order.

3. Jamie picks meals from a badged menu

✓Opt in—✓Survey & cards—3Pick meals—4Charge—5Review—6Settle
Meal selection page with HSA/FSA Eligible badges on meals

Your page

What the customer sees

The menu, with HSA/FSA badges on the meals that fit Jamie’s survey answers.

What you do

Read eligibility by payment token and badge the returned items. The practitioner has not reviewed the case yet, so the status is pending.

GET /api/v1/eligibility/token/{payment_token} returns:

{
"eligibility_status": "pending",
"items": ["salmon-teriyaki-bowl", "chicken-pesto-plate", "protein-breakfast-box"],
"lmn_expires_at": null
}

items lists the meals that the survey predicts the LMN will cover, plus any meals that need no LMN. Truemed charges the first order from the same list, so your badges and the split always agree. Label these badges pending clinical review.

If you read first-order eligibility with Retrieve Eligibility by Provision Request, switch to this read. The pending token read returns the same response.

4. Jamie places the order, and you charge it

✓Opt in—✓Survey & cards—✓Pick meals—4Charge—5Review—6Settle

Your fulfilment worker · no new customer screen

What you do: Charge the order on the token as soon as Jamie places it, and ship it on schedule.

Jamie sees your order confirmation, ideally with an estimate of what goes on each card.

Create Payment Session:

POST /payments/v1/create_payment_session
{
"payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42",
"total_amount": 3550,
"order_items": [
{ "item_id": "salmon-teriyaki-bowl", "name": "Salmon teriyaki bowl", "price": 1450, "quantity": 1 },
{ "item_id": "chicken-pesto-plate", "name": "Chicken pesto plate", "price": 1450, "quantity": 1 },
{ "item_id": "chocolate-lava-cake", "name": "Chocolate lava cake", "price": 650, "quantity": 1 }
]
// …plus the required fields listed in API calls
}

Send every line in cents, including the dessert. Truemed works out the split.

The first payment session reports processing until the practitioner decides. Truemed holds the authorization during that time, so ship the box on schedule. Your Truemed contact can share the current review turnaround. If Jamie places more orders before the decision, each one also reports processing and settles on the same decision.

A 200 from Create Payment Session means the authorization hold is in place on both cards. If the hold fails, Create Payment Session returns 422 with next_action: "UpdatePaymentMethod" and holds nothing. Recover the order as in When HSA/FSA funds run out.

Showing the payment breakdown in the order summary

Confirmation is the natural place to show Jamie how the order will split. Build the estimate from two reads you already have:

  • Which meals are eligible: items from the eligibility read in step 3.
  • The comparable amount per meal: comparable_item_price_cents on each item from the catalog read. Cache it, and re-read the catalog at least monthly.

For each line, an eligible meal puts comparable_item_price_cents × quantity on the personal card and the rest on HSA/FSA. A meal that is not in items goes entirely on the personal card. Jamie’s box, with an illustrative comparable amount of $6.00:

LinePricePersonal cardHSA/FSA card
Salmon teriyaki bowl$14.50$6.00$8.50
Chicken pesto plate$14.50$6.00$8.50
Chocolate lava cake (not eligible)$6.50$6.50$0.00
Meals total$35.50$18.50$17.00

Three things are specific to the first order:

  • The estimate assumes approval. Eligibility is still pending when Jamie confirms. If the practitioner declines, the whole order goes on the personal card, so word the estimate as “if approved”.
  • Show it as an estimate, not a promise. Truemed settles the exact split when Truemed settles the order in step 6. If the HSA/FSA balance is short, the charge fails unless auto-retry is on; see When HSA/FSA funds run out.
  • Truemed sends the final numbers. Jamie’s itemized receipt in step 6 shows what went to each card.

5. A practitioner reviews the case

✓Opt in—✓Survey & cards—✓Pick meals—✓Charge—5Review—6Settle

Truemed review · no new customer screen

What you do: Wait for the second payment_token.updated. It carries the decision, and payment_session_id names the first order. Update Jamie’s record, because the token is the same one you already hold.

Jamie has already left checkout. If the case is declined, Truemed emails Jamie directly.

{
"event_type": "payment_token.updated",
"data": {
"payment_token": "tm_token_4e2a91c8-70bd-4f36-9a15-c8b3d6e07f42",
"provision_token_request_id": "b1f0c7a2-5d3e-4a19-9c6b-2f8e41d07a55",
"payment_session_id": "0b7c6e2a-1f4d-4c8e-9a3b-5d2e7f81c640",
"eligibility_status": "approved",
"lmn_expires_at": "2027-08-06"
}
}

Truemed captures the first order with the split from step 4, in one capture for the full total. Later orders put the covered meals on the HSA/FSA card.

If Jamie already holds an approved LMN on your channel and that LMN covers the first order, no review runs. Truemed sends approved as soon as you create the first payment session.

6. Truemed settles the first order

✓Opt in—✓Survey & cards—✓Pick meals—✓Charge—✓Review—6Settle

Truemed · no new customer screen

What you do: Nothing. Truemed captures the first payment session, and the session reports captured.

Jamie gets an itemized receipt showing what went to each card.

Jamie’s next box skips steps 1 to 6 and charges right away. See Subsequent orders.

What your integration needs

Before you build the first order, confirm you can:

  • Store provision_token_request_id on the customer record at signup.
  • Listen for the iframe completion message and close the frame.
  • Receive payment_token.updated on a subscribed webhook endpoint and store the token.
  • Badge the menu from the token read.
  • Charge the first order with Create Payment Session as soon as the customer places it.
  • Accept a first payment session that reports processing until the practitioner decides.
  • Handle a second payment_token.updated for the same token by updating the customer record.
  • Get the token when the customer lands before the webhook, and recover a missed webhook. See API calls.