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. 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:
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. |