Cardinal Cruise API

Welcome to the Cardinal Cruise API Documentation! Here you will find resources and details on how to get up and running with Cardinal Cruise API as fast as possible.

Cardinal Cruise API is our non-JavaScript implementation that supports 3DS 1.0 and EMV 3DS. This integration allows the merchant to use an iframe to complete the device profiling and 3DS authentication requirements without the need for including 3rd party JavaScript directly on your site. This implementation does still require the use of JavaScript on the page. The integration is divided into two components. The first is for device data collection and the second is to initiate the authentication session (Frictionless or Challenge flows).




Prerequisites

To complete a Cardinal Cruise API integration you will need to have the following components completed. These particular steps are not covered in this guide. Please refer to the below links for more documentation details on how to complete these steps:

Documentation for Review
Merchant Requirements
  1. Device Data Collection

  2. Authentication Steps:

    • Centinel Core - Lookup Request/Response

    • Create an authentication session using the StepUpUrl

    • Centinel Core - Authenticate Request/Response

Cardinal Cruise API Steps

The following steps outline the requirements for integrating Cardinal Cruise API into your website.

Step 1: Choose your Device Data Collection Option

Step 2: Start Consumer Authentication with Lookup Request
Step 3: Handling the Lookup Response
Step 4: Continue with Consumer Authentication
Step 5: Handling the Consumer Authentication Response
Step 6: Run Authenticate Request to Receive Authentication Values
Step 7: Process Authorization to Processor

Flow

The below document outlines the transactional flow to complete a Cardinal Cruise API transaction.

Documentation Flows - Cruise API.pdf


Implementation of Cardinal Cruise API

The below steps are required to enable Cardinal Consumer Authentication using our Cardinal Cruise API integration. We included sections in addition that include Device Data Collection Options and running the Centinel Core messages for the Lookup, Continuing with CCA, and processing the Authenticate Request.  

Step 1: Choose your Device Data Collection Option

By choosing one of the Device Data Collection option, Cardinal is able to collect the EMV 3DS required browser data elements in order to make the 3DS 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). 

Note

The Method URL is a concept in the EMV 3DS protocol that allows an 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.

DFReferenceId / ReferenceId

When integrating Cardinal Cruise API integration method for CCA, it is required to populate the DFReferenceId in the cmpi_lookup request. In order to populate this ID correctly, these are the options compared to which Device Data Collection Option you have chosen.  

Option 1: You can subscribe to the payments.setupComplete callback function and pull the sessionId from the response and use that as your DFReferenceId in the cmpi_lookup request. Note, you will not need to add or populate the ReferenceId claim when generating the JWT.

Option 2: You can generate your own value, add this to the ReferenceId claim when the JWT is generated and pass the same value as your DFReferenceId in the cmpi_lookup request.

The DFReferenceId and the ReferenceId fields are 2 different names for the same value. Make sure to pass the same unique Id in both fields.

Step 2: Start Consumer Authentication with Lookup Request 

CCA is initiated by the merchant, typically when the customer clicks 'Place Order" or 'Submit Order' button. Instead of getting a card authorization, you will need to initiate the cmpi_lookup before authorization to our Cardinal Centinel platform. This API call is a backend server-to-server message that will be used to start the CCA transaction.

Please follow the Getting Started and Lookup Request/Response sections for completing your backend integration.

Getting Started

Lookup Request (cmpi_lookup)

Note

The DFReferenceId is required in the cmpi_lookup request. Merchants must pass a unique value of DFReferenceId on each Lookup request.



Device Data Collection must be triggered for each call of cmpi_lookup. This must be done even if the card number has not changed. This is due to EMV 3DS ACS Method URL data which is only valid for 1 transaction attempt. This data must be recollected by the ACS on each call to the ACS for authentication.



Step 3: Handling the Lookup Response 

The Lookup Response may return back a StepUpUrl, Payload, ACSUrl and TransactionId, when these fields are populated, you can use these fields to determine if you need to present the authentication session to the consumer. 

If you need to present the authentication session, then continue with CCA in Step 4 - Continue with Consumer Authentication.  When there is a frictionless response returned, which means no step up, then the StepUpUrl, Payload, and ACSUrl will not be populated. 

NOTE: If a Challenge is requested by the issuer, you must continue to Step 4 within 30 seconds of receiving the Lookup Response. If the StepUp does not occur within this window you may receive an error or an authentication failure and a new authentication request must be created before proceeding.



There is a new field and value returned called <StepUpUrl> in order to successfully Continue with Consumer Authentication.  The StepUpUrl will manage the user interaction with the ACS as well as 3DS version compatibility for 3DS 1.0 and all EMV 3DS versions.

You may want to consult with your Activation Manager to assist with handling the other Lookup Response uses cases for authentication.

There needs to be a Merchant Level account configuration to enable the Cardinal Cruise API integration in order to return <StepUpUrl>



Step 4: Continue with Consumer Authentication

After the Lookup Response is returned, you will then need to generate a JSON Web Token (JWT) with the following values: ACSUrlPayloadTransactionId, your ReturnUrl and (Cardinal generated) ReferenceId. The ReferenceId is the same value that you had previously passed as DFReferenceId on the Lookup Request. 

When adding these values to the JWT, you will securely sign them with a secret key provided during the onboarding process. 

StepUp JWT Sample
1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "jti": "4595beb0-a4a9-11e8-8fd8-bdf5ff435fec", "iat": 1534790755, "iss": "Midas-XXXXX-Key", "OrgUnitId": "59c2745f2f3e7357b4aa516a", "ReturnUrl": "http://localhost:8189/cart/enterprise/term", "ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15", "Payload": { "ACSUrl": "https://merchantacsdev.cardinalabs.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "Payload": "eNpVUV1PwjAUfe+vIMRX13ZAMsmlCTKJmIAwBzw3XeMaWTe6TfHf25ZNtE/3nNv7cc6FNDdSxm9StEYyWMu65u9yoLLZsE7W2+NiV+7MkzpcZJ7qlgwZbOeJPDP4lKZWpWY0IEEIuIfItjAi57phwMX5cbVh1D3AHUJQSLOKr6xPXDECzQvJ1irj9X36VcZl85oD9iQCUba6Md8sGhPAPUDQmhPLm6aaYtfFj61VIwNRFoBdEgG+7bNtXVRbmReVMUFfNvtlFu+PD4n4OFQHnZ/4MmmzdD4D7H4gyHgjWUhoRKKQDGg0HU+mI6vW8wh44TZhd3QSELtXBxFUbtD8iujEpf4yVk1rjNSil9MjBPJSlVraP3bGb2w13DZfPDtfRWMdG9HQ2+qBr1XWlJCQkS9W3iHsCnB3M9yd10b/zv4DGhKoaw==", "TransactionId": "sRMPWCQoQrEiVxehTnu0" }, "ObjectifyPayload": true }

Once you have the StepUp JWT, you will need to pass that to the web front-end and create an iFrame to POST the StepUp JWT to the StepUpUrl that was returned on the Lookup Response. The size of the iFrame is in your control, and can be tailored to your current checkout experience. The Cruise API Step Up will acknowledge this size and look to fill both the height and width completely. Please keep in mind the following guidelines for Step Up frame sizing:

  • In 3DS 1.0.2, most issuers have designed content around a standard 400x400 pixel size

  • In EMV 3DS, issuers have designed content around the following 4 available challenge window sizes: 250x400, 390x400, 500x600, 600x400

    • You can help inform the issuer of your preferred size by using the ACSWindowSize property on the Lookup Request

We recommend using the ThreeDSVersion property on the Lookup Response to help identify the sizing of your iFrame.

Alongside the JWT, you may also opt to post another field with a name of MD. The MD field allows you to pass any data specific to your checkout session and have it echoed back to you on your ReturnUrl. For example, you may utilize this to reference your SessionId related to the consumer, allowing you to maintain the consumers experience pre- and post-authentication. Any value provided in this field must be URL encoded.

NOTE: it is not recommended to deviate from iFrame usage; performing a full page redirect may be technically possible, though it is not an officially supported method of render.

POST to StepUpUrl Example
1 2 3 4 5 6 <iFrame height="400" width="390"> <form name="stepup" method="POST" action="https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp"> <input type="hidden" name="JWT" value="JWT generated by merchant per spec" /> <input type="hidden" name="MD" value="ABC123XYZ456" /> </form> </iFrame>

Step Up Loaded (Optional)

This event occurs during the Step Up flow, following the onload event within the ACS page. The stepUp.acsRedirection message provides insight into the proper redirect & loading of the ACS content. This event is intended to confirm the redirect, though is not representative of a successfully rendered ACS challenge. Cardinal is unable to programmatically view or process the contents of the ACS page due to the security policies utilized in a 3-D Secure challenge. This is simply intended as a notification that the Step Up page has properly rendered and submitted to the ACS. While unlikely, it's important to know that it is possible this event can be triggered even if the ACS has rendered an error page.

NOTE: Use of this event requires a configuration to be enabled on your account. If you would like to take advantage of this notification, please work with your account manager to enable the Enable Step Up PostMessage configuration. 



Field

Type

Value

Description

Field

Type

Value

Description

MessageType

String

stepUp.acsRedirection

The message type for this object

TransactionId

String



The Core transactionId the event is in reference to. This value is first returned on the cmpi_lookup





PostMessage Consumption
1 2 3 4 {   "MessageType": "stepUp.acsRedirection",   "TransactionId": "Wan8wbhnN45SmHTT2Yg0" }



Example Integration

The below is a sample of how this event can be listened to and processed.



Sample Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 /**  *  The origin value will change with environments  *    - STAG: https://centinelapistag.cardinalcommerce.com  *    - PROD: https://centinelapi.cardinalcommerce.com  **/ let cruiseApiOrigin = 'https://centinelapistag.cardinalcommerce.com'   /**  * NOTE: This event binding will not work in older IE browsers.  * You will need to also implement attachEvent if you need to support older IE browsers.  * https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#legacy_internet_explorer_and_attachevent  **/ window.addEventListener('message', (evnt) => {   try {     // Filter postMessage events by origin     if (evnt.origin === cruiseApiOrigin) {       // CruiseAPI events are stringified JSON objects to ensure backwards compatibility with older browsers       var data = JSON.parse(evnt.data)       if (data !== undefined && data.MessageType !== undefined && data.MessageType === 'stepUp.acsRedirection') {         // Do merchant logic       }     }   } catch (e) {     console.error('failed to parse CruiseAPI postMessage event', e)   } }, false)



Step 5: Handling the Consumer Authentication response

After the Consumer interacts with the Issuer's ACS, it's important to properly handle getting the session back.  This is done via the ReturnUrl set in the StepUp JWT that the merchant set.  The payload sent to the ReturnUrl will be URL encoded and Base64 encoded. 

The response posted back to the ReturnUrl will have two fields:  TransactionId and Response. 

TransactionId - will be the Cardinal Transaction Id that is required when making the next API called, cmpi_authenticate request. 

Response - is the payload returned back from the Issue ACS, such as the CRes in 2.0 or the PARes in 1.0.  This value is optional to be sent on the cmpi_authenticate request. 

POST to ReturnUrl Example
1 TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=ABC123XYZ456&Response=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1YjdlMmMxNC0xYTUzLTRlN2EtODNmMS1kMGVhMWVjMjM5MDEiLCJhY3NUcmFuc0lEIjoiZDk3NmNiNWUtYzlmZC00NDc1LWI3ZGMtMDcwNWUzNThlMjFjIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0



Step 6: Run Authenticate Request to receive authentication values

After the authentication session is complete, you will need to make the second API call, called the cmpi_authenticate request.  This API request will allow you to pull back the results of authentication as well as the authentication values required to be passed in authorization.  At a minimum, all you need is the TransactionId sent to your ReturnUrl in order to make the cmpi_authenticate request.  Or, you can pass the TransactionId and the Response in the PAResPayload field on the authenticate request (Some existing implementations may prefer sending in the PAResPayload field to keep existing compatibility with their system).  



Please follow the Authenticate Request/Response sections for completing your backend integration.

Authenticate Request (cmpi_authenticate)

Step 7: Process authorization to Processor

After processing the cmpi_authenticate request, on the response you will need to take the results of authentication and send them on your authorization request for processing.  Please consult and refer to your gateway or processor implementation guides for how to pass 3DS data elements in authorization.