The 3DS2 Client SDK is a JavaScript library which makes it possible to perform 3DS2 after a PayEncrypted (or AuhorizeEncrypted) request (for more info on Client-Side Encryption, check the CSE SDK and the Creditcard documentation). The SDK can be used by either referencing the following link: https://checkout.buckaroo.nl/api/3ds2/ClientSdk, or by downloading the library and adding it to your client code.

Currently 3DS2 is only available for Visa, MasterCard, Maestro, VisaElectron, CarteBleue, CarteBancaire, VPAY, Dankort and Nexi.

After performing the PayEncrypted (or AuthorizeEncrypted) action, you will get a response which contains a ThreeDsVersion parameter in the service specific output parameters. When this parameter starts with a 2 (for example "2.1.0"), the Buckaroo3ds.Client.initiateAuthentication function should be called on the client side. Otherwise the consumer should be redirected to the RedirectUrl.

When the initiateAuthentication function is called, a DOM-element should be available in which an iframe may be rendered. This DOM-element should be visible for the consumer, because in the challenge flow, an iframe is rendered where the consumer must perform a challenge at its issuing bank. This iframe may have 5 different sizes which can be set in the challengeWindowSize property of the Buckaroo3ds.ClientRequestClasses.OptionalData object. The possible values are: "Small" or "1" (250 x 400 pixels), "Medium" or "2" (390 x 400 pixels), "LargeHeight" or "3" (500 x 600 pixels), "LargeWidth" or "4" (600 x 400 pixels) and "FullScreen" or "5". The default value of this property is Small. An example on how to use this function is found below.

After the initiateAuthentication function is called, the SDK will take care of the rest. It will request 3DS2 authentication and after the authentication was successful it will finalize (authorize at the acquirer) the transaction. At certain moments during the processing, the callbacks given in the Buckaroo3ds.Client.Options object will be called. When the finalize step was performed, the either the finalizeSuccesCallback or the finalizeFailedCallback will be called with a ThreeDsEvent object which will contain a ReturnUrl in its data, so the consumer may be redirected to this ReturnUrl. A more detailed explanation on the Buckaroo3ds.Client.Options object can be found below.

Buckaroo3ds.Client.initiateAuthentication function

On the right an example is shown on how to use this function.

The initiateAuthentication function has the following parameters:

  • transactionKey: The transaction key received in the transaction response;
  • container: The DOM-element where the 3DS2 iframe should be rendered, us the query selector format for this.
  • browserAcceptHeader: The Accept-header of the client when loading the page.
  • optionalData: An object containing optional data which will be sent in the 3DS2 authenticate request. See the SDK for the content of this object and all possible values.
  • options: An object containing callback functions.
copy
payEncryptedRequestXhr.onload(function() {
	if (payEncryptedRequestXhr.status >= 200 && payEncryptedRequestXhr.status < 400) {
		var response = JSON.parse(payEncryptedRequestXhr.response);
		var threeDsVersion = response.Services[0].Parameters.filter(param => param.Name === "ThreeDsVersion")[0].Value;
		if (response.Status.Code.Code === 791 && threeDsVersion && threeDsVersion[0] === "2") {
			var browserAcceptHeader = document.querySelector("#browserAcceptHeader").value;
			var optionalData = null; // Create a new Buckaroo3ds.ClientRequestClasses.OptionalData object.
			var options = null; // Create a new Buckaroo3ds.Client.Options object.
			Buckaroo3ds.Client.initiateAuthentication(response.Key, "#iframeDiv", browserAcceptHeader, optionalData, options);
		}
	}
});

Buckaroo3ds.Client.Options object

This object can be filled with callback functions which will be triggered on the given events. All callback functions will be fed with a Buckaroo3ds.Client.ThreeDsEvent object, which consists of a fail reason (failReason), some data (data) and a method completion indicator (methodCompletionIndicator).

  • resolvedMethodCompletionIndicatorCallback: This callback is called when a method completion indicator could be resolved. The methodCompletionIndicator property of the ThreeDsEvent object is only filled in this callback.
  • receivedChallengeResultCallback: This callback is called when a challenge has been completed.
  • preAuthenticateSuccessCallback: This callback is called when the pre-authentication step was performed successfully.
  • preAuthenticateFailCallback: This callback is called when the pre-authentication step has failed.
  • authenticateSuccessCallback: This callback is called when the authentication step was performed successfully.
  • authenticateFailCallback: This callback is called when the authentication step has failed.
  • finalizeSuccessCallback: This callback is called when the finalize step was performed successfully.
  • finalizeFailCallback: This callback is called when the finalize step has failed.
copy
function initiate3ds2(transactionKey, browserAcceptHeader) {
    var options = new Buckaroo3ds.Client.Options(null, challengeResultCallback, null, null, authenticateSuccessCallback, null, finalizeCallback, finalizeCallback);
    Buckaroo3ds.Client.initiateAuthentication(transactionKey, "#iframeDiv", browserAcceptHeader, null, options);
}
function authenticateSuccessCallback(event) {
    if (event.data.TransactionStatus === "C") {
        $("#consumer-messages").hide();
        $("#iframeDiv").show();
        setPageHeight();
    }
}
function challengeResultCallback(event) {
    $("#iframeDiv").hide();
    $("#consumer-messages").show();
    setPageHeight();
}
function finalizeCallback(event) {
    var data = JSON.parse(event.data);
    redirect(data.ReturnUrl, true);
}