Managing 3DS Challenge

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 Android application as follows:

  • Pass the sdkChallengePayload to the Paysafe Android SDK.
    threeDSecureService.challenge(<Your current app context>, sdkChallengePayLoad, new ThreeDSChallengeCallback {
    
        @Override
        public void onSuccess(ChallengeResolution challengeResolution) {
            // Use the challenge resolution to launch the proper UI
        }
    
        @Override
        public void onError(ThreeDSecureError error) {
            // Handle the error
        }
    })
  • The challenge() method will provide a ChallengeResolution object used to start an activity that will let the user handle the required 3DS challenge. You can begin the challenge resolution screen from either an action or a fragment, calling the corresponding method. A request code must be provided and can be used later to retrieve the result of the 3DS challenge:
    // Start from activity. The result will be returned in the provided activity's onActivityResult()
    challengeResolution.startForResult(activity, <Your request code>);
    
    // Start from fragment. The result will be returned in the provided fragment's onActivityResult()
    challengeResolution.startForResult(fragment, <Your request code>);
    
    // Alternatively, you can get a pending intent and handle it on your own
    challengeResolution.getResolutionIntent();
  • When the user has completed the challenge, the Paysafe SDK will handle the control back to your application by calling onActivityResult() on the activity or fragment you provided to the ChallengeResolution.startForResult() method. Here is how you can handle the challenge result:

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if (<Your request code> == requestCode) {
            final ChallengeResult challengeResult = ChallengeResult.fromIntent(data);
            if (challengeResult.isSuccessful()) {
                final String authenticationId = challengeResult.getAuthenticationId();
                // Send the authenticationId to your server to check the authentication status
            } else {
                final ThreeDSecureError error = challengeResult.getError();
                // Handle the error to get more information
            }
        }
  • After the user completes 3DS challenge, you will receive the authenticationId of the current authentication. You should send this to your server so it can call the Paysafe REST APIs and check if the payment has been completed or not. If you receive another sdkChallengePayload, just 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_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_MERCHANT_CONFIGURATION 9501 The configuration of the provided merchant account is invalid. The Paysafe Support team should be notified.

If you cannot solve the issue on your own, you can get in touch with the Paysafe Support at integrations@paysafe.com 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 Android SDK, and you can proceed with the normal flow of your application.

Did you find this page useful?