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).
Table of Contents |
---|
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:
Created a Cardinal Merchant Account for CCA
Documentation for Review
Merchant Requirements
Device Data Collection
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).
Info |
---|
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.
Info |
---|
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. |
Anchor | ||||
---|---|---|---|---|
|
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.
Info |
---|
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. |
Based on the EMVCo requirement, merchants need to display a processing screen (for example, a progress bar or a spinning wheel) during the AReq message processing.
Please ensure that following considerations are taken into account:
1. Display the Processing screen that conveys to the Cardholder that processing is occurring (refer to below illustrations).
2. Include the DS logo for display with or without a white box at the center of the screen unless specifically requested not to include.
3. Not include any other design element or text in the Processing screen.
4. Display the Processing screen for a minimum of two seconds.
Sample Browser Lightbox Processing Screen:
Sample Inline Browser Processing Screen:
Anchor | ||||
---|---|---|---|---|
|
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.
Info |
---|
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> |
Anchor | ||||
---|---|---|---|---|
|
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.
In an event where ReturnUrl field is NOT passed on the StepUp Request, Cardinal will return a postMessage event to indicate the result of challenge. Refer to StepUp Response (postMessage) to review all the events exposed during a StepUp.
StepUp JWT Sample
Code Block | ||
---|---|---|
| ||
{ "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
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
The parent iFrame size must match the challenge window size or the ACSWindowSize sent in the lookup request. Failing to specify the parent iFrame size may result in a poor UX experience. |
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
Code Block | ||
---|---|---|
| ||
<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 | ||||
---|---|---|---|---|
|
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
Code Block |
---|
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 | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
|
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.