The first order

The first order is the only one that waits on Truemed. The customer signs up, picks meals, and places the order without delay. You hold that order unpaid until Truemed sends a valid payment token, then charge it. The customer never waits on a screen, and later orders reuse the token with no wait.

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

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://dev.truemed.com/survey/6c2d9e41-7b83-4f52-a0d1-3ea95c6b8f27"
}

2. Jamie completes the survey and enters both cards

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

Wait for the frame to report it is done, then close it and send Jamie to the menu.

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

3. Jamie picks meals from a badged menu

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 provision request and badge the returned items. The practitioner has not reviewed the case yet, so the status is pending.

GET /api/v1/eligibility/provision_request/{provision_token_request_id} returns:

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

items lists the meals Jamie is pre-qualified for, available right away. The final say comes later, when a practitioner approves Jamie’s LMN.

4. Jamie places the order, and you hold it

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:

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 you charge 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

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

6. You charge the held order

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. Jamie’s next box starts here, skipping steps 1 to 5. 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.
• Badge the menu from the provision-request read.
• Hold a placed, unpaid first order in your fulfilment queue.
• Receive payment_token.updated on a subscribed webhook endpoint and store the token.
• Charge the held order with Create Payment Session once the webhook lands, in either outcome.
• Recover a missed webhook. See API calls.