Embedded Checkout (iFrame)

The iFrame is an alternative presentation of the standard payment session—the same eligibility survey, card entry, statuses, and webhooks as the hosted redirect, just rendered inline on your page instead of sending the customer to a Truemed-hosted page. Use it when you want customers to stay on your site through checkout.

Everything you build for the redirect flow still applies—creating the session, handling payment_session_complete, and fulfilling on captured. Only two things change:

Enable the iFrame

Add the optional use_iframe parameter to create_payment_session. When use_iframe is true, the redirect_url in the response is an iframe-compatible URL you render inline instead of redirecting to.

Example Request

1
{
2
  "use_iframe": true,
3
  "total_amount": 0,
4
  "order_items": [],
5
  "success_url": "https://example.com/success",
6
  "failure_url": "https://example.com/failure",
7
  "idempotency_key": "key",
8
  "customer_email": "customer@example.com",
9
  "customer_name": "Customer"
10
}

Example Response

1
{
2
  "id": "session_id",
3
  "redirect_url": "https://truemed.com/..."
4
}

Handling iFrame Responses

Partner sites can set the iframe element’s src to redirect_url and this will render Truemed’s survey and checkout in the iframe. A message event listener will need to be added to listen for messages from the iframe. Upon completion of the survey and payment, Truemed will send a message from the iframe to the parent using the browser’s PostMessage API with two parameters success and redirectUrl. After handling the message, the iframe can be removed.

• success - boolean that returns true if checkout flow was successful on Truemed’s end, false if otherwise
• redirectUrl - string that will be set to success_url from the original create request body if success is true or failure_url if success is false. Only need to be used if redirect is desired or need to handle success and failure differently.

Apple Pay requires allow="payment" on the iframe and HTTPS on the parent page. Card payments and Link work without it.

Example Handler

1
function openTruemedIframe(redirectUrl) {
2
  const iframe = document.createElement('iframe');
3
  iframe.id = 'truemed-checkout';
4
  iframe.src = redirectUrl;
5
  iframe.allow = 'payment';
6
  iframe.style.width = '100%';
7
  iframe.style.height = '100%';
8
9
  document.body.appendChild(iframe); // Or append to any desired element
10
11
  window.addEventListener('message', function(event) {
12
    const { success, redirectUrl } = event.data ?? {};
13
    if (success === undefined || redirectUrl === undefined) {
14
      // Handle no data or invalid data shape
15
      // We typically recommend ignoring these, defaulting to no-op unless you explicitly recognize the event.
16
      return;
17
    }
18
19
    if (success) {
20
      // Handle success
21
      // ...
22
      // or redirect to previously provided success_url
23
      window.location.href = redirectUrl;  // Redirect to success URL
24
    } else {
25
      // Handle failure
26
      // ...
27
      // or redirect to previously provided failure_url
28
      window.location.href = redirectUrl;  // Redirect to failure URL
29
    }
30
31
    // Remove the iframe
32
    document.body.removeChild(iframe);
33
  });
34
}