Set up PostMessage Mechanism

When integrating the Card Display form, the Card Capture form or the Card Security Code Capture Form, customers may wish to process messages and notifications from the form in the parent page - this to enable the parent page to be notified on actions taken inside the iframe.

For example, a customer may want to display only one submit button for their form and the capture form (the PCI Booking capture form includes a "submit" button of its own).
For this use case, PCI Booking has provided a secure, postMessage, cross-domain iFrame mechanism to allow customers to have one "submit" button for the combined form and initiate an action both in PCI Booking (for tokenizing the card) and in the backend of the client (for storing everything else).

• To define the postMessage method in the card display form, go to Request a Card Display Form.
• To define the postMessage method in the card capture form, go to Request a Card Entry Form.
• To define the postMessage in the CVV capture form, go to Request a Card Security Code Entry Form.

PostMessage Mechanism Diagram

The diagram below will demonstrate the flow of actions from the site visitor going to the site through the process of validating and submitting the forms to the response sent back to the site visitor once completed:

postMessageHost parameter

The capture and display forms include an optional parameter called postMessageHost. This parameter prevents cross-domain hacking and tells the PCI Booking form the domain of the parent page where the form is hosted on.

📘

For Example:

If you load the form in a site with the URL https://www.mysite.com/page/form, the postMessageHost parameter should be https://www.mysite.com in a URL encoded format (https%3A%2F%2Fwww.mysite.com)

Workflow

Terminology: The PCI Booking iframe will be displayed inside a parent page.

1. The customer should include a function in the parent page to handle the messages that are returned from the iframe. The iframe can provide the following data:

• ready - indicating that the iframe has been loaded successfully and is waiting for input
• valid - indicating that the iframe form has been filled properly and all data entry validations have passed successfully.
• frameDimensionsChanged - indicating that the iframe has loaded with different dimensions. This allows the customer to reload the parent page and change the display parameters for the iframe to fit the new size.
  *invalid - indicating that the data provided by the visitor is invalid and the form still cannot be submitted.
  Below is an example of such a function:

function handleFrameMessage(e) {
  var host = 'https://service.pcibooking.net/'
  var originDomain = e.origin.replace("http://", "").replace("https://", "");
  var postMessageOrigin = host.replace("http://", "").replace("https://", "").toLowerCase();
  if (postMessageOrigin.endsWith('/'))
    postMessageOrigin = postMessageOrigin.substring(0, postMessageOrigin.length - 1);


  if (originDomain.toLowerCase() === postMessageOrigin) {
    if (e.data == 'ready') {
      iframeIsReady = true;
      $("#iframePayment").fadeIn(1000);
      console.log("Messaging Log: " + e.data);
    }
    else if (e.data == 'valid') {
      continueSubmitReservationAndThenCardIframe(e);
    }
    else if (e.data.indexOf("frameDimensionsChanged") === 0) {
      var objectParts = e.data.split(':');
      var width = parseInt(objectParts[1]);
      var height = parseInt(objectParts[2]);
      $("#iframePayment").height(height).attr("height", height);
      console.log("Messaging Log: " + e.data);
    }
    else if (e.data[0] === "{") {
      console.log("Messaging Log: ");
      console.log(JSON.parse(e.data));
    }
    else {
      alert("Please fill all the mandatory fields");
    }
  }
}

2. The customer should also include a message event listener to handle the responses from the iframe and trigger the function mentioned above.
   Below is an example of such a listener:

...
	if (window.addEventListener) {
     window.addEventListener('message', handleValidateMessageFromPciBooking);
   }
   else if (window.attachEvent) {
     window.attachEvent('onmessage', handleValidateMessageFromPciBooking);
   }
...

3. Lastly, the customer should include a function in the parent page to process the form and redirect to the next page once the card form has been submitted successfully.
   This function should be made to store all of the form fields provided in the parent page and all of the token details that are provided after the iframe is submitted and redirected to the success / failure pages (see steps #7 and #8.
4. When the "Submit" button is clicked, it should validate the form fields in the parent page and it should send a validation request to the iframe.
   Below is an example of such validation request:

...	
	receiver.postMessage("validate", 'https://service.pcibooking.net/');
...

5. PCI Booking will validate the card form to show error messages and will send postMessage with a valid/invalid response back to the customer's parent page - this response will be processed by the function mentioned in step #1.
   If the validation of the form in the parent page fails or the response from the PCI Booking iframe is that the iframe is not valid, a message should be sent to the visitor informing them that there is a problem with the information provided.
   If the validation (of both the parent form and the iframe) is successful, the parent page can proceed with storing the data in the following steps:
6. A request to store the iframe data and tokenize the card is sent to the iframe.
   Below is an example of such validation request:

...	
	receiver.postMessage("submit", 'https://service.pcibooking.net/');
...

7. PCI Booking will tokenize the card details and redirects the iframe to the Booker's success/fail URL which was provided in the iframe request.
8. Since the success/fail pages are within the same domain f the parent page, they will be able to pass along parameters to it and trigger a function in it to store the data (see step #3) and redirect the visitor to the confirmation page.

Possible PostMessage Message Data

When using the PostMessage mechanism, you will encounter the following scenarios and the resulting message data returned in the PostMessage:

Example

You can see an example of the PostMessage mechanism in use in our card capture demo page.
While this demo is designed to display everything - both capture forms and confirmation pages, on the same page display, the above logic is the same.

In order to view the data being returned in the PostMessage mechanism, please open the web console on your browser:

Chrome
Opening the “Console” panel of Chrome’s DevTools:

Firefox
Opening the “Console” panel in Firefox’s Developer Tools:

Internet Explorer
Opening the “Console” panel in Internet Explorer’s F12 Developer Tools:

Safari
Note: In order to view the console in Safari, you have to enable the “Show Develop menu in menu bar” setting in the “Advanced” pane of Safari’s preferences (screenshot).

Opening the “Console” panel in Safari’s Web Inspector:

Opera
Opening the “Console” panel in Opera: