Cardknox is now Sola
Learn More
LogoLogo
Contact Us
  • Introduction
  • 🔗API
    • Transaction API
      • Credit Card
      • Check (ACH)
      • EBT
      • Gift Card
      • Fraud
    • Customer and Recurring API
    • Reporting API
    • Account Boarding API
      • Account Boarding Merchant Agreement
      • Account Boarding Swagger UI
    • Code Samples
    • Error Codes
  • 📦SDK
    • .NET SDK
      • Transaction Workflow
    • iOS SDK
      • iOS SDK - Technical Guide
      • Workflow
    • Android SDK
      • Android SDK - Technical Guide
  • 🧰 Cardknox Products
    • 3D Secure 2.0
      • Client-Side Integration
        • Client-Side Integration (Non-iFields)
      • Server-Side Integration
    • Account Updater
    • Batch Processing
    • Browser-Based POS systems (BBPOS)
    • CloudIM Developer Guide
    • Deep Linking
      • Deep Linking Integration for Third-Party Websites
    • EBT Online
    • Gateway Emulators
    • iFields
      • Angular iFields
    • Merchant Portal
      • FAQ
    • Mobile App
    • Split Capture
    • Tap to Phone - Android
    • Partner Portal
    • PaymentSITE
      • QR Codes for PaymentSITE
    • Webhooks
  • 📱Mobile Wallets
    • Apple Pay Hosted Checkout
      • Apple Pay Hosted Checkout Initial Setup
      • Apple Pay Prerequisites
      • Apple Pay Hosted Checkout Objects Reference (Request)
      • Apple Pay Hosted Checkout Objects Reference (Response)
      • Apple Pay iFields Integration
      • Apple Pay Hosted Checkout Sample Code
      • Apple Pay Features
      • Set up Apple Pay Merchant ID with Cardknox
    • Click-To-Pay - Hosted Checkout
      • Click-To-Pay Initial Setup
      • Click-To-Pay Sample Code
      • Click-To-Pay iFields Integration
      • Click-To-Pay Objects Reference (Request)
      • Click-To-Pay Objects Reference (Response)
    • Google Pay Hosted Checkout
      • Google Pay Control Object
      • Google Pay Request Objects
      • Google Pay Response Objects
      • Google Pay Sample Code
      • iFields Integration
      • Google Pay FAQ
  • 🔌Plugins
    • Netsuite
      • NetSuite Features and Demo
    • WooCommerce
    • Magento Plugin
    • RMH (Retail Management Hero)
    • RMS (Retail Management Systems)
  • 📖Articles
    • Frequently Asked Questions
    • How to Build POS Integration Flows
    • Card Present Integration Guide
  • Glossary of Terms
Powered by GitBook
On this page
  • Configuration Properties
  • Methods
  • Implementation Steps

Was this helpful?

Export as PDF
  1. Cardknox Products
  2. 3D Secure 2.0
  3. Client-Side Integration

Client-Side Integration (Non-iFields)

Last updated 7 months ago

Was this helpful?

This is the Non-iFields Client-Side Integration document for 3D Secure 2.0.

For the iFields client-side 3DS 2.0 integration, refer to

Configuration Properties

The javascript object exposes the following properties:

Property

Description

Allowed Values/Comments

configuration.enableConsoleLogging

Can be set by the user to turn console logging on for debugging purposes or off to remove extra console writes. Defaults to true.

true/false

configuration.onVerifyComplete

Should be set by the user - this is a function handler that will be called when a challenge (step-up) is completed (see below for sample function)

name of your javascript function that will handle the transaction completion

referenceId

Set by the internal code, this property will contain the 3DS reference id for the current transaction

Passed to gateway as part of transaction

initializeStatus

Set by the internal code, this property will contain the status of initialization

Passed to gateway as part of transaction

error

Set by the internal code, this will contain any error information relevant to the 3DS process

Passed to gateway as part of transaction

Methods

Method name

Description

Parameters

initialize3DS

To be called on the page load, to set up the environment for processing a 3DS authentication transaction

threeDSEnvironment - string - set to either “prod” or “staging”

profileBin

To be called before submitting the initial transaction

bin - 9 digit card bin

verifyTrans

To be called if the initial transaction response status is “V”, indicating that a challenge/step-up is required for authentication

A javascript object with the following values from the Cardknox gateway response: {xRefNum, xVerifyURL, xVerifyPayload, xInternalID }

Implementation Steps

Import the Library

Add two JS file references to your web page in your page header:

// JS file reference #1:
// ----- Staging:
<script src="https://songbirdstag.cardinalcommerce.com/cardinalcruise/v1/songbird.js" type="text/javascript"></script>
// ----- Production:
<script src="https://songbird.cardinalcommerce.com/cardinalcruise/v1/songbird.js" type="text/javascript"></script>

// JS file reference #2:
<script src="https://cdn.cardknox.com/sdk-3ds/1.0.2110.1401-beta/cardknox-3ds.min.js" type="text/javascript"></script>

Create JavaScript handler for verification

When a 3DS 2.0 step-up authentication flow occurs, you must handle this by sending the verification results to the payment gateway. Create a JavaScript function on your page to do this. The ck3DS object will call this function automatically when a step-up verification completes. The function will receive the verification results as input parameters.

The order of parameters is as shown in the following code sample:

function handle3DSResults(actionCode, xCavv, xEciFlag, 
        xRefNum, xAuthenticateStatus, xSignatureVerification) 
{
    alert('submitting verify form with verification results');
    
    var url = "_some_url_of_your_server_to_handle_the_response_and_post_to_gateway";
    var postData = {
        xRefNum: xRefNum,
        xCavv: xCavv,
        xEci: xEciFlag,
        xAuthenticateStatus: xAuthenticateStatus,
        xSignatureVerification: xSignatureVerification,
        x3dsActionCode: actionCode,
        x3dsError: ck3DS.error
    };
    
    $.ajax({
        method: "POST",
        url: url,
        data: postData
    }).done(function (jsonResp) {
        log(jsonResp);
        if (jsonResp.Status == 'S') {
            // handle success, eg. show receipt
        }
        else {
            // handle error
        }
    })
    .fail(function (xhr, status, err) {
        var errorMessage = xhr.status + ': ' + xhr.statusText;
        // handle failure
    });
}

Configure the 3DS object

In your page load, add the initialization code:

$( document ).ready(function() {
  // set up configuration
  ck3DS.configuration.enableConsoleLogging = true;
  
  // Below can be used to conditionally turn off 3DS handling 
  // ck3DS.configuration.process3DS = true; 
  
  // name of function that was set up in step #2
  ck3DS.configuration.onVerifyComplete = handle3DSResults; 
  
  var environment = "staging"; // supported values: staging, production
  ck3DS.initialize3DS(environment);
});

Add 3DS profiling and submit results with the initial payment request

In the form submit handler, before submitting the payment, add the 3DS values to the data to be sent on to the gateway, using whatever submit mechanism is being used on your page. For example, the code below sets the hidden fields on the page to the corresponding values and then submits the form:

ck3DS.profileBin(_9_DIGIT_CARD_BIN_HERE_)
  .then((binProfilingResult) =>
  {      
      // Set the 3DS response fields 
      $("#x3dsReferenceId").val(ck3DS.referenceId);
      $("#x3dsInitializeStatus").val(ck3DS.initializeStatus);
      $("#x3dsError").val(ck3DS.error);
      var form_data = $("#payment_form").serialize();
      
      $.ajax({
        method: "POST",
        url: url,
        data: form_data
      }).done(function (jsonResp) {          
          // handle response
      })
      .fail(function (xhr, status, err) {
          var errorMessage = xhr.status + ': ' + xhr.statusText;
          // handle failure
      });
  });    

Handle 3DS Challenge

Modify the above code (line 15 in the sample snippet above) to correctly handle the server response. If the response from Cardknox had a status of V / Verify, call the verifyTrans function. The parameters this function needs are returned as part of the gateway response object and should just be passed along:

if (jsonResp.xResult === 'A') {
    // handle approval, eg. show receipt
}
else if (jsonResp.xResult === 'V'){
  ck3DS.verifyTrans(jsonResp);
}
else {
    // handle other responses....
}

When 3DS verification is complete, the onVerifyComplete handler (created in step 2 and "hooked up" in step 3) will be called with the response fields that should be passed to your server.

🧰
iFields