`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.

IMPORTANT

Each request that you send to Cybersource requires header information. For information about constructing the headers for your request, see the REST Getting Start Developer Guide
.

The figure below shows the Microform Integration process.

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.

Implementing Microform Integration is a three-step process:

Creating the Server-Side Capture Context

Setting Up the Client Side

Validating the Transient Token

The figure below shows the flow for implementing Microform Integration:

`Microform Integration` Implementation Workflow

Microform Integration v2

Styling

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

General Appearance

The

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

Microform Integration v2

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.

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;
});

Microform Integration v2

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/

Microform Integration v2

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.

Microform Integration v2

API Reference

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

Microform Integration v2

`Microform Integration` v2

Figure:

How It Works

PCI Compliance

Browser Support

Getting Started

Figure:

Styling

General Appearance

Explicitly Setting Container Height

Managed Classes

Input Field Text

Supported Properties

Events

Subscribing to Events

Card Detection

Autocomplete

Security Recommendations

PCI DSS Guidance

Self Assessment Questionnaire

Storing Returned Data

API Reference