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

1 Prerequisites
- 1.1 Documentation for Review
- 1.2 Merchant Requirements
2 Cardinal Cruise API Steps
3 Flow
4 Implementation of Cardinal Cruise API

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

Merchant Requirements

Device Data Collection
- Option 1 - Data Exchange API plus JWT [Recommended]
- Option 2 - JWT - Card BIN in JWT
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.

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

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.

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)

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.

Sample Browser Lightbox Processing Screen:

Sample Inline Browser Processing Screen:

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.

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

There are 2 ways in which Cardinal can return a response to the merchant:

1. Option 1: Response returned to the ReturnUrl set in merchant StepUp JWT

The payload sent to the ReturnUrl will be URL encoded and Base64 encoded.

The response posted back to the ReturnUrl includes two fields:

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=eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJlMzcxZDAzNy1lMTFlLTRkZWQtOWYwZC1mMGM3OTZjMTc2OWMiLCJhY3NUcmFuc0lEIjoiYjc5MjU1YzItYWRjOC00MmVmLWE2ZDUtZWM1MDEyNDUzYTg3IiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJ0cmFuc1N0YXR1cyI6IlkifQ

2. Option 2: Response returned via postMessage event

Refer to https://cardinaldocs.atlassian.net/wiki/spaces/CC/pages/3146514450 to review all the events exposed as part of the StepUp flow.

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.