3DS2 Client SDK

      3DS2 Client SDK


        Article summary

        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.

        Download the library here:

        ClientSdk.js

        Buckaroo3ds.Client.initiateAuthentication function

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

        The initiateAuthentication function has the following parameters:

        NameDescription
        transactionKeyThe transaction key received in the transaction response
        containerThe DOM-element where the 3DS2 iframe should be rendered, us the query selector format for this.
        browserAcceptHeaderThe Accept-header of the client when loading the page.
        optionalDataAn 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.
        optionsAn object containing callback functions.
        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).

        headerheader
        resolvedMethodCompletionIndicatorCallbackThis callback is called when a method completion indicator could be resolved. The methodCompletionIndicator property of the ThreeDsEvent object is only filled in this callback.
        receivedChallengeResultCallbackThis callback is called when a challenge has been completed.
        preAuthenticateSuccessCallbackThis callback is called when the pre-authentication step was performed successfully.
        preAuthenticateFailCallbackThis callback is called when the pre-authentication step has failed.
        authenticateSuccessCallbackThis callback is called when the authentication step was performed successfully.
        authenticateFailCallbackThis callback is called when the authentication step has failed.
        finalizeSuccessCallbackThis callback is called when the finalize step was performed successfully.
        finalizeFailCallbackThis callback is called when the finalize step has failed.

        Was this article helpful?

        What's Next