JavaScript SDK Challenge Function

The challenge function initializes the challenge procedure for a customer. It has the following parameters:

  • The Base64-encoded version of the public (single-use token generating) API key. Note that this key can only be used to generate single-use tokens and has no other API access rights, such as those required for taking payments. Consequently, this key can be exposed publicly in the user's browser.
  • An options object containing the environment to use (Test or Live) and the SDK challenge payload.
  • A callback function to handle errors or notify the caller with the authentication ID.

The function signature is as follows:

paysafe.threedsecure.challenge(apikey,options,callback);

Environment

The options object contains a string to select the environment to use to handle the challenge, either LIVE (the Paysafe Production environment) or TEST (the Paysafe Merchant Test or Sandbox environment).

Do not use real card numbers or other payment instrument details in the Merchant Test environment as it is not compliant with Payment Card Industry Data Security Standards (PCI-DSS), and does not protect cardholder/payee information. Any upload of real cardholder data is strictly prohibited, as described in the Terms of Use.

Test

paysafe.threedsecure.challenge("my Base64 encoded single-use-token API key", {
	environment: "TEST",
	sdkChallengePayload: "Challenge payload returned by the call to the /authentications endpoint"
}, function (id, error) {...});

Live

paysafe.threedsecure.challenge("my Base64 encoded single-use-token API key", {
	environment: "LIVE",
	sdkChallengePayload: "Challenge payload returned by the call to the /authentications endpoint"
}, function (id, error) {...});

Default

If you omit the environment object, by passing an empty or null value for this parameter, the Live environment will be used.

paysafe.threedsecure.challenge("my Base64 encoded single-use-token API key", {
	sdkChallengePayload: "JavaScript SDK challenge payload returned by the call to the /authentications endpoint"
}, function (id, error) {...});

Challenge Function and Objects

Here is a full list of the challenge function parameters, the JavaScript objects used by the challenge function, and the parameters they contain.

Parameter Required Type Description
apiKey true string The Base64-encoded version of the public (single-use token generating) API key.
options true object This is an object that contains the environment and the sdkChallengePayload.
callback true function This is a function that will either return the authenticationId or an error code.
options
environment false string

This selects the environment to use to handle the challenge. The possible values are:

  • LIVE – used for Production
  • TEST – used for the Merchant test or sandbox environment

If no environment is specified, the value defaults to LIVE.

sdkChallengePayload

true

string

This is the JavaScript SDK challenge payload returned by the call to the /authentications endpoint.

callback

The callback function is invoked to handle errors or notify the caller with the authentication ID.

Parameter Required Type Description
id false string If the operation is successful, this is the ID that will be used to call the /authentications/{id} endpoint to retrieve the results of the challenge.
error false object Object containing information for the error. This field is present if the operation fails. The contents of this object are described below.
error
code true string

This is the error code.

displayMessage true string

This is the error message that will be displayed.

detailedMessage false string

This is a detailed description of the error.

correlationId false string

This is the unique error ID that should be provided to Paysafe Support during an investigation.

An example is shown below:

function callback(id, error) {
	if (error) {
		// error handling
	} else {
		// manage a further call (preferably server-to-server) to the /authentications/{id} endpoint to receive the results of the challenge
	}
}

Challenge Errors

The following errors will not be returned through the provided callback function but rather thrown.

Code
Display Message
Detailed Message
Description
9004 There was an error (9004), please contact our support. Callback should be function. The callback parameter must be a valid function.
9012 There was an error (9012), please contact our support. Invalid number of arguments. The supplied number of arguments is not 3.

An example of error handling is shown below:

try {
	paysafe.threedsecure.challenge(apiKey, options, (id, challengeError) => {
		// Regular callback function
	});
} catch (e) {
	//Handle the thrown exception
}

Errors Passed to callback

The following errors will be returned through the provided callback function.

Code
Display Message
Detailed Message
Description
9013 There was an error (9013), please contact our support. Invalid apiKey parameter. The supplied apiKey parameter is not a string or is not a valid Base64-encoded value.
9014 There was an error (9014), please contact our support. Unhandled error occurred. An error that was not handled by the SDK has been thrown.
9015 There was an error (9015), please contact our support. Invalid options argument. The supplied options parameter is not an object.
9500 There was an error (9500), please contact our support. Invalid option fields: ${options} Invalid values passed as options.
Did you find this page useful?