On This Page
Reference
This reference provides additional information for creating
Microform Integration
web pages.JavaScript API Reference
This reference provides details about the JavaScript API for creating
Microform Integration
web
pages.Class: Field
An instance of this class is returned when you add a Field to a Microform integration using
microform.createField. With this
object, you can then interact with the Field to subscribe to events, programmatically set
properties in the Field, and load it to the DOM.
Methods
clear()
Programmatically clear any entered value within the field.
Example
field.clear();
dispose()
Permanently remove this field from your Microform integration.
Example
field.dispose();
focus()
Programmatically set user focus to the Microform input field.
Example
field.focus();
load(container)
Load this field into a container element on your page.
Successful loading of this field will trigger a load event.
Name | Type | Description |
---|---|---|
container | HTMLElement | string | Location in which to load this field. It can be
either an HTMLElement reference or a CSS selector string that will be used to load
the element. |
Examples
Using a CSS selector
field.load('.form-control.card-number');
Using an HTML element
const container = document.getElementById('container'); field.load(container);
off(type, listener)
Unsubscribe an event handler from a Microform Field.
Name | Type | Description |
---|---|---|
type | string | Name of the event you wish to unsubscribe from.
|
listener | function | The handler you wish to be unsubscribed. |
Example
// subscribe to an event using .on() but keep a reference to the handler that was supplied. const focusHandler = function() { console.log('focus received'); } field.on('focus', focusHandler); // then at a later point you can remove this subscription by supplying the same arguments to .off() field.off('focus', focusHandler);
on(type, listener)
Subscribe to events emitted by a Microform Field. Supported eventTypes are:
- autocomplete
- blur
- change
- focus
- inputSubmitRequest
- load
- unload
- update
Some events may return data as the first parameter to the callback otherwise this will be
undefined. For further details see each event's documentation using the links above.
Name | Type | Description |
---|---|---|
type | string | Name of the event you wish to subscribe to. |
listener | function | Handler to execute when event is triggered. |
Example
field.on('focus', function() { console.log('focus received'); });
unload()
Remove a the Field from the DOM. This is the opposite of a load operation.
Example
field.unload();
update(options)
Update the field with new configuration options. This accepts the same parameters as
microform.createField(). New options will be merged into the existing configuration of the
field.
Name | Type | Description |
---|---|---|
options | object | New options to be merged with previous
configuration. |
Example
// field initially loaded as disabled with no placeholder const number = microform.createField('number', { disabled: true }); number.load('#container'); // enable the field and set placeholder text number.update({ disabled: false, placeholder: 'Please enter your card number' });
Events
autocomplete
Emitted when a customer has used a browser or third-party tool to perform an
autocomplete/autofill on the input field. Microform will attempt to capture additional
information from the autocompletion and supply these to the callback if available. Possible
additional values returned are:
- name
- expirationMonth
- expirationYear
If a value has not been supplied in the autocompletion, it will be undefined in the
callback data. As such you should check for its existence before use.
Examples
Possible format of data supplied to callback
{ name: '_____', expirationMonth: '__', expirationYear: '____' }
Updating the rest of your checkout after an autocomplete event
field.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; });
blur
This event is emitted when the input field has lost focus.
Example
field.on('blur', function() { console.log('Field has lost focus'); }); // focus the field in the browser then un-focus the field to see your supplied handler execute
change
Emitted when some state has changed within the input field. The payload for this event
contains several properties.
Type:
objectName | Type |
---|---|
card | object |
valid | boolean |
couldBeValid | boolean |
empty | boolean |
Examples
Minimal example:
field.on('change', function(data) { console.log('Change event!'); console.log(data); });
Use the card detection result to update your UI.
const cardImage = document.querySelector('img.cardDisplay'); const cardSecurityCodeLabel = document.querySelector('label[for=securityCode]'); // create an object to map card names to the URL of your custom images const cardImages = { visa: '/your-images/visa.png', mastercard: '/your-images/mastercard.png', amex: '/your-images/amex.png', maestro: '/your-images/maestro.png', discover: '/your-images/discover.png', dinersclub: '/your-images/dinersclub.png', jcb: '/your-images/jcb.png' }; field.on('change', function(data) { if (data.card.length === 1) { // use the card name to to set the correct image src cardImage.src = cardImages[data.card[0].name]; // update the security code label to match the detected card's naming convention cardSecurityCodeLabel.textContent = data.card[0].securityCode.name; } else { // show a generic card image cardImage.src = '/your-images/generic-card.png'; } });
Use the card detection result to filter select element in another part of your
checkout.
const cardTypeOptions = document.querySelector('select[name=cardType] option'); field.on('change', function(data) { // extract the identified card types const detectedCardTypes = data.card.map(function(c) {return c.cybsCardType;}); // disable any select options not in the detected card types list cardTypeOptions.forEach(function (o) { o.disabled = detectedCardTypes.includes(o.value); }); });
Updating validation styles on your form element.
const myForm = document.querySelector('form'); field.on('change', function(data) { myForm.classList.toggle('cardIsValidStyle', data.valid); myForm.classList.toggle('cardCouldBeValidStyle', data.couldBeValid); });
focus
Emitted when the input field has received focus.
Example
field.on('focus', function() { console.log('Field has received focus'); }); // focus the field in the browser to see your supplied handler execute
inputSubmitRequest
Emitted when a customer has requested submission of the input by pressing Return key or
similar. By subscribing to this event you can easily replicate the familiar user experience
of pressing enter to submit a form. Shown below is an example of how to implement this. The
inputSubmitRequest
handler will:- Call Microform.createToken().
- Take the result and add it to a hidden input on your checkout.
- Trigger submission of the form containing the newly created token for you to use server-side.
Example
const form = document.querySelector('form'); const hiddenInput = document.querySelector('form input[name=token]'); field.on('inputSubmitRequest', function() { const options = { // }; microform.createToken(options, function(response) { hiddenInput.value = response.token; form.submit(); }); });
load
This event is emitted when the field has been fully loaded and is ready for user
input.
Example
field.on('load', function() { console.log('Field is ready for user input'); });
unload
This event is emitted when the field has been unloaded and no longer available for user
input.
Example
field.on('unload', function() { console.log('Field has been removed from the DOM'); });
update
This event is emitted when the field has been updated. The event data will contain the
settings that were successfully applied during this update.
Type:
objectExample
field.on('update', function(data) { console.log('Field has been updated. Changes applied were:'); console.log(data); });
Module: FLEX
Flex(captureContext)
new Flex(captureContext)
For detailed setup instructions, see Getting Started.
Parameters:
Name | Type | Description |
---|---|---|
captureContext | String | JWT string that you requested via a
server-side authenticated call before starting the checkout flow. |
Example
Basic Setup
<script src="[INSERT clientLibrary VALUE HERE]" integrity=”[INSERT clientLibraryIntegrity VALUE HERE]” crossorigin=”anonymous”> </script>//Note: Script location and integrity value should be sourced from the capture context response clientLibrary and clientLibraryIntegrity values. <script> const flex = new Flex('captureContext');</script>
Methods
microform(optionsopt) > {Microform}
This method is the main setup function used to initialize
Microform Integration
. Upon
successful setup, the callback receives a microform
, which is used to
interact with the service and build your integration. For details, see Class: Microform.Name | Type | Description |
---|---|---|
options | Object |
Name | Type | Attributes | Description |
---|---|---|---|
styles | Object | <optional> | Apply custom styling to all the fields in
your integration. |
Returns:
Type: Microform
Examples
Minimal Setup
const flex = new Flex('header.payload.signature'); const microform = flex.microform();
Custom Styling
const flex = new Flex('header.payload.signature'); const microform = flex.microform({ styles: { input: { color: '#212529', 'font-size': '20px' } } });
Class: Microform
An instance of this class is returned when you create a Microform integration
using
flex.microform
. This object allows the creation of Microform
Fields. For details, see Module: Flex.Methods
createField(fieldType, optionsopt) > {Field}
Create a field for this Microform integration.
Parameters
Name | Type | Attributes | Description |
---|---|---|---|
fieldType | string | Supported values:
| |
options | object | <optional> | To change these options after
initialization use field.update() . |
Properties
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
aria-label | string | <optional> | Set the input's label for use by
assistive technologies using the aria-label attribute. | |
aria-required | boolean | <optional> | Used to indicate through assistive
technologies that this input is required for submission using the aria-required attribute. | |
autoformat | Boolean | <optional> | true | Enable or disable automatic formatting of
the input field. This is only supported for number fields and will automatically
insert spaces based on the detected card type. |
description | string | <optional> | Sets the input's description for use by
assistive technologies using the aria-describedby attribute. | |
disabled | Boolean | <optional> | false | Sets
the disabled attribute on the input. |
maxLength | number | <optional> | 3 | Sets the maximum length attribute on the
input. This is only supported for securityCode fields and may take
a value of 3 or 4 . |
placeholder | string | <optional> | Sets
the placeholder attribute on the input. | |
styles | stylingOptions | <optional> | Apply custom styling to this
field | |
title | string | <optional> | Sets the title attribute on the input. Typically used
to display tooltip text on hover. |
Returns
Type: Field
Examples
Minimal Setup
const= new Flex('.........'); const microform = flex.microform('card'); const number = microform.createField('number');
Providing Custom Styles
const flex = new Flex('.........'); const microform = flex.microform(); const number = microform.createField('number', { styles: { input: { 'font-family': '"Courier New", monospace' } } });
Providing Custom Styles to All Fields within the
Microform Integration
const= new Flex('.........'); // apply styles to all fields const microform = flex.microform('card', { styles: customStyles }); // override the text color for for the card number field only const number = microform.createField('number', { styles: { input: { color: '#000' }}});
Providing Custom Styles to A Specific Field within the
Microform Integration
const= new Flex('.........'); const microform = flex.microform('card'); const number = microform.createField('number'), { styles: { input: { 'font-family': '"Courier New", monospace' } }});
Setting the Length of a Security Code Field
const= new Flex('.........'); const microform = flex.microform('card'); const securityCode = microform.createField('securityCode', {maxlength:4});
createToken(options, callback)
Request a token using the card data captured in the Microform fields. A successful token creation will receive a transient token as its second callback parameter.
Parameter
Name | Type | Description |
---|---|---|
options | object | Additional tokenization options. |
callback | callback | Any error will be returned as the first
callback parameter. Any successful creation of a token will be returned as a string
in the second parameter. |
Properties
Name | Type | Attributes | Description |
---|---|---|---|
type | string | <optional> | Three digit card type string. If set,
this will override any automatic card detection. |
expirationMonth | string | <optional> | Two digit month string. Must be padded
with leading zeros if single digit. |
expirationYear | string | <optional> | Four digit year string. |
Examples
Minimal example omitting all optional parameters.
microform.createToken({}, function(err, token) { if (err) { console.error(err); return; } console.log('Token successfully created!'); console.log(token); });
Override the
cardType
parameter using a select element that is part of your checkout.// Assumes your checkout has a select element with option values that are card type codes: // <select id="cardTypeOverride"> // <option value="001">Visa</option> // <option value="002">Mastercard</option> // <option value="003">American Express</option> // etc... // </select> const options = { type: document.querySelector('#cardTypeOverride').value }; microform.createToken(options, function(err, token) { // handle errors & token response });
Handling error scenarios
microform.createToken(options, function(err, token) { if (err) { switch (err.reason) { case 'CREATE_TOKEN_NO_FIELDS_LOADED': break; case 'CREATE_TOKEN_TIMEOUT': break; case 'CREATE_TOKEN_NO_FIELDS': break; case 'CREATE_TOKEN_VALIDATION_PARAMS': break; case 'CREATE_TOKEN_VALIDATION_FIELDS': break; case 'CREATE_TOKEN_VALIDATION_SERVERSIDE': break; case 'CREATE_TOKEN_UNABLE_TO_START': break; default: console.error('Unknown error'); break; } else { console.log('Token created: ', token); } });
Class: MicroformError
This class defines how error scenarios are presented by Microform, primarily as the first
argument to callbacks. See callback(erropt, nullable, dataopt,
nullable) > {void}.
Members
(static, readonly)
Reason Codes - Field Load ErrorsPossible errors that can occur during the loading or unloading of a field.
Properties
Name | Type | Description |
---|---|---|
FIELD_UNLOAD_ERROR | string | Occurs when you attempt to unload a field
that is not currently loaded. |
FIELD_ALREADY_LOADED | string | Occurs when you attempt to load a field
which is already loaded. |
FIELD_LOAD_CONTAINER_SELECTOR | string | Occurs when a DOM element cannot be
located using the supplied CSS Selector string. |
FIELD_LOAD_INVALID_CONTAINER | string | Occurs when an invalid container
parameter has been supplied. |
FIELD_SUBSCRIBE_UNSUPPORTED_EVENT | string | Occurs when you attempt to subscribe to
an unsupported event type. |
FIELD_SUBSCRIBE_INVALID_CALLBACK | string | Occurs when you supply a callback that is
not a function. |
(static, readonly)
Reason Codes - Field object CreationPossible errors that can occur during the creation of a Field object createField(fieldType, optionsopt) > {Field}.
Properties
Name | Type | Description |
---|---|---|
CREATE_FIELD_INVALID_FIELD_TYPE | string | Occurs when you try to create a field
with an unsupported type. |
CREATE_FIELD_DUPLICATE | string | Occurs when a field of the given type has
already been added to your integration. |
(static, readonly)
Reason Codes - Flex object CreationPossible errors that can occur during the creation of a Flex object.
Properties
Name | Type | Description |
---|---|---|
CAPTURE_CONTEXT_INVALID | string | Occurs when you pass an invalid
JWT. |
CAPTURE_CONTEXT_EXPIRED | string | Occurs when the JWT you pass has
expired. |
(static, readonly)
Reason Codes - Iframe validation errorsPossible errors that can occur during the loading of an iframe.
Properties
Name | Type | Description |
---|---|---|
IFRAME_JWT_VALIDATION_FAILED | string | Occurs when the iframe cannot validate
the JWT passed. |
IFRAME_UNSUPPORTED_FIELD_TYPE | string | Occurs when the iframe is attempting to
load with an invalid field type. |
(static, readonly)
Reason Codes - Token creationPossible errors that can occur during the request to create a token.
Properties
Name | Type | Description |
---|---|---|
CREATE_TOKEN_NO_FIELDS_LOADED | string | Occurs when you try to request a token,
but no fields have been loaded. |
CREATE_TOKEN_TIMEOUT | string | Occurs when
the createToken call was unable to proceed
|
CREATE_TOKEN_XHR_ERROR | string | Occurs when there is a network error when
attempting to create a token. Resend the capture context request and reload
Microform. |
CREATE_TOKEN_NO_FIELDS | string | Occurs when the data fields are
unavailable for collection. |
CREATE_TOKEN_VALIDATION_PARAMS | string | Occurs when there's an issue with
parameters supplied to createToken . |
CREATE_TOKEN_VALIDATION_FIELDS | string | Occurs when there's a validation issue
with data in your loaded fields. Instruct the customer to enter valid
data. |
CREATE_TOKEN_VALIDATION_SERVERSIDE | string | Occurs when server-side validation
rejects the createToken request. |
CREATE_TOKEN_UNABLE_TO_START | string | Occurs when no loaded field was able to
handle the createToken request. |
(nullable)correlationID :string
The correlationId of any underlying API call that resulted in this error.
Type
String
(nullable)details :array
Additional error specific information.
Type
Array
(nullable)informationLink :string
A URL link to general online documentation for this error.
Type
String
message :string
A simple human-readable description of the error that has occurred.
Type
String
reason :string
A reason corresponding to the specific error that has occurred.
Type
String
Global
Type Definitions
callback(erropt, nullable, dataopt, nullable) > {void}
Microform uses the error-first callback pattern, as commonly used in Node.js.
If an error occurs, it is returned by the first
err
argument of the callback. If no error occurs, err
has a null value and any return data is provided in the second argument.Parameters
Name | Type | Attributes | Description |
---|---|---|---|
err | MicroformError. See Class: MicroformError. | <optional>
<nullable> | An Object detailing occurred errors,
otherwise null. |
data | * | <optional>
<nullable> | In success scenarios, this is whatever
data has been returned by the asynchronous function call, if any. |
Returns
Type: void
Example
The following example shows how to make use of this style of error handling in your code:
foo(function (err, data) { // check for and handle any errors if (err) throw err; // otherwise use the data returned console.log(data); });
StylingOptions
Styling options are supplied as an object that resembles CSS but is limited to a subset of CSS properties that relate only to the text within the iframe.
Supported CSS selectors:
- input
- ::placeholder
- :hover
- :focus
- :disabled
- valid
- invalid
Supported CSS properties:
- 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
Any unsupported properties will not be applied and raise
a
console.warn()
.Properties
Name | Type | Attributes | Description |
---|---|---|---|
input | object | <optional> | Main styling applied to the input
field. |
::placeholder | object | <optional> | Styles for the ::placeholder
pseudo-element within the main input field. This also adds vendor prefixes for
supported browsers. |
:hover | object | <optional> | Styles to apply when the input field is
hovered over. |
:focus | object | <optional> | Styles to apply when the input field has
focus. |
:disabled | object | <optional> | Styles applied when the input field has
been disabled. |
valid | object | <optional> | Styles applied when Microform detects
that the input card number is valid. Relies on card detection being enabled. |
invalid | object | <optional> | Styles applied when Microform detects
that the input card number is invalid. Relies on card detection being
enabled. |
Example
const styles = { 'input': { 'color': '#464646', 'font-size': '16px', 'font-family': 'monospace' }, ':hover': { 'font-style': 'italic' }, 'invalid': { 'color': 'red' } };
Capture Context API
The capture context request is a signed JSON Web Token
(JWT) that includes all of the merchant-specific parameters. This request tells the
frontend JavaScript library how to behave within your payment experience. The request
provides authentication, one‑time keys, the target origin to the
Microform Integration
integration in addition to allowed card networks and payment
types (card or check). The capture context request includes these elements:- allowedCardNetworks
- allowedPaymentTypes
- clientVersion
- targetOrigins
- Target Origin
- The target origin is defined by the scheme (protocol), hostname (domain) and port number (if used).You must use the https:// protocol. Sub‑domains must also be included in the target origin.Any valid top‑level domain is supported such as .com, .co.uk, and.gov.br. Wildcards are not supported.For example, if you are launchingUnified Checkouton example.com, the target origin could be any of the following:You can define the payment cards and digital payments that you want to accept in the capture context.
- Allowed Card Networks
- Use theallowedCardNetworksfield to define the card types.These card networks are available for card entry:
- American Express
- Cartes Bancaires
- Carnet
- China UnionPay
- Diners Club
- Discover
- EFTPOS
- ELO
- JCB
- JCrew
- Mada
- Maestro
- Mastercard
- Meeza
- Visa
When you integrate withMicroform Integrationto accept card or check information, you must include at least one card network in theallowedCardNetworksfield in the capture context request. - Allowed Payment Types
- You can specify the type ofMicroform Integrationyou want to accept in the capture context. You can accept card and check information.
- Use theallowedPaymentTypesfield to define the payment type:
- CARD
- CHECK
allowedPaymentTypesfield is optional. When this field is provided in the capture context, theMicroform Integrationdefaults the field toCARDand is returned in the response regardless.
IMPORTANT
When integrating with
Cybersource
APIs, Cybersource
recommends that you
dynamically parse the response for the fields that you are looking for. Additional
fields may be added in the future. You must ensure that your integration can
handle new fields that are returned in the response. While the underlying data
structures will not change, you must also ensure that your integration can
handle changes to the order in which the data is returned.
Cybersource
uses semantic versioning practices, which enables you to
retain backwards compatibility as new fields are introduced in minor version
updates.Endpoint
Production:
POST
https://api.cybersource.com
/microform/v2/sessionsTest:
POST
https://apitest.cybersource.com
/microform/v2/sessionsRequired Fields for Requesting the Capture
Context
Your capture context request for accepting card and check
information must include these fields:
- This field is required only for accepting card information.
- This field is required only for accepting check information.
- The URL in this field value must containhttps.
Cybersource
REST API
Reference.REST Example: Requesting the Capture Context
Capture Context Request for Accepting Card and Check Information
{ "clientVersion": "v2", "targetOrigins": [ "https://www.example.com", "https://www.basket.example.com", "https://ecom.example.com" ], "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "CARTESBANCAIRES", "CARNET", "CUP", "DINERSCLUB", "DISCOVER", "EFTPOS", "ELO", "JCB", "JCREW", "MADA", "MAESTRO", "MEEZA" ], "allowedPaymentTypes": [ "CARD", "CHECK" ] }
Successful Encrypted JWT Response for Accepting Card and Check
Information
eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJ4Sy9RZzJzcWNiajNaODdIS0VwZGpSQUFFUEJLenFVaUlrdXdrelRadVNQeG9GWDNOK0VtT3k2ZGlBSXhwMHhvQStJc1Y5czlZZmRZVUJmbDFpV01kRVVmekhMTmhLQ1ZiOFAzSHg0bTQxejl6aEVcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoiaTI5NmZmbUdiVkVRbG5zanNrQnBrajRCU1pRbE9Vd2Z2SUpsdUNIaHVkTEsxQmk4MEtpOVVfb0h2Mmxsd0NJSXFUMHdJWTBvaS1HM0xVc09BUUpjNUpwX08tY1VIdzFjeXV3aDVtWXZkUWZFM0JlcnRUcDZHQ1JLcFVyUjlDOGZoaTNfV1lQTDMwNjMxMGJXajh4OXY0UnlpR1BYUHdnUlJhVDlmbXJRV1diTHZaeFNZQ0Zpal9lSEZaYXQxa1JNdG5pTk5IUTNlV1ViWUV5QWZPSExOWDhUUmN6cjYybkdpeGh4NEFNYVB5YlEtTy0wM1pjRER4UldTLTI0UGhheVVYRjZnVlAydzNHc2hhOFQxSklnYlZSc253bHVuZ01jRExtZFI1cF9ITFlRdnNyX3BFS3pZd2tDQmFOUXA0ZjRkbXhyaVIyT2IyUU5fMXRkU2FUVzN3Iiwia2lkIjoiMDBXSXlhTndYcUJhdHNuYkVmMVNFTjFncHREbDExOUYifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsImFsbG93ZWRDYXJkTmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiLCJBTUVYIiwiTUFFU1RSTyIsIkRJU0NPVkVSIiwiRElORVJTQ0xVQiIsIkpDQiIsIkNVUCIsIkNBUlRFU0JBTkNBSVJFUyJdLCJ0YXJnZXRPcmlnaW5zIjpbImh0dHBzOi8vdGhlLXVwLWRlbW8uYXBwc3BvdC5jb20iXSwibWZPcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJhbGxvd2VkUGF5bWVudFR5cGVzIjpbIkNBUkQiLCJDSEVDSyJdfSwidHlwZSI6Im1mLTIuMS4wIn1dLCJpc3MiOiJGbGV4IEFQSSIsImV4cCI6MTczMzQ5MDQwNywiaWF0IjoxNzMzNDg5NTA3LCJqdGkiOiJZcHdxWlNaTTZ1T1FBV1RoIn0.f24avtv-oUGfSaGqlQZfOZ4B6A-6E6yWymdgUtZmDDOVNanx5uLt5fxSBzAdmtC4em0kORatiS5pMhE66bCJT-ujIMHtdPITq9JJuE4Tm-NdfzznXlhz-qMM_setgmDXYLIIAeaUmSVebMwWqxBVmpQHRIBq2plwfB5dAH411aO-U1_DDJi14sIOLzUr_xhgfLJWsJ_B3gZkSaHrRaHWpnO-okCanTrVKCaFP1X5rKUilGII4wcJLdUyU3f9zFwteQ7wFfG81mRRWz4Gb4YgLt43TCD-jSigCAtgX_mqRyMqzCJtZXkf0Nf-o0bJLAc8-ce8MmeZD8H4uG42Eu-0UA
Decrypted Capture Context Header for Accepting Card and Check
Information
{ "kid": "j4", "alg": "RS256" }
Decrypted Capture Context Body with Selected Fields for Accepting Card
and Check Information
{ "flx": { "path": "/flex/v2/tokens", "data": "xK/Qg2sqcbj3Z87HKEpdjRAAEPBKzqUiIkuwkzTZuSPxoFX3N+EmOy6diAIxp0xoA+IsV9s9YfdYUBfl1iWMdEUfzHLNhKCVb8P3Hx4m41z9zhE=", "origin": "https://stageflex.cybersource.com", "jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "i296ffmGbVEQlnsjskBpkj4BSZQlOUwfvIJluCHhudLK1Bi80Ki9U_oHv2llwCIIqT0wIY0oi-G3LUsOAQJc5Jp_O-cUHw1cyuwh5mYvdQfE3BertTp6GCRKpUrR9C8fhi3_WYPL306310bWj8x9v4RyiGPXPwgRRaT9fmrQWWbLvZxSYCFij_eHFZat1kRMtniNNHQ3eWUbYEyAfOHLNX8TRczr62nGixhx4AMaPybQ-O-03ZcDDxRWS-24PhayUXF6gVP2w3Gsha8T1JIgbVRsnwlungMcDLmdR5p_HLYQvsr_pEKzYwkCBaNQp4f4dmxriR2Ob2QN_1tdSaTW3w", "kid": "00WIyaNwXqBatsnbEf1SEN1gptDl119F" } }, "ctx": [ { "data": { "clientLibraryIntegrity": "CLIENT LIBRARY INTEGRITY VALUE GOES HERE", "clientLibrary": "CLIENT LIBRARY VALUE GOES HERE", "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "MAESTRO", "DISCOVER", "DINERSCLUB", "JCB", "CUP", "CARTESBANCAIRES" ], "targetOrigins": [ "https://the-up-demo.appspot.com" ], "mfOrigin": "https://stageflex.cybersource.com", "allowedPaymentTypes": [ "CARD", "CHECK" ] }, "type": "mf-2.1.0" } ], "iss": "Flex API", "exp": 1733490407, "iat": 1733489507, "jti": "YpwqZSZM6uOQAWTh" }
Capture Context Request for Accepting Card Information
{ "clientVersion": "v2", "targetOrigins": [ "https://www.example.com", "https://www.basket.example.com", "https://ecom.example.com" ], "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "CARTESBANCAIRES", "CARNET", "CUP", "DINERSCLUB", "DISCOVER", "EFTPOS", "ELO", "JCB", "JCREW", "MADA", "MAESTRO", "MEEZA" ], "allowedPaymentTypes": [ "CARD" ] }
Successful Encrypted JWT Response for Accepting Card Information
eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJ1Q0RERW94M2dDQk1VaHI2T1ZDVGt4QUFFS1pHSTRHcDFvQ2pyYXlVb1MxQzdGOXE2WFpyYXhGbGxMVDMvenE2cjFnNXoxS1U2UDZseldqRVFTVVJoZUtxUThoVWJkZVNNdmt5SERTTXUwV01tMzhcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoiMXNDY3NZNC1WZTNWU0VKekhnelJ5WjVDOURrM0VHZ2ZPOGd5SDc5bVJfSlN6NzdmWTdfV1loM3psdTkyTFVfeU5KVTBUMzdOQmVzd0szU2c0YnRNaU41Q0FCbWNXLWNSckhta2k0MVZoNUZRMmtjcWZSSlgxNVhZN1A3R25GTnd4QzVkUG9UM29NM1czRFVHaUMyYW56enhIN3pNNlA3N2hFbnc2TkZHSXlBdXhJRWFwRG9DaXlEVW5NdFRwV2lBV3YzTF9OVHZOaHRkVE4tNm1GRWU1RmdVYmlzeWtrTzlWMHZaS0d6SWRWWmdTdE42cHlnUGhVbnlNXzJIVmIxQmkyWjNKaElhZDFLUW02SGl0NklwYjNyUTBHRWZsN0ZWOUV3NGZyNzJpekQ0WVg2WHo0V3ZuMzlLN3J3WkhCRXdNM3l5Wl9ELTBUbjM1MFhvUlBUVjB3Iiwia2lkIjoiMDB4V1A1eUh1UE1kNkFkNHdwVzNzQkt1bWFaQ01zYWMifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsImFsbG93ZWRDYXJkTmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiLCJBTUVYIiwiTUFFU1RSTyIsIkRJU0NPVkVSIiwiRElORVJTQ0xVQiIsIkpDQiIsIkNVUCIsIkNBUlRFU0JBTkNBSVJFUyJdLCJ0YXJnZXRPcmlnaW5zIjpbImh0dHBzOi8vdGhlLXVwLWRlbW8uYXBwc3BvdC5jb20iXSwibWZPcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJhbGxvd2VkUGF5bWVudFR5cGVzIjpbIkNBUkQiXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzY0MzA0MTQsImlhdCI6MTczNjQyOTUxNCwianRpIjoiZDVZbzVhNU0wWFBPQ1BxZiJ9.G4Ea-gIk6SG5ULE4NE5OsdPI41YaAuTEMHDstBgkFzczIWwzJScvXs4hgWiyA-1ZLGITedlumGj-0x8jxmYTWeTm7D0fP8RL0w148EpDLMD8xMHpAJMdMqZTmYHyichsy8uOZKVOn9NbnuQqfDeQS_rLpJV3tMe2NwJL3RdBXdJ894ihKpFP2yXE1wQeLekNiYJ6s-Uuxwf0jf2CSN_TJAjnfVR6bqlpWbUpiUaBLcqDsHHe_pcrd5g2r-1LEfCiOV9RIw7844XKFNLQZvt_alQjItuMy8M9LVhnlRWCSnTKB1iV1RUxuTWtMzTvHmQWPx4nShqzE3j0Hp61c0PmBw
Decrypted Capture Context Body with Selected Fields for Accepting Card
Information
{ "flx": { "path": "/flex/v2/tokens", "data": "gEQUL6QggbM2m8R3/KhDLxAAEOmhvNFhDd+amn9NHURTfjqqN8+7dy/YKQXz0Ik2yhRVQ8omdKZ8VojIYkwOB9yUo/8LdddXruIQ3O5dSfmbW6A=", "origin": "https://stageflex.cybersource.com", "jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "vHtaFM0e1ljAQ1Lnza95LdsBh10p78lz13rUdMe29vBESIeI912Fix514WXa97Ijh-pBuonFRcsyL0_-CF98rdhow6sZMhPdyOA9ud-PcAOwSHm-HrUUU_XkHGUVslBINAFOpOCYZh9qZ7jk6-5-Gk6MeyD4ok0BNz4XIKht_hj8yJQhphPz17hjguL9KPqK45HTl_D3SEStkbSaPK4fe-glMv2YJRh3nvdQYXkm-0cDmx4nets_4SH8U5DUwoFAB-Zh30-KHHe2nGbCYNrh7oUOEoC7mmF90HG0jwsbI5KSNDStckQ8pEZhpppVWyPh0CjzOmDidlkjUZ8hMJARWw", "kid": "008vKoQ3ycDeaUxLN6bPlfk9cjIjqSrb" } }, "ctx": [ { "data": { "clientLibraryIntegrity": " CLIENT LIBRARY INTEGRITY VALUE GOES HERE", "clientLibrary": "CLIENT LIBRARY VALUE GOES HERE", "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "MAESTRO", "DISCOVER", "DINERSCLUB", "JCB", "CUP", "CARTESBANCAIRES" ], "targetOrigins": [ "https://example.com" ], "mfOrigin": "https://example.com", "allowedPaymentTypes": [ "CARD" ] }, "type": "mf-2.1.0" } ] }
Capture Context Request for Accepting Check Information
{ "clientVersion": "v2", "targetOrigins": [ "https://www.example.com", "https://www.basket.example.com", "https://ecom.example.com" ], "allowedPaymentTypes": ["CHECK"] }
Successful Encrypted JWT Response for Accepting Check Information
eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJtdnkwVk9OVk40bzA4bTRGQjhmU3FCQUFFS0JWOTdlNnR2VDd4cHdqaFkwMDRydFJ1dGI0R2YwWlNwNGdNeEkvanBVSWxFblZKa2JtUVNHaWFnUEdGc0NPazdMbHJGTHFKcXN2eitoTHhrY08xRkFcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoidmRpN0gtM1MzMTkyZlc5WC1BTmpvdjlFdXU4ZGxPOTBtU2gyUGVyMF9PdHZ4YlJITTBrakZpTHlKaGQwUUR3VlNWbUlhRFc2aGtCa1k2Ui1lcWRnaTdUVUNGZEQ3UUU1ckNkZGhZZTIycTh0RUNQZkpOWWJ6STZZTVBxTkFyYWc5LUhhWVo1X2tOX0JvMm5EclN4RFJ0MHBDbGxyd2d2Q1ZLb2M0RWF6ZE93QUE4dnI2VVh4Ty1SWVI2Z1R5VEZia244Q2hDVHNvWDByam5VWVI1VjdRaE95YzMzWEJUTVNDYTVBOHFQNDZnZXpvQjZ0dDA0SlQtRVVMWE9vYndVcVdvd0E3TTJzWUYydkFoQkVuMmt0REJFWVJSN3E0aWEyVHRIS1JPUW9FTjhZNjNiNFNaTGZDQk82cEc2QXpnSWpya3RkQXhIOXR0WURYdFJYS1YxeTN3Iiwia2lkIjoiMDBiQlN1d3VpdGtYeExROGFISWloMm5qMFhQNFpXYUsifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsInRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly90aGUtdXAtZGVtby5hcHBzcG90LmNvbSJdLCJtZk9yaWdpbiI6Imh0dHBzOi8vc3RhZ2VmbGV4LmN5YmVyc291cmNlLmNvbSIsImFsbG93ZWRQYXltZW50VHlwZXMiOlsiQ0hFQ0siXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzM0OTAxODEsImlhdCI6MTczMzQ4OTI4MSwianRpIjoiSXdEdHAxZkVZM2QwYUh6OSJ9.arokacvdTSUIehBY0ICi__2szuCdrvykJZq4T69n4OcWGym5PErJO0moJD-QYynhFj7_0k-G39qbkNJydB3UyF2qJSaqwZiopO27kuqk8u9Z0cY-V9Nu04JgaV4s18doxnzx6vdTCC3krrIcxeINi23Qu-Szcpg7aaGvPVXMC0DVC14WUQiGJkOakJ54jWtl2VoFAgYziUMcYYpk4hxLVxurBtT7lvrfCXKoyWtxiUxoEpOc_Td_qi5nA8ByWUaieQmp1Zej61khQJ_hmXtlsAt4BqxeJWoJeR_5Sjz0vD5y4-oAeNNrAulDem7CKiRJQbI9fyqT-H5Cmjd6YQchxQ
Decrypted Capture Context Body with Selected Fields for Accepting Check
Information
{ "flx": { "path": "/flex/v2/tokens", "data": "mvy0VONVN4o08m4FB8fSqBAAEKBV97e6tvT7xpwjhY004rtRutb4Gf0ZSp4gMxI/jpUIlEnVJkbmQSGiagPGFsCOk7LlrFLqJqsvz+hLxkcO1FA=", "origin": "https://example.com", "jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "vdi7H-3S3192fW9X-ANjov9Euu8dlO90mSh2Per0_OtvxbRHM0kjFiLyJhd0QDwVSVmIaDW6hkBkY6R-eqdgi7TUCFdD7QE5rCddhYe22q8tECPfJNYbzI6YMPqNArag9-HaYZ5_kN_Bo2nDrSxDRt0pCllrwgvCVKoc4EazdOwAA8vr6UXxO-RYR6gTyTFbkn8ChCTsoX0rjnUYR5V7QhOyc33XBTMSCa5A8qP46gezoB6tt04JT-EULXOobwUqWowA7M2sYF2vAhBEn2ktDBEYRR7q4ia2TtHKROQoEN8Y63b4SZLfCBO6pG6AzgIjrktdAxH9ttYDXtRXKV1y3w", "kid": "00bBSuwuitkXxLQ8aHIih2nj0XP4ZWaK" } }, "ctx": [ { "data": { "clientLibraryIntegrity": "CLIENT LIBRARY INTEGRITY VALUE GOES HERE", "clientLibrary": "CLIENT LIBRARY VALUE GOES HERE ", "targetOrigins": [ "https://the-up-demo.appspot.com" ], "mfOrigin": "https://stageflex.cybersource.com", "allowedPaymentTypes": [ "CHECK" ] }, "type": "mf-2.1.0" } ], "iss": "Flex API", "exp": 1733490181, "iat": 1733489281, "jti": "IwDtp1fEY3d0aHz9" }
Getting Started Examples
Example: Checkout Payment Form for Accepting Card Information
This simple payment form captures the name, PAN, CVN, month, and year, and a pay button
for submitting the information.
Back to Client-Side Setup.
<h1>Checkout</h1> <div id="errors-output" role="alert"></div> <form action="/token" id="my-sample-form" method="post"> <div class="form-group"> <label for="cardholderName">Name</label> <input id="cardholderName" class="form-control" name="cardholderName" placeholder="Name on the card"> <label id="cardNumber-label">Card Number</label> <div id="number-container" class="form-control"></div> <label for="securityCode-container">Security Code</label> <div id="securityCode-container" class="form-control"></div> </div> <div class="form-row"> <div class="form-group col-md-6"> <label for="expMonth">Expiry month</label> <select id="expMonth" class="form-control"> <option>01</option> <option>02</option> <option>03</option> <option>04</option> <option>05</option> <option>06</option> <option>07</option> <option>08</option> <option>09</option> <option>10</option> <option>11</option> <option>12</option> </select> </div> <div class="form-group col-md-6"> <label for="expYear">Expiry year</label> <select id="expYear" class="form-control"> <option>2021</option> <option>2022</option> <option>2023</option> </select> </div> </div> <button type="button" id="pay-button" class="btn btn-primary">Pay</button> <input type="hidden" id="flexresponse" name="flexresponse"> </form>
Example: Checkout Payment Form for Accepting Check
Information
This simple payment form captures the name, PAN, CVN, month, and year, and a pay button
for submitting the information.
Back to Client-Side Setup.
<h1>Checkout</h1> <div id="errors-output" role="alert"></div> <form action="/token" id="my-sample-form" method="post"> <div class="form-group"> <label id="routingNumber-label">Routing Number</label> <div id="routingNumber-container" class="form-control"></div> <label for="accountNumber-label">Account Number</label> <div id="accountNumber-container" class="form-control"></div> <label for="accountNumberConfirm-label">Account Number Confirm</label> <div id="accountNumberConfirm-container" class="form-control"></div> </div> <div class="form-row"> <div class="form-group col-md-6"> <label for="accountType">Account Type</label> <select id="accountType" name="accountType" class="form-control"> <option value="C">Checking</option> <option value="S">Savings</option> <option value="X">Corporate checking</option> </select> </div> </div> <button type="button" id="pay-button" class="btn btn-primary">Pay</button> <input type="hidden" id="flexresponse" name="flexresponse"> </form>
Back to Transient Token Time Limit.
payButton.('click', function () { // Compiling MM & YY into optional parameters const options = { expirationMonth: document.querySelector('#expMonth').value, expirationYear: document.querySelector('#expYear').value }; // microform.createToken(options, function (err, token) { if (err) { // handle error console.error(err); errorsOutput.textContent = err.message; } else { // At this point you may pass the token back to your server as you wish. // In this example we append a hidden input to the form and submit it. console.log(JSON.stringify(token)); flexResponse.value = JSON.stringify(token); form.submit(); } }); });
Back to Transient Token Time Limit.
payButton.('click', function () { // Compiling account type into optional parameters var options = { accountType: document.querySelector('#accountType').value, }; // microform.createToken(options, function (err, token) { if (err) { // handle error console.error(err); errorsOutput.textContent = err.message; } else { // At this point you may pass the token back to your server as you wish. // In this example we append a hidden input to the form and submit it. console.log(JSON.stringify(token)); flexResponse.value = JSON.stringify(token); form.submit(); } }); });
Example: Customer-Submitted Form with Card
Information
Back to Transient Token Time Limit.
<script> // Variables from the HTML form const form = document.querySelector('#my-sample-form'); const payButton = document.querySelector('#pay-button'); const flexResponse = document.querySelector('#flexresponse'); const expMonth = document.querySelector('#expMonth'); const expYear = document.querySelector('#expYear'); const errorsOutput = document.querySelector('#errors-output'); // the capture context that was requested server-side for this transaction const captureContext = <% -keyInfo %> ; // custom styles that will be applied to each field we create using Microform const myStyles = { 'input': { 'font-size': '14px', 'font-family': 'helvetica, tahoma, calibri, sans-serif', 'color': '#555' }, ':focus': { 'color': 'blue' }, ':disabled': { 'cursor': 'not-allowed' }, 'valid': { 'color': '#3c763d' }, 'invalid': { 'color': '#a94442' } }; // setup Microform const flex = new Flex(captureContext); const microform = flex.microform({ styles: myStyles }); const number = microform.createField('number', { placeholder: 'Enter card number' }); const securityCode = microform.createField('securityCode', { placeholder: '•••' }); number.load('#number-container'); securityCode.load('#securityCode-container'); // Configuring a Listener for the Pay button payButton.addEventListener('click', function () { // Compiling MM & YY into optional paramiters const options = { expirationMonth: document.querySelector('#expMonth').value, expirationYear: document.querySelector('#expYear').value }; // microform.createToken(options, function (err, token) { if (err) { // handle error console.error(err); errorsOutput.textContent = err.message; } else { // At this point you may pass the token back to your server as you wish. // In this example we append a hidden input to the form and submit it. console.log(JSON.stringify(token)); flexResponse.value = JSON.stringify(token); form.submit(); } }); }); </script>
Example: Customer-Submitted Form with Check Information
Back to Transient Token Time Limit.
<script> // Variables from the HTML form const form = document.querySelector('#my-sample-form'); const payButton = document.querySelector('#pay-button'); const flexResponse = document.querySelector('#flexresponse'); const accountType = document.querySelector('#accountType') const errorsOutput = document.querySelector('#errors-output'); // the capture context that was requested server-side for this transaction const captureContext = <% -keyInfo %> ; // custom styles that will be applied to each field we create using Microform const myStyles = { 'input': { 'font-size': '14px', 'font-family': 'helvetica, tahoma, calibri, sans-serif', 'color': '#555' }, ':focus': { 'color': 'blue' }, ':disabled': { 'cursor': 'not-allowed' }, 'valid': { 'color': '#3c763d' }, 'invalid': { 'color': '#a94442' } }; // setup Microform const flex = new Flex(captureContext); const microform = flex.microform("check", { styles: myStyles }); const routingNumber = microform.createField("routingNumber", { placeholder: "Enter routing number" }); const accountNumber = microform.createField("accountNumber", { placeholder: "Enter account number" }); const accountNumberConfirm = microform.createField("accountNumberConfirm", { placeholder: "accountNumberConfirm" }); routingNumber.load('#routingNumber-container') accountNumber.load('#accountNumber-container') accountNumberConfirm.load('#accountNumberConfirm-container') // Configuring a Listener for the Pay button payButton.addEventListener('click', function () { // Compiling MM & YY into optional paramiters const options = { accountType: document.querySelector('#accountType').value, }; // microform.createToken(options, function (err, token) { if (err) { // handle error console.error(err); errorsOutput.textContent = err.message; } else { // At this point you may pass the token back to your server as you wish. // In this example we append a hidden input to the form and submit it. console.log(JSON.stringify(token)); flexResponse.value = JSON.stringify(token); form.submit(); } }); }); </script>
Example: Token Payload with Card Information
Back to Transient Token Response Format.
{ "iss": "Flex/00", "exp": 1728911080, "type": "mf-2.0.0", "iat": 1728910180, "jti": "1D1S6JK9RL6EK667H1I370689A63I2I8YLFJSPJ1EUSKIPMJJWEL670D16E89AF8", "content": { "paymentInformation": { "card": { "expirationYear": { "value": "2025" }, "number": { "detectedCardTypes": [ "001" ], "maskedValue": "XXXXXXXXXXXX1111", "bin": "411111" }, "securityCode": {}, "expirationMonth": { "value": "01" } } } } }
Example: Token Payload with Check Information
Back to Transient Token Response Format.
{ "iss" : "Flex/00", "exp" : 1732527524, "type" : "mf-2.1.0", "iat" : 1732526624, "jti" : "1D3HRVI3KM4HFWQAZ2JFI993NEVBAH5NYJFIH82RAMYWDUJ444KT674445A4EAC0", "content" : { "paymentInformation" : { "bank" : { "routingNumber" : { }, "account" : { "number" : { }, "type" : { } } }, "paymentType" : { "name" : { "value" : "CHECK" } } } } }
Example: Token Payload with Multiple Card Types
Back to Transient Token Response Format.
{ "iss": "Flex/08", "exp": 1661350495, "type": "mf-2.0.0", "iat": 1661349595, "jti": "1C174LLWIFFR9OV0V0IJQOY0IB1JQP70ZNF4TBI3V6H3AIOY0W1T6306325F91C0", "content": { "paymentInformation": { "card": { "expirationYear": { "value": "2023" }, "number": { "detectedCardTypes": [ "042", "036" ], "maskedValue": "XXXXXXXXXXXX1800", "bin": "501767" }, "securityCode": {}, "expirationMonth": { "value": "01" } } } } }
Example: Capture Context Public Key
"jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "3DhDtIHLxsbsSygEAG1hcFqnw64khTIZ6w9W9mZNl83gIyj1FVk-H5GDMa85e8RZFxUwgU_zQ0kHLtONo8SB52Z0hsJVE9wqHNIRoloiNPGPQYVXQZw2S1BSPxBtCEjA5x_-bcG6aeJdsz_cAE7OrIYkJa5Fphg9_pxgYRod6JCFjgdHj0iDSQxtBsmtxagAGHjDhW7UoiIig71SN-f-gggaCpITem4zlb5kkRVvmKMUANe4B36v4XSSSpwdP_H5kv4JDz_cVlp_Vy8T3AfAbCtROyRyH9iH1Z-4Yy6T5hb-9y3IPD8vlc8E3JQ4qt6U46EeiKPH4KtcdokMPjqiuQ", "kid": "00UaBe20jy9VkwZUQPZwNNoKFPJA4Qhc" }
Example: Validating the Transient Token
This example shows how to extract the signature key from the capture context and use the
key to validate the transient token object returned from a successful microform
interaction.
console.log('Response TransientToken: ' + req.body.transientToken); console.log('Response CaptureContext: ' + req.body.captureContext); // Validating Token JWT Against Signature in Capture Context const capturecontext = req.body.captureContext; const transientToken = req.body.transientToken; // Extracting JWK in Body of Capture Context const ccBody = capturecontext.split('.')[1]; console.log('Body: ' + ccBody); const atob = require('atob'); const ccDecodedValue = JSON.parse( atob(ccBody)); const jwk = ccDecodedValue.flx.jwk; console.log('CaptureContext JWK: ' + JSON.stringify(jwk)); // Converting JWK to PEM const jwkToPem = require('jwk-to-pem'), jwt = require('jsonwebtoken'); const pem = jwkToPem(jwk); // Validating JWT const validJWT = jwt.verify(transientToken, pem); console.log('Validated Resposonse: ' + JSON.stringify(validJWT));
Example: Authorization with a Transient Token Using the REST API
{ "clientReferenceInformation": { "code": "TC50171_3" }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "Tanya", "lastName": "Lee", "address1": "1234 Main St.", "locality": "Small Town", "administrativeArea": "MI", "postalCode": "98765-4321", "country": "US", "district": "MI", "buildingNumber": "123", "email": "tanyalee@example.com", "phoneNumber": "987-654-3210" } }, "tokenInformation": { "transientTokenJwt": "eyJraWQiOiIwN0JwSE9abkhJM3c3UVAycmhNZkhuWE9XQlhwa1ZHTiIsImFsZyI6IlJTMjU2In0.eyJkYXRhIjp7ImV4cGlyYXRpb25ZZWFyIjoiMjAyMCIsIm51bWJlciI6IjQxMTExMVhYWFhYWDExMTEiLCJleHBpcmF0aW9uTW9udGgiOiIxMCIsInR5cGUiOiIwMDEifSwiaXNzIjoiRmxleC8wNyIsImV4cCI6MTU5MTc0NjAyNCwidHlwZSI6Im1mLTAuMTEuMCIsImlhdCI6MTU5MTc0NTEyNCwianRpIjoiMUMzWjdUTkpaVjI4OVM5MTdQM0JHSFM1T0ZQNFNBRERCUUtKMFFKMzMzOEhRR0MwWTg0QjVFRTAxREU4NEZDQiJ9.cfwzUMJf115K2T9-wE_A_k2jZptXlovls8-fKY0muO8YzGatE5fu9r6aC4q7n0YOvEU6G7XdH4ASG32mWnYu-kKlqN4IY_cquRJeUvV89ZPZ5WTttyrgVH17LSTE2EvwMawKNYnjh0lJwqYJ51cLnJiVlyqTdEAv3DJ3vInXP1YeQjLX5_vF-OWEuZfJxahHfUdsjeGhGaaOGVMUZJSkzpTu9zDLTvpb1px3WGGPu8FcHoxrcCGGpcKk456AZgYMBSHNjr-pPkRr3Dnd7XgNF6shfzIPbcXeWDYPTpS4PNY8ZsWKx8nFQIeROMWCSxIZOmu3Wt71KN9iK6DfOPro7w" } }
JSON Web Tokens
JSON Web Tokens (JWTs) are digitally signed JSON objects based on the open standard RFC 7519. These tokens provide a compact, self-contained
method for securely transmitting information between parties. These tokens are
signed with an RSA-encoded public/private key pair. The signature is calculated
using the header and body, which enables the receiver to validate that the content
has not been tampered with. Token-based applications are best for applications that
use browser and mobile clients.
A JWT takes the form of a string, consisting of three parts separated by dots:
- Header
- Payload
- Signature
This example shows a JWT:
xxxxx.yyyyy.zzzzz
Browser Support
Microform Integration
is supported on these browsers and versions: - Chrome 80 or later
- Edge 109 or later
- Firefox 115 or later
- Opera 106 or later
- Safari 13 or later
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.Test Card Numbers
Use these test card numbers to test your
Microform Integration
configuration.Combine the BIN with the card number when sending to
Microform Integration
.Card Brand | BIN | Card Number | Expiration Date | CVV |
---|---|---|---|---|
Visa | 424242 | 4242424242 | 12/2024 | 123 |
Mastercard | 555555 | 5555554444 | 02/2025 | 265 |
American Express | 378282 | 246310005 | 03/2026 | 7890 |
Cartes Bancaires | 436000 | 0001000005 | 04/2040 | 123 |
Carnet | 506221 | 0000000009 | 04/2024 | 123 |
China UnionPay | 627988 | 6248094966 | 04/2040 | 123 |
Diners Club | 305693 | 09025904 | 04/2040 | 123 |
Discover | 644564 | 4564456445 | 04/2040 | 123 |
JCB | 353011 | 13333 0000 | 04/2040 | 123 |
Maestro | 675964 | 9826438453 | 04/2040 | 123 |
Mada | 446404 | 0000000007 | 04/2040 | 123 |
ELO | 451416 | 0000000003 | 04/2040 | 123 |
JCrew | 515997 | 1500000005 | 04/2040 | 123 |
EFTPOS | 401795 | 000000000009 | 04/2040 | 123 |
Meeza | 507808 | 3000000002 | 04/2040 | 123 |