JavaScript SDK Start Function

The start function initializes the device fingerprinting 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), account ID, and a card object containing the bank identification number (BIN) of the card that will be used.
  • A callback function to handle errors or notify the caller with the device fingerprinting ID.

The function signature is as follows:

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

Environment

The options object contains a string to select the environment to use for device fingerprinting, 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.start("my Base64 encoded single-use API key", {
	environment: "TEST",
	accountId: "Preferred account ID",
	card: {
		cardBin: "The card BIN"
	}
}, function (deviceFingerprintingId, error) {...});

Live

paysafe.threedsecure.start("my Base64 encoded single-use API key", {
	environment: "LIVE",
	accountId: "Preferred account ID",
	card: {
		cardBin: "The card BIN"
	}
}, function (deviceFingerprintingId, 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.start("my Base64 encoded single-use API key", {
	accountId: "Preferred account ID",
	card: {
		cardBin: "The card BIN"
	}
}, function (deviceFingerprintingId, error) {...});

Start Function and Objects

Here is a full list of the start function parameters, the JavaScript objects used by the start 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 account ID, the environment, and a card object containing the Bank Identification Number (BIN).
callback true function This is a function that will either return the deviceFingerprintingId or an error code.
options
environment false string

This selects the environment to use for device fingerprinting. 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.

accountId true string

This is the account ID that will be used for the transaction.

card true object

This object contains the card bank identification number (BIN) required for the device fingerprinting operation.

card
cardBin true number

This is the card Bank Identification Number (BIN). This is typically the first 6–8 digits of the card.

callback

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

Parameter Required Type Description
deviceFingerprintingId false string If the operation is successful, the device fingerprinting ID is returned.
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(deviceFingerprintingId, error) {
	if (error) {
		// error handling
	} else {
		// manage a further call to the /authentications endpoint with the provided deviceFingerprintingId
	}
}

Start 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.start(apiKey, options, (deviceFingerprintingId, startError) => {
		// 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} The values passed as options are invalid.
9501 There was an error (9501), please contact our support. Invalid merchant configuration setup The merchant configuration setup is invalid.
Did you find this page useful?