Cardinal Cruise Hybrid

MODAL AUTHENTICATIONCCA

The Cardinal Cruise JS Hybrid integration decouples the integration to allow a merchant more flexibility and control based on the number of their systems involved. The Cardinal Cruise JS Hybrid integration will use Songbird.js for device data collection, it will require a back-end server-to-server API call to initiate the transaction, if an authentication session is required, then feed the API results into Songbird.js for rendering the authentication session.

This approach is typically recommended for customers who have already integrated to our API calls and want to upgrade to our Cardinal Cruise solution, have different layers in their payment processing infrastructure, or uses tokenization on the front-end.  For more information on which integration method to choose, please review the Consumer Authentication section for more details. 

As a reminder, either the Cardinal Cruise JS Standard, or Hybrid methods are required in order to support EMVCo 2.0 protocols. We strongly recommend you prepare yourself as soon as possible. 

This guide assumes you have completed the Getting Started With Cardinal Centinel section, which is the baseline integration with Songbird.js. If you have already added other payment brands, some steps may already be completed.

Prerequisites

You must have the following to complete a CCA integration:


TLS Global Mandate

It is important to note that the Cardinal Cruise integration of Javascript, specifically Songbird.js, uses TLS 1.2 cipher suites and protocols and above. If you are currently using a deprecated TLS cipher suite and protocol (Ie: TLS 1.0 or 1.1) you will be required to upgrade to the latest and approved TLS 1.2 cipher suites and protocols. You can find the approved cipher suite list here.

Cardinal Cruise Hybrid Steps

The following steps outline the requirements for integrating CCA into your baseline Cardinal Cruise integration, which was completed by following the steps in the Getting Started With Cardinal Centinel section.

Step 1: JWT Creation
Step 2: Include the Script
Step 3: Configure It
Step 4: Listen for Events
Step 5: Initialize It
Step 6: Include BIN Detection CCA
Step 7: Start Cardinal Consumer Authentication with Lookup Request CCA
Step 8: Handling the Lookup Response CCA
Step 9: Continue with CCA CCA
Step 10: Handling the CCA Response CCA
Step 11: JWT Validation

Flow

The below document outlines the transactional flow to complete a CCA hybrid transaction.

Implementation of Cardinal Cruise Hybrid

The below steps are required to enable CCA with your Cardinal Cruise Hybrid integration. We included sections in addition to Getting Started With Cardinal Centinel for including BIN Detection, running the Lookup Request & Response, Continuing with CCA and listening & processing the response.

Tip

Cardinal Cruise JS Hybrid integration allows for more flexibility when initiating CCA. As an integrator, it is required to run Steps 1 through Step 5 prior to initiating the cmpi_lookup request. However, you have the option to run Steps 1 through Steps 5 on a page prior to where the cmpi_lookup is initiated. This can be leveraged as a way to run the required device data collection and allow enough time to complete.

DFReferenceId / ReferenceId

When integrating Cardinal Cruise Hybrid method for CCA, it is required to populate the DFReferenceId in the cmpi_lookup request. In order to populate this ID correctly, there are two options available.

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 7: Start Cardinal 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. 

BIN Detection 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 3DS 2.0 ACS MethodURL 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 8: Handling the Lookup Response 

The Lookup Response will return back an ACSUrl and Payload field, 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 9.

IMPORTANT


NOTE: If a Challenge is requested by the issuer, you must continue to Step 9 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.


Note

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


Step 9: Continue with Consumer Authentication

After the Lookup Response is returned, take the ACSUrl, Payload, and TransactionId and include them in the Cardinal.continue function in order to proceed with the authentication session.

The Cardinal.continue will display a modal window and automatically post the consumer's session over to the acs url for authentication.  

Order object in the below example has been shortened for brevity.

Cardinal.continue Example
Cardinal.continue('cca',
{
    "AcsUrl":"https://testcustomer34.cardinalcommerce.com/merchantacsfrontend/pareq.jsp?vaa=b&gold=AAAAAAAA...AAAAAAA",
    "Payload":"eNpVUk1zgjAQvedXME7PJEFBVdKt1CECeDkVCk2PcfcnNjv8Kr+7tx4nlbGOcz/se6G1uMENPTPeeIz1G37WGEUth7YnpO21TfTvF3wDCBqspQ=="
},
{
    "OrderDetails":{
        "TransactionId" :"123456abc"
        // Add the rest of the Order object
    }
});

Continue not working?

Cardinal.continue will only work after the payments.setupComplete event has been triggered. Try running Cardinal.continue later in your flow if payments.setupComplete has not triggered yet.


Looking for more on Cardinal.continue?

Refer to the cardinal.Continue section for more information.

Step 10: Handling the CCA Response

Songbird.js will handle all the user interactions up until CCA has returned back the authentication result. The next step in the integration is to add logic to your payements.validated event to handle specific return values for CCA.  The field ActionCode should be used as the primary transaction status indicator. Below are the possible values for ActionCode and what they indicate.

ValueDescription
SUCCESSAuthentication was completed successfully. You will have a CAVV, ECIFlag, and XID to send during authorization.
NOACTIONAuthentication was not applicable, but no service level errors were encountered. When the ErrorNumber is 0, generally this means you may move on to authorization, but be aware the transaction may not be eligible for liability shift.
FAILUREAuthentication resulted in a failure, this includes a the end user failing authentication.
ERRORAn error was encountered. Refer to ErrorNumber and ErrorDescription for more details on the error. If a Payment object is present you may have additional details in the ReasonCode and ReasonDescription fields within the Payment object.

Looking for CCA response objects?

Refer to the response objects section for information on what the CCA Payment object looks like.

The below example is what you should expect the response JWT to contain on a successful CCA transaction.

Example Decoded Response JWT
{
    "iss": "MidasNoDVKey",
    "iat": 1496955266,
    "exp": 1496962466,
    "jti": "b75eb632-4196-4330-b55f-41669b4938f5",
    "ConsumerSessionId": "88cac5a7-cfd4-467e-9f1c-5874407e44a4",
    "ReferenceId": "88cac5a7-cfd4-467e-9f1c-5874407e44a4",
    "Payload": {
        "Validated": true,
        "Payment": {
            "Type": "CCA",
            "ProcessorTransactionId": "gNs7EBbClOnmQORKDBt0",
            "ExtendedData": {
                "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz+=",
                "ECIFlag": "05",
                "XID": "Z05zN0VCYkNsT25tUU9SS0RCdDA=",
                "Enrolled": "Y",
                "PAResStatus": "Y",
                "SignatureVerification": "Y"
            }
        },
        "ActionCode": "SUCCESS",
        "ErrorNumber": 0,
        "ErrorDescription": "Success"
    }
}

Alternative Option for Handling the CCA Response

Another option that is available, is to only take the ProcessorTransactionId from the payments.validated response and include that on a backend call to Cardinal Centinel called the cmpi_authenticate request.  Some clients may find this helpful if they have already integrated the Lookup & Authenticate message pair.  

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

Getting Started

Authenticate Request (cmpi_authenticate)

An additional Cardinal Centinel configuration is available to suppress the 3-D Secure values and only populate the ProcessorTransactionId field.


Now you are ready to test your Consumer Authentication integration

Please refer to the following CCA Test Cases

Step 11: JWT Validation

Once the response JWT is received in the payments.validated event, you will need to send the response JWT to your backend to verify and extract the results. We recommend that any values sent to 3rd parties are sourced from the response JWT after it has been properly validated. 

Security Warning

JWT validation should only ever be done on the server side for security reasons. Doing JWT validation on the front end is not an acceptable flow.

Looking for more information?

For more in depth information on JWT validation including code samples in a few languages, check out the JWT Validation page.

Please note that each Claim key is case sensitive.

ClaimDescription
audMerchant jti Id - This is the 'jti' field from your request JWT echoed back. This field allows you to match up your request JWT with Cardinals response JWT.
jtiJWT Id - A unique identifier for this response JWT. This value is generated by Cardinal.
iatIssued At Time - This is a timestamp of when the JWT was created.
issIssuer - The request JWT's iss field echoed back.
ConsumerSessionIdThe unique session Id for the current user.
PayloadThe response object for your request. This field will contain any actual state information on the transaction. This is the decoded data object that is passed into the payments.validated event as the first argument.

JWT Payload Example

Below is an example of the JSON content of a basic response JWT Payload where we are passing an object within the Payload claim:

Raw JWT Sample
{
  "iss": "5b7eb7072f3e7305c029cd39",
  "iat": 1576870062,
  "exp": 1576877262,
  "jti": "0316f090-17af-4c91-b840-94a44fac198c",
  "ConsumerSessionId": "0_00b447b6-9072-4c21-9c7f-09a0d535fc6f",
  "ReferenceId": "0_00b447b6-9072-4c21-9c7f-09a0d535fc6f",
  "aud": "c56797a0-235e-11ea-96b5-9b6c28b8308b",
  "Payload": {
    "Validated": true,
    "Payment": {
      "Type": "CCA",
      "ProcessorTransactionId": "Mbmr4329wVoH43M3w7a0",
      "ExtendedData": {
        "Amount": "1500",
        "CAVV": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
        "CurrencyCode": "840",
        "ECIFlag": "05",
        "ThreeDSVersion": "2.1.0",
        "PAResStatus": "Y",
        "SignatureVerification": "Y"
      }
    },
    "ActionCode": "SUCCESS",
    "ErrorNumber": 0,
    "ErrorDescription": "Success"
  }
}

Below is an example of the JSON content of a basic response JWT Payload where we are passing a string within the Payload claim. This would occur when the request JWT included a ObjectifyPayload flag set to false:

Stringified JWT Sample
{
  "iss": "Midas-TwoDotOh-Key",
  "iat": 1576870531,
  "exp": 1576877731,
  "jti": "90ecd237-dbfe-447e-a46b-2aa5301d0d5e",
  "ConsumerSessionId": "0_f7b7bce8-dd33-429a-97e4-619595bd27a9",
  "ReferenceId": "0_f7b7bce8-dd33-429a-97e4-619595bd27a9",
  "aud": "8bce4d80-235f-11ea-96b5-9b6c28b8308b",
  "Payload": "{\"Validated\":true,\"Payment\":{\"Type\":\"CCA\",\"ProcessorTransactionId\":\"2VbZqSYOixT20IfxLih0\",\"ExtendedData\":{\"Amount\":\"1500\",\"CAVV\":\"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA\\u003d\",\"CurrencyCode\":\"840\",\"ECIFlag\":\"05\",\"ACSTransactionId\":\"94fa1daf-0d59-45fe-96b3-fa1bc37c7387\",\"DSTransactionId\":\"6373816e-d86a-4e20-b797-79429ad3c92e\",\"ThreeDSServerTransactionId\":\"b0ab6fa5-2ef6-4324-acdf-83d74fa32f9d\",\"ThreeDSVersion\":\"2.1.0\",\"Enrolled\":\"Y\",\"PAResStatus\":\"Y\",\"SignatureVerification\":\"Y\"}},\"ActionCode\":\"SUCCESS\",\"ErrorNumber\":0,\"ErrorDescription\":\"Success\"}"
}

Now you are ready to test your Consumer Authentication integration

Please refer to the following CCA Test Cases

You can begin testing transactions after you have completed the above steps for integrating Cardinal Cruise Standard into your merchant front end environment.