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:

• Cardinal Cruise Account Credentials

• Created a Cardinal Merchant Account for CCA

Documentation for Review

• JWT Creation

  • For Device Data Collection - we recommend using the Authentication Request JWT for this flow 

  • For POST to the StepUpUrl - we recommend using the Transactional Request JWT for this flow

• Centinel Core cmpi_lookup

• Centinel Core cmpi_authenticate

Merchant Requirements

1. Device Data Collection

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

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

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

   • Option 4 - Data Exchange API plus JWT

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

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

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

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

• Option 4 - Data Exchange API plus JWT

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). 

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.

Anchor
Step2 Step2

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)

Anchor

Step3

Step3

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. 

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.

Anchor

Step4

Step4

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: ACSUrl, Payload, TransactionId,

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

{
  "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

<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. 

PostMessage Consumption

{
  "MessageType": "stepUp.acsRedirection",
  "TransactionId": "Wan8wbhnN45SmHTT2Yg0"
}

Example Integration

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

Sample Code

/**
 *  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)

Anchor

Step5

Step5

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

TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=ABC123XYZ456&Response=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1YjdlMmMxNC0xYTUzLTRlN2EtODNmMS1kMGVhMWVjMjM5MDEiLCJhY3NUcmFuc0lEIjoiZDk3NmNiNWUtYzlmZC00NDc1LWI3ZGMtMDcwNWUzNThlMjFjIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0

Anchor

Step6

Step6

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)

Anchor

Step7

Step7

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.