Microform Integration v2
Microform Integration
v2Microform 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 theFlex APIv2 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: 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.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:
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.