Iframe Integration

An iframe, also known as an inline frame, is used to embed an independently hosted HTML document (child) inside of another HTML document (parent). Thus the child is isolated from the parent and provides a layer of separation between the two.

Using our hosted iframe forms helps to reduce your PCI scope by separating your application from your user’s sensitive data.

You will need to use JavaScript in order to receive messages sent from the iframe which may contain successful returned data or, to allow for responsiveness in your iframe, the current height of the embedded form.

NOTE: Before you’re able to use our iframes, you will need to be configured to use this feature. You will need to provide us with the referer URL from which you will be sending requests to embed the iframe. JavaScript provides an easy way to access this information through document.referrer on the browser page you’ll be embedding the form if you’re unsure.

Step 1:

To begin, add the iframe HTML element to your page. There are many attributes provided by the iframe element which can be found here.

<iframe id="myiframe" frameborder="0" allowfullscreen />

Step 2:

Add an event listener to the parent window. This event listener will be listening for messages sent from the child.

window.addEventListener("message", (e) => {
      const {data} = e
      //retrieve the iframe element from the parent document
      var iframe = document.getElementById("myiframe")

      //if the data object contains the height key, this means that the embedded form's height 
      //has initialized or has changed.
      if (data.height) {
        iframe.height = data.height;
      }
      
      //do work to consume the data contained in the data object
      //a returned data object that does not contain the key "height" is a success
    })

Step 3:

You will need to make an initial call to retrieve a temporary token. This temporary token will be used to render the form and to validate for submission.

fetch(`${domain}/api/v1/tokens/temp_token`, {
        headers: {
          Accept: "application/json",
          "Content-Type": "application/json",
          Authorization: `Bearer ${private_token}`,
          Referer: // `AFTER THE URL IS PROVIDED TO BERKELEY`
        },
        method: "GET"
      })

This temporary token is only valid for three minutes. After that, form submission cannot take place and you will receive an error, displayed on the form, stating that your session has expired.

Step 4:

With the retrieved temporary token, you can now add to your iframe the src attribute using the base url and a query string containing parameters for your form. Below are the parameters you can pass in the url query string:

Tokenization Forms:

Example: https://{{domain}}/iframe/v1/forms?t=jvLQgHiVTA1UMsJ4WKhpG5BzCdyxYn&form_type=card

Step 5:

With the form now rendered on your page, the user has under three minutes to enter their information into the form and submit it. They user will enter their information in the form and press submit.

Upon submission, we verify the data and if it is valid. If not, errors will display on the form to inform the user that there was an issue with their information or with submitting their form.

If a submission is successful, we return a data object and the flow is complete. Below are successful responses you may receive depending based on the form_type used:

Tokenization forms:

data = {
  data: {
    token: pctk_13487329045723094582709857
  }
}

📘

Related pages:

Iframe Sensitive Card Details
DirectSend User Guide
Iframe/Hosted PIN Management Integration