Flex Token Use Cases

These examples list the API fields required for the Setup, Check Enrollment, and Validate Authentication services when using a Flex Microform token. An example of a request payload and a successful response for each service is provided.

A Flex Microform token is valid for 15 minutes. After 15 minutes, a new Flex Microform token is needed.

Setting Up Device Data Collection When Using a Flex Microform Token

Running the Setup service identifies the customer's bank and prepares for collecting data about the device that the customer is using to place the order. In this use case, a Flex Microform token is used instead of the payment card data.

Endpoint

POST /risk/v1/authentication-setups

Example: Setup with a Flex Microform Token

{  "tokenInformation": {    "transientToken": "1C0RNHMQBTATXFCFNGR5EXH3XNOP6359LGLL9J283ATABJ8Z11NL66D834239B51"  }}

{  "consumerAuthenticationInformation": {    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",    "deviceDataCollectionUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",    "referenceId": "004ac0ad-f0a6-4800-9d7a-962de6eb446c",    "token": "AxizbwSTiUOd9P85Jq6mABEBTyDYFkxkAhMQyaSZejFczCmBWAAAnxnb"  },  "id": "7254442740716751204006",  "status": "COMPLETED",  "submitTimeUtc": "2024-09-04T10:04:34Z"}

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.

Field	Requirement
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Country-Specific Requirements

Field	Requirement
`consumerAuthenticationInformation.overrideCountryCode`	For Meeza transactions, this value must be set to `EG` if Egypt was not set as the country in merchant configuration during merchant boarding.
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.
`merchantInformation.merchantDescriptor.country`	For Meeza transactions, this value must be set to `EG` if Egypt was not set as the country in merchant configuration during merchant boarding.

Required Field for Setup with a Flex Microform Token

This field is required to use a Flex Microform token when you request the payer authentication Setup service.

Field	Notes
`tokenInformation.transientToken`

Checking Enrollment When Using a Flex Microform Token

The Check Enrollment service verifies whether the customer's card is enrolled in a card authentication program. In this use case, a Flex Microform token is used instead of the payment card data. Flex Microform tokens are only valid for 15 minutes.

Endpoint

POST /risk/v1/authentications

Example: Check Enrollment with a Flex Microform Token (Challenge)

{  "orderInformation": {    "amountDetails": {      "currency": "USD",      "totalAmount": "10.99"    },    "billTo": {      "address1": "1 Market St",      "address2": "Address 2",      "administrativeArea": "CA",      "country": "US",      "locality": "san francisco",      "firstName": "John",      "lastName": "Doe",      "phoneNumber": "4158880000",      "email": "[email protected]",      "postalCode": "94105"    }  },  "deviceInformation": {    "ipAddress": "139.130.4.5",    "httpAcceptContent": "test",    "httpBrowserLanguage": "en_us",    "httpBrowserJavaEnabled": "N",    "httpBrowserJavaScriptEnabled": "Y",    "httpBrowserColorDepth": "24",    "httpBrowserScreenHeight": "100000",    "httpBrowserScreenWidth": "100000",    "httpBrowserTimeDifference": "300",    "userAgentBrowserValue": "GxKnLy8TFDUFxJP1t"  },  "consumerAuthenticationInformation": {    "deviceChannel": "BROWSER",    "transactionMode": "eCommerce",    "referenceId": "CybsCruiseTester-b767b4ea"  },  "tokenInformation": {    "transientToken": "1C0RNHMQBTATXFCFNGR5EXH3XNOP6359LGLL9J283ATABJ8Z11NL66D834239B51"  }}

{  "clientReferenceInformation": {    "code": "1725444594611"  },  "consumerAuthenticationInformation": {    "challengeRequired": "N",    "authenticationTransactionId": "jzULqrneaqG5H3Jev780",    "strongAuthentication": {      "OutageExemptionIndicator": "0"    },    "token": "AxjzbwSTiUOpWHIlxG5lABEBTyDYFlzPSBcS0JhdrSTL0YrmYUwKwAAAwwQS",    "acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",    "acsReferenceNumber": "Cardinal ACS",    "stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",    "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEi...",    "directoryServerTransactionId": "231b97bd-2a3d-4500-b666-fda90334e5db",    "veresEnrolled": "Y",    "threeDSServerTransactionId": "1d0c7257-9bd3-4fe9-b399-8c513c88d699",    "acsOperatorID": "MerchantACS",    "specificationVersion": "2.2.0",    "acsTransactionId": "83c7e636-3af2-4a96-9e59-7c6754127d24"  },  "errorInformation": {    "reason": "CONSUMER_AUTHENTICATION_REQUIRED",    "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction."  },  "id": "7254445946286742204005",  "paymentInformation": {    "card": {      "bin": "445653",      "type": "VISA"    }  },  "status": "PENDING_AUTHENTICATION",  "submitTimeUtc": "2024-09-04T10:09:55Z"}

Card-Specific Requirements

Field	Requirement
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Country-Specific Requirements

Field	Requirement
`consumerAuthenticationInformation.overrideCountryCode`	For Meeza transactions, this value must be set to `EG` if Egypt was not set as the country in merchant configuration during merchant boarding.
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.
`merchantInformation.merchantDescriptor.country`	For Meeza transactions, this value must be set to `EG` if Egypt was not set as the country in merchant configuration during merchant boarding.

Required Fields for Checking Enrollment with a Flex Microform Token

Field	Notes
`consumerAuthenticationInformation.deviceChannel`
`consumerAuthenticationInformation.referenceId`
`deviceInformation.httpAcceptBrowserValue`
`deviceInformation.httpAcceptContent`
`deviceInformation.httpBrowserColorDepth`
`deviceInformation.httpBrowserJavaEnabled`
`deviceInformation.httpBrowserJavaScriptEnabled`
`deviceInformation.httpBrowserLanguage`
`deviceInformation.httpBrowserScreenHeight`
`deviceInformation.httpBrowserScreenWidth`
`deviceInformation.httpBrowserTimeDifference`
`deviceInformation.ipAddress`
`deviceInformation.userAgentBrowserValue`	When the customer's browser provides this value, you must include it in your request.
`orderInformation.amountDetails.currency`
`orderInformation.amountDetails.totalAmount`	Required when the `orderInformation.lineItems.unitPrice` field is not used.
`orderInformation.billTo.address1`
`orderInformation.billTo.address2`
`orderInformation.billTo.administrativeArea`	Required for the US and Canada.
`orderInformation.billTo.country`	Required for the US and Canada.
`orderInformation.billTo.email`
`orderInformation.billTo.firstName`
`orderInformation.billTo.lastName`
`orderInformation.billTo.locality`
`orderInformation.billTo.phoneNumber`
`orderInformation.billTo.postalCode`
`paymentInformation.card.expirationYear`
`paymentInformation.card.expirationMonth`
`paymentInformation.card.type`

Validating a Challenge When Using a Flex Microform Token

The Validation service verifies the authentication results after the cardholder completes the step-up challenge. In this use case, a Flex Microform token is used instead of the payment card data.

Endpoint

POST /risk/v1/authentication-results

Example: Validate Challenge with a Flex Microform Token

{  "paymentInformation": {    "card": {      "type": "001"    }  },  "consumerAuthenticationInformation": {    "authenticationTransactionId": "jzULqrneaqG5H3Jev780"  }}

{  "clientReferenceInformation": {    "code": "pavalidatecheck",    "partner": {      "developerId": "7891234",      "solutionId": "89012345"    }  },  "consumerAuthenticationInformation": {    "indicator": "vbv",    "eciRaw": "05",    "authenticationResult": "0",    "strongAuthentication": {      "OutageExemptionIndicator": "0"    },    "authenticationStatusMsg": "Success",    "eci": "05",    "token": "AxizLwSTiUOsVuUwvt1DABEBTyDYFmPAAhMQyaSZejFczCmATUmo",    "cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",    "paresStatus": "Y",    "xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",    "directoryServerTransactionId": "231b97bd-2a3d-4500-b666-fda90334e5db",    "threeDSServerTransactionId": "1d0c7257-9bd3-4fe9-b399-8c513c88d699",    "specificationVersion": "2.2.0",    "acsTransactionId": "83c7e636-3af2-4a96-9e59-7c6754127d24"  },  "id": "7254446789006754504003",  "paymentInformation": {    "card": {      "bin": "445653",      "type": "VISA"    }  },  "status": "AUTHENTICATION_SUCCESSFUL",  "submitTimeUtc": "2024-09-04T10:11:19Z"}

Card-Specific Requirements

Field	Requirement
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Country-Specific Requirements

Field	Requirement
`consumerAuthenticationInformation.overrideCountryCode`	For Meeza transactions, this value must be set to `EG` if Egypt was not set as the country in merchant configuration during merchant boarding.
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.
`merchantInformation.merchantDescriptor.country`	For Meeza transactions, this value must be set to `EG` if Egypt was not set as the country in merchant configuration during merchant boarding.

Required Fields for Validating a Challenge with a Flex Microform Token

Field	Notes
`consumerAuthenticationInformation.authenticationTransactionId`
`paymentInformation.card.type`

Was this page helpful?

Last published: September 29, 2026