IFrame integration - Card field iFrame

Tokenization frame

The iframe provides maximum flexibility by only generating input elements for the sensitive data to be tokenized in the iframe. While the form utilizing the iframe will reside on your server, the input for the sensitive data will be replaced with an iframe that resides within our secure environment.

These subjects will be covered in this documentation:

Testing
Creating the iframe
Building the configuration object
Styling the iframe
Using the iframe
Events
Iframe functions
Full sample
Create a token transaction

Testing

We've created an iframe test page which you can use to create a sample configuration array.
Go to test page.

Creating the iframe

Setting up the iframe, consists of two steps: creating an iframe Configuration Object, and loading the iframe into the DOM using the iframe JS Library which can be included into your page from:
https://staging-paymentapi.masspay.io/iframe/iframe.min.js

Note: You must include the link to this file and not self-host this file.

Building the configuration object

Here is an overview of the configuration object options:

Parameter	Type	Required	Description
origin	string	true	The fully qualified Origin of your application
placeholder	string	false	Optionally sets the placeholder attribute of the input
height	string	false	The height of the iframe
debug	bool	false	If enabled, data will be output to the console to assist with debugging
styles	object	false	CSS to be applied to the PAN and CVV inputs. See Styling the Iframe

Here is an example of the configuration object:

{
  "organisation": "fab04e42-0901-4e33-839d-4a326d037497",
  "origin": "https://example.com/",
  "placeholder": "1234 1234 1234 1234",
  "height": "35px",
  "debug": false,
  "styles": {
    "base": "border: 1px solid #ccc;",
    "focus": "border-color: #66afe9;",
    "error": "border-color: #FF0000;"
  }
}

Styling the iframe

The iframe is styled by passing the CSS in the configuration object used to generate the iframe. The styles object consists of three elements: base, focus and error.

Parameter	Type	Description
base	string	The base style applied to the input element within the iframe
focus	string	Optional style applied when input element within the iframe gains focus
error	string	Style applied to the input element if a validation failure occurs
placeholder	string	Allows for the styling of the input placeholder text

Here is an example of the configuration object including styles:

{
  "organisation": "fab04e42-0901-4e33-839d-4a326d037497",
  "origin": "https://example.com/",
  "placeholder": "1234 1234 1234 1234",
  "height": "35px",
  "debug": false,
  "styles": {
    "base": "border: 1px solid #ccc;",
    "focus": "border-color: #66afe9;",
    "error": "border-color: #FF0000;"
    "placeholder": "color: #999999;"
  }
}

Using the iframe

Now that you've built your configuration object, the last step is to render the iframe on your form. Reference the Iframe JS Library located at https://staging-paymentapi.masspay.io/iframe/iframe.min.js and invoke the CardFrame.Iframe() method to generate a new iframe object. This method accepts two parameters: the ID of the container in which you want to render the iframe and the iframe configuration Object you created.

Here is an example of the code to load the iframe:

var iframe = new CardFrame.Iframe("iframeDiv", iframeConfig);

// add event listeners here

iframe.load();

Events

Each event object returned from the iframe will contain properties relevant to the type of message or event. Wiring up one or more of these events to your instance of the iframe is done on the iframe object generated by the call to the on() function and supplying a callback function.

Event	Raise Condition(s)
load	The iframe has loaded
focus	The input in the iframe gains focus
blur	The input in the iframe loses focus
change	The input value has changed. Raised only if the data has changed between the most recent focus and blur events
cardTypeChange	The possible card type entered by the user has changed (see CardTypeChange event fields below)
error	An error occurred during the invocation of a command
validate	The validate command was invoked, either directly by the user or as part of the Tokenize command (see Validate event fields below)
tokenize	The tokenize command was invoked (see Tokenize event fields below)

Event Data The Load, Focus, Blur and Change events do not provide any additional information - they are simply there to inform the parent page of the current state of the iframe.CardTypeChange, Validate, Tokenize and Error, on the other hand, return a JSON object that contains additional information, as described below.

Here is an example of the code to add event listeners:

var iframe = new CardFrame.Iframe("iframeDiv", iframeConfig);

// add event listeners here
iframe.on("load", function () { console.log("Loaded") });
iframe.on("focus", function () { console.log("Focus") });
iframe.on("blur", function () { console.log("Blur") });
iframe.on("change", function () { console.log("Change:") });
iframe.on("cardTypeChange", function (data) { console.log("CardTypeChange:" + JSON.stringify(data)) });
iframe.on("validate", function (data) { console.log("Validate:" + JSON.stringify(data)) });
iframe.on("tokenize", function (data) { console.log("Tokenize:" + JSON.stringify(data)) });
iframe.on("error", function (data) { console.log("Error:" + JSON.stringify(data)) });

// calling the load function adds the iframe to the DOM
iframe.load();

CardTypeChange

Field	Type	Description
possible_card_type	string	Indicates the possible card type based on the data entered. Possible values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'

Validate

Field	Type	Description
is_valid	bool	Indicates whether or not the input data is valid
card_type	string	The type of credit card. Valid return values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'
last_four	string	The last four characters of the input data
first_six	string	The first six characters of the input data
validator	string	If isValid is false, this will list the validator(s) that failed

Tokenize

Field	Type	Description
first_six	string	The first six characters of the input data
last_four	string	The last four characters of the input data
card_type	string	The type of credit card. Valid return values are 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb'
token	string	The token generated from the provided data

Error

Field	Type	Description
error	string	Description of the error(s) that occurred during execution of the invoked command
referenceNumber	long	The reference number for the invoked command

Iframe functions

The iframe library exposes the following functions:

Name	Description
Load	Loads the iframe and adds it to the DOM
Focus	Set the focus of the page to the input element with the iframe
Blur	Remove focus from the input element within the iframe
Reset	Restore iframe contents to initial state
Remove	Remove iframe from the DOM
Validate	Invokes validation routines on the contents of the iframe
Tokenize	Validates and tokenizes the contents of the iframe (if validations succeeds)

Here is an example of the code to use these functions:

iframe.load();
iframe.focus();
iframe.blur();
iframe.reset();
iframe.remove();
iframe.validate();
iframe.tokenize();

Full sample

This is a complete sample:

<!DOCTYPE html>
<html lang="en">
    <body>
        <h1>Iframe Example</h1>
        <p>This is an example of the iframe:</p>

        <form method="post" id="my_payment_form">
            <div id="card-iframe"></div>
            <input type="text" id="card-token" name="card-token" disabled placeholder="result token" />
            <input type="submit" value="Go!" />
        </form>
        <p>
            <strong>Copy example number:</strong><br/>
            4000 0000 0000 0002<br />
            4444 3333 2222 1111<br />
            5200 0000 0000 0007<br />
            6759 6498 2643 8453<br />
        </p>

        <script src="https://staging-paymentapi.masspay.io/iframe/masspay/iframe.min.js"></script>
        <script>
            function loadFrame() {
                const iframeConfig = {
                    organisation: "[Your organisation]",
                    origin: "[Your origin]",
                    placeholder: "1234 1234 1234 1234",
                    height: "35px",
                    debug: false,
                    styles: {
                        base: "width: 100%; box-sizing: border-box; height: 34px; padding: 6px; font-size: 14px; color: #555; border: 1px solid #ccc;",
                        focus: "border-color: #66afe9; outline: 0;",
                        error: "border-color: #FF0000; outline: 0;"
                    }
                };

                // load iframe
                let iframe = new CardFrame.Iframe('card-iframe', iframeConfig);
                iframe.load();
                iframe.on('tokenize', function (data) {
                    console.log('tokenize data', data);
                    document.getElementById('card-token').value = data.token;
                });
                document.getElementById('my_payment_form').addEventListener('submit', function(e) {
                    e.preventDefault();
                    iframe.tokenize();
                });
            }

            loadFrame();
        </script>
    </body>
</html>

Create a token transaction

The last step is creating a transaction by supplying the card token. Next to the card token we also need a card holder name, expiry date and cvv. Please be aware that due to PCI compliance you're never allowed to store the CVV.

A token transaction is initiated in the same way as other transactions. However the details field should have the following extra fields:

{
    card_holder <string>: Cardholder's name
    card_token <string>: Card token. For performing a transaction based on a card token. The fields card_holder, card_token, card_cvv and card_expiry_month and card_expiry_year are required
    card_cvv <string>: Card CVV/CVC. Please be aware that due to PCI compliance you're never allowed to store the CVV/CVC
    card_expiry_month <integer>: The card expiry month
    card_expiry_year <integer>: The card expiry year
}

For instance, here is a valid request body that initiates a token transaction:

{
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": 14,
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "dynamic_descriptor": "orderdesc01",
    "merchant_reference": "my order id",
    "payment_product": "ideal",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "details": {
        "redirect_url": "https://example.com/finalize",
        "card_holder": "N van Veen",
        "card_token": "a540bf6a-554b-4a95-9a93-f0ba5cb202e8",
        "card_cvv": "123",
        "card_expiry_month": "12",
        "card_expiry_year": "26",
    },
    "webhook_transaction_update": "https://example.com"
}

Remember that the amount must be specified without a decimal point, meaning the value 14 refers to the amount 0.14.