Iframe Integration

This guide describes step by step how to use Berkeley inline iframe – when you have to embed an independently hosted HTML document inside of another one.

The main benefit which the usage of this form brings to you is the reduction of your PCI scope by separating your application from your user’s sensitive data.

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.

JavaScript

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.

JavaScript

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:

Variable	Required	Details
t	Yes	Temporary token
form_type	Yes	The form which you wish to render. Can be one of: card, bank, etransfer_email, etransfer_sms.
v	Conditional	If form_type is card, you need to specify v1 or v2 card tokenization.
region	No	Defaults to ca (Canada) For the United States, use us. Is not used for form_type set_pin
form_title	No	Adds a title to the form
card_number_label	No	Alternate label for Card Number form_type card only
cvv_label	No	Alternate label for CVV form_type card only
t_type	No	Defaults to push Transaction type you expect the card to be using. If you expect the tokenized card to use both push and pull transactions, pass in pull value form_type card only

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:

elixir

data = {
  data: {
    token: pctk_13487329045723094582709857
  }
}

📘

Related pages:

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