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

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.