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