This section contains the information you need to set up your server. Initializing
Microform Integration
within your webpage begins with a server‑to‑server
call to the sessions API. This step authenticates your merchant credentials and
establishes how the
Microform Integration
frontend components will function.
The sessions API request contains parameters that define how
Microform Integration
performs.
The server-side component provides this
information:
A transaction-specific public key is used by the customer's browser to protect the
transaction.
An authenticated context description package that manages the payment experience on
the client side. It includes available payment options such as card networks,
payment interface styling, and payment methods.
The functions are compiled in a JSON Web Token (JWT)
object referred to as the
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:
Ensure that all endpoints within your ownership are secure with some kind of
authentication so they cannot be called at will by bad actors.
Do not pass the
targetOrigin
in any external requests. Hard
code it on the server side.
For more information on requesting the capture context, see Capture Context.
Validating the Server-Side Capture Context
The capture context that you generated is a JSON Web Token (JWT) data object. The
JWT is digitally signed using a public key. The purpose is to ensure the validity of the
JWT and confirm that it comes from
Cybersource
. When you do not have a
key specified locally in the JWT header, you should follow best cryptography practices
and validate the capture context signature.
To validate a JWT, you can obtain its public key. This public RSA key is in JSON Web Key
(JWK) format. This public key is associated with the capture context on the
Cybersource
domain.
To get the public key of a capture context from the header of the capture context itself,
retrieve the key ID associated with the public key. Then, pass the key ID to the
public-keys
endpoint.
Example
From the header of the capture context, get the key ID (
kid
) as shown in
this example:
{
"kid": "3g"
,
"alg": "RS256"
}
Append the key ID to the endpoint
/flex/v2/public-keys/
3g
. Then,
call this endpoint to get the public key.
IMPORTANT
When validating the public key, some cryptographic methods
require you to convert the public key to PEM format.
Resource
Pass the key ID (kid), that you obtained from the capture context header, as a path
parameter, and send a GET request to the
/public-keys
endpoint:
Test:
https://apitest.cybersource.com
/flex/v2/public-keys/
{kid}
Production:
https://api.cybersource.com
/flex/v2/public-keys/
{kid}
The resource returns the public key. Use this public RSA key to validate the capture
context.
with your native payment
acceptance web page or mobile application.
Web Page
Initiate and embed
Microform Integration
into your payment
acceptance web page.
Decode the JWT from the
/microform/v2/sessions
response to
get the capture context.
Use the
clientLibrary
and
clientLibraryIntegrity
values that are returned in
the JWT from
/microform/v2/sessions
response to obtain the
Microform Integration
JavaScript library URL and integrity
value that you use to create your script tags.
IMPORTANT
You must do this for every transaction as these
values can be unique for each transaction. Do not hard code these
values, as this can result in client-side
Microform Integration
errors. If you do not do this for every transaction, you may load a
JavaScript library that is incompatible with the version you requested
in the
/sessions
request.
Example
/sessions
Response:
"data":{ "clientLibrary":"[EXTRACT clientLibrary VALUE from here]", "clientLibraryIntegrity": "[EXTRACT clientLibraryIntegrity VALUE from here]" }
Example Script
Tags
<script src="[INSERT clientLibrary VALUE HERE]" integrity=”[INSERT clientLibraryIntegrity VALUE HERE]” crossorigin=”anonymous”> </script>
Example Code for loading the script dynamically following JWT
extraction
Tags
const head = document.getElementsByTagName('head')[0];
const script = document.createElement('script');
script.type = 'text/javascript';
script.async = true;
script.onload = function() {
// Invoke the Flex SDK once the scripts are loaded asynchronously
flexSetup();
}
//url extracted from the JWT
script.src = url;
//integrity extracted from the JWT
if (clientLibraryIntegrity) {
script.integrity = clientLibraryIntegrity;
script.crossOrigin = "anonymous";
}
head.appendChild(script);
Create the HTML placeholder objects to attach to the microforms.
Microform Integration
attaches the microform fields to
containers within your HTML. Within your HTML checkout, replace the
payment card and CVN tag with a simple container.
Microform Integration
uses the container to render an iframe for
secured credit card input. The following example contains simple
div
tags to define where to place the PAN and CVN
fields within the payment acceptance page:
Invoke the Flex SDK by passing the capture context that was generated in
the previous step to the microform object.
const flex = new Flex(captureContext);
Initiate the microform object with styling to match your web page.
After you create a new Flex object, you can begin creating your
Microform. You will pass your baseline styles and ensure that the button
matches your merchant page:
The response to a successful customer interaction with
Microform Integration
is a transient token. The transient token is a reference to the payment data that is
collected on your behalf. Tokens allow secure card or check payments to occur without
risk of exposure to sensitive payment information. The transient token is a short-term
token that expires after 15 minutes. This reduces your PCI burden/responsibility and
ensures that sensitive information is not exposed to your back-end systems.
Transient Token Time Limit
The sensitive data associated with the transient token is available for use only for 15
minutes or until one successful authorization occurs. Before the transient token
expires, its data is still usable in other non-authorization services. After 15 minutes,
you must prompt the customer to restart the checkout flow.
Example: Creating the Pay Button with Event Listener for Accepting Check
Information
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();
}
});
});
When the customer submits the form,
Microform Integration
securely collects
and tokenizes the data in the loaded fields as well as the options supplied to the
createToken()
function. The month and year are included in the
request. If tokenization succeeds, your callback receives the token as its second
parameter. Send the token to your server, and use it in place of the PAN when you use
supported payment services.
Example: Customer-Submitted Form for Accepting Check
Information
<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>
Transient Token Response Format
The transient token is issued as a JSON Web Token (RFC
7519). A JWT is a string consisting of three parts that are separated by
dots:
Header
Payload
Signature
JWT example:
xxxxx.yyyyy.zzzzz
The payload portion of the token is an encoded Base64url JSON string and contains various
claims.
IMPORTANT
When you integrate 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.
The internal data structure of the
JWT can expand to contain additional data elements. Ensure that your integration and
validation rules do not limit the data elements contained in responses.
Example: Token Payload for Accepting Check Information
After receiving the transient token, validate its integrity using the public key embedded
within the capture context created at the beginning of this flow. This verifies that
Cybersource
issued the token and that no data tampering occurred
during transit.
Use the capture context public key to cryptographically validate the JWT provided from a
successful
microform.createToken
call. You might have to convert
the JSON Web Key (JWK) to privacy-enhanced mail (PEM) format for compatibility with some
JWT validation software libraries.
The
Cybersource
SDK has functions that verify the token response. You
must verify the response to ensure that no tampering occurs as it passes through the
cardholder device. Do so by using the public key generated at the start of the
process.
