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://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://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://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.