Creating the iFrame

Setting up the iFrame consists of three steps:

Generating an Authentication Key
Creating an iFrame configuration object
Loading the iFrame into the DOM using the Basys iFrame JS library. To test out the iFrame, the following script must be included into your page from this URL:

Test: 
<script src="https://sandbox.api.basyspro.com/Iframe/iframe-v3.js"/>

Parameter

Type

Required

Config API Mapping

Description

tokenExID

string

true

data.iframeConfiguration.iqProV2.tokenizationId

Your TokenID

tokenScheme

string

true

data.iframeConfiguration.iqProV2.tokenScheme

Either the name (case insensitive) or the JSON value of the Token Scheme to be used

authenticationKey

string

true

data.iframeConfiguration.iqProV2.authenticationKey

The generated Authentication Key

timestamp

string

true

data.iframeConfiguration.iqProV2.timestamp

The timestamp when the authentication key was generated, in the following format:

yyyyMMddHHmmss

NOTE: This value must match the one provided when generating your Authentication Key.


origin

string

true

data.iframeConfiguration.iqProV2.origin

The fully qualified origin of your application. In the TokenEx Production environment, the origin must use HTTPS.

styles

object

false

N/A

CSS to be applied to the PAN and CVV inputs (see Styling the iFrame)


placeholder

string

false

Optionally sets the placeholder attribute of the input

pci

boolean

false

true

Specifies if the PCI version of the iFrame should be rendered; defaults to false

enablePrettyFormat

bool

false

true

If pci is true, then enabling this property will auto format the credit card number as it appears on the physical card

NOTE: This will only apply if input type is set to text. It will not work if input type is set to "num" or "tel".

enableValidateOnBlur

bool

false

If true, then the Validate function will be called when the input loses focus; otherwise, Validate must be invoked manually

inputType

string

false

Allowed values are "number", "tel", and "text". If nothing is supplied, this will default to "text"

allowUnknownCardTypes

bool

false

If true, then unknown, or types other than 'masterCard', 'americanExpress', 'discover', 'visa', 'diners', or 'jcb' will tokenize; defaults to false

NOTE: If this field is true while using Custom Data Types in PCI w/ CVV or CVV Only modes, the CVV text field's allowable input will be 4. Use the cvvValidRegex field to validate the length of the CVV input.

debug

bool

false

If enabled, data will be output to the console to assist with debugging

customRegEx

string

false

If present, the RegEx expression provided will be used during validation events in addition to any internal validation. Please note that the backslash is an escape character - if used in your RegEx, it will need to be escaped

cvv

bool

false

Specifies if a CVV iFrame should be rendered; defaults to false

cvvInputType

string

false

Allowed values are "number", "tel", and "text"; if nothing is supplied, this will default to "text"

cvvContainerID

string

false

CvvTextBox

The container in which you want to render the CVV iFrame when cvvOnly is false

cvvPlaceholder

string

false

CVV

Optionally sets the placeholder attribute of the CVV input when cvvOnly is false

customDataTypes

object

false

Custom validations appended to our standard brand detection (see Using Custom Data Types)

customDataLabel

string

false

Allows customization of the iframe data label. If none supplied, this defaults to "Data"

customCvvDataLabel

string

false

Allows customization of the CVV iframe data label. If none supplied, this defaults to "CVV"

maskInput

bool

false

Hides the input being typed by masking it with masking character

font

string

false

A google font to use in the iframe

title

string

false

Content of the title element used by the iframe document

cvvTitle

string

false

Content of the title element used by the cvv iframe document


enableAriaRequired

bool

false

If true, sets the aria-required and aria-invalid attributes to true. When Validate function is called aria-invalid will update according to the result of isValid


inputMode


string

false

See MDN Input Mode for acceptable modes.

expiresInSeconds

int

false

The expiration time when the authentication key is going to expire after initial load.

Valid range: 1 to 1200 Seconds

NOTE: Default expiration time is set to 1200 seconds (20 Minutes).

The expiration time will be reset to default, in case if user provides value which

Is less than or equal to 0
Is greater than 1200


inputMaxLength

int

false

Sets the maxLength property of the input.

NOTE: This parameter only works with input type "text".

useExtendedBIN

bool

false

If true, returns the first eight characters of the PAN in the Tokenize response.

NOTE: Will not return firstEight in the Tokenize response if:

PCI is false
or PAN is fewer than 16

characters.

enableValidateOnKeyUp

bool

false

If true, then the Validate function will be called after each keystroke; otherwise, Validate must be invoked manually

NOTE: This functionality is only available for PCI and PCIwithCVV iFrame modes


enableValidateOnCvvKeyUp

bool

false

If true, then the Validate function will be called after each keystroke in the CVV iframe; otherwise, Validate must be invoked manually

NOTE: This functionality is only available for PCIwithCVV iFrame modes

returnAutoCompleteValues


bool

false

If true, then this will return nameOnCard and cardExp values whenever a user utilizes the browsers autocomplete functionality.

NOTE: Autocomplete must be enabled

cardMaxLengths

object

false

EXAMPLE:
cardMaxLengths: {
"visa" : 16,"mastercard" : 19,
"americanexpress" : 19,
"discover" : 16,
"diners" : 16,
"jcb" : 19
}
This field is optional.

Providing an object for this field requires all properties, i.e. card brands, to be specified on the object.

Either all card brand properties on the object must have integer values, or they all must be set to null.

If no object is provided for this field, the max length for any card brand will be set to the default max length, which is 19.

If the object is not used but still provided, set all the card brand property values to null, and the values will default to 19.

Required card brands:
americanexpress
diners
discover
jcb
mastercard
visa

NOTE: This functionality is only available for PCI and PCIwithCVV iFrame modes. Max Length for PCI and PCIwithCVV is 19 by default

Putting It All Together

Now that you've built your configuration object, the last step is to render the iFrame on your form. Reference the Test Basys iFrame JS Library located at https://sandbox.api.basyspro.com/Iframe/iframe-v3.js and invoke the TokenEx.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.

var iframe = new TokenEx.Iframe("tokenExIframeDiv", iframeConfig); 
// Add event listeners here 
iframe.load();