Request the Setup Service

Request the Setup service before selecting the button to submit payment. Request the Setup service separately without including other services. The Setup service response includes a JSON Web Token (JWT) that contains credentials to create a secure channel with you. The Setup response also includes a reference ID to use during the authentication and a URL to use when transferring the device data collected in the next step.

Run the Setup service as soon as the customer enters their card number to avoid any delay in the customer experience. The next step in the process, device data collection, cannot start until the Setup response is received because the response has the URL where the device data is sent.

After the customer credit card is entered, immediately begin device data collection.

Setup Endpoint

Setup Request Fields

When requesting the Setup service, you must send the customer's payment information. This can be either the actual encrypted card information or a token associated with the payment data.

Besides the required fields, the request might also include any of these fields:

Setup Response Fields

The response from the issuing bank might include these API fields:

Collect Device Data

One of the key components to authenticating a cardholder during an online transaction is to compare information about the device that the customer is currently using to the information in the bank's database about devices the customer used in past transactions.

Device data collection starts on the merchant end after you receive the server-side Setup service response as described in Request the Setup Service and pass the access token and the device data collection URL to the front end. When device data gets to the data collection URL, a Method URL defined in the 3-D Secure protocol captures the entire card number to identify the issuing bank.

A hidden 10 x 10 pixel iframe is rendered in the browser, and using the access token, you send the customer device data to the device data collection URL. The device data collection can take up to 10 seconds. If you proceed with the check enrollment service as described in Check Enrollment before a response is received, the collection process stops and an error occurs. Despite the error, as long as you include the data from the eleven browser fields as explained in Check Enrollment, you can still proceed with the EMV authentication.

Start device data collection immediately after you receive the customer card number to ensure that the data collection runs in the background while the customer continues with the checkout process, ensuring a minimum of waiting. When a customer changes to a different card number, begin the Setup and device data collection process again as soon as the new card number is entered.

<iframe id="cardinal_collection_iframe" name="collectionIframe" height="10" width="10" style="display: none;"></iframe><form id="cardinal_collection_form" method="POST" target="collectionIframe" action=https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect>  <input id="cardinal_collection_form_input" type="hidden" name="JWT" value="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJSZWZlcmVuY2VJZCI6ImE0NjVlYzU1LTMwNTEtNGYwZC05MGE0LWZjMDNlMGE2MWQxOSIsIlJldHVyblVybCI6Imh0dHA6XC9cL2xvY2FsaG9zdDo4MDgyXC9yZXF1ZXN0LWNhdGNoZXJcL2NhdGNoLXJlcXVlc3QucGhwIiwianRpIjoianRpXzVmMDVkM2VkY2U0MjYzLjc5MjQwNzMzIiwiaWF0IjoxNTk0MjE3NDUzLCJpc3MiOiI1YjIzZjhjMGJmOWUyZjBkMzQ3ZGQ1YmEiLCJPcmdVbml0SWQiOiI1NWVmM2YwY2Y3MjNhYTQzMWM5OWI0MzgifQ.Yw9cB9Hdrg71GPL40oAC0g3CVKYElNGe0uvN9JAaw2E"></form>

<script>window.onload = function() {var cardinalCollectionForm = document.querySelector('#cardinal_collection_form');if(cardinalCollectionForm) // form existscardinalCollectionForm.submit();}</script>

window.addEventListener("message", function(event) {  if (event.origin === "https://centinelapistag.cardinalcommerce.com") {    console.log(event.data);  }}, false);

{  "MessageType": "profile.completed",  "Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",  "Status": true}

Check Enrollment

Request the Check Enrollment service only after you receive the device data collection response. If you check enrollment before receiving the device data collection response, data collection stops. Data collection can take up to 10 seconds. Set a timer that expires after 10 seconds of waiting for a response to the data collection so that the check enrollment service starts even when the device data collection response was not received.

With the device data collected, the issuer runs a risk assessment that results in one of these outcomes:

• Frictionless success (low risk)
• Challenge required (moderate risk)
• Frictionless failure or decline (high risk)

Enrollment Check Endpoint

Enrollment Check Request Fields

The consumerAuthenticationInformation.referenceId field is mapped from the consumerAuthenticationInformation.referenceId field as discussed in Request the Setup Service.

The consumerAuthenticationInformation.returnUrl value is set to the URL to which the issuing bank redirects the customer as discussed in Present the Step-Up Challenge.

These fields are required (merchant ID is in the header):

You can send additional request data to reduce your issuer step-up authentication rates. Send all available fields. As a backup, if device data collection fails, include these 11 device information fields in your request. If a failure does occur, adding these device information fields ensures a transaction is not downgraded. If you do not have data for a field, do not send dummy data.

You can request the size of the challenge window in the consumerAuthenticationInformation.acsWindowSize request field.

To request the Check Enrollment service, you must send the encrypted payment data or a token or some other equivalent of card data used by your integration. The request fields can include any of these:

Field values must use the ISO 3166-2 format.

Present the Step-Up Challenge

Initiate step-up authentication on the front end after you receive the response as discussed in Check Enrollment. Frictionless authentication does not require this step-up iframe step. This step is only for step-up authentication when the issuing bank wants to challenge the cardholder.

When a challenge is needed to prove a customer's identity, a JSON Web Token is returned to you that contains a step-up URL. You open an iframe where the access token to the step-up URL (also known as the endpoint) is posted. The iframe must be sized appropriately to enable the cardholder to complete the challenge. The iframe manages customer interaction with the card-issuing bank's access control server. The bank asks the customer to provide identifying information. After the customer completes the challenge, the process moves to validating the information that the customer sent.

{    "messageType": "CReq",    "messageVersion": "2.2.0",    "threeDSServerTransID": "c4b911d6-1f5c-40a4-bc2b-51986a98f991",    "acsTransID": "47956453-b477-4f02-a9ef-0ec3f9f779b3",    "challengeWindowSize": "02"}

<iframe name="step-up-iframe" height="400" width="400"></iframe><form id="step-up-form" target="step-up-iframe" method="post" action="https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp">  <input type="hidden" name="JWT" value="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmNmFmMTRmOS04YWRjLTRiNzktOGVkYS04YWVlMTI2NTkzZTEiLCJpYXQiOjE1OTYwNTEyNzYsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5NjA1NDg3NiwiT3JnVW5pdElkIjoiNTVlZjNmNTZmNzIzYWE0MzFjOTlkNTRiIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AifX0.H8j-VYCJK_7ZEHxGz82_IwZGKBODzPaceJNNC99xZRo" />  <input type="hidden" name="MD" value="optionally_include_custom_data_that_will_be_returned_as_is" /></form>

<script>window.onload = function() {    var stepUpForm = document.querySelector('#step-up-form');    if(stepUpForm) // Step-Up form exists    stepUpForm.submit();}</script>

TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=null

Validate the Results

When you receive the step-up response as discussed in Present the Step-Up Challenge, verify that the customer was successfully authenticated. Frictionless authentication does not require this validation step. Validation is required only for step-up authentication.

Validation Endpoint

Validation Request Fields

The consumerAuthenticationInformation.authenticationTransactionId field in this step is mapped from the consumerAuthenticationInformation.authenticationTransactionId field in Present the Step-Up Challenge.

These fields are required:

Interpreting the Validation Response

If the authentication is rejected (TransStatus R), Visa, China UnionPay, Elo, JCB, Diners Club, Discover, and American Express recommend not proceeding to authorization. Instead, ask the customer to use another payment method.

Proceed with the order according to the validation response that you receive. The possible validation response statuses are the same for all card types.

Redirecting Customers to a Pass or Fail Message Page

After authentication is complete, redirect the customer to a page containing a success or failure message. You must ensure that the messages displayed to customers are accurate and complete, and that the message addresses all possible scenarios for enrolled and non-enrolled cards. For example, if the authentication fails, display a message such as this to the customer:

Authentication FailedYour card issuer cannot authenticate this card. Please select another card or form of payment to complete your purchase.