On This Page

Server-Side Setup

This section contains the information you need to set up your server. Initializing Microform Integration within your webpage begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials and establishes how the Microform Integration frontend components will function. The sessions API request contains parameters that define how Microform Integration performs.

The server-side component provides this information:

A transaction-specific public key is used by the customer's browser to protect the transaction.

An authenticated context description package that manages the payment experience on the client side. It includes available payment options such as card networks, payment interface styling, and payment methods.

The functions are compiled in a JSON Web Token (JWT) object referred to as the capture context
. For information JSON Web Tokens, see JSON Web Tokens.

Capture Context

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:

allowedPaymentTypes

clientVersion

targetOrigins

For information about JWTs, see JSON Web Tokens.

Target Origin: The target origin is defined by the scheme (protocol), host name (domain), and port number (if used).

You must use the https:// protocol. Sub-domains must also be included in the target origin.

Any valid top-level domain is supported, such as .com, .co.uk, and.gov.br. Wildcards are not supported.

For example, if you are launching Unified Checkout on example.com, the target origin could be any of these values:

https://example.com
https://subdomain.example.com
https://example.com:8080

You can define the payment cards and digital payments that you want to accept in the capture context.
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. Possible values:
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.

Creating the Server-Side Capture Context

The first step in integrating with Microform Integration is to develop the server-side code that generates the capture context. The capture context is also known as a session.

You can use the SDK or call the API directly to generate the capture context.

To use the SDK to generate the capture context, use the sample code here: Flex Samples on Github.

Follow these steps to call the API directly to generate the capture context:

Send an authenticated POST request to the

/sessions

endpoint to create your capture context session:

Production
:

https://api.cybersource.com/microform/v2/sessions

Test
:

https://apitest.cybersource.com/microform/v2/sessions

Include the target origin URL and at least one accepted card type in the content of the body of the request. You must also include the type of Microform Integration you want to include in the capture context for accepting eCheck information. If you do not include the allowedPaymentTypes
field in your capture request, the value defaults to

CARD

For example:

{
	"clientVersion": "v2",
	"targetOrigins": [
		"https://www.example.com"
	],
	"allowedCardNetworks": [
		"VISA"
	],
	"allowedPaymentTypes": [
		"CHECK"
	]
}

To embed within multiple nested iframes, you must specify the origins of all the browser contexts used. For example:

{
	"clientVersion": "v2",
	"targetOrigins": [
		"https://www.example.com",
		"https://www.basket.example.com",
		"https://ecom.example.com"
	],
	"allowedCardNetworks": [
		"VISA",
		"MASTERCARD",
		"AMEX",
		"CARTESBANCAIRES",
		"CARNET",
		"CUP",
		"DINERSCLUB",
		"DISCOVER",
		"EFTPOS",
		"ELO",
		"JCB",
		"JCREW",
		"MADA",
		"MAESTRO",
		"MEEZA"
	],
	"allowedPaymentTypes": [
		"CHECK"
	]
}

Pass the capture context response data object to your front-end application. The capture context is valid for 15 minutes.

Successful Encrypted JWT Response

eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJtdnkwVk9OVk40bzA4bTRGQjhmU3FCQUFFS0JWOTdlNnR2VDd4cHdqaFkwMDRydFJ1dGI0R2YwWlNwNGdNeEkvanBVSWxFblZKa2JtUVNHaWFnUEdGc0NPazdMbHJGTHFKcXN2eitoTHhrY08xRkFcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoidmRpN0gtM1MzMTkyZlc5WC1BTmpvdjlFdXU4ZGxPOTBtU2gyUGVyMF9PdHZ4YlJITTBrakZpTHlKaGQwUUR3VlNWbUlhRFc2aGtCa1k2Ui1lcWRnaTdUVUNGZEQ3UUU1ckNkZGhZZTIycTh0RUNQZkpOWWJ6STZZTVBxTkFyYWc5LUhhWVo1X2tOX0JvMm5EclN4RFJ0MHBDbGxyd2d2Q1ZLb2M0RWF6ZE93QUE4dnI2VVh4Ty1SWVI2Z1R5VEZia244Q2hDVHNvWDByam5VWVI1VjdRaE95YzMzWEJUTVNDYTVBOHFQNDZnZXpvQjZ0dDA0SlQtRVVMWE9vYndVcVdvd0E3TTJzWUYydkFoQkVuMmt0REJFWVJSN3E0aWEyVHRIS1JPUW9FTjhZNjNiNFNaTGZDQk82cEc2QXpnSWpya3RkQXhIOXR0WURYdFJYS1YxeTN3Iiwia2lkIjoiMDBiQlN1d3VpdGtYeExROGFISWloMm5qMFhQNFpXYUsifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsInRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly90aGUtdXAtZGVtby5hcHBzcG90LmNvbSJdLCJtZk9yaWdpbiI6Imh0dHBzOi8vc3RhZ2VmbGV4LmN5YmVyc291cmNlLmNvbSIsImFsbG93ZWRQYXltZW50VHlwZXMiOlsiQ0hFQ0siXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzM0OTAxODEsImlhdCI6MTczMzQ4OTI4MSwianRpIjoiSXdEdHAxZkVZM2QwYUh6OSJ9.arokacvdTSUIehBY0ICi-QYynhFj7_0k-G39qbkNJydB3UyF2qJSaqwZiopO27kuqk8u9Z0cY-V9Nu04JgaV4s18doxnzx6vdTCC3krrIcxeINi23Qu-Szcpg7aaGvPVXMC0DVC14WUQiGJkOakJ54jWtl2VoFAgYziUMcYYpk4hxLVxurBtT7lvrfCXKoyWtxiUxoEpOc_Td_qi5nA8ByWUaieQmp1Zej61khQJ_hmXtlsAt4BqxeJWoJeR_5Sjz0vD5y4-oAeNNrAulDem7CKiRJQbI9fyqT-

AFTER COMPLETING THE TASK

Important Security Note:

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.

Example

eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJtdnkwVk9OVk40bzA4bTRGQjhmU3FCQUFFS0JWOTdlNnR2VDd4cHdqaFkwMDRydFJ1dGI0R2YwWlNwNGdNeEkvanBVSWxFblZKa2JtUVNHaWFnUEdGc0NPazdMbHJGTHFKcXN2eitoTHhrY08xRkFcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoidmRpN0gtM1MzMTkyZlc5WC1BTmpvdjlFdXU4ZGxPOTBtU2gyUGVyMF9PdHZ4YlJITTBrakZpTHlKaGQwUUR3VlNWbUlhRFc2aGtCa1k2Ui1lcWRnaTdUVUNGZEQ3UUU1ckNkZGhZZTIycTh0RUNQZkpOWWJ6STZZTVBxTkFyYWc5LUhhWVo1X2tOX0JvMm5EclN4RFJ0MHBDbGxyd2d2Q1ZLb2M0RWF6ZE93QUE4dnI2VVh4Ty1SWVI2Z1R5VEZia244Q2hDVHNvWDByam5VWVI1VjdRaE95YzMzWEJUTVNDYTVBOHFQNDZnZXpvQjZ0dDA0SlQtRVVMWE9vYndVcVdvd0E3TTJzWUYydkFoQkVuMmt0REJFWVJSN3E0aWEyVHRIS1JPUW9FTjhZNjNiNFNaTGZDQk82cEc2QXpnSWpya3RkQXhIOXR0WURYdFJYS1YxeTN3Iiwia2lkIjoiMDBiQlN1d3VpdGtYeExROGFISWloMm5qMFhQNFpXYUsifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsInRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly90aGUtdXAtZGVtby5hcHBzcG90LmNvbSJdLCJtZk9yaWdpbiI6Imh0dHBzOi8vc3RhZ2VmbGV4LmN5YmVyc291cmNlLmNvbSIsImFsbG93ZWRQYXltZW50VHlwZXMiOlsiQ0hFQ0siXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzM0OTAxODEsImlhdCI6MTczMzQ4OTI4MSwianRpIjoiSXdEdHAxZkVZM2QwYUh6OSJ9.arokacvdTSUIehBY0ICi-QYynhFj7_0k-G39qbkNJydB3UyF2qJSaqwZiopO27kuqk8u9Z0cY-V9Nu04JgaV4s18doxnzx6vdTCC3krrIcxeINi23Qu-Szcpg7aaGvPVXMC0DVC14WUQiGJkOakJ54jWtl2VoFAgYziUMcYYpk4hxLVxurBtT7lvrfCXKoyWtxiUxoEpOc_Td_qi5nA8ByWUaieQmp1Zej61khQJ_hmXtlsAt4BqxeJWoJeR_5Sjz0vD5y4-oAeNNrAulDem7CKiRJQbI9fyqT-

Base64 decode the capture context to get the key ID (

kid

) from its header:

{
  "kid": "3g",
  "alg": "RS256"
}

Get its public key from

/flex/v2/public-keys/3g

{
    "kty":"RSA",    
    "use":"enc",
    "kid":"3g",
    "n":"ir7Nl1Bj8G9rxr3co5v_JLkP3o9UxXZRX1LIZFZeckguEf7Gdt5kGFFfTsymKBesm3Pe
     8o1hwfkq7KmJZEZSuDbiJSZvFBZycK2pEeBjycahw9CqOweM7aKG2F_bhwVHrY4YdKsp
     _cSJe_ZMXFUqYmjk7D0p7clX6CmR1QgMl41Ajb7NHI23uOWL7PyfJQwP1X8HdunE6ZwK
     DNcavqxOW5VuW6nfsGvtygKQxjeHrI-gpyMXF0e_PeVpUIG0KVjmb5-em_Vd2SbyPNme
     nADGJGCmECYMgL5hEvnTuyAybwgVwuM9amyfFqIbRcrAIzclT4jQBeZFwkzZfQF7MgA6QQ",
     "e":"AQAB"
}