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