This revision contains only editorial changes and no technical updates.
25.04.02
Unified Checkout
Added a client version history and the features included in each version. See Client Version History.
Added information on the available features and the fields specific to each feature
to the Capture Context API. See Capture Context API
Microform Integration
Added more information on nested iframes in the capture context. See Capture Context.
Click to Pay Drop-In UI
Added more information on nested iframes in the capture context. See Capture Context.
25.04.01
Unified Checkout
Added more information on nested iframes in the capture context. See Capture Context.
Microform Integration
Added more information on nested iframes in the capture context. See Capture Context.
Click to Pay Drop-In UI
Added more information on nested iframes in the capture context. See Capture Context.
25.03.01
Microform Integration
v2
Added information about choosing your preferred card number prefix length and
supported scenarios. See the Include Card Prefix sections of these topics:
Capture Context (server-side set up for the capture context)
Capture Context API
(requesting the capture context using the capture context API)
Updated the description of Transient Token Time Limit for accepting card
information
Added information about choosing your preferred card number prefix length and
supported scenarios. See the Include Card Prefix sections of these topics:
Capture Context
(server-side set up for the capture context)
Capture Context API
(requesting the capture context using the capture context API)
Added information about choosing your preferred card number prefix length and
supported scenarios. See the Include Card Prefix sections of these topics:
Capture Context
(server-side set up for the capture context)
Capture Context API
(requesting the capture context using the capture context API)
25.01.02
Unified Checkout
Added optional set-up parameters to control the types of credentials that Google Pay
on
Updated the capture context request sections to include the most recent client
version and allowed payment types. See Capture Context and Capture Context API.
Click to Pay Drop-In UI
Updated the capture context request sections to include the most recent client
version and allowed payment types. See Capture Context and Capture Context API.
Added information about China UnionPay cards that do not have a card verification
number (CVN) and expiration date. See the Important note in Capture Context.
24.09.01
Microform Integration
Removed information about Microform version numbering.
This revision contains only editorial changes and no
technical updates.
VISA Platform Connect: Specifications and Conditions for
Resellers/Partners
The following are specifications and conditions that apply to a Reseller/Partner enabling
its merchants through
Cybersource for
Visa Platform Connect
(“VPC”)
processing
. Failure to meet any of the specifications and conditions below is
subject to the liability provisions and indemnification obligations under
Reseller/Partner’s contract with Visa/Cybersource.
Before boarding merchants for payment processing on a VPC acquirer’s connection,
Reseller/Partner and the VPC acquirer must have a contract or other legal agreement
that permits Reseller/Partner to enable its merchants to process payments with the
acquirer through the dedicated VPC connection and/or traditional connection with
such VPC acquirer.
Reseller/Partner is responsible for boarding and enabling its merchants in
accordance with the terms of the contract or other legal agreement with the relevant
VPC acquirer.
Reseller/Partner acknowledges and agrees that all considerations and fees associated
with chargebacks, interchange downgrades, settlement issues, funding delays, and
other processing related activities are strictly between Reseller and the relevant
VPC acquirer.
Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is
responsible for payment processing issues, including but not limited to, transaction
declines by network/issuer, decline rates, and interchange qualification, as may be
agreed to or outlined in the contract or other legal agreement between
Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR
OMISSIONS BY THE
Visa Platform Connect
ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA
NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR
ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE
RELEVANT
Visa Platform Connect
ACQUIRER.
Introducing
Digital Accept
Secure Integration Product Suite
The Secure Integration Product Suite allows you to simplify the acceptance of sensitive
customer payment information. When a customer enters their payment details on your
webpage, app, or elsewhere, it is replaced with a transient token. Tokenization ensures
that the card data can be transported securely, which limits your exposure and
significantly reduces your Payment Card Industry Data Security Standard (PCI DSS)
compliance burden.
The Secure Integration Product Suite consists of three products that can be used in a
variety of scenarios:
Unified Checkout
,
Microform Integration
, and
Flex API
.
Unified Checkout
Unified Checkout
is a pre-configured drop-in UI for accepting online
payments. It supports multiple payment methods including traditional cards and
digital wallets such as Google Pay and Visa Click to Pay. Because it is
pre-configured with digital payment support,
Unified Checkout
enables
you to go live faster and substantially reduce the development burden of accepting a
multitude of payment options. This solution is ideal for sellers looking for a
complete payment acceptance technology with support for multiple payment
methods.
is a payment card and card verification acceptance
solution that can be embedded. Use it to securely accept payment information at your
web page and have complete control over the look and feel of your payment form.
Microform Integration
captures the card number and card verification
number fields from within your existing user interface. This solution is for sellers
looking for a secure way to capture sensitive payment data from within their own
customized payment form.
can be used to securely capture and transport payment
data between systems. This solution is ideal for Internet of Things (IoT) and
third-party integrations. For more information, see Flex API.
Digital Accept
Product Comparison
This chart compares
Digital Accept
products and features.
Figure:
Products and Features Comparison Chart
Flex API
v2
The
Flex API
v2 suite enables a merchant to ensure secure transmission
of payment information captured from client-side code. Integrate your system with
Flex API
v2 to enable
Cybersource
to protect your
customer's primary account number (PAN), card verification number (CVN), and other
payment information when payment processing activity crosses the Web.
IMPORTANT
Flex API
is not designed to be used from the
browser. For securing payment information from the browser, please see the
Microform Integration
product.
Use the APIs in this suite to secure your customer's payment information, and exchange
this sensitive data for a
transient token
. A transient token is a temporary
reference to sensitive data that
Cybersource
has securely stored on your
behalf. A transient token can be transported and stored safely without adding risk to
your PCI DSS burden.
IMPORTANT
The transient token response can be cryptographically validated
to ensure that payload injection attacks can be mitigated.
Before you capture the payment data from the client application, generate the context in
which the data is to be captured and tokenized. The
capture context
can
help you to limit PCI exposure to the context in which it is captured.
After you capture the payment data from the client application, the
Flex API
v2 can secure and tokenize the data:
Cybersource
secures your customer's card data at the device
using one-time public encryption keys.
Cybersource
then replaces the card data in the client
application form with a transient token. A transient token can only be accessed
by the merchant.
After you tokenize the payment information, you can initiate
Cybersource
services that use transient tokens in place of your customer's payment information.
Flex API
v2 Integration Task List
The
Flex API
v2 is a suite of APIs that enables a merchant to safely
and securely accept customer payment information from within a
client application. The objective is to replace
sensitive payment information with a transient token that can be transmitted without
exposing the payment information.
The first step to Flex API v2 is to generate the context of the customer payment
information that is to be captured and tokenized.
IMPORTANT
Declaring the capture context ensures that no data can be injected
into the process by a malicious actor.
To generate the capture context, use the
/sessions
API endpoint to
specify the payment data to be captured. The API returns a JSON Web Token (JWT) data
object that contains the authentication component of the interactions and the one-time
public encryption keys to which the payment information is to be secured.
IMPORTANT
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.
Resource
Send a fully authenticated POST request from your backend system to the
/sessions
API:
Test:
https://apitest.cybersource.com
/flex/v2/sessions
Production:
https://api.cybersource.com
/flex/v2/sessions
The resource returns a capture context, which is a JWT date element containing the
keys necessary to encrypt the payment data.
Payment API Fields
This is the list of possible fields to capture and tokenize.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.address2
orderInformation.billTo.administrativeArea
orderInformation.billTo.buildingNumber
orderInformation.billTo.company
orderInformation.billTo.country
orderInformation.billTo.district
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.phoneNumber
orderInformation.billTo.postalCode
orderInformation.shipTo.address1
orderInformation.shipTo.address2
orderInformation.shipTo.administrativeArea
orderInformation.shipTo.buildingNumber
orderInformation.shipTo.company
orderInformation.shipTo.country
orderInformation.shipTo.district
orderInformation.shipTo.firstName
orderInformation.shipTo.lastName
orderInformation.shipTo.locality
orderInformation.shipTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.securityCode
paymentInformation.card.type
This example shows the JWT decoded, containing the JSON Web Key (JWK) encryption
keys:
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.
API endpoint accepts a JSON Web Encryption (JWE) data
object that has been encrypted using the RsaOaep encryption scheme and the JSON Web
Key (JWK) provided in the capture context. JWE is a standard that defines how data
can be encrypted using JSON-based data structures. For details, see IETF RFC 7516 at
https://tools.ietf.org/html/rfc7516.
The JWE format consists of five sections separated by a period (
.
) delimiters:
header . encrypted_key . cypher_text . iv . auth_tag
The payload for the
/tokens
request is a JWE data object.
This shows an encrypted payload in a fully formed JWE data object:
After the payment information is secured in a JWE data object, it can be tokenized.
Use the resulting transient token within
Cybersource
APIs in place
of the payment information associated with it.
To tokenize the payment information, send the encrypted payment data to the
/tokens
API endpoint. The API responds to the request with a
transient token in the form of a JSON Web Token (JWT).
IMPORTANT
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.
Resource
IMPORTANT
Flex API
is not designed to be used from
the browser. For securing payment information from the browser, please see the
Microform Integration
product.
Send an unauthenticated POST request from your customer’s device or backend system to
the
/tokens
API endpoint:
Test:
https://apitest.cybersource.com
/flex/v2/tokens
Production:
https://api.cybersource.com
/flex/v2/tokens
The resource returns a transient token that represents the supplied customer card
data. The token can replace the payment information in any follow-on
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
/tokens
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.
Using the Transient Token to Process a Payment
After you validate the transient token, you can use it in
place of the PAN with payment services for 15 minutes. The transient token can be
used multiple times within the 15-minute period.
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.
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
/tokens
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.
Using the Transient Token to Process a Payment
After you validate the transient token, you can use it in
place of the PAN with payment services for 15 minutes. The transient token can be
used multiple times within the 15-minute period.
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.
After you validate the transient token, you can use it in
place of the PAN with payment services for 15 minutes. The transient token can be
used multiple times within the 15-minute period.
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.
JavaScript library to securely replace
sensitive input fields with
Cybersource
-hosted secure iframes. These
iframes capture payment information, including card numbers
and
eCheck
data. This ensures that sensitive data is
handled securely within your checkout process.
Accepting Card Information
For card transactions, the captured card number is replaced with a mathematically
irreversible token that only you can use. This token can be used in place of the
card number for follow-on transactions in existing
Cybersource
APIs.
Microform Integration
replaces the following card payment fields in your
input form:
Payment Card (PAN)
CVN
Month (non-sensitive)
Year (non-sensitive)
With this option you can pass imonth and year in the request (if required), but these
fields are non-sensitive.
This figure shows the
Microform Integration
process for accepting
card information.
Figure:
Microform Integration
Process with Card Information
Accepting
eCheck
Information
Microform Integration
also supports the
acceptance of
eCheck
information. As with card transactions, the
sensitive
eCheck
data is securely captured and replaced with a
token.
Accepting
eCheck
information enables merchants to collect funds
from a customer's bank account through both the ACH service and eCheck service (US
only) for
either of these flows:
ACH services
are a set of connections composed of the legacy gateway
solutions where
Cybersource
serves as the gateway.
eCheck
, the new service on Payments 2.0, is the
acquirer solution where
Cybersource
is the acquirer.
Microform Integration
replaces these
eCheck
information fields in your payment input form:
Routing Number
Account Number
Account type (non-sensitive)
This figure shows the
Microform Integration
process for accepting
eCheck
information.
Figure:
Microform Integration
Process with
eCheck
Information
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 information as follows:
Card information input fields:
Payment card or PAN
CVN
eCheck
information input fields:
Routing number
Account number
These iframes are hosted by
Microform Integration
, and the payment data is
submitted directly to
Cybersource
through the secure Flex API v2 suite.
This means that this data never passes through your systems.
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 the
Flex API
v2 suite.
Client-side JavaScript library that you integrate into your digital payment acceptance
web page for the secure acceptance of payment information:
Card information input fields:
Payment card or PAN
CVN
eCheck
information input fields:
Routing number
Account number
Accept Card Information
This section covers the implementation steps needed to complete the server-side and
client-side setup for accepting card information with
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
front-end 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)
.
These fields are available for requesting the capture context for accepting card information:
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. The transient token can be used multiple times within
the 15-minute period. 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
card information
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. For more information, see JSON Web Tokens.
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.
Using the Transient Token to Process a Payment
After you validate the transient token, you can use it in
place of the PAN with payment services for 15 minutes. The transient token can be
used multiple times within the 15-minute period.
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.
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
front-end 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.
These fields are available for requesting the capture context for accepting eCheck
information:
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
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 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
// 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.
Within your HTML checkout, replace the
routing number, account number, and confirm account number 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
routing number, account number, and confirm account number
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. The transient token can be used multiple times within
the 15-minute period. After 15 minutes, you must prompt the customer to restart the
checkout flow.
Example: Creating the Pay Button with Event Listener for Accepting
eCheck
Information
const button = document.querySelector("#myButton");
button.addEventListener("click", function () {
// Compiling accounttype into optional parameters
const options = {
accountType: document.querySelector(“#accountType”).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.
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
information
when you use supported payment services.
Example: Customer-Submitted Form for Accepting
eCheck
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 parameters
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. For more information, see JSON Web Tokens.
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.
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.
Next Steps
After you complete the server-side and client-side setup for accepting payment
information with
events and obtain
them through event listeners. For information, see Events.
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:
To style the text within the iframe element, use the JavaScript library.
The
styles
property in the set-up options accepts a CSS-like object that
allows customization of the text. Only a subset of the CSS properties is supported.
const 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'
}
};
const flex = new Flex('..........');
// apply styles to all fields
const microform = flex.microform({ styles: customStyles });
const securityCode = microform.createField('securityCode');
// override the text color for the card number field
const number = microform.createField('number', { styles: { input: { color: '#000' }}});
Supported Properties
These 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.
Events
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.
const secCodeLbl = document.querySelector('#mySecurityCodeLabel');
const 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 Integration
attempts to detect the card type as it is
entered. As card numbers are entered, detection information is sent back in the
change
event. You can use this information to build a dynamic user
experience by providing feedback to the user as they type their card number.
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.
It is up to the merchant to then take the results from
cardDetection
and pass that
into the
type
parameter within the
microformInstance.createToken(options,...)
method.
Microform Integration
no longer attempts to determine a single card type by default.
Instead, it returns
detectedCardTypes
, in the transient token response and the
merchant can decide how to handle this information.
Support for Dual-Branded Cards
Microform Integration
supports dual-branded cards. To utilize this feature, you
must include the card networks that have overlapping BIN ranges in the capture context
request. For
example:
These properties are in the object only if they contain a value; otherwise, they are
undefined. Verify the properties before using the event. This example displays how to use
this event to update other fields in your checkout process:
const 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;
});
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.
Parameters
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.
Unsubscribe an event handler from a Microform Field.
Parameter
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.
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.
Parameter
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 verify that it exists before use.
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.
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 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.
});
// disable any select options not in the detected card types list
cardTypeOptions.forEach(function (o) {
o.disabled = detectedCardTypes.includes(o.value);
});
});
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
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.
Parameter
Name
Type
Description
options
Object
Property
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();
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:
number
securityCode
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');
const= new Flex('.........');
// apply styles to all fields
const microform = flex.microform('card', { styles: customStyles });
// override the text color for the card number field only
const number = microform.createField('number', { styles: { input: { color: '#000' }}});
Providing Custom Styles to A Specific Field within the
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.
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
This 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 will raise
a
console.warn()
alert.
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.
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:
You can define the payment cards and digital payments that you want to
accept in the capture context.
You can provide up to nine origins in the
targetOrigins
field for nested iframes. If your
list of origins in the
targetOrigins
field contains
more than five entries, you must do the following:
Compare the list of origins in the
v2/sessions
targetOrigins
field with the
location.ancestorOrigins of the browser and ensure that they
match. For more information, see this description about
the location.ancestorOrigins property on the Mozilla Developer
website.
Confirm that the count of origins in the
targetOrigins
field matches that in the
content. If any origins are missing or are mismatched, the
system will not allow Microform to load and a client-side error
message appears.
If your application does not require up to nine nested iframes,
Cybersource
recommends that you minimize the number of nested
iframes to maintain optimal performance.
Allowed Card Networks
Use the
allowedCardNetworks
field 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
PayPak
Visa
When you integrate with
Microform Integration
to accept
card
or
eCheck
information, you must include at least one card network in the
allowedCardNetworks
field in the capture context
request.
Allowed Payment Types
You can specify the type of
Microform Integration
you want to
accept in the capture context. You can accept card
and
eCheck
information.
Use the
allowedPaymentTypes
field to define the payment
type:
CARD
CHECK
The
allowedPaymentTypes
field is optional. When this
field is provided in the capture context, the
Microform Integration
defaults the field value to
CARD
and is returned in the
response.
Include Card Prefix
You can control the length of the card number prefix to be received in the
response to the capture context
/sessions
request:
6 digits
8 digits
no prefix at all
To specify your preferred card number prefix length, include or exclude
the
transientTokenResponseOptions.includeCardPrefix
field
in the capture context
/sessions
request.
If you want to receive a 6-digit card number prefix in the
response:
Do not
include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context
/sessions
request.
This example shows how a 6-digit card number prefix
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.
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();
}
});
});
Example: Creating the Pay Button with
Event Listener for Checks
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
<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>
<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 parameters
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>
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.
A JWT takes the form of a string, and consists of three parts separated by dots:
<Header>.<Payload>.<Signature>
The header and payload is
Base64-encoded JSON
and contains these claims:
Header
: The algorithm and token type. For
example:
{
"kid": "zu",
"alg": "RS256"
}
Payload
: The claims of what the token represents. For
example:
: The signature is computed from the header and payload using a
secret or private key.
IMPORTANT
When working with JWTs,
Cybersource
recommends that you use a well- maintained JWT library to ensure proper decoding
and parsing of the JWT.
IMPORTANT
When parsing the JWT’s JSON payload, you must ensure that you
implement a robust solution for transversing JSON. Additional elements can be
added to the JSON in future releases. Follow JSON parsing best practices to
ensure that you can handle the addition of new data elements in the future.
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
.
Test Card Numbers
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
Introduction to
Unified Checkout
Unified Checkout
provides a single interface with which you can
accept numerous types of digital payments.
Unified Checkout
calls other
follow-on services such as Payments,
Decision Manager
, and
Payer Authentication
.
Unified Checkout
consists of a server-side component and a client-side JavaScript library.
The server-side component authenticates your merchant identity and instructs the system
to act within your payment environment. The response contains limited-use public keys.
The keys are for end-to-end encryption and contain merchant-specific payment information
that drives the interaction of the application. The client-side JavaScript library
dynamically and securely places digital payment options onto your e-commerce page.
The provided JavaScript library enables you to securely accept many payment options
within your e-commerce environment.
Unified Checkout
can be embedded
seamlessly into your existing webpage, simplifying payment acceptance.
When a customer selects a payment method from the button widget,
Unified Checkout
handles all of the interactions with the digital payment that
was chosen.
Unified Checkout
is also able to orchestrate requests for to
follow-on services such as Payments,
Decision Manager
, and
Payer Authentication
before it provides a response to your e-commerce system.
The figure below shows
Unified Checkout
with customer checkout payment
options.
Figure:
Button Widget
For examples of different payment method UIs through
into your
platform, you must follow several integration steps. This section gives a high-level
overview of how to integrate and launch
Unified Checkout
on your
webpage and process a transaction. You can find the detailed specifications of the
APIs later in this document.
The integration flow consists of four events:
You send a server-to-server API request for a capture context. This request is
fully authenticated and returns a JSON Web Token (JWT) that is necessary in
order to invoke the frontend JavaScript library. For information on setting up
the server side, see Server-Side Set Up.
You invoke the
Unified Checkout
JavaScript library using the JWT
response from the capture context request. For information on setting up the
client side, see Client-Side Set Up.
You process the payment through the
Unified Checkout
complete
mandate feature and interpret the response of the transaction flow that is
displayed on your browser.
IMPORTANT
If you do not use the complete mandate for
Unified Checkout
, you must request follow-on services using a
transient token to process the payment.
Optional:
Capture the full payment response through webhook
notifications.
Information that is captured by
Unified Checkout
, including the billing
and shipping address, can be retrieved using the payment details API.
The figure below shows the
Unified Checkout
payment flow.
Figure:
Unified Checkout
Payment Flow
For more information on the specific APIs referenced, see these topics:
, you must first ensure that your merchant ID (MID)
is configured to use the service and that any payment methods you intend to use are
properly set up.
If you are unable to access this page, contact your sales
representative.
In the
Business Center
, go to the left navigation panel and choose
Payment Configuration
>
Unified
Checkout
.
You can configure various payment methods such as Apple Pay,
Click to Pay
, and Google Pay. Click
Set
up
and follow the instructions for your selected payment
methods. When payment methods are enabled, they appear on the payment
configuration page.
IMPORTANT
You must configure payment methods you want to use for
each transacting MID.
Figure:
Click
Manage
to edit your existing
payment method configurations or enroll in new payment methods as they are
released.
Server-Side Set Up
This section contains the information you need to
set up your server. Initializing
Unified Checkout
within your webpage
begins with a server-to-server call to the sessions API. This step authenticates your
merchant credentials, and establishes how the
Unified Checkout
frontend
components will function. The sessions API request contains parameters that define how
Unified Checkout
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
This section contains the information you need to set up your server. Initializing
Unified Checkout
within your webpage begins with a server-to-server
call to the sessions API. This step authenticates your merchant credentials, and
establishes how the frontend components will function. The sessions API request contains
parameters that define how
Unified Checkout
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
Unified Checkout
integration in addition to allowed card networks and
payment types. The capture context request includes these elements:
allowedCardNetworks
allowedPaymentTypes
clientVersion
targetOrigin
completeMandate
Use the
targetOrigins
and the
allowedPaymentTypes
fields to define the target origin and
the accepted digital payment methods in your capture context. Use the
comppleteMandate
to orchestrate follow-on services such as
Payments,
This diagram shows how elements of the capture context request appear in the card entry
form.
Figure:
Anatomy of a Manual Card Entry Form
Client-Side Set Up
This section contains the information you need to set up the client side. You use the
Unified Checkout
JavaScript library to add the payment interface to
your e-commerce site. It has two primary components:
The button widget, which lists the payment methods available to the customer.
The payment acceptance page, which captures payment information from the cardholder.
You can set up the payment acceptance page to be embedded with your webpage or added
as a sidebar.
Follow these steps to set up the client:
Load the JavaScript library.
Initialize the accept object, the capture context JWT. For information JSON Web
Tokens, see JSON Web Tokens.
Initialize the unified payment object with optional parameters.
Show the button list or payment acceptance page or both.
Process the payment request using the instructions included within the capture
mandate.
The response to these interactions is a transient token that you use to retrieve the
payment information captured by the UI.
Loading the JavaScript Library and Invoking the Accept Function
Use the client library asset path and client library integrity value that is returned by
the capture context response to invoke
Unified Checkout
on your page.
You can retrieve these values from the
clientLibrary
and
clientLibraryIntegrity
fields that are returned in the JWT from
https://apitest.cybersource.com
/up/v1/capture-contexts
. You can use these
values to create your script tags.
You must perform this process for each transaction, as these values may be unique for
each transaction. You must avoid hard-coding values for the
clientLibrary
and
clientLibraryIntegrity
fields to prevent client-side errors.
For example, a response from
https://apitest.cybersource.com
/up/v1/capture-contexts
would
include:
"data": {
"clientLibrary":"[EXTRACT clientLibrary VALUE from here]",
"clientLibraryIntegrity": "[EXTRACT clientLibraryIntegrity VALUE from here]"
}
Below is an example script
tag:
<script src="[INSERT clientLibrary VALUE HERE]"
integrity=”[INSERT clientLibraryIntegrity VALUE HERE]”
crossorigin=”anonymous”></script>
IMPORTANT
Use the
clientLibrary
and
clientLibraryIntegrity
parameter values in the capture context
response to obtain the
Unified Checkout
JavaScript library URL and the
integrity value. This ensures that you are always using the most up-to-date library and
protects against fraud. Do not hard-code the
Unified Checkout
JavaScript
library URL or integrity value.
When you load the library, the capture context from your initial server-side request is
used to invoke the accept function.
JavaScript Example: Initializing the SDK
try {
const accept = await Accept(captureContext);
const up = await accept.unifiedPayments(sidebar);
} catch (error) {
// merchant logic for handling issues
console.error("something went wrong: " + error);
}
In this example,
captureContext
refers to the capture context
JWT.
JavaScript Example: Displaying the Button List
After you initialize the
Unified Checkout
object, you can add the
payment application and payment acceptance pages to your webpage. You can attach the
embedded
Unified Checkout
tool and payment acceptance pages to any
named element within your HTML. Typically, they are attached to explicit named
components that are replaced with
The response to the unifiedPayment.show() method is a JWT data object referred to
here as a transient token. The transient token contains all the payment information
captured during the
Unified Checkout
payment journey.
JavaScript Example: Client-Defined Trigger for
Click to Pay
or PAN
Entry
When you are presenting
CLICKTOPAY
or
PANENTRY
as
allowed payment types, you can load the UI without displaying the
Checkout with Card
button by creating a trigger that
defines what loads the UI.
You can create a trigger by calling the
createTrigger()
method on an
existing unified payments object and pass in these two parameters:
The payment method that the trigger is linked to. It is required.
IMPORTANT
You can create a trigger only for
CLICKTOPAY
or
PANENTRY
payment
methods.
The container for the payment screen. It is required when you are in
embedded mode.
// Example: Basic usage with full sidebar experience
// Create a trigger
const trigger = up.createTrigger("CLICKTOPAY");
// Show the trigger
// In this example, when a button in your UI is clicked
const myButton = document.getElementById("myButton");
myButton.addEventListener("click", async () => {
const transientToken = await trigger.show();
console.log(transientToken);
})
// Example: Payment screen in a container
// Define the container for the payment screen to be rendered in
var options = { containers: { paymentScreen: '#paymentScreenContainer' } };
// Create the trigger
const trigger = up.createTrigger("CLICKTOPAY", options);
// Show the trigger
// In this example, when a button in your UI is clicked
const myButton = document.getElementById("myButton");
myButton.addEventListener("click", async () => {
const transientToken = await trigger.show();
console.log(transientToken);
})
JavaScript Example: Processing a Payment
Payment is initiated when
Unified Checkout
captures the customer's
payment information by calling the
The response to a successful customer interaction with
Unified Checkout
is
a transient token. This is returned in the response from the
unifiedPayment.show()
function. The transient token is a
reference to the payment data collected on your behalf. Tokens allow secure card
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 tokens can be included requests sent to the Payment Details and Payment
Credentials APIs in exchange for the customer payment data that is collected. This data
can include the payment account number (PAN) or tokenized credentials.
Transient Token Format
The transient token is issued as a JSON Web Token (JWT) (RFC 7519).
For information on JSON Web Tokens, see JSON Web Tokens.
The payload portion of the token is a Base64-encoded JSON string and contains various
claims. For more information, see JSON Web Tokens.
Example: Transient Token Format
Transient Token Payload
{
"iss": "Flex/00",
"exp": 1706910242,
"type": "gda-0.9.0",
"iat": 1706909347,
"jti": "1D1I2O2CSTMW3UIXOKEQFI4OQX1L7CMSKDE3LJ8B5DVZ6WBJGKLQ65BD6222D426",
"metadata": {
"consumerPreference": {
"saveCard": true
},
"tokenizedCard": {
"card": {
"maskedValue": "XXXXXXXXXXXX9876",
"prefix": "123456",
"expirationMonth": "MM",
"expirationYear": "YYYY"
}
}
},
"content": {
"orderInformation": {
"billTo" : {
// Empty fields present within this node indicate which fields were captured by
// the application without exposing you to personally identifiable information
// directly.
},
"amountDetails" : {
// Empty fields present within this node indicate which fields were captured by
// the application without exposing you to personally identifiable information
// directly.
},
"shipTo" : {
// Empty fields present within this node indicate which fields were captured by
// the application without exposing you to personally identifiable information
// directly.
}
},
"paymentInformation": {
"card": {
"expirationYear": {
"value": "2028"
},
"number": {
"maskedValue": "XXXXXXXXXXXX1111",
"bin": "411111"
},
"securityCode": {},
"expirationMonth": {
"value": "06"
},
"type": {
"value": "001"
}
}
}
}
}
PAN BIN in
metadata
Object
The
cardDetails
object, including the PAN BIN, is included in
the transient token
metadata
when a
Click to Pay
network token is used as a payment method. This allows you to display information about
the card on invoices and see the BIN details that are linked to the underlying card.
and enables you to determine if the payload is fully
authenticated. When
authenticationStatus
is set to
true
, the payload is fully authenticated. When
authenticationStatus
is set to
false
, the
transaction is not authenticated.
If you are using
Unified Checkout
with the complete API and you include
consumerAuthentication
in the
complete mandate request, then
Payer Authentication
is called automatically if it
is available for the selected payment method and card network. In this case, there is no
action required on your
part.
"metadata": {
"authenticationStatus": "true"
}
}
Token Verification
When you receive the transient token, you should cryptographically verify its integrity
using the public key embedded within the capture context. Doing so verifies that
Cybersource
issued the token and that the data has not been tampered
with in transit. Verifying the transient token JWT involves verifying the signature and
various claims within the token. Programming languages each have their own specific
libraries to assist.
accepts dual-branded cards. To use this feature, you must
include the card networks that have overlapping BIN ranges in the capture context
request. For
example:
When a card number within an overlapping BIN range is entered, the network that is listed
first in the value array for the
allowedCardNetworks
field is used.
For example, if the card number 403550XXXXXXXXXX is entered, the payment network is
Visa.
During the transaction, the card type is populated with the first network in the list,
and the
detectedCardTypes
field includes all of the detected card types in the
transient token.
The
detectedCardTypes
field is returned in the transient token
response only when more than one card type is detected.
Authorizations with a Transient Token
This section provides the minimum information required in order to perform a successful
authorization with a
Unified Checkout
transient token. You can use this method
to construct more complex payment scenarios that are not supported by the
unifiedPayment.complete()
payment method.
IMPORTANT
When you process payments through
Unified Checkout
,
Unified Checkout
invokes service orchestration directly. When you send an
authorization request using a transient token, you are using an alternative method for
processing payments.
The transient token is a short-term token that expires after 15 minutes. Doing so eliminates
the need to send sensitive payment data along with the request. For more information on
transient tokens, see Transient Tokens.
To send the transient token with a request, use the
tokenInformation.transientTokenJwt
field.
This example shows a transient token in the context of an authorization
request:
endpoint. This data includes cardholder name and billing and shipping details. For more information, see Payment Details API.
IMPORTANT
Fields supplied directly in an API request supersede those that are also present in the transient token. For example, in the request below, the total amount might have been overridden because of a tax calculation.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments
Required Field for an Authorization with a Transient Token
The capture context request contains all of the merchant-specific parameters that tell the
front-end JavaScript library what to do within your payment experience.
The capture context is a signed JSON Web Token (JWT) containing this information:
Merchant-specific parameters that dictate the customer payment experience for the
current payment transaction.
A one-time public key that secures the information flow during the current payment
transaction.
The capture context request includes these fields:
You can define the payment cards and digital payments that you want to accept in the
capture context.
Allowed Card Networks
Use the
allowedCardNetworks
field 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
PayPak
Visa
To support dual-branded or co-badged cards, you must list your supported card type
values for the
allowedCardNetworks
field based on your preference
for processing card numbers. For example, if a card is dual-branded as Visa and Cartes
Bancaires, and Cartes Bancaires is listed first, the card type is set to Cartes
Bancaires after the card number is entered in your
Unified Checkout
card
collection form. For information on dual-branded or co-badged cards, see Dual-Branded Cards.
Allowed Payment Types
You can specify the type of
Unified Checkout
digital payment methods
that you want to accept in the capture context.
Use the
allowedPaymentTypes
field to define the payment type:
APPLEPAY
CHECK
CLICKTOPAY
GOOGLEPAY
PANENTRY
PAZE
AFTERPAY
IDEAL
MULTIBANCO
IMPORTANT
Click to Pay
accepts American Express,
Mastercard, and Visa for saved cards. Visa and Mastercard tokenize payment credentials
using network tokenization for all
Click to Pay
requests.
Click to Pay
uses
Click to Pay
Token Requester IDs
(TRIDs) rather than your existing TRIDs to generate network tokens.
For more
information on enabling and managing these digital payment methods, see these
topics:
recommends
that you dynamically parse the response for the fields that you are looking for when you
integrate with
Cybersource
APIs.
Cybersource
may add
additional fields in the future.
You must ensure that your integration can handle new
fields that are returned in the response. Even though the underlying data structures do
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.
Features
Unified Checkout
comprises these features.
Save Card
Click to Pay
and PAN entry payment methods support
Save Card when they are set as allowed payment types on
Unified Checkout
.
When the feature is enabled, the customer can save their card information
for future purchases placed at your website.
IMPORTANT
This
feature is available only for card credentials that are manually
entered during checkout.
When the customer checks the box and finalizes their purchase, you
receive a notification in the transient token response to your capture
context request. The transient token payload includes the
consumerPreference.saveCard
field value set to
true
:
"captureMandate" : {
"requestSaveCard": true
}
Combo Cards
A combo card is a single card in Brazil that functions as both a debit and a
credit card.
Unified Checkout
enables the cardholder to choose
whether to pay for a transaction using a debit or credit card. The
cardholder can choose the card that they want to use when they enter their
card details or when they choose a stored Visa card from their
Click to Pay
wallet during checkout. While in the card
details section of the payment form, the cardholder is prompted for a debit
or credit card. Credit is the default option.
IMPORTANT
Combo cards are supported on client version 0.24
and later.
To enable combo cards during checkout, you must include the
comboCard
field in your capture context request
and set the field value to
true
. When the
comboCard
field value is set to
true
, the option to use a debit or credit card
appears for all Visa cards that are entered in
Unified Checkout
and for all cards that are already stored in
Click to Pay
. If you do not want to offer a combo card at
checkout, do not include the
comboCard
field in your
capture context request:
"captureMandate" : {
"comboCard": true
}
Cadastro de Pessoas Físicas (CPF) – Brazilian Tax ID
The tax ID feature is for customers in Brazil and provides your customers
with a way to include their Consumer National Identifier when it is
requested at checkout. Include this field in the capture context to display
this field within the flow for manual card entry and
Automatic email lookup occurs when an email address is included in the
capture context request. If the user has a
Click to Pay
account but is not on a recognized device, a one-time password (OTP) screen
appears and the user is prompted to enter their OTP. If the user does not
have a
Click to Pay
account, the user must enter their
card information manually. They will have the option to create a
Click to Pay
account.
To enable email autolookup, you must
include
CLICKTOPAY
as a value in the
allowedPaymentTypes
field and include an email
address in the capture context.
Removal of Confirm and Continue Screen
You can opt to not show the confirmation screen to the cardholder during
checkout when a user selects an existing
Click to Pay
card from their
Click to Pay
account. To hide the
confirmation screen you must set these fields to these corresponding values
in the capture context:
The capture context that you generate is a JSON Web Token (JWT) data object. The JWT is
digitally signed using a public key and confirms the validity of the JWT and that it
comes from
Cybersource
. When you do not have a key in the JWT header,
Cybersource
recommends that you follow cryptography best practices
and validate the capture context signature.
To validate a JWT, you must obtain its public key. This public RSA key is in JSON Web Key
(JWK) format. The 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,
you must retrieve the key ID associated with the public key and then pass the key ID to
the
/flex/v2/public-keys
endpoint:
From the header of the capture context, get the key ID
(
kid
):
{
"kid": "3g",
"alg": "RS256"
}
Send a GET request to the
/flex/v2/public-keys
endpoint and
include the key ID. For example:
Test:
GET
https://apitest.cybersource.com
/flex/v2/public-keys/{3g}
Production:
GET
https://api.cybersource.com
/flex/v2/public-keys/{3g}
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.
This section contains the information you need to retrieve the non-sensitive data associated
with a
Unified Checkout
transient token and the payment details API. This API
can be used to retrieve personally identifiable information, such as the cardholder name and
billing and shipping details, without retrieving payment credentials, which helps ease the PCI
compliance burden.
There are two methods of authentication, and they are described in the
recommends
that you dynamically parse the response for the fields that you are looking for when you
integrate with
Cybersource
APIs.
Cybersource
may add
additional fields in the future.
You must ensure that your integration can handle new
fields that are returned in the response. Even though the underlying data structures do
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:
GET
https://api.cybersource.com
/up/v1/payment-details/
{id}
Test:
GET
https://apitest.cybersource.com
/up/v1/payment-details/
{id}
The
{id}
is the full
JWT received from
Unified Checkout
as the result of capturing payment
information. The transient token is a JWT object that you retrieved as part of a
successful capture of payment information from a cardholder.
, you must first register for
each digital payment method that you would like enabled on your page. This enablement
process sends the appropriate information to the digital payment systems and registers
your page with each system.
This section contains information about enabling and managing
digital payments on
Unified Checkout
in the
Business Center
:
Apple Pay
Enrolling in Apple Pay
Preparing a device for testing Apple Pay on
Unified Checkout
Click to Pay
Enabling
Click to Pay
Google Pay
Enrolling in Google Pay
Managing Google Pay authentication types
Enrolling in Apple Pay
Apple Pay is a digital payment service that enables users to make secure and convenient
transactions using their Apple devices. Users can add their credit or debit cards to the
Wallet app and use them to pay online or in apps in a safe and convenient consumer
experience.
To enable Apple Pay you must first host a public certificate on your
web page and then pass your merchant name and domain name to Apple. Apple crawls out
to your web page to validate the presence of this certificate to ensure the web
pages are properly vetted and registered with Apple.
Follow these steps to
validate your domain and enroll in Apple Pay:
In order to run an end-to-end test of the Apple Pay service on
Unified Checkout
,
you must prepare an Apple test device by loading Apple Pay test cards onto the device.
Follow these steps to prepare your Apple test device for end-to-end testing:
Make sure your Apple Developer account is configured for Apple Pay.
Register your Apple Pay test device with Apple.
Load Apple Pay test cards onto your Apple test device.
ADDITIONAL INFORMATION
The Apple Developer center provides the instructions in the
Sandbox Testing page for Apple Pay:
Follow the steps described in
Create a Sandbox Tester Account
.
Follow the steps described in
Adding a Test Card Number
.
Enabling
Click to Pay
Click to Pay
is a digital payment solution that allows
customers to pay with their preferred card network and issuer without entering their
card details on every website. Customers can use Visa, Mastercard, and American Express
cards to streamline their purchase experience.
Click to Pay
provides
a fast, secure, and consistent checkout experience across devices and browsers.
Follow
these steps to enable in
Click to Pay
on
Unified Checkout
:
Navigate to
Payment Configuration >
Unified Checkout
.
In the Click to Pay section, click
Set Up
.
Enter your business name and website URL.
Click
Submit
.
Contact your implementation contact
or
technical account manager
to request that you be enabled for
tokenization within
Click to Pay
. Your implementation
contact
or technical account
manager
will confirm that you were configured successfully and that you
can now accept digital payments with
Click to Pay
.
Set Up Customer Authentication for Visa
Follow these steps to use the
Business Center
to enable customer
authentication through
Click to Pay
. Authentication methods differ in
each region and are dependent on the issuer, the cardholder device, and the
Click to Pay
configuration. These authentication methods are
available:
3-D Secure
FIDO
Card verification value (CVV)
One-time password (OTP)
IMPORTANT
After you complete these steps, Visa determines which
authentication method to use. When Visa determines that they will authenticate,
they authenticate each
Click to Pay
transaction through the
appropriate method. This may be a frictionless authentication or the customer
may need to provide more information when required by the issuer.
. If
eCheck is not listed in the Available Products section in the
Business Center
, you must contact your portfolio owner to enable your account to apply for
eCheck.
IMPORTANT
If you have a business account or a financial relationship
with Bank of America, Wells Fargo, or Chase, and you would like them to process
your transactions, you must contact our Sales or Support team for more
information on our ACH product.
Enrolling in Alternative Payment Methods
Before you can enroll in alternative payment methods on
Unified Checkout
, you must first be enabled for the alternative payment
platform. Contact your portfolio administrator for more information.
Follow these
steps to enroll in any of the alternative payment methods available on
Unified Checkout
:
Manage Permissions
Portfolio administrators
can set permissions for new or existing
Business Center
user roles for
Unified Checkout
.
Administrators retain full read and write permissions. They enable you to regulate
access to specific pages and specify who can access, view, or amend digital products
within
Unified Checkout
.
Portfolio administrators
must apply the appropriate user role
permission for any existing or newly created
If you are a transacting merchant, you might find that your permissions are restricted.
If your permissions are restricted, a message appears indicating that you do not have
access, or buttons might appear gray. To make changes to your digital products within
Unified Checkout
that have restricted permissions, contact
your portfolio administrator's customer support
representative
This section describes the payment methods you can use in your
Unified Checkout
integration. After you successfully integrate one payment
method, you can add another from the same category with minimal adjustments to your
existing configuration.
accepts several card types including global
networks such as Visa, Mastercard, and American Express.
Unified Checkout
also accepts local schemes such as Cartes
Bancaires in France, EFTPOS in Australia, and PayPak in Pakistan.
Card Support
Support for card brands varies based on the payment method for these services:
Payments
Decision Manager
Payer Authentication
This table shows which card types are
accepted for each payment method and which region:
Card Brand by Region and Payment Method
Region
Card Brand
Manual Card Entry
Apple Pay
Click to Pay
Google Pay
Paze
Asia Pacific
China UnionPay
Asia Pacific
EFTPOS
Asia Pacific
JCB
CEMEA
mada
CEMEA
Meeza
CEMEA
PayPak
Europe
Cartes Bancaires
Global
American Express
Global
Diners Club
Global
Mastercard
Global
Visa
Global and Europe
Maestro
Latin America
Carnet
Latin America
ELO
US and Canada
Discover
US and Canada
JCrew
Online Bank Transfers
Online bank transfers enable customers to complete their purchase by securely logging
into their online banking environment. This method is secure, trusted, and widely used
in many European countries.
This is how online bank transfers work:
Figure:
Online Bank Transfers
The customer chooses online bank transfer as their payment method during
checkout.
The customer chooses their bank from the list of available banks and is
redirected to their bank's website or application where they are prompted to
enter their account credentials.
The customer confirms their payment and completes the authorization
process.
The customer is notified that the payment is complete.
The customer returns to your website for payment confirmation.
Unified Checkout
supports these online bank transfer payment methods
accepted by PPRO:
iDeal
iDEAL enables customers to pay online through their mobile banking app or
online bank account and provides you with a payment guarantee.
Multibanco
Multibanco enables customers to pay for a range of goods and services by
bank transfer. These services include e-commerce, licenses, and taxes
post-purchase. Multibanco is supported by all banks in Portugal.
Przelewy24|P24
Przelewy24, or P24, is a Poland-based real-time online bank transfer payment
method. P24 is one of the most popular payment methods in Poland covering
all major consumer banks.
Online Bank Transfer Payment Method Support
Payment Method
Capture Context
allowedPaymentTypes
Capture Context
completeMandate.type
Separate Capture?
Payment Confirmation
Customer Country (Country Code)
Customer Currency
iDEAL
IDEAL
CAPTURE
or
PREFER_AUTH
No
Immediate
Netherlands (NL)
EUR
Mutlibanco
MULTIBANCO
CAPTURE
or
PREFER_AUTH
No
Immediate
Portugal (PT)
EUR
Przelewy24|P24
P24
CAPTURE
or
PREFER_AUTH
No
Immediate
Poland (PL)
PLN
iDeal
iDEAL enables customers to pay online through their mobile banking app or online bank
account and provides you with a payment guarantee. iDEAL supports these banks:
ABN AMRO
ASN Bank
bunq
ING
Knab
Rabobank
RegioBank
Revolut
SNS
Svenska Handelsbanken
Triodos Bank
Van Lanschot
Opt in to iDeal on
Unified Checkout
Follow these steps to opt in to iDeal on
Unified Checkout
:
Add iDeal to your integration by adding
IDEAL
to the
allowedPaymentTypes
field object within the capture
context request:
Set the
completeMandate.type
field value to
CAPTURE
or
PREFER_AUTH
.
You can capture the funds immediately if you include the
completeMandate.type
field in the capture context
request and set the value to
CAPTURE
.
If you accept more than one payment type and must perform an
authorization where funds are collected at a later time, set the
completeMandate.type
field to
PREFER_AUTH
. The funds are captured immediately for
the online bank transfer.
Include these required fields for online bank transfers in the capture context request:
orderInformation.billTo.country
orderInformation.billTo.firstName
orderInformation.billTo.lastName
Include this optional field for online bank transfers in the capture context request:
orderInformation.billTo.address1
orderInformation.billTo.email
Multibanco
Multibanco enables customers to pay for a range of goods and services by bank transfer.
These services include e-commerce, licenses, and taxes post-purchase. Multibanco is
supported by all banks in Portugal.
Opt in to Multibanco on
Unified Checkout
Follow these steps to opt in to Multibanco on
Unified Checkout
:
Add Multibanco to your integration by adding
MULTIBANCO
to the
allowedPaymentTypes
field object within the capture
context request:
Set the
completeMandate.type
field value to
CAPTURE
or
PREFER_AUTH
.
You can capture the funds immediately if you include the
completeMandate.type
field in the capture context
request and set the value to
CAPTURE
.
If you accept more than one payment type and must perform an
authorization where funds are collected at a later time, set the
completeMandate.type
field to
PREFER_AUTH
. The funds are captured immediately for
the online bank transfer.
Include these required fields for online bank transfers in the capture context request:
orderInformation.billTo.country
orderInformation.billTo.firstName
orderInformation.billTo.lastName
Include this optional field for online bank transfers in the capture context request:
orderInformation.billTo.address1
orderInformation.billTo.email
Example: Verify Status for Online Bank Transfers
When the status of your payment request is
PENDING
, you can verify
the status by sending a GET request to the URL that is included in the
Buy Now, Pay Later payment methods enable customers to purchase goods or services
immediately and pay in installments over time. With Buy Now, Pay Later, you are paid
immediately and in full, while your customers pay nothing or only a portion of the total
at the time of purchase. The remaining balance is typically spread over equal, often
interest-free, payments.
Buy Now, Pay Later is increasingly popular for both online and in-store purchases and is
supported by providers such as Klarna, Afterpay, Affirm, and PayPal.
This is how Buy Now, Pay Later works:
Figure:
Buy Now, Pay Later
The customer chooses their Buy Now, Pay Later payment method during
checkout.
The customer chooses how much they want to pay, such as nothing, installments,
or the total amount.
The unpaid amount is divided into equal installments that are paid over a fixed
amount of time.
You receive the full payment after the customer completes checkout, and the Buy
Now, Pay Later provider collects the installment payments from your
customer.
Unified Checkout
supports this Buy Now, Pay Later payment method:
Afterpay/Clearpay
Afterpay is a Buy Now, Pay Later service that allows customers to
purchase items immediately and pay for them in four interest-free
installments over a period of 6 weeks. Afterpay is also known as
Clearpay in the UK, and Cash App Afterpay in the US.
Afterpay is a Buy Now, Pay Later service that allows customers to purchase items
immediately and pay for them in four interest-free installments over a period of 6
weeks. Afterpay is also known as Clearpay in the UK, and Cash App Afterpay in the US.
Follow these steps to opt in to the Afterpay/Clearpay payment method in
Unified Checkout
:
Add Afterpay to your integration by adding
AFTERPAY
to the
allowedPaymentTypes
field within the capture context
request. The default field value is
AFTERPAY
even if you want
to support Cash App Afterpay in the US or Clear Pay in the UK.
Set the
completeMandate.type
field value to
AUTH
,
CAPTURE
or
PREFER_AUTH
.
You can perform a sale and capture
the funds immediately if you include the
completeMandate.type
field in the capture context
request and set the value to
CAPTURE
.
You can capture the
funds later if you include the
completeMandate.type
field in the capture context request and set the value to
AUTH
. When you capture the funds later, you must
perform a capture using the payments API. See Captures.
If you accept more than one payment type and must perform an
authorization where funds are collected at a later time, set the
completeMandate.type
field to
PREFER_AUTH
. You must perform a capture using the
payments API when an authorization is performed. A capture is performed
automatically if an authorization is not allowed by the payment
type.
Include these required fields in the capture context request:
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.address1
orderInformation.billTo.locality
orderInformation.billTo.postalCode
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
Include these optional fields in the capture context request:
IMPORTANT
These fields are required when the
requestShipping
fild is set to
true
.
orderInformation.shipTo.firstName
orderInformation.shipTo.lastName
orderInformation.shipTo.address1
orderInformation.shipTo.locality
orderInformation.shipTo.postalCode
orderInformation.shipTo.administrativeArea
orderInformation.shipTo.country
Captures
This section provides the information you need in order to capture an authorized
transaction.
For
China UnionPay
, use the capture service to process pre-authorization completions.
Limitations for the
JCN Gateway
Processor
Listed below are the maximum amounts that can be processed:
The maximum amount for an authorization is limited to 8 digits: 99,999,999.
The maximum amount for a capture or credit is limited to 7 digits: 9,999,999.
Supported Card Types
All supported card types can process captures.
.
Endpoint
Production:
POST
https://api.cybersource.com
/pts/v2/payments/
{id}
/captures
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments/
{id}
/captures
The
{id}
is the transaction ID
returned in the authorization response.
Required Fields for Capturing an Authorization
Use these required fields for capturing an authorization.
requires the customer to
navigate through a sequence of interfaces. This section includes examples of the
interfaces your customers can expect when completing a payment with these payment
methods on
Unified Checkout
:
Apple Pay
Click to Pay
Google Pay
Manual payment entry
Payment with a bank account
Paze
Apple Pay UI
These screen captures show the sequence of events your customer can expect when
completing a payment with Apple Pay.
Figure:
Apple Pay UI
Click to Pay
UI
These screen captures show the sequence of events your customer can expect when
completing a payment with
Click to Pay
.
Figure:
Click to Pay
UI
Google Pay UI
These screen captures show the sequence of events your customer can expect when
completing a payment with Google Pay.
Figure:
Google Pay UI
Manual Payment Entry UI
These screen captures show the sequence of events your customer can expect when
completing a payment by manually entering payment, shipping, and contact
information.
Figure:
Manual Entry Payment Details
Figure:
Manual Entry Shipping Details
Figure:
Manual Entry Contact Details
Figure:
Manual Entry Review and Confirm
Pay with Bank Account UI
These screen captures show the sequence of events your customer can expect when
completing a payment with a bank account.
Figure:
Pay with Bank Account Order Summary
Figure:
Pay with Bank Account Checkout
Figure:
Pay with Bank Account Checking Account
Figure:
Pay with Bank Account Routing Number
Figure:
Pay with Bank Account Contact Details
Figure:
Pay with Bank Account Review and Confirm
Figure:
Pay with Bank Account Review and Confirm Disclaimer
Paze UI
These screen captures show the sequence of events your customer can expect when
completing a payment with Paze.
Figure:
Paze UI
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.
A JWT takes the form of a string, and consists of three parts separated by dots:
<Header>.<Payload>.<Signature>
The header and payload is
Base64-encoded JSON
and contains these claims:
Header
: The algorithm and token type. For
example:
{
"kid": "zu",
"alg": "RS256"
}
Payload
: The claims of what the token represents. For
example:
: The signature is computed from the header and payload using a
secret or private key.
IMPORTANT
When working with JWTs,
Cybersource
recommends that you use a well- maintained JWT library to ensure proper decoding
and parsing of the JWT.
IMPORTANT
When parsing the JWT’s JSON payload, you must ensure that you
implement a robust solution for transversing JSON. Additional elements can be
added to the JSON in future releases. Follow JSON parsing best practices to
ensure that you can handle the addition of new data elements in the future.
Unified Checkout
Integration
Examples
This section contains the information you need in order to integrate
Unified Checkout
within your e-commerce experience and use the
unifiedPayment.complete()
method.
Unified Checkout
with Authorization
This section contains the capture context and JavaScript examples to integrate
Unified Checkout
into your e-commerce page. You can use these examples to
collect your customer's payment information and process an authorization. You must
initiate a capture request to move funds and complete the transaction.
This section contains the capture context and JavaScript examples to integrate
Unified Checkout
into your e-commerce page. You can use these examples to
collect your customer's payment information. Payment processing and service
orchestration are completed through the back end of the integrator.
<script type="text/javascript">
const sidebar = true;
const captureContext = document.getElementById("captureContext").value;
const showArgs = {
containers: { paymentSelection: "#buttonPaymentListContainer" }
};
async function launchCheckout() {
try {
const accept = await Accept(captureContext);
const up = await accept.unifiedPayments(sidebar);
const tt = await up.show(showArgs);
console.log(tt); // merchant logic for passing the Transient token to their backend for service orchestration
} catch (error) {
// merchant logic for handling issues
console.error("something went wrong: " + error);
}
}
// Call the function
launchCheckout();
</script>
Echeck Payment with a Transient Token
This section contains a request example for making a payment with an eCheck using a
transient token. You must meet these requirements to make an eCheck payment with a
transient token:
The
paymentType.name.value
field value must be set to
CHECK
in the transient token.
You must include the
paymentInformation.paymentType.name
field in your request and the value must be set to
The locale field within the capture context request consists of an ISO 639 language code,
an underscore (_), and an ISO 3166 region code. The locale controls the language in
which the application is rendered. The following locales are supported:
ar_AE
bg_BG
ca_ES
cs_CZ
da_DK
de_AT
de_DE
el_GR
en_AU
en_CA
en_GB
en_IE
en_NZ
en_US
es_AR
es_CL
es_CO
es_ES
es_MX
es_PE
es_US
fi_FI
fr_CA
fr_FR
he_IL
hr_HR
hu_HU
id_ID
it_IT
ja_JP
km_KH
ko_KR
lo_LA
ms_MY
nb_NO
nl_NL
pl_PL
pt_BR
ro_RO
ru_RU
sk_SK
sl_SI
sv_SE
th_TH
tl_PH
tr_TR
vi_VN
zh_CN
zh_HK
zh_MO
zh_SG
zh_TW
Reason Codes
A
Unified Checkout
request response returns one of the following reason
codes:
Reason Codes
Reason Code
Description
200
Successful response.
201
Capture context created.
400
Bad request.
Possible
reason
values:
CAPTURE_CONTEXT_EXPIRED
CAPTURE_CONTEXT_INVALID
CREATE_TOKEN_TIMEOUT
CREATE_TOKEN_XHR_ERROR
INVALID_APIKEY
SDK_XHR_ERROR
SHOW_LOAD_CONTAINER_SELECTOR
SHOW_LOAD_INVALID_CONTAINER
SHOW_PAYMENT_TIMEOUT
SHOW_TOKEN_TIMEOUT
SHOW_TOKEN_XHR_ERROR
UNIFIEDPAYMENT_PAYMENT_PARAMITERS
UNIFIEDPAYMENTS_VALIDATION_FIELDS
UNIFIEDPAYMENTS_VALIDATION_PARAMS
404
The specified resource not found in the
system.
500
Unexpected server error.
Introduction to
the
Click to Pay Drop-In UI
The
Click to Pay Drop-In UI
powered by
Unified Checkout
provides an interface for easy acceptance of
Click to Pay
payments from Visa, Mastercard, and American Express cards.
Throughout this guide we refer to both
Click to Pay Drop-In UI
and
Unified Checkout
.
Click to Pay Drop-In UI
consists of a server-side component and a client-side
JavaScript library.
The server-side component authenticates your merchant identity and instructs the system
to act within your payment environment. The response contains limited-use public keys.
The keys are used for end-to-end encryption and contain merchant-specific payment
information that drives the interaction of the application. The client-side JavaScript
library dynamically and securely places digital payment options into your e-commerce
page.
The provided JavaScript library enables you to place a payment application within your
e-commerce environment. This embedded component offers
Click to Pay
and card entry to your customers.
Whether a customer uses a stored
Click to Pay
card or enters their
payment information manually,
the
Click to Pay Drop-In UI
handles all user
interactions and provides a response to your e-commerce system.
The figure below shows the
Click to Pay Drop-In UI
for a recognized user.
Figure:
Embedded Component
IMPORTANT
Each request that you send to
Cybersource
requires header information. For information about constructing the headers for your
request, see the
is designed to provide customers with a
friction-free payment experience across many payment experiences. The user experience
has been optimized for mobile use and performs equally well on mobile and desktop
devices.
Click to Pay
recognizes customers as follows:
The customer is a recognized
Click to Pay
customer.
The customer is not recognized but is a
Click to Pay
customer.
The customer is a guest at checkout.
These workflows show you the pages a customer encounters based on their status:
recognized
experience. This interaction occurs when a customer’s device is recognized by the
Click to Pay Drop-In UI
.
A customer's device is recognized under these conditions:
When the customer has used
Click to Pay
on their device
through any
Click to Pay
channel.
If the customer chose to have their device remembered during a previous
transaction.
Figure:
Recognized
Click to Pay
Customer
Unrecognized
Click to Pay
Customer
This section provides an overview of the
Click to Pay Drop-In UI
unrecognized
experience. This interaction occurs when a customer's device is not recognized by the
Click to Pay Drop-In UI
. This condition occurs when the customer has a
Click to Pay
account but has not used it on their device
previously.
Figure:
Unrecognized
Click to Pay
Customer
Guest Customer
This section provides an overview of the
Click to Pay Drop-In UI
guest
experience. This interaction occurs when the customer has not created a
Click to Pay
account, or their issuer has not provisioned their card into
Click to Pay
.
Figure:
Guest Customer
Click to Pay Drop-In UI
Flow
To integrate
Unified Checkout
into your
platform, you must follow several integration steps. This section gives a high-level
overview of how to integrate and launch
Unified Checkout
on your
webpage and process a transaction. You can find the detailed specifications of the
APIs later in this document.
You send a server-to-server API request for a capture context.
This request is fully authenticated and returns a JSON Web Token (JWT)
that is necessary to invoke the frontend JavaScript library.
For information on setting up the server side, see
Server-Side Set Up.
You invoke the
Unified Checkout
JavaScript library using the JWT
response from the capture context request. For information on setting up the
client side, see Client-Side Set Up.
You use the response from
the
Click to Pay Drop-In UI
to retrieve
payment credentials for payment processing or other steps.
This figure illustrates the system's payment flow.
Figure:
Click to Pay
Payment Flow
For more information on the specific APIs referenced, see these topics:
This section contains the information you need to
set up your server. Initializing
Unified Checkout
within your webpage
begins with a server-to-server call to the sessions API. This step authenticates your
merchant credentials, and establishes how the
Unified Checkout
frontend
components will function. The sessions API request contains parameters that define how
Unified Checkout
performs.
The server-side component provides this information:
A transaction-specific public key that 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 interaction methods.
The functions are compiled in a JSON Web Token (JWT) object referred to as the
This section contains the information you need to set up your server. Initializing
Unified Checkout
within your webpage begins with a server-to-server
call to the sessions API. This step authenticates your merchant credentials, and
establishes how the frontend components will function. The sessions API request contains
parameters that define how
Unified Checkout
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
Unified Checkout
integration in addition to allowed card networks and
payment types. The capture context request includes these elements:
allowedCardNetworks
allowedPaymentTypes
clientVersion
targetOrigin
completeMandate
Use the
targetOrigins
and the
allowedPaymentTypes
fields to define the target origin and the accepted digital payment methods in your capture
context. For example:
For more information on requesting the capture context, see Capture Context API.
Client-Side Set Up
This section contains the information you need to set up the client side. You use the
Unified Checkout
JavaScript library to integrate with your e-commerce
website. It has two primary components:
The button widget, which lists the payment methods available to the customer.
The payment acceptance page, which captures payment information from the cardholder.
You can integrate the payment acceptance page with your webpage or add it as a
sidebar.
The
Unified Checkout
JavaScript library supports
Click to Pay
and manual card entry payment methods.
Follow these steps to set up the client:
Load the JavaScript library.
Initialize the accept object the capture context JWT. For information JSON Web
Tokens, see JSON Web Tokens.
Initialize the unified payment object with optional parameters.
Show the button list or payment acceptance page or both.
The response to these interactions is a transient token that you use to retrieve the
payment information captured by the UI.
Adding the Payment Application and Payment Acceptance
After you initialize the
Unified Checkout
object, you can add the payment
application and payment acceptance pages to your webpage. You can attach the
Unified Checkout
embedded tool and payment acceptance pages to any named
element within your HTML. Typically, they are attached to explicit named
<div>
components that are replaced with
Click to Pay Drop-In UI
iframes
.
IMPORTANT
If you do not specify a location for the payment acceptance page, it
is placed in the sidebar.
Transient Tokens
The response to a successful customer interaction with
the
Click to Pay Drop-In UI
is a transient token. The
transient token is a reference to the payment data collected on your behalf. Tokens
enable secure card payments without risking exposure to sensitive payment information.
The transient token is a short-term token with a duration of 15 minutes.
Capture Context API
This section contains the information you need to request the capture context using the
capture context API.
The capture context request contains all of the merchant-specific parameters that tell the
frontend JavaScript library how to behave within your payment experience.
The capture context is a signed JSON Web Token (JWT) containing this information:
Merchant-specific parameters that dictate the customer payment experience for the
current payment transaction.
A one-time public key that secures the information flow during the current payment
transaction.
The capture context request includes these elements:
You can define the payment cards and digital payments that you want to accept in the
capture context.
Allowed Card Networks
Use the
allowedCardNetworks
field to define the card types.
These card networks are available for card entry:
American Express
Carnet
Cartes Bancaires
China UnionPay
Diners Club
Discover
EFTPOS
ELO
JCB
JCrew
mada
Maestro
Mastercard
Meeza
PayPak
Visa
To support dual-branded or co-badged cards, you must list your supported card types
values for the
allowedCardNetworks
field based on your preference
for processing card numbers. For example, if a card is dual-branded as Visa and Cartes
Bancaires and Cartes Bancaires is listed first, the card type is set to Cartes
Bancaires after the card number is enter in your
Unified Checkout
card
collection form. For information on dual-branded or co-badged cards, see Dual-Branded Cards.
Include Card Prefix
You can control the length of the card number prefix to be received in the response to
the capture context
/sessions
request:
6 digits
8 digits
no prefix at all
IMPORTANT
When you request the card number prefix for a
Click to Pay
tokenized credential, 6 digits are returned.
To
specify your preferred card number prefix length, include or exclude the
transientTokenResponseOptions.includeCardPrefix
field in the
capture context
/sessions
request.
If you want to receive a 6-digit card number prefix in the response
Do not
include the
transientTokenResponseOptions.includeCardPrefix
field in the capture context
/sessions
request.
This example shows how a 6-digit card number prefix
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.
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.
Features
This section includes information on the features that are supported in
Click to Pay
.
Save Card
Save Card is supported for the
Click to Pay
payment
method. When the feature is enabled, the
Click to Pay
payment flow offers the customer the option to save their card
information for future purchases placed at your website.
IMPORTANT
This feature is available only for card credentials
that are manually entered during checkout. If
Click to Pay
is an available payment method, do
not
select
Save this card with
Click to Pay
.
When the customer selects the checkbox and finalizes their purchase, you
receive a notification in the transient token response to your capture
context request. The transient token payload includes the
consumerPreference.saveCard
field value set to
true
.
Combo Cards
A combo card is a single card that functions as both a debit and a credit
card.
Click to Pay
enables the cardholder to choose
whether to pay for a transaction using a debit or credit card. The
cardholder can select the card that they want to use when they enter their
card details or when they choose a stored Visa card from their
Click to Pay
wallet during checkout. While in the card
details section of the payment form, the cardholder is prompted to decide if
they would like to pay using a debit or credit card. Credit is selected as
the default option.
IMPORTANT
Combo cards are supported on client version 0.24
and later.
IMPORTANT
Combo cards are required for issuers that are
located in Brazil.
To enable combo cards during checkout, you must include the
comboCard
field in your capture context request
and set the field value to
true
. When the
comboCard
field value is set to
true
, the option to use a debit or credit card
appears for all Visa cards that are entered in
Click to Pay
and for all cards that are already stored in
Click to Pay
. If you do not want to offer combo
card at checkout, do not include the
comboCard
field
in your capture context request.
Tax ID
The tax ID feature provides your customers with a way to include their
Consumer National Identifier when it is requested at checkout.
IMPORTANT
This feature is required for customers in
Brazil.
Email Autolookup
Automatic email lookup occurs when an email address is included in the
capture context request. If the user has a
Click to Pay
account but is not on a recognized device, a one-time password (OTP) screen
appears and the user is prompted to enter their OTP. If the user does not
have a
Click to Pay
account, the user must enter their
card information manually and they will have the option to create a
Click to Pay
account.
To enable email autolookup, you must
include
CLICKTOPAY
as a value in the
allowedPaymentTypes
field and include an email
address in the capture context.
Requesting the Capture Context
This section shows you how to request the capture context.
Endpoint
Production:
POST
https://api.cybersource.com
/up/v1/capture-contexts
Test:
POST
https://apitest.cybersource.com
/up/v1/capture-contexts
Required Fields for Requesting the Capture Context
Use these required fields to request the capture context:
Required Fields for Requesting the Capture
Context
Your capture context request must include these fields:
Required Field for Retrieving Transient Token Payment Details
Your payment credentials request must include this field:
id
The
{id}
is the full JWT received from
Unified Checkout
as the result of capturing payment
information.
Payment Credentials API
This section contains the information you need to retrieve the full payment credentials collected by the
Unified Checkout
tool using the payment credentials API. The payment information is returned in a redundantly signed and encrypted payment object. It uses the JSON Web Tokens (JWTs) as the data standard for communicating this sensitive data.
IMPORTANT
Payment information returned by the
payment-credentials
endpoint will contain Personal Identifiable Information (PII). Retrieving this sensitive information requires your system to comply with PCI security standards. For more information on PCI security standards, see: https://www.pcisecuritystandards.org/
The response is returned using a JWE data object that is encrypted with your public key created during the
To decrypt the JWE response, use your private key created during the
Unified Checkout
tool's integration. The decrypted content is a JWS data object containing a JSON payload. This payload can be validated with the
Unified Checkout
public signature key.
IMPORTANT
Cybersource
recommends
that you dynamically parse the response for the fields that you are looking for when you
integrate with
Cybersource
APIs.
Cybersource
may add
additional fields in the future.
You must ensure that your integration can handle new
fields that are returned in the response. Even though the underlying data structures do
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.
Returned Credentials
A payment account number (PAN) or network token is returned on your request depending on
your payment method and
Click to Pay
account status:
Payment Credentials Returned by Card Type and
Click to Pay
Account Status
Click to Pay
Account Status
American Express
Mastercard
Visa
New card not saved in
Click to Pay
PAN
PAN
PAN
New card saved in
Click to Pay
PAN
Network Token
Network Token
Existing card stored in
Click to Pay
PAN
Network Token
Network Token
When you retrieve PAN information from the Payment Credentials API, the response
includes the PAN, card expiration date, and the card verification value (CVV). When you
retrieve network token information, the response includes the network token and network
token cryptogram.
IMPORTANT
Visa and Mastercard always attempt to provision a network token.
When a network token is not provisioned, the default payment method is the PAN. When there
is a PAN transaction, the PAN is not stored in the consumers wallet and it is treated as a
single transaction.
Network tokens are generated in the wallet of the
Click to Pay
token requestor ID (TRID). When tokenization is successful, Visa
attempts to complete authentication during the
platform by
invoking the Payment Credentials API. This API retrieves all of the data captured by
Unified Checkout
. This information is transmitted in an encrypted
format to ensure the security of the payment information while in transit.
You must generate an encryption key pair to retrieve this encrypted payment information,
and the public encryption key must uploaded to the
Unified Checkout
system.
Generate a Public Private Key Pair
You must generate a public-private key pair to upload to the
Unified Checkout
system. The public key is uploaded to the
Unified Checkout
platform and
is used to encrypt sensitive information in transit. The private key is used to decrypt
the sensitive payment information on your server. Only the private key can properly
decrypt the payment information.
IMPORTANT
You must secure your private decryption key. This key must never be
exposed to any external systems or it will risk the integrity of the secure
channel.
Unified Checkout
accepts only keys that meet these requirements:
Only RSA keys are supported. Elliptical curves are not supported.
The minimum accepted RSA key size is 2048 bits.
RSA keys must be in JWK format. More information on JWK format is available
here:
When you have generated your encryption key pairs, you can upload your key to the
Unified Checkout
platform. Keys can be loaded at any hierarchy that is
enabled for them and are used for all child entities that do not have keys loaded. You
can upload a key at parent and child levels, but child keys override parent
keys.
Follow these steps to upload your key pair:
Navigate to
Payment Configuration > Unified Checkout
.
The
Unified Checkout
configuration page opens.
Click
Enabled
. You can upload your key in the
appropriate section.
Upload the public encryption key in JWK format, and click
Save
.
Enable
Click to Pay
To enable
Click to Pay
on
Unified Checkout
, you must
first register
Click to Pay
. This process sends the appropriate
information to the digital payment systems and registers your page with each system.
Enable
Click to Pay
for
Unified Checkout
in the
Business Center
.
Click to Pay
is listed as an available
digital payment method offered by
Unified Checkout
.
Click to Pay
Appendix
Supported Countries for
Click to Pay
Click to Pay
is supported in these countries:
Argentina
Australia
Austria
Brazil
Bulgaria
Canada
China
Colombia
Costa Rica
Czech Republic
Denmark
Dominican Republic
Ecuador
El Salvador
Finland
France
Germany
Greece
Honduras
Hong Kong
Hungary
India
Indonesia
Ireland
Italy
Japan
Jordan
Kuwait
Malaysia
Mexico
Netherlands
New Zealand
Nicaragua
Norway
Panama
Paraguay
Peru
Poland
Qatar
Romania
Saudi Arabia
Singapore
Slovakia
Slovenia
South Africa
Spain
Sweden
Switzerland
Thailand
Ukraine
United Arab Emirates
United Kingdom
United States
Uruguay
Vietnam
Click to Pay
UI
Completing a payment with
Unified Checkout
requires the customer to
navigate through a sequence of interfaces. This section includes examples of the
interfaces that your customers can expect when completing a payment with
Click to Pay
.
Figure:
Click to Pay
UI
Processing Authorizations with a Transient Token
After you validate the transient token, you can use it in
place of the PAN with payment services for 15 minutes. The transient token can be
used multiple times within the 15-minute period.
Authorization with a Transient Token
This section provides the minimal set of information required to perform a successful
authorization with a transient token that is generated by the Flex API.
IMPORTANT
Each request that you send to
Cybersource
requires header information. For information about constructing the headers for your
request, see the
REST Example: Authorization with a Transient Token
Request
IMPORTANT
The transient token may already contain information such as
billing address and total amount. Any fields included in the request will
supersede the information contained in the transient token.
enables merchants to securely accept customer payment
information captured within a server-side application using a set of APIs. These APIs
protect your customer's primary account number (PAN), card verification number (CVN),
and other payment information by embedding it within a transient token. This allows
payment data to be stored and transported and complies with the Payment Card Industry
Data Security Standard (PCI DSS) policies and procedures. These transient tokens can be
validated by the receiver to ensure the data integrity and protect against data
injection attacks.
WARNING
Flex API
is intended for server-side applications only.
Do not use the
Flex API
in client-side applications. To add secure
payments directly into client-side code, use
Unified Checkout
.
IMPORTANT
Each request that you send to
Cybersource
requires header information. For information about constructing the headers for your
request, see the
Establish a payment session with a predefined customer context.
Validate the JSON Web Token.
Populate the JSON Web Token with customer information.
Customer Context
An important benefit of the
Flex API
is managing Personal Identifiable
Information (PII). You can set up your customer context to include all PII
associated with transactions, protecting this information from third parties.
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.
A JWT takes the form of a string, and consists of three parts separated by dots:
<Header>.<Payload>.<Signature>
The header and payload is
Base64-encoded JSON
and contains these claims:
Header
: The algorithm and token type. For
example:
{
"kid": "zu",
"alg": "RS256"
}
Payload
: The claims of what the token represents. For
example:
: The signature is computed from the header and payload using a
secret or private key.
IMPORTANT
When working with JWTs,
Cybersource
recommends that you use a well- maintained JWT library to ensure proper decoding
and parsing of the JWT.
IMPORTANT
When parsing the JWT’s JSON payload, you must ensure that you
implement a robust solution for transversing JSON. Additional elements can be
added to the JSON in future releases. Follow JSON parsing best practices to
ensure that you can handle the addition of new data elements in the future.
