UK Gateway

1.0 Setting up the 3DS Javascript

The JavaScript used in the browser flow performs most of the heavy lifting on behalf of the merchants. The JavaScript collects all the device data of the user’s browser, communicates directly with the 3DS Server and handles the user experience of the cardholder during the challenge.

1.1 Add the JavaScript on website

The JavaScript can be added to your site as any other client side script, through a script tag. It is suggested to add the script after all your content before closing the HTML body tag.

The JavaScript URLs depend on the environment used:

1.2 Configure the JavaScript

Cardinal.configure is an optional function that allows to pass configuration object into the JavaScript. Not using this function to your integration will result to use the default configuration options. It is advised to call this function only once per page load and should be called before Cardinal.setup.

Root Level Configuration

Logging

Button

Payment

For example, to control the logging volume from the library, use the Cardinal.configure function, as seen below:

Cardinal.configure example

Cardinal.configure({
    logging: {
        level: "on"
    }
}); 

 Example of using all configuration option possible

{
    timeout: 8000,
    maxRequestRetries: 2,
    button:{
        containerId: 'Cardinal-Payments'
    },
    logging:{
        level: 'on'
    },
    payment:{
        view: 'modal',
        framework: 'bootstrap3',
        displayLoading: false
    }
}  

1.3 Listen for events

This function sets up an event subscription with the JavaScript to trigger a callback function when the event is triggered by the JavaScript. A valid event subscription requires a namespace and a callback function to be run when the event is triggered. Calling this function with the same namespace multiple times will result in callback being triggered multiple times.

The following sections discuss the events that a merchant can listen to.

1.3.1 payments.setupComplete

payments.setupComplete() is an optional event which should be called after the Cardinal.setup() function.

To listen the payments.setupComplete event:

Cardinal.on('payments.setupComplete', function(setupCompleteData){
    // Do something
});

 If an error has happened during the Cardinal.setup() function, then the payments.setupComplete() will not be triggered. If your callback gets executed, you know that the JavaScript is available to run transactions. This function will receive 2 arguments that describe the loaded state of theJavascript and the current session identifier.

The following object is returned back to the merchant on the payments.setupComplete event as the first argument.

Module State

Example of payments.setupComplete data object

{
  "sessionId": "0_4f85c155-6604-4056-8957-7090412af179",
  "modules": [{
    "module": "CCA",
    "loaded": true
  }]
}

1.3.2 payments.validated

payments.validated event is triggered when the transaction has been finished and the control is given back to the merchant page. It includes data on how the transaction attempt ended that should be used in the logic for reviewing the results and decision making, how to proceed with the transaction.

If the payments.validated is successful ("ActionCode": "SUCCESS") then the data needed to proceed with the payment Authorisation ( CAVV, ECIFlag, XID, Enrolled, PAResStatus, SignatureVerification) will be included in the "Payment" object.

To listen the payments.validated event:

Cardinal.on('payments.validated', function(decodedResponseData, responseJWT){
    // Do something
});

 The payments.validated event consists of the Response Data and the Response JWT.

The payments.validated can result into three different cases:

Response Data

At minimum the response data will include a base object as seen below. However, depending on what occurred in the response additional fields may be present.

The payment object for the 3DS transactions is:

Below you some samples of different values returned to the payments.validated event are presented. These JSON objects would be the first argument and the Payload claim of the response JWT where a response JWT was returned.

Successful Response example:

{
   "Validated": true,
    "Payment": {
        "Type": "CCA",
        "ProcessorTransactionId": "uAthLfEYg83iEverTlk0",
        "ExtendedData": {
            "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz+=",
            "ECIFlag": "05",
            "XID": "dUF0aExmRVlnODNpRXZlclRsazA=",
            "Enrolled": "Y",
            "PAResStatus": "Y",
            "SignatureVerification": "Y"
        }
    },
    "ActionCode": "SUCCESS",
    "ErrorNumber": 0,
    "ErrorDescription": "Success"
} 

API Level Error (will include a Response JWT to be validated)

{
    "Validated": false,
    "ErrorNumber": 4000,
    "ErrorDescription": "Validation Error A valid merchant consumer session ID is required.",
    "ActionCode": "ERROR",
    "Payment": {}
}

Service Level Error (will not include a Response JWT)

{
    "Validated": false,
    "ErrorNumber": 1000,
    "ErrorDescription": "Error processing request. We have encountered an unexpected error.",
    "ActionCode": "ERROR",
    "Payment": {}
}

1.4 Initialise JavaScript

To initiate the communication with the server, call the Cardinal.setup() function. All the necessary pre-processing steps should have been completed by the time that the consumer is ready to checkout. Listen for the payments.setupComplete event to get notified when the JavaScript has finished initializing (Section 5.4.1).

1.4.1 Set up the JavaScript

Cardinal.setup function informs the JavaScript what type of event you are planning to complete on the page it is running on and what files it needs to bootstrap to facilitate that event.

Initialization types

Example of Cardinal.setup

Cardinal.setup("init", {
    jwt: document.getElementById("JWTContainer").value
});

 A common way to pass your JWT into the JavaScript is to place its value into a hidden input on page load. Using Cardinal.setup() function you can look for that element and select its value.

Example of placing a JWT into a hidden input

<input type="hidden" id="JWTContainer" value="[Insert your JWT here]" />

1.5 Cardinal Continue

After the Lookup Response is returned, pass the ACSUrl (acs_url), Payload (payload), and TransactionId (transaction_id) 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 Issuer’s URL (acs_url) for authentication.

The syntax for Cardinal.continue:

Cardinal.continue(PAYMENT_BRAND, CONTINUE_DATA, ORDER_OBJECT, NEW_JWT)

Continue Object

Cardinal.continue will only work after the payments.setupComplete event has been triggered. Cardinal.continue is suggested to be run later in the flow if payments.setupComplete is not triggered yet.

Example of Cardinal.continue:

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

1.6 BIN Detection

To successfully complete the 3DS Method, the Issuing bank should be contacted to receive the browser information before the authentication is started. Therefore, the BIN is required to be communicated to the JavaScript before sending the lookup request.

There are two ways to implement the BIN Detection to a merchant’s web application:

1) Field Decorator This implementation is the simplest and recommended approach when the full PAN is available. A merchant may directly start the JavaScript, provide the PAN and allow for payments.setupComplete event to complete. A new attribute to the input field to identify which field it maps to within the Order Object needs to be added. The credit card number is mapped to the AccountNumber field, therefore for the BIN Detection the AccountNumber will be passed to the attribute ‘data-cardinal-field’.

Field Decorator Example

<input type="text" data-cardinal-field="AccountNumber" id="creditCardNumber" name="creditCardNumber" />

 The field decorator will attach an event listener to the element that will update the BIN as the cardholder types it in. The BIN value will be updated automatically if the cardholder changes cards or needs to correct an entry.

2) Event Based

The bin.process event is the recommended event base profiling the merchant uses an card that is stored on file. The merchant will need to provide a minimum of the first 6 (e.g. BIN) up to the full card number of the consumer (e.g. max of 19 digits). The more digits of the card number provided the better chances of matching if there is a corresponding EMV 3DS Method URL.

Bin.process example

Cardinal.trigger("bin.process", '1234567894561237');

1.7 Cardinal.trigger

Cardinal.trigger function triggers an event within Songbird. This is a way to actively send Songbird data instead of waiting passively for events to occur.

Cardinal.trigger syntax

Cardinal.trigger("EVENT_NAME_SPACE", 'DATA');

1.7.1 bin.process

For bin.process event described in BIN Detection.

Cardinal.trigger implementation example

Cardinal.trigger("bin.process", '1234567894561237')
  .then(function(results){
    if(results.Status) {
        // Bin profiling was successful. Some merchants may want to only move forward with CCA if profiling was successful
    } else {
        // Bin profiling failed
    }
  
    // Bin profiling, if this is the card the end user is paying with you may start the CCA flow at this point or send the lookup request
    Cardinal.start('cca', myOrderObject);
  })
  .catch(function(error){
    // An error occurred during profiling
  })

1.7.2 jwt.update

jwt.update is an event to allow the merchant to change the JWT at any point. This event will update the local cached order object within the JavaScript but it will not push anything to the Cardinal infrastructure. This removed the need to pass in a new JWT into an event such as Cardinal.start or Cardinal.continue.

Cardinal.trigger implementation example

Cardinal.trigger('jwt.update', 'my_new_jwt_value');