configure()

Configuration method for initializing the API. Please note this method should be called only once for the page load. After calling this method, API will provide configuration values as member variables.

Default wsVersion in the absence of a user provided configuration: 57

Default userLanguage in the absence of a user provided configuration: en-US

Usage

ThreeDS.configure(threedsConfig)

Example


ThreeDS.configure({
    merchantId: "TESTMERCHANT",
    sessionId: "SESSION0002899787259G30902270H6",
    containerId: "ABC",
    callback: function() {
        if (ThreeDS.isConfigured())
            console.log("Done with configure");
    },
    configuration: {
        userLanguage: "en-US",
        wsVersion: 57
    }
});

threedsConfig Object

(COMPULSORY)

Configuration values

merchantId String

(COMPULSORY)

Merchant Id

sessionId String

(COMPULSORY)

Hosted Session Id created for this session

containerId String

The <div> id in your html where the API will inject a hidden iframe.

callback Function

(COMPULSORY)

A function that will be invoked once the API has been initialized.

configuration JSON

(COMPULSORY)

JSON value supporting data elements like userLanguage, REST API version (wsVersion)

userLanguage String

A language identifier or IETF language tag to control the language of the payment page displayed to the payer. For example, “en_US”, es, “fr-CA”. By default, the language is “en_US”.

wsVersion Number

(COMPULSORY)

The Web Services API version that you submitted the request in.

Return Value

None

isConfigured()

Convenience method to check if the API has been configured successfully

Usage

ThreeDS.isConfigured()

Example

ThreeDS.isConfigured();

Arguments

None

Return Value

result Boolean

A {boolean} value determining if the ThreeDS API has been configured correctly.

onEvent()

Method to subscribe for event changes. Subscribing to the events will enable the integration code to listen for state changes during the payment flows. The data argument of the callback will provide the ThreeDS method that was used to initiate the payment.

Usage

ThreeDS.onEvent(event, callback)

Example

ThreeDS.onEvent("EVENT_BEFORE_INITIATE_AUTHENTICATION", function (data) {
    //The data argument of the callback will provide the ThreeDS method that was used to initiate the payment
});

Arguments

event Enumeration COMPULSORY

Event to subscribe to. See supported events list below.

callback Function COMPULSORY

The callback function

Events Names Constants

Here is the list of events currently supported by the ThreeDS API:

EVENT_BEFORE_INITIATE_AUTHENTICATION
EVENT_AFTER_INITIATE_AUTHENTICATION
EVENT_BEFORE_AUTHENTICATE_PAYER
EVENT_AFTER_AUTHENTICATE_PAYER

Return Value

None

initiateAuthentication()

Authentication for the arguments passed. This method will call INITIATE_AUTHENTICATION REST API and returns the raw response in data.response field.

Usage

ThreeDS.initiateAuthentication(orderId, transactionId, callback, optionalParams)

Example

var optionalParams = {
    sourceOfFunds: {
        type: "CARD"
    },
    order: {
        walletProvider: "MASTERPASS_ONLINE"
    }
};

ThreeDS.initiateAuthentication("1234", "XYZ", function (data) {
    if (data && data.error) {
        var error = data.error;
        // Something bad happened, the error value will match what is returned by the Authentication API
        console.error("error.code : ", error.code);
        console.error("error.msg : ", error.msg);
        console.error("error.result : ", error.result);
        console.error("error.status : ", error.status);
    }
    else {
        console.log("After Initiate 3DS ", data);

        //data.response will contain information like gatewayRecommendation, authentication version, etc.
        console.log("REST API raw response ", data.restApiResponse);
        console.log("Correlation Id", data.correlationId);
        console.log("Gateway Recommendation", data.gatewayRecommendation);
        console.log("HTML Redirect Code", data.htmlRedirectCode);
        console.log("Authentication Version", data.authenticationVersion);

        switch (data.gatewayRecommendation) {
            case "PROCEED":
                authenticatePayer(); //merchant's method
                break;
            case "DO_NOT_PROCEED":
                tryOtherPayment(); //merchant's method, you can offer the payer the option to try another payment method.
                break;
        }
    }
}, optionalParams);

Compulsory Arguments

orderId String

(COMPULSORY)

Unique identifier for this order

transactionId String

(COMPULSORY)

Unique identifier for this payment authentication

callback Function

(COMPULSORY)

The callback function

Return Value

None

authenticatePayer()

Authentication method for authenticating payer using 3DS that was initiated using initiateAuthentication call. This method will call AUTHENTICATE_PAYER REST API and returns the raw response in data.restApiResponse field.

Usage

ThreeDS.authenticatePayer(orderId, transactionId, callback, optionalParams)

Example

var optionalParams = {
    fullScreenRedirect: true,
    billing: {
        address: {
            city: "London",
            country: "GBR"
        }
    }
};

ThreeDS.authenticatePayer("5678", "ABC", function (data) {
    if (!data.error) {
        //data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
        console.log("REST API response ", data.restApiResponse);
        console.log("HTML redirect code ", data.htmlRedirectCode);
    }
}, optionalParams);
  

Compulsory Arguments

orderId String

(COMPULSORY)

Order Id of the transaction

transactionId String

(COMPULSORY)

Transaction Id of the transaction

callback Function

(COMPULSORY)

The callback function

optionalParams Object

Any additional REST API request params

fullScreenRedirectBoolean

Indicates whether or not the user wants to automatically get redirected using htmlRedirectCode property provided by callback.

If fullScreenRedirect is set to ‘false’, content of htmlRedirectCode received from callback needs to be manually inserted into an empty <DIV> element, this being the last element in the <BODY> of your payment page.

If fullScreenRedirect is set to ‘true’ it will be handled automatically.

If the user, in addition, provides device.browserDetails.3DSecureChallengeWindowSize property then in order to have automatic redirect the value must be equal to ‘FULL_SCREEN’. Otherwise, the user will need to handle this manually despite fullScreenRedirect property being equal to ‘true’.

Callback data

restApiResponse String

The REST API response

correlationId String

The last correlation id that was used for making the REST API call

gatewayRecommendation String

The gateway recommendation based on the cumulative risk score as determined by the ACS and the gateway.

htmlRedirectCode String

Code to create the authentication UI.

Return Value

None

getLastCorrelationId()

Get the last correlation id that was used for making the REST API call.

Since this is an API with majority of request & response processing happening asynchronously, it would be nice to know which callback handler is being processed for which request call. The API client/integration code can use correlationId as a way to identify the response for the corresponding request. It’s an optional argument to the API methods. If this value isn’t passed, API will generate a new UUID every time before making the REST API call.

The integration code can use getLastCorrelationId() method to find the last correlation id that was used for a given API request, on cases where the id wasn’t passed to the API method.

The value of correlationId will be the same for a given API request on their before and after events. The integration code can use correlationId for tracking the event handlers specific to the events.

Usage

ThreeDS.getLastCorrelationId()

Example

ThreeDS.getLastCorrelationId();

Arguments

None

Return Value

correlationId String

A String with the last correlation id that was used for making the REST API call