Skip to main content

Server-Side Setup

This section contains the information you need to set up your server. Setting up the server side of Flex Microform v2 begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials and establishes how the Flex Microform v2 front-end components function. The sessions API request contains parameters that define how Flex Microform v2 performs.

The server-side component provides this information:

  • A transaction-specific public key 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.

These parameters are compiled into a JSON Web Token (JWT) object referred to as the capture context. For information about JWTs, see JSON Web Tokens.

Setting up the server side of Microform Integration for card information is a three-step process:

Review the capture context fields

These fields are available for requesting the capture context for accepting card information:

Required fields:

  • allowedCardNetworks
  • clientVersion
  • targetOrigins

Optional fields:

  • allowedPaymentTypes
  • transientTokenResponseOptions

For information about JWTs, see JSON Web Tokens. For the full field reference, see Capture Context API.

Create the server-side 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, see the sample code at Flex Samples on GitHub.

Send an authenticated POST request to the /microform/v2/sessions endpoint

POST /microform/v2/sessions
POST /microform/v2/sessions

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

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

To embed the target origin URL 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", "JAYWAN", "JCB", "JCREW", "KSCP", "MADA", "MAESTRO", "MEEZA", "PAYPAK", "UATP"],  "allowedPaymentTypes": ["CARD"]}

Pass the capture context response to your front-end application

The capture context is valid for 15 minutes.

Successful Encrypted JWT Response

eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJ1Q0RERW94M2dDQk1VaHI2T1ZDVGt4QUFFS1pHSTRHcDFvQ2pyYXlVb1MxQzdGOXE2WFpyYXhGbGxMVDMvenE2cjFnNXoxS1U2UDZseldqRVFTVVJoZUtxUThoVWJkZVNNdmt5SERTTXUwV01tMzhcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoiMXNDY3NZNC1WZTNWU0VKekhnelJ5WjVDOURrM0VHZ2ZPOGd5SDc5bVJfSlN6NzdmWTdfV1loM3psdTkyTFVfeU5KVTBUMzdOQmVzd0szU2c0YnRNaU41Q0FCbWNXLWNSckhta2k0MVZoNUZRMmtjcWZSSlgxNVhZN1A3R25GTnd4QzVkUG9UM29NM1czRFVHaUMyYW56enhIN3pNNlA3N2hFbnc2TkZHSXlBdXhJRWFwRG9DaXlEVW5NdFRwV2lBV3YzTF9OVHZOaHRkVE4tNm1GRWU1RmdVYmlzeWtrTzlWMHZaS0d6SWRWWmdTdE42cHlnUGhVbnlNXzJIVmIxQmkyWjNKaElhZDFLUW02SGl0NklwYjNyUTBHRWZsN0ZWOUV3NGZyNzJpekQ0WVg2WHo0V3ZuMzlLN3J3WkhCRXdNM3l5Wl9ELTBUbjM1MFhvUlBUVjB3Iiwia2lkIjoiMDB4V1A1eUh1UE1kNkFkNHdwVzNzQkt1bWFaQ01zYWMifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsImFsbG93ZWRDYXJkTmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiLCJBTUVYIiwiTUFFU1RSTyIsIkRJU0NPVkVSIiwiRElORVJTQ0xVQiIsIkpDQiIsIkNVUCIsIkNBUlRFU0JBTkNBSVJFUyJdLCJ0YXJnZXRPcmlnaW5zIjpbImh0dHBzOi8vdGhlLXVwLWRlbW8uYXBwc3BvdC5jb20iXSwibWZPcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJhbGxvd2VkUGF5bWVudFR5cGVzIjpbIkNBUkQiXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzY0MzA0MTQsImlhdCI6MTczNjQyOTUxNCwianRpIjoiZDVZbzVhNU0wWFBPQ1BxZiJ9.G4Ea-gIk6SG5ULE4NE5OsdPI41YaAuTEMHDstBgkFzczIWwzJScvXs4hgWiyA-1ZLGITedlumGj-0x8jxmYTWeTm7D0fP8RL0w148EpDLMD8xMHpAJMdMqZTmYHyichsy8uOZKVOn9NbnuQqfDeQS_rLpJV3tMe2NwJL3RdBXdJ894ihKpFP2yXE1wQeLekNiYJ6s-Uuxwf0jf2CSN_TJAjnfVR6bqlpWbUpiUaBLcqDsHHe_pcrd5g2r-1LEfCiOV9RIw7844XKFNLQZvt_alQjItuMy8M9LVhnlRWCSnTKB1iV1RUxuTWtMzTvHmQWPx4nShqzE3j0Hp61c0PmBw

Validate the server-side capture context

The capture context you generated is a JSON Web Token (JWT) data object, digitally signed using a public key. Validating the signature ensures the JWT is valid and confirms that it comes from . When you do not have a key specified locally in the JWT header, 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 and is associated with the capture context on the domain. To get the public key 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):

{ "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.

Resource

Pass the key ID (kid), which you obtained from the capture context header, as a path parameter, and send a GET request to the /public-keys endpoint:

GET /flex/v2/public-keys/{kid}
GET /flex/v2/public-keys/{kid}

The resource returns the public key. Use this public RSA key to validate the capture context.

Example

Parse the JWT 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_JLkP3o9UxXZRX1LIZFZeckguEf7Gdt5kGFFfTsymKBesm3Pe8o1hwfkq7KmJZEZSuDbiJSZvFBZycK2pEeBjycahw9CqOweM7aKG2F_bhwVHrY4YdKsp_cSJe_ZMXFUqYmjk7D0p7clX6CmR1QgMl41Ajb7NHI23uOWL7PyfJQwP1X8HdunE6ZwKDNcavqxOW5VuW6nfsGvtygKQxjeHrI-gpyMXF0e_PeVpUIG0KVjmb5-em_Vd2SbyPNmenADGJGCmECYMgL5hEvnTuyAybwgVwuM9amyfFqIbRcrAIzclT4jQBeZFwkzZfQF7MgA6QQ",  "e": "AQAB"}

Related Information

Last published: September 29, 2026