Introduction

Microform can be described as a combination of two things:

  • A javascript library, let's call it microform.js
  • A Cybersource-hosted payment page, or pages, designed to look like a text input field, let's call it a Microform page or just Microform

Microform page would be embedded into merchant's hosted payment page to where normally the input field would be, thus essentially replacing it.

Here's an example of how would an html of a very simple (too simple, actually, it's just for explanation purpose) payment page form look like without a product like Microform.

<form>
<div class="form-group">
<label for="card_number_input_id">Card number</label>
<input type="text" class="form-control" id="card_number_input_id" placeholder="Enter your card number">
</div>
</form>
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Now, here's what a page with Microform would like like, before Microform page is loaded:

<form>
<div class="form-group">
<label for="microform_container_id">Card number</label>
<div class="form-control" id="microform_container_id">
</div>
</div>
</form>
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

And after:

<form>
<div class="form-group">
<label for="microform_container_id">Card number</label>
<div class="form-control flex-microform" id="microform_container_id">
<iframe hspace="0" vspace="0" frameborder="0" scrolling="no" allowtransparency="true" marginwidth="0" marginheight
            ="0" src="https://testflex.cybersource.com/cybersource/assets/microform/0.11.1/iframe.html?keyId
            =08RB5bS9NLNX0SxOt95C0C8JlosRAWNH#{&quot;microformId&quot;:&quot;dc239cd3-3655-45d0-b88f-6a84e1a627b9&quot;,&quot
            ;fieldId&quot;:&quot;b91b1a21-b4ae-4bf9-a7a3-c1ae4ff0a867&quot;,&quot;jwt&quot;:&quot
            ;eyJraWQiOiIzZyIsImFsZyI6IlJTMjU2In0
            .eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJMb0Z6bWJRWmJTcE1ISmtqck10UXBSQUFFR3MzaUdOSUlwdEhTSGZRekRy
            VjNXdWhCa0k1N1psZFdtdGplMjdjS2R4M3hqUW5kM1hQbW1OVUVoV2RNWlByenVkTlJ1M0FyTVVLcXh6MiswK2p5Vm9HNWRtUGxlQW40YmhnTXlPd
            0h5MjciLCJvcmlnaW4iOiJodHRwczovL3Rlc3RmbGV4LmN5YmVyc291cmNlLmNvbSIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZS
            I6ImVuYyIsIm4iOiIxRjVaOG5FeEVYM3QtNnBNeklKWnhqNEN5MWZ1alpWNmlxWVFKZ2l5WmYzZ1FOY0NPcUR5Z2hGSUhkU3FmN3FJNU5XZjZib01
            oSGtwODcwMmNSaF9RX3lvdFFTMFBJV1NUeHA2VldYYWY0emMyUFdjVEJwZTZqMEtiNDJNZjQyY19IcXpMdHJNR0p3UmlGYVI1TElJZnM2QVNOUV9a
            VjBBc1ZxVmhtbDVTUUNEdm16NGVuTnJEc2Nwbmp2dktJbGdnclVYaXEyVDVXcU5RbEVZcTl6alN4Mk00WmFLZ1JwUDdYc1JHemRGd3hlV2s4dzBka
            2xlUW9sTE1Eb1E4Z1pBOGt3aW1pR0VNVXctV1F1SjlmaFRXVHZYNmI5U0toQXBrNW1FRjk5a2RTQndGMjE3d2JXZVh3S2pURGxDdW15bU5oWXRGN1
            R6SUtIYUpTRnpKczN5S3ciLCJraWQiOiIwOFJCNWJTOU5MTlgwU3hPdDk1QzBDOEpsb3NSQVdOSCJ9fSwiY3R4IjpbeyJkYXRhIjp7InRhcmdldE9
            yaWdpbnMiOlsiaHR0cDovL2xvY2FsaG9zdDo4MDgyIl0sIm1mT3JpZ2luIjoiaHR0cHM6Ly90ZXN0ZmxleC5jeWJlcnNvdXJjZS5jb20ifSwidHlw
            ZSI6Im1mLTAuMTEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE1OTM3MDU5ODMsImlhdCI6MTU5MzcwNTA4MywianRpIjoibmI3MG0zS1VNR
            EdqMWhkdCJ9.EjgPgQIEhMdUn54iCk4wPxmBD9i_zVcFmFiNp50U8n1K22edvctDzst9X0
            -BJmBvUl4oWVTx6GcsJKqnW7mm9QltZTpmnXr8qRiL4qMEoCaWB87Aqxm-_-DMzBePq4wtu5Shj3WIrCdQeV9ocSJ35hkIR
            -z7BVROw5rjWKUTU3nZC2b7OMIFAjOfo72huTJ8wdGbl9aHzVfNX2morY9WuKiiVC8GR81PQnQYDSvURAtYV3_eTZyyBY7ekc94aoF69uXY8ZuxES
            T2gW0MM0RM7xC95Xph3GsTi3GBiIJr2iWzs11DCE7uRyp0UQPli_uI0ON5hXJC2lEkwxoHk7ZhHA&quot;,&quot;microformConfig&quot
            ;:{&quot;styles&quot;:{&quot;input&quot;:{&quot;font-size&quot;:&quot;16px&quot;,&quot;font-family&quot;:&quot
            ;helvetica, tahoma, calibri, sans-serif&quot;,&quot;color&quot;:&quot;#555&quot;},&quot;::placeholder&quot
            ;:{&quot;color&quot;:&quot;#868E96&quot;,&quot;opacity&quot;:1}}},&quot;config&quot;:{&quot;placeholder&quot
            ;:&quot;Enter card number&quot;,&quot;styles&quot;:{},&quot;autoformat&quot;:true},&quot;fieldType&quot;:&quot
            ;number&quot;}" style="overflow: hidden; position: relative; border: none; width: 100%; height: 100%;"></iframe>
</div>
</div>
</form>
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This iframe will contain the Microform page, hosted by Cybersource, and the only part of this page which is visible to the user is a text input.

Features

SAQ-A

As Microform is a page hosted externally from merchant's system, it should allow qualification for an SAQ-A PCI DSS assessment.

Visual style

Before Microform is loaded merchant can specify the visual style of Microform page to match the style of the surrounding website. This is achieved through managed classes and css properties.

Managed classes

Microform automatically applies some classes to its container in response to internal state changes. By making use of these classes merchant can style the container.

For example, Microform will assign style flex-microform-invalid to the container if the card number or card security code is not valid. See more about managed classes in the guide.

CSS properties

Through microform.js merchant can style the input text within the iframe element. This is done through CSS properties, please see the guide for the full list and here's an example of how styles are specified:

var microform = flex.microform({ styles:
{
'input': {
'font-size': '16px',
'font-family': 'helvetica, tahoma, calibri, sans-serif',
'color': '#555'
},
'::placeholder': { 'color': '#868E96', 'opacity': 1 }
}
});
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Microform doesn't support custom fonts.

Events

In addition to styles merchant can subscribe to Microform events through microform.js. Events allow merchant react to changes within Microform and dynamically update the page. For example, an autocomplete event will let merchant know the field was prepulated by browser 'saved card' functionality. A change event will inform of a change to the input field (e.g. text change) and carry additional insight about the card number, see below:

{
"valid": false,
"couldBeValid": true,
"card": [
{
"name": "visa",
"brandedName": "Visa",
"cybsCardType": "001",
"spaces": [
4,
8,
12
],
"lengths": [
13,
14,
15,
16,
17,
18,
19
],
"securityCode": {
"name": "CVV",
"length": 3
},
"luhn": true,
"valid": false,
"couldBeValid": true
}
],
"empty": false
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Example of subscribing for a change event:

var flex = new Flex(captureContext);
var microform = flex.microform({ styles: mfStyles });
var number = microform.createField('number', { placeholder: 'Enter card number' });
number.on('change', function (data) {
...
});
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

For a complete list of supported events please check the guide.

In summary, managed classes, CSS properties, and events allow merchant to design Microform to look and feel like the rest of the site.

Encryption and security

Microform offers RsaOaep256 (or just RsaOaep for older browsers) encryption of Cardholder Data (PAN) and Sensitive Authentication Data (CAV2/CVC2/CVV2/CID). Before the card number and card security code leave front-end application they will be encrypted and sent within a JWE.

JWE stands for JSON Web Encryption. Simply put, JWE is an encrypted JWT. See more at https://tools.ietf.org/html/rfc7516.

Microform will only allow itself to be embedded within a trusted website. This is done through Capture Context (trusted endpoints), which will 'start' Microform.

Microform is served over TLS 1.2+ from flex.cybersource.com. This domain is rated A+ by the independent SSL Labs.

In summary, Microform offers Message Layer and Transport Layer Encryption.

Flex API and Transient Tokens

Back-end API Microform talks to is Flex API (a RESTful API). There are two merchant facing endpoints. One is for generation of the Capture Contexts, the other one is for generation of the Transient Tokens.

Transient Token

Transient Token, roughly speaking, is a temporary token which is stored in memory instead of a database. It will be available for just 15 minutes or until the first successful authorization. It is possible to first use it, for example, in a Payer Authentication or a DM transaction, and then for the Authorization.

The key benefit of transient tokens is to have a reference to Sensitive Authentication Data and to be able to pass that reference through back-end systems instead of sending the Card Security Code for example.

Tokenization

Obviosuly, Microform is a type of a payment page. The interesting fact about Microform though is that it does not actually process the payment, instead its purpose is to securely and quickly capture and tokenize any sensitive data and remove it from the front-end application.

The response of Microform (or, to be specific, of Flex API) is the Transient Token, which merchant would through a back-end application send to Cybersource APIs.

Request

Here's a small code fragment showing how tokenisation is done:

var flex = new Flex(captureContext);
var microform = flex.microform({ styles: mfStyles });
var number = microform.createField('number', { placeholder: 'Enter card number' });
var securityCode = microform.createField('securityCode', { placeholder: '•••' });
microform.createToken(options, function (e, response) {
if (e) {
console.error(e);
} else {
console.log(response);
}
});
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

For a complete sample of front-end code, please see the guide, Basic Integration paragraph.

Response

Transient Token is a signed JWT.

Header:

{
"kid": "08JCys3k83VbJP4MM2Ikv5VAA6rbbHve",
"alg": "RS256"
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Payload:

{
"data": {
"number": "400000XXXXXX0002",
"type": "001"
},
"iss": "Flex/08",
"exp": 1594051118,
"type": "mf-0.11.0",
"iat": 1594050218,
"jti": "1E1WQAG60CXZKSGIVILQKT1A7H59G7D3RVXNP9ECTM65C8YB3D8J5F034A2E8A64"
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The jti claim is the Transient Token itself. Depending on API merchant will be required to send just the jti claim or the complete encoded JWT. See respective API guides for more information. It will expire as specified in exp claim.

Sequence diagram

JWT has to be verified before use. Public key to verify Transient Token JWT's signature is provided in the Capture Context flx.jwk claim.