Search Overlay

Managing 3DS Challenge

Please Note: As an ISV / Paysafe Partner, you will need to complete all of the below "merchant" steps on behalf of the Parent Merchant Legal Entity (PMLE) that your merchants will be operating under.

According to the 3DS 2 specification, the user should be challenged before completing a payment. This is also called as "Challenge flow".

There is, however, the possibility that a bank considers the payment as a low - risk. In this case, no challenge will be given to the user. This is called "frictionless flow". Your app should be able to handle both 3DS flows.

Handling the Challenge Flow

When calling the /authentications endpoint from the Paysafe REST APIs, your server will receive a sdkChallengePayload. This means that the user must complete a 3DS challenge before completing the authentication. You can handle the challenge in your iOS application as follows:

  • Pass the sdkChallengePayload to the Paysafe iOS SDK.
[self.threeDSecureService challengeWithSdkChallengePayload: sdkChallengePayload
completion:^(NSString * _Nullable authenticationId, NSError * _Nullable error) {
if(error) {
// Handle the error to get more information
} else if(authenticationId) {
// Send the authenticationId to your server to check the authentication status
threeDSecureService.challenge(sdkChallengePayload: sdkChallengePayload,
completion: {(result: Result<String, Error>) in
switch result {
case let .failure(error):
// Handle the error to get more information

case let .success(authenticationId):
// Send the authenticationId to your server to check the authentication status
  • Challenge() method will prompt a new screen that will let the user handle the required 3DS challenge. Once the challenge is completed, Paysafe SDK will shift the control back to your application by calling the challenge() completion method.
  • Once the user completes the 3DS challenge, you will receive the authenticationId of the current authentication. Send the authenticationId to your server.

  • Your server will further make calls to the Paysafe REST APIs and check if the payment is completed or not. If you receive another sdkChallengePayload, repeat the current step.

If the SDK fails to generate a device fingerprint, you will receive a ThreeDSecureError that contains useful information about the cause of the failure. When troubleshooting, you can start by checking the error code and detailed message. Below, you can check the currently supported error codes:

Error Information
Error Code Value Explanation
ERROR_CODE_CONNECTION_FAILED 9001 The operation failed due to a timeout or a connectivity issue.
ERROR_CODE_INVALID_RESPONSE 9002 Server returned an invalid data format which could not be handled by the SDK.
ERROR_CODE_INVALID_API_KEY 9013 Invalid API key or API secret provided when creating a Paysafe API Client.
ERROR_CODE_INTERNAL_SDK_ERROR 9014 A general SDK error. The detailed message should provide additional information.
ERROR_CODE_INVALID_OPTIONS 9015 Invalid option fields error. The detailed message should provide additional information.
ERROR_CODE_INVALID_MERCHANT_CONFIGURATION 9501 The configuration of the provided merchant account is invalid. The Paysafe Support team should be notified.
ERROR_CODE_TRANSACTION_FAILED_OR_CANCELED 9601 The operation failed due to a cancellation or a failure.

If you cannot solve the issue on your own, you can get in touch with the Paysafe Support at and provide them with the error correlation ID.

Handling the Frictionless Flow

When there is no sdkChallengePaylod in the /authentications result, it means that the user has completed a "frictionless" payment. In this case, there is no need for any additional processing from the Paysafe iOS SDK, and you can proceed with the normal flow of your application.