This Device Data Collection page provides a set of options for our Customers to integrate one of these requirements for our Cardinal Cruise API integration.  By choosing one of the Device Data Collection option, Cardinal is able to collect the 3DS 2.0 (EMV 3DS) required browser data elements in order to make the 3DS 2.0 request and invoke the 3DS Method URL if available. We will leverage this process to place the required Method URL on the merchant's site, within an iframe, if the Issuing Bank chooses to use one. (Per EMV 3DS requirements, a merchant must place and run the Method URL on their website if an Issuing Bank uses one). 

The Method URL is a concept in the EMV 3DS protocol that allows and Issuing Bank to obtain additional browser information prior starting the authentication session to help facilitate risk-based authentication. The implementation techniques to obtain the additional browser information is out of scope of the EMV 3DS protocol. As a note, this same process was done in 3DS 1.0, however it was done when the Consumer's browser was redirected to the ACS URL, this Method URL step allow for a better user experience.

Endpoints

Staging:  https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
Production:  https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect

Prerequisites

To support Device Data Collection, you must complete one of these Options below

  • The Integrator must have access to the card BIN (BIN is the first 6-8 digits of a card number) or full card number of cardholder
  • The Integrator must create an iframe on their website and post to the Device Data Collection URL

Implementation Options

Overview of each Device Data Collection option. 

  1. Option 1 - JWT - Card BIN to full Card Number in JWT
    1. This option is the recommended approach and allows for the integrator to pass the Card BIN to full Card Number in the JWT
  2. Option 2 - API - Card BIN to Card Number in API (to BIN Intelligence API)
    1. This option allows the integrator to not pass the Card BIN to full Card Number in the JWT, but allows you to pass the Card BIN to full Card Number in an API Call to setup the Device Data Collection session and in response obtain a ReferenceId to pass up to the web frontend instead of the Card BIN. 
  3. Option 3 - JWT - Card BIN as a POST parameter plus JWT
    1. This option allows the integrator to pass the Card BIN directly from the web fronted to the Device Data Collection URL instead of the JWT.  However, a JWT is still required to authenticate the session.

Option 1 - JWT - Card BIN to full Card Number in JWT

This implementation option is the simplest and recommended approach which requires less moving parts.  As part of the JWT generation, all you will need to do is add the card bin to full card number in the Payload within the Transactional JWT.  When the Device Data Collection URL is invoked, the Transactional JWT will be posted over to the URL.  

Integration Steps:

  1. Card BIN to full Card Number goes into the Transactional JWT 
  2. POST Transactional JWT to the Device Data Collection URL
  3. Handle the Response from the Device Data Collection URL on the ReturnUrl provided within the TransactionalJWT


<iFrame height="1" width="1" style="display: none;">
<form id="collectionForm" name="devicedata" method="POST" action="https://centinelapisbox.cardinalcommerce.com:50486/V1/Cruise/Collect">
<input type="hidden" name="JWT" value="Transactional JWT generated per specification" />
</form>
<script>window.onload = function() {    
// Auto submit form on page load
document.getElementById('collectionForm').submit();
}
</script>
</iFrame>


This example shows the ReturnUrl being populated in the Transactional JWT instead of a POST parameter.

Option 2 - API - Card BIN to Card Number in API (to BIN Intelligence API)

This implementation option allows the integrator to pass the card bin to full card number via a JSON request to Cardinal instead of passing the card bin to card number to the frontend.  The benefit of this approach is the ability to pass the card bin to card number server-side from the integrator to Cardinal and never surface this information up to the frontend.  However, this uses an additional API call to pass this data between the integrator and Cardinal servers. 

Flow:  

Integration Steps:

  1. Cardinal Cruise Account Credentials
  2. Connecting to the BIN Intelligence API
  3. BIN Intelligence Request Field Names (Card BIN to full Card Number goes into the AccountNumber field)
  4. Handling the BIN Intelligence API Response with ReferenceId
  5. Generating an Authentication JWT with ReferenceId
  6. Initiating the DeviceDataCollectionUrl
  7. Handle the Response from the Device Data Collection URL

Connecting to the BIN Intelligence API

Endpoints for Staging and Production

Staginghttps://geostag.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/Load

Productionhttps://geo.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/Load

BIN Intelligence Request Field Names

Field

Description

Required

Signature

Base64 encoded SHA256 of SHA512 value that is a hash of timestamp, TransactionId and API Key

Y

Timestamp

Java Epoch time in millis (0:00:00 UTC on 1 January 1970)

Y

Identifier

api key identifier or Name value

Y

Algorithm

The hashing algorithm used to generate the Signature value. Valid options include:

  • SHA-256

Y

TransactionId

Alpha numeric value transactionId. Length 5-55 characters long

Y

OrgUnitId

Processor/Merchant level OrgUnitId, depending on the endpoint

Y

Payload

The Payload for the BIN Intelligence request will contain an AccountNumber where the Card BIN to full Card Number will be passed.

Y

BINsThis field represents the Consumer's Credit Card Number.  The BINs field must contain at a minimum, the Card BIN (first 8 digits) to the full Card Number in the request. This field type is an array of strings.Y
Examples of generating a Signature Value
Timestamp: 2019-01-14T20:42:13.216Z
Milliseconds Since Epoch: 1547498533216
TransactionId: 07643622
ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44
Signature: wpGKFbhcBl+8JLVXGP0QqBooK6dtLBv9bYtI15NXL1U=


Timestamp: 2019-01-14T20:42:13.216Z
Milliseconds Since Epoch: 1547498533216
TransactionId: 07643622
ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44
Signature: SBF4wmV5LPCsb7Em+Yfa2RB4xtohV8s2ffYArhPUrZqjEsgUjbuVzBPyhgYma5x71T5y7dIHPJHE2uqL3Vp0Hg==
Example of the BIN Intelligence JSON Request
{
  "Signature":"2ejC+DdvSVyRD2PnskTGw4G7rg0CqwfZNAqniChWjp0=",
  "Timestamp":"2018-09-19T19:04:05.104Z",
  "TransactionId" : "132456789",
  "Identifier" : "aalkjdfalkdjfaslkdj",
  "OrgUnitId" : "564cdcbcb9f63f0c48d6387f",
  "Algorithm" : "SHA-256",
  "Payload" : {
    "BINs" : ["4100000000000000000"]
  }
}


No ReturnUrl is needed in the BIN Intelligence Request.  This is not a request JWT, so the Custom Claims like ReturnUrl are not valid. 


Handling the BIN Intelligence Response with ReferenceId

The BIN Intelligence response will include a ReferenceId and DeviceDataCollectionUrl if successful, these two values will be used when invoking the DeviceDataCollectionUrl within an iframe on your website.  We are essentially initiating the session with the Card BIN to full Card Number and returning back a ReferenceId to invoke the frontend DeviceDataCollectionUrl.  

BIN Intelligence Response Fields

Field

Type

Description

Required

ErrorNumber

AN(255)

Application error number. A non-zero value represents the error encountered while attempting the process the message request.

Y

TransactionId

AN(50)

A transaction identifier returned back from Cardinal

Y

Payload

-

The Payload for the BIN Intelligence response will contain a ReferenceId and a DeviceDataCollectionUrl

Y

ReferenceId

AN(50)This identifier represents the DeviceDataCollection session that has been started and must be passed in the Authentication JWT when invoking the DeviceDataCollectionUrl

Y

DeviceDataCollectionUrl

AN(100)

The DeviceDataCollectionUrl is the location to send the Authentication JWT when invoking the Device Data Collection process.

Y

Generating an Authentication JWT with ReferenceId

After the BIN Intelligence API response is received, the integrator must generate an Authentication JWT with the ReferenceId received in the response.  The Authentication JWT and the DeviceDataCollectionUrl must be sent up to the merchant's frontend in order to complete the Device Data Collection requirement.   In addition, the integrator can also include a ReturnUrl as a root level custom claim in order to receive the response from Device Data Collection Url. 

Example of the Authentication JWT with a root level ReturnURL custom claim
{
  "jti": "7b9e0f50-a4a7-11e8-91e8-795883ca8f10",
  "iat": "1534789987",
  "iss": "Midas-TwoDotOh-Key",
  "OrgUnitId": "59c2745f2f3e7357b4aa516a",
  "ReferenceId": "60b98564-2faa-4d39-9c41-ce913ba3be99",
  "ReturnUrl": "http://localhost:8189/cart/enterprise/collect-term"
}

Initiating the DeviceDataCollectionUrl

Now that you have successfully called the BIN Intelligence API to start the Device Data Collection session, generated an Authentication JWT, you will need to pass the Authentication JWT and Device Data Collection URL up to your frontend.  The front end is the location required to initiate the DeviceDataCollectionUrl because this url needs access to the Consumer's browser in order to invoke Method Url.  You will need to initiate a form post in a hidden iframe to the Device Data Collection URL that was passed up from your backend system and the Authentication JWT as a post parameter.  

<iFrame height="1" width="1" style="display: none;"> 
<form id="collectionForm" name="devicedata" method="POST" action="https://centinelapisbox.cardinalcommerce.com:50486/V1/Cruise/Collect">
<!--POST Parameters: is the JWT which is the Authentication JWT with the ReferenceId from the BIN Intelligence API Response-->              
<input type="hidden" name="JWT" value="Authentication JWT generated per specification" />
</form>
<script>window.onload = function() {// Auto submit form on page load
document.getElementById('collectionForm').submit();}
</script>
</iFrame>

Handle the Response from the Device Data Collection URL

Now that you have successfully posted the Authentication JWT over to the Device Data Collection URL, you can now setup a process to handle the response.  Handling the response is important to know when the Device Data Collection URL has completed its processing.  We support two ways to handle the response back from the Device Data Collection URL.  

Option 1 - Using a ReturnUrl

The ReturnUrl option is a merchant defined URL that must go in the Transactional or Authentication JWT as a root level claim and it will be the location to which you receive the consumer session back after the Device Data Collection URL has completed processing or not.  After the Device Data Collection URL has completed, it will initiate a form post to the ReturnUrl

{
  "jti": "f7c64630-a167-11e8-9db5-9f12cae676de",
  "iat": 1534432854,
  "iss": "Midas-NoDV-Key",
  "OrgUnitId": "564cdcbcb9f63f0c48d6387f",
  "ReferenceId": "c3989c38-6caf-410a-8965-459b1e814648",
  "ReturnUrl": "http://localhost:8189/cart/enterprise/collect-term",
  "Payload": {
    "OrderDetails": {
      "Amount": 1500,
      "CurrencyCode": 840,
      "OrderNumber": "asdf"
    }
  },
  "ObjectifyPayload": true
}


FieldTypeDescription
ResponseStringThe response JWT from CentinelAPI that includes the results of the profiling attempt.


{
  "iss": "5b7c5b922f3e733a44320e85",
  "iat": 1535052764,
  "exp": 1535059964,
  "jti": "83840924-a856-4901-ab21-0b61421c0933",
  "aud": "49e56790-a70b-11e8-9354-f715d5987f69",
  "Payload": {
    "ActionCode": "SUCCESS",
    "SessionId": "0_efc85926-b576-4574-ae92-e1dd11132582",
    "ErrorNumber": 0,
    "ErrorDescription": "Success"
  }
}

ReturnUrl Response

The ReturnUrl Response object is the Payload object of a collect response flow.

FieldTypeDescription
ActionCodeString

The status of the collect attempt.

Possible Values:

  • SUCCESS
  • FAILURE
SessionIdStringThe SessionId or McsId that was used for this profiling session. Only returned on successful profiling
ErrorNumberNumberError number indicating the result. 0 is success
ErrorDescriptionStringA text description of the ErrorNumber field.
Option 2 - Using postMessage

The postMessage option uses the browser postMessage API to listen for a specific event type called profile.completed. This event includes a simple status field to notify the merchant if the profiling was successful or not.  An event called profile.completed will notify the listener when the Device Data Collection process completed. 

window.addEventListener("message", (event) => {
            // This domain changes with every environment. This origin value will be the CentinelAPI domain
            // event message sample
            //{MessageType: "profile.completed", SessionId: "0_57f063fd-659a-4779-b45b-9e456fdb7935", Status: true}
            if (event.origin === "https://centinelapisbox.cardinalcommerce.com:50486/") {
                let data = JSON.parse(event.data);
                console.warn('Merchant received a message:', data)

                if (data !== undefined && data.Status) {
                    console.warn('Songbird ran DF successfully')
                    //Use in cmpi_lookup if DFReferenceId not provided in JWT
                    $('#DFReferenceId').val(data.SessionId)
                }
            }
        }, false);


Option 3 - JWT - Card BIN as a POST parameter plus JWT

Option 3 allows you to post the BIN to full Card number as a POST parameter along with the Transactional JWT. When the Device Data Collection URL is invoked, the Transactional JWT and the BIN will be posted over to the URL. This option allows the integrator to pass the Card BIN directly from the web front end to the Device Data Collection URL instead of the JWT.  However, a JWT is still required to authenticate the session. The example below shows the ReturnURL being populated in the Transactional JWT along with a POST parameter.

Integration Steps:

  1. POST Transactional JWT and the Card BIN to the full Card number to the Device Data Collection URL.
  2. Handle the Response from the Device Data Collection URL on the ReturnUrl provided within the Transactional JWT
<iFrame height="1" width="1" style="display: none;">
<form id="collectionForm" name="devicedata" method="POST" action="https://centinelapisbox.cardinalcommerce.com:50486/V1/Cruise/Collect">
<!-- POST Parameters: Bin=First 6 digits to full pan of the payment card number. For merchants unable to utilize the First 6 of the Cardnumber, optional Rest API is
 available to generate a session identifier representing the session. JWT=JWT generated per merchant spec --> 
<input type="hidden" name="Bin" value="410000" />
<input type="hidden" name="JWT" value="JWT generated per merchant spec" />
</form>
<script>window.onload = function() {
  // Auto submit form on page load 
  document.getElementById('collectionForm').submit();
}
</script>
</iFrame>


This example shows the ReturnUrl being populated in the Transactional JWT along with a POST parameter.