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 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 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 iOS SDK, and you can proceed with the normal flow of your application.