Versions Compared

Old Version 62

changes.mady.by.user Chris Bohatka

Saved on

compared with

New Version Current

changes.mady.by.user Suyash Somani

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Removing Amount & Currency validation statement regarding EMV 3DS only

Status
colourBlue
titlemodal
 
Status
colourYellow
titleauthentication
 
Status
colourRed
titleCCA

The Cardinal Cruise Standard integration for CCA is purely a JavaScript approach that is all encompassing. When enabling this approach for CCA, this integration will handle the device data collection, initiating the transaction for CCA, presenting the authentication session if required, and returning the results of authentication once completed. This is a simple and easy approach that is the recommended integration approach for CCA. For more information on which integration method to choose, please review the Consumer Authentication section for more details.

Info

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


Table of Contents

Prerequisites

You must have the following to complete a CCA integration:


Info
titleTLS 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 Standard Steps

The following steps outline the requirements for integrating the Consumer Authentication into your baseline Cardinal Cruise JS integration, which was completed by following the steps in the Getting Started 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 

Status
colourRed
titleCCA

Step 7: Order Object Requirements 
Status
colourRed
titleCCA

Step 8: Start Cardinal Consumer Authentication 
Status
colourRed
titleCCA

Step 9: Handling the CCA Response 
Status
colourRed
titleCCA

Step 10: JWT Validation

Flow

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

View file
nameDocumentation Flows - Cruise Standard.pdf
height150

Implementation of Cardinal Cruise Standard

The below steps are required to enable CCA with your Cardinal Cruise JS Standard integration. We included a section for building the Order Object, Start CCA, and listening for payments.validated in addition to the already completed Getting Started steps.

Step 7:  Order Object Requirements

The following fields are required to be present within the order object sent to Cardinal for a CCA transaction. These values must be passed in on the Cardinal.start() event shown in the next section at the latest. Here is a JSON example.

Step 8:  Start Cardinal Consumer Authentication

Cardinal Consumer Authentication is initiated by the merchant, typically when the customer clicks 'Place Order" or 'Submit Order' button. Instead of getting a card authorization, you need to initiate the Cardinal.start() before authorization.

Note
titleStart not working?

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


Code Block
Cardinal.start("cca", data);

In this example, the second argument of data is a Request Order Object. You can construct this object ahead of time or pass it directly, as shown here:

Code Block
Cardinal.start("cca", {
  OrderDetails: {
    OrderNumber: "1234567890"
  },
  Consumer: {
    Account: {
    AccountNumber: "XXXXXXXXXXXX1234",
    ExpirationMonth: "01",
    ExpirationYear: "2099"
  }
}
  ...
});


Info
titleWatch for Splatted Values

AccountNumber in the above example is splatted only for security in this document. You must pass the full AccountNumber. The Order Object used in the example was shortened for brevity.

Step 9:  Handling the CCA Response

Excerpt

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


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

Code Block
languagejs
titleExample Decoded Response JWT
linenumberstrue
{
  "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"
  }
}

NOTE: It is highly recommended that you verify the Amount and Currency values within the response prior to sending to authorization. The values returned on payments.validated will represent the values used during authentication; these values should match the values at the time of authorization. Currently, Amount and Currency will only be returned on EMV 3DS transactions. Additional work to populate these values in all 3DS versions is underway.

Step 10: 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. 

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


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


Excerpt

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:

Code Block
languagejs
titleRaw JWT Sample
linenumberstrue
{
  "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:

Code Block
languagejs
titleStringified JWT Sample
linenumberstrue
{
  "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\"}"
}



Info
iconfalse
titleNow 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.