iFrame Payment Session

Overview

Payment partners can add a new optional boolean parameter use_iframe to the endpoint for creating a new payment session.

Setting use_iframe to true will return an iframe-compatible URL in the redirect_url property of the response.

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 redirect_url. 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
• redirect_url - 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.

Example Handler

1
// Example to handle iFrame checkout
2
function openTruemedIframe(redirectUrl) {
3
  const iframe = document.createElement('iframe');
4
  iframe.id = 'truemed-checkout';
5
  iframe.src = redirectUrl;
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
    if (!event.data || typeof(event.data) !== 'object') {
13
      // Handle no data or invalid data shape
14
      // ...
15
      return;
16
    }
17
18
    const { success, redirectUrl } = event.data;
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
}