Microform Integration
v2

Microform Integration
replaces the card number input field of a client application with a
Cybersource
-hosted field that accepts payment information securely and replaces it with a non sensitive token.
You can style this page to look and behave like any other field on your website, which might qualify you for PCI DSS assessments based on SAQ A.
Microform Integration
provides the most secure method for tokenizing card data. Sensitive data is encrypted on the customer’s device before HTTPS transmission to
Cybersource
. This method reduces the potential for man-in-the middle attacks on the HTTPS connection.

How It Works

The
Microform Integration
JavaScript library enables you to replace the sensitive card number input field with a secure iframe (hosted by
Cybersource
), which captures data on your behalf. This embedded field will blend seamlessly into your checkout process.
When captured, the card number is replaced with a mathematically irreversible token that only you can use. The token can be used in place of the card number for follow-on transactions in existing
Cybersource
APIs.

PCI Compliance

The least burdensome level of PCI compliance is SAQ A. To achieve this compliance, you must securely capture sensitive payment data using a validated payment provider.
To meet this requirement,
Microform Integration
renders secure iframes for the payment card and card verification number input fields. These iframes are hosted by
Cybersource
and payment data is submitted directly to
Cybersource
through the secure
Flex API
v2 suite, never touching your systems.

Browser Support

  • Chrome 80 or later
  • Edge 109 or later
  • Firefox 115 or later
  • Opera 106 or later
  • Safari 13 or later

Getting Started

Microform Integration
replaces the primary account number (PAN) or card verification number (CVN) field, or both, in your payment input form. It has two components:
  • Server-side component to create a capture context request that contains limited-use public keys from the
    Flex API
    v2 suite.
  • Client-side JavaScript library that you integrate into your digital payment acceptance web page for the secure acceptance of payment information.

Styling

Microform Integration
can be styled to look and behave like any other input field on your site.

General Appearance

The 
<iframe>
 element rendered by Microform has an entirely transparent background that completely fills the container you specify. By styling your container to look like your input fields, your customer will be unable to detect any visual difference. You control the appearance using your own stylesheets. With stylesheets, there are no restrictions and you can often re-use existing rules.

Explicitly Setting Container Height

Typically, input elements calculate their height from font size and line height (and a few other properties), but
Microform Integration
requires explicit configuration of height. Make sure you style the height of your containers in your stylesheets.

Managed Classes

In addition to your own container styles,
Microform Integration
automatically applies some classes to the container in response to internal state changes.
Class
Description
.flex-microform
Base class added to any element in which a field has been loaded.
.flex-microform-disabled
The field has been disabled.
.flex-microform-focused
The field has user focus.
.flex-microform-valid
The input card number is valid.
.flex-microform-invalid
The input card number invalid.
.flex-microform-autocomplete
The field has been filled using an 
autocomplete/autofill
 event.
To make use of these classes, include overrides in your application’s stylesheets. You can combine these styles using regular CSS rules. Here is an example of applying CSS transitions in response to input state changes:
.flex-microform { height: 20px; background: #ffffff; -webkit-transition: background 200ms; transition: background 200ms; } /* different styling for a specifc container */ #securityCode-container.flex-microform { background: purple; } .flex-microform-focused { background: lightyellow; } .flex-microform-valid { background: green; } .flex-microform-valid.flex-microform-focused { background: lightgreen; } .flex-microform-autocomplete { background: #faffbd; }

Input Field Text

To style the text within the iframe element, use the JavaScript library. The 
styles
 property in the setup options accepts a CSS-like object that allows customization of the text. Only a subset of the CSS properties is supported.
var customStyles = { 'input': { 'font-size': '16px', 'color': '#3A3A3A' }, '::placeholder': { 'color': 'blue' }, ':focus': { 'color': 'blue' }, ':hover': { 'font-style': 'italic' }, ':disabled': { 'cursor': 'not-allowed', }, 'valid': { 'color': 'green' }, 'invalid': { 'color': 'red' } }; var flex = new Flex('..........'); // apply styles to all fields var microform = flex.microform({ styles: customStyles }); var securityCode = microform.createField('securityCode'); // override the text color for for the card number field var number = microform.createField('number', { styles: { input: { color: '#000' }}});

Supported Properties

The following CSS properties are supported in the 
styles: { ... }
 configuration hash. Unsupported properties are not added to the inner field, and a warning is output to the console.
  • color
  • cursor
  • font
  • font-family
  • font-kerning
  • font-size
  • font-size-adjust
  • font-stretch
  • font-style
  • font-variant
  • font-variant-alternates
  • font-variant-caps
  • font-variant-east-asian
  • font-variant-ligatures
  • font-variant-numeric
  • font-weight
  • line-height
  • opacity
  • text-shadow
  • text-rendering
  • transition
  • -moz-osx-font-smoothing
  • -moz-tap-highlight-color
  • -moz-transition
  • -o-transition
  • -webkit-font-smoothing
  • -webkit-tap-highlight-color
  • -webkit-transition

Events

You can subscribe to
Microform Integration
events and obtain them through event listeners. Using these events, you can easily enable your checkout user interface to respond to any state changes as soon as they happen.
Events
Event Name
Emitted When
autocomplete
Customer fills the credit card number using a browser or third-party extension. This event provides a hook onto the additional information provided during the 
autocomplete
 event.
blur
Field loses focus.
change
Field contents are edited by the customer. This event contains various data such as validation information and details of any detected card types.
focus
Field gains focus.
inputSubmitRequest
Customer requests submission of the field by pressing the Return key or similar.
load
Field has been loaded on the page and is ready for user input.
unload
Field is removed from the page and no longer available for user input.
update
Field configuration was updated with new options.
Some events may return data to the event listener’s callback as described in the next section.

Subscribing to Events

Using the 
.on()
 method provided in the 
microformInstance
 object, you can easily subscribe to any of the supported events.
For example, you could listen for the 
change
 event and in turn display appropriate card art and display brand-specific information.
var secCodeLbl = document.querySelector('#mySecurityCodeLabel'); var numberField = flex.createField('number'); // Update your security code label to match the detected card type's terminology numberField.on('change', function(data) { secCodeLbl.textContent = (data.card && data.card.length > 0) ? data.card[0].securityCode.name : 'CVN'; }); numberField.load('#myNumberContainer');
The 
data
 object supplied to the event listener’s callback includes any information specific to the triggered event.

Card Detection

By default, Microform attempts to detect the card type as it is entered. Detection info is bubbled outwards in the 
change
 event. You can use this information to build a dynamic user experience, providing feedback to the user as they type their card number.
{ "card": [ { "name": "mastercard", "brandedName": "MasterCard", "cybsCardType": "002", "spaces": [ 4, 8, 12], "lengths": [16], "securityCode": { "name": "CVC", "length": 3 }, "luhn": true, "valid": false, "couldBeValid": true }, /* other identified card types */ ] }
If
Microform Integration
is unable to determine a single card type, you can use this information to prompt the customer to choose from a possible range of values.
If 
type
 is specified in the 
microformInstance.createToken(options,...)
 method, the specified value always takes precedence over the detected value.

Autocomplete

By default,
Microform Integration
supports the autocomplete event of the 
cardnumber
 field provided by certain browsers and third-party extensions. An 
autocomplete
 event is provided to allow easy access to the data that was provided to allow integration with other elements in your checkout process.
The format of the data provided in the event might be as follows:
{ name: '_____', expirationMonth: '__', expirationYear: '____' }
These properties are in the object only if they contain a value; otherwise, they are undefined. Check for the properties before using the event. The following example displays how to use this event to update other fields in your checkout process:
var number = microform.createField('number'); number.on('autocomplete', function(data) { if (data.name) document.querySelector('#myName').value = data.name; if (data.expirationMonth) document.querySelector('#myMonth').value = data.expirationMonth; if (data.expirationYear) document.querySelector('#myYear').value = data.expirationYear; });

Security Recommendations

By implementing a Content Security Policy, you can make use of browser features to mitigate many cross-site scripting attacks.
The full set of directives required for
Microform Integration
is:
Security Policy Locations
Policy
Sandbox
Production
frame-src
https://testflex.
cybersource
.com/
https://flex.
cybersource
.com/
child-src
https://testflex.
cybersource
.com/
https://flex.
cybersource
.com/
script-src
https://testflex.
cybersource
.com/
https://flex.
cybersource
.com/

PCI DSS Guidance

Any merchant accepting payments must comply with the PCI Data Security Standards (PCI DSS).
Microform Integration
’s approach facilitates PCI DSS compliance through self-assessment and the storage of sensitive PCI information.

Self Assessment Questionnaire

Microform Integration
handles the card number input and transmission from within iframe elements served from
Cybersource
controlled domains. This approach can qualify merchants for SAQ A-based assessments. Related fields, such as card holder name or expiration date, are not considered sensitive when not accompanied by the PAN.

Storing Returned Data

Responses from
Microform Integration
are stripped of sensitive PCI information such as card number. Fields included in the response, such as card type and masked card number, are not subject to PCI compliance and can be safely stored within your systems. If you collect the CVN, note that it can be used for the initial authorization but not stored for subsequent authorizations.

API Reference

This reference provides details about the JavaScript API for creating
Microform Integration
web pages.