Step 2: Device Data Collection

Device data collection starts on the merchant end after you receive the server-side Setup service response as described in Step 1: 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 stipulated in the 3-D Secure protocal 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 Step 3: Payer Authentication Check Enrollment Service before a response is received, the collection process is short-circuited and an error occurs. Despite the error, as long as you include the data from the eleven browser fields as explained in Step 3: Payer Authentication Check Enrollment Service, you can still proceed with the EMV authentication.
It is recommended that the device data collection start 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.

Figure:

Process Flow for Device Data Collection
Process Flow diagram for Device Data Collection

Best Practices

These practices should be followed for this step in order to achieve optimal performance and to minimize potential operating issues.
  • After the customer credit card number is entered, immediately begin the device data collection.
  • Device data collection must complete before the enrollment check begins.
  • While not required, it is highly recommended to pass the values from the 11 browser-based fields in the request. The information from these fields serves as a backup, in case the device data collection does not complete correctly.
  • As much billing data as possible (unless restricted by regional mandates) should be supplied to the issuing bank to ensure that the issuer's risk assessment software has the most comprehensive data.
  • The billing data such as state and country must be formatted according to ISO 3166-2 format specifications to ensure that the network can properly validate the data.

Which Device Data is Collected

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. This information is maintained in the acess control server (ACS) at the issuing bank. This device information focuses on the web browser and includes these types of data:
  • IP address
  • Browser language
  • Browser type
  • Browser version
  • Computer operating system
  • System time zone
  • Screen dimensions
  • Color depth
A successful device data collection process that includes the 11 browser fields listed in the check enrollment step increases the chances of a frictionless authentication. Business rules evaluate whether a transaction is risky enough to require the buyer to authenticate their identity. These business rules are configured in the issuer's risk analysis software that evaluates each transaction.
Step 2: Device Data Collection

Building the Iframe

The iframe has these parameters:
  • Form POST Action: The POST goes to the URL that is opened within an iframe. This URL is the value provided by the
    payerAuthSetupReply_deviceDataCollectionURL
     response field discussed in Step 1: Setup Service.
  • JWT POST Parameter: Use the value from the
    payerAuthSetupReply_accessToken
     response field discussed in Step 1: Setup Service.
Step 2: Device Data Collection

Initiating the Device Data Collection Iframe

Initiate a form POST in a hidden 10 x 10 pixel iframe and send it to the device data collection URL (
payerAuthSetupReply_deviceDataCollectionURL
).
Place the HTML anywhere inside the
<body>
 element of the checkout page. Dynamically replace the value of the form action attribute and JWT POST parameter with the response values discussed in Step 1: Setup Service. See this example.
Initiate the Device Data Collection Iframe
<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.eyJSZWZlcmVuY2VJZCI6ImE0NjVlYzU1LTMwNTEtN GYwZC05MGE0LWZjMDNlMGE2MWQxOSIsIlJldHVyblVybCI6Imh0dHA6XC9cL2xvY2FsaG9zdDo4MDgyXC9yZXF1ZX N0LWNhdGNoZXJcL2NhdGNoLXJlcXVlc3QucGhwIiwianRpIjoianRpXzVmMDVkM2VkY2U0MjYzLjc5MjQwNzMzIi wiaWF0IjoxNTk0MjE3NDUzLCJpc3MiOiI1YjIzZjhjMGJmOWUyZjBkMzQ3ZGQ1YmEiLCJPcmdVbml0SWQiOiI1 NWVmM2YwY2Y3MjNhYTQzMWM5OWI0MzgifQ.Yw9cB9Hdrg71GPL40oAC0g3CVKYElNGe0uvN9JAaw2E">
</form>
Step 2: Device Data Collection

Submitting the Device Data Collection Iframe

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body>
 element as shown in this example. The JavaScript invokes the iframe form POST automatically when the window loads. You must submit it before requesting the Check Enrollment service.
JavaScript to Invoke the Iframe Form POST
 
 <script>
window.onload = function() { 
var cardinalCollectionForm = document.querySelector('#cardinal_collection_form'); 
if(cardinalCollectionForm) // form exists 
cardinalCollectionForm.submit();
}
</script>
Step 2: Device Data Collection

Receiving the Device Data Collection URL Response

Receiving the response indicates that the device data collection URL completed its processing. The response is an event callback that contains a message with the status of the device data collection process.
Use the
event.origin
 URL that corresponds to your environment:
  • Test:
    https://centinelapistag.cardinalcommerce.com
  • Production:
    https://centinelapi.cardinalcommerce.com
Study the example below to understand how to subscribe to the event. Add JavaScript to receive the response from the device data collection iframe. Place the JavaScript after the closing
</body>
 element.
Listen for Device Data Collection Response
window.addEventListener("message", function(event) {
  if (event.origin === https://centinelapistag.cardinalcommerce.com) {
    console.log(event.data);
  }
}, false);
This example shows a response payload from the event. None of the returned data needs to be stored for future use.
Event Listener Callback Payload
{
  "MessageType": "profile.completed",
  "Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",
  "Status": true
}
Step 2: Device Data Collection