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
front-end JavaScript library how to behave within your payment experience. The request
provides authentication, one-time keys, the target origin to the
Microform Integration
, in addition to allowed card networks and payment
types (card or check). The capture context request includes these elements:
If you want to receive an 8-digit card number prefix in the response
Include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context request, and set the value to
true
.
IMPORTANT
Per PCI DSS
requirements, this requirement applies only to card numbers
longer than 15 digits and for Discover, JCB, Mastercard,
UnionPay, and Visa brands.
If the card type entered is not part of these brands, a
6-digit card number prefix is returned instead.
If the card type entered is not part of these brands but
is
co-branded
with these brands, an 8-digit card
number prefix is returned.
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
field 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
Depending on the cryptographic method you use to validate the public key,
you might need to convert the key to privacy-enhanced mail (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 use these values for every transaction.
These values can be unique for each transaction.
IMPORTANT
Do not hard code these values, because
doing so can result in client-side
Microform Integration
errors.
If you do not hard code these values for all transactions,
you can 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
// values read from capture context
const clientLibrary = " ";
const clientLibraryIntegrity = " ";
// create script tag
const script = document.createElement("script");
script.src = clientLibrary;
script.type = "text/javascript";
script.async = true;
script.integrity = clientLibraryIntegrity;
script.crossOrigin = "anonymous";
// run setup code after script has loaded successfully
script.onload = function () {
// SETUP
};
// insert to document
document.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. This 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 in API requests for a 15-minute duration.
After 15 minutes, you must prompt the customer to restart the checkout flow.
Example: Creating the Pay Button with Event Listener for Accepting Card Information
const button = document.querySelector("#myButton");
button.addEventListener("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) {
// handle err
if (err) {
console.error(err);
errorsOutput.textContent = err.message;
return;
}
// 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 Account Type is 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
eCheck
data
when you use supported payment services.
Example: Customer-Submitted Form for Accepting Card
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 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 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();
}
});
});
</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 Card 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.
After you validate the transient token, you can use it in place of the PAN with payment
services for 15 minutes. See Transient Token Time Limit.
When the consuming service receives a request containing a transient token, it retrieves
the tokenized data and injects the values into your request before processing, and none
of the sensitive data is stored on your systems. In some scenarios, the
jti
value contained in the JWT transient token response must be
extracted and used instead of the entire JWT.
