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

• Lookup Request (cmpi_lookup)

• Lookup Response (cmpi_lookup)

Merchant Requirements

1. Device Data Collection

   • Option 1 - Data Exchange API plus JWT [Recommended]

   • Option 2 - JWT - Card BIN to full Card Number in 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 - Data Exchange API plus JWT

• Option 2 - JWT - Card BIN to full Card Number in 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.

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.  

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>

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.

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 StepUp Response (postMessage) to review all the events exposed as part of the StepUp flow.

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.