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.
Table of Contents |
---|
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.
- Option 1 - JWT - Card BIN to full Card Number in JWT
- This option is the recommended approach and allows for the integrator to pass the Card BIN to full Card Number in the JWT
- Option 2 - API - Card BIN to Card Number in API (to BIN Intelligence API)
- 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.
- Option 3 - JWT - Card BIN as a POST parameter plus JWT
- 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.
AnchorDDCOption1 DDCOption1
Option 1 - JWT - Card BIN to full Card Number in JWT
DDCOption1 | |
DDCOption1 |
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:
- Card BIN to full Card Number goes into the Transactional JWT
- POST Transactional JWT to the Device Data Collection URL
- Handle the Response from the Device Data Collection URL on the ReturnUrl provided within the TransactionalJWT
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> |
Info | ||
---|---|---|
| ||
This example shows the ReturnUrl being populated in the Transactional JWT instead of a POST parameter. |
AnchorDDCOption2 DDCOption2
Option 2 - API - Card BIN to Card Number in API (to BIN Intelligence API)
DDCOption2 | |
DDCOption2 |
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:
- Cardinal Cruise Account Credentials
- Connecting to the BIN Intelligence API
- BIN Intelligence Request Field Names (Card BIN to full Card Number goes into the AccountNumber field)
- Handling the BIN Intelligence API Response with ReferenceId
- Generating an Authentication JWT with ReferenceId
- Initiating the DeviceDataCollectionUrl
- Handle the Response from the Device Data Collection URL
Connecting to the BIN Intelligence API
Endpoints for Staging and Production
Staging: https://geostag.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/Load
Production: https://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:
| 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 |
BINs | This 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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Timestamp: 2019-01-14T20:42:13.216Z Milliseconds Since Epoch: 1547498533216 TransactionId: 07643622 ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44 Signature: wpGKFbhcBl+8JLVXGP0QqBooK6dtLBv9bYtI15NXL1U= |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "Signature":"2ejC+DdvSVyRD2PnskTGw4G7rg0CqwfZNAqniChWjp0=", "Timestamp":"2018-09-19T19:04:05.104Z", "TransactionId" : "132456789", "Identifier" : "aalkjdfalkdjfaslkdj", "OrgUnitId" : "564cdcbcb9f63f0c48d6387f", "Algorithm" : "SHA-256", "Payload" : { "BINs" : ["4100000000000000000"] } } |
Info | ||
---|---|---|
| ||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> |
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "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 } |
Field | Type | Description |
---|---|---|
Response | String | The response JWT from CentinelAPI that includes the results of the profiling attempt. |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "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.
Field | Type | Description |
---|---|---|
ActionCode | String | The status of the collect attempt. Possible Values:
|
SessionId | String | The SessionId or McsId that was used for this profiling session. Only returned on successful profiling |
ErrorNumber | Number | Error number indicating the result. 0 is success |
ErrorDescription | String | A 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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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); |
AnchorDDCOption3 DDCOption3
Option 3 - JWT - Card BIN as a POST parameter plus JWT
DDCOption3 | |
DDCOption3 |
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:
- POST Transactional JWT and the Card BIN to the full Card number to the Device Data Collection URL.
- Handle the Response from the Device Data Collection URL on the ReturnUrl provided within the Transactional JWT
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> |
Info | ||
---|---|---|
| ||
This example shows the ReturnUrl being populated in the Transactional JWT along with a POST parameter. |