Netcetera 3DS SDK API

Instantiation

First an instance of ThreeDS2ServiceSDK should be created. When creating the ThreeDS2ServiceSDK object, two constructors are available. One with a bundle argument and one without it. The default value for the bundle is Bundle.main. In case you want to specify a separate bundle for resources, pass the value using the ThreeDS2ServiceSDK(bundle:Bundle) constructor.

Initialization

The 3DS Requestor App calls the initialize method at the start of the payment stage of a transaction. The app passes configuration parameters, UI configuration parameters, and user locale to this method. The ThreeDS2Service instance is unusable prior to the initialization.

In order to use the ThreeDS2Service for further actions, initialize it with ThreeDS2Service.initialize(...) method.

Example:

Note: There is an additional option for the integrator to initialize the SDK via a call without the success and failure callbacks. However, it is important to be mentioned that the method without callbacks is a blocking method. Therefore, it should be called on a background thread and should be handled as a long lasting operation in order to avoid UI unresponsiveness.

During initialization, security checks are performed and device information is collected. These parameters will be a part of the Authentication and will be provided to the ACS via 3DS Server for risk analysis.

For more details about the security checks and their handling, refer to Security Features.

For more details on the device data that is collected, refer to EMVCo 3DS SDK Device Info Specification.

Warnings

After the security checks have been performed, the SDK provides the outcome as a list of Warning objects.

To obtain the result of these security checks call ThreeDS2Service.getWarnings().

Each of the resulting Warning objects has a Severity with value of LOW, MEDIUM and HIGH and it is up to the integrator to decide whether and how to act on each of them. For more details, please refer to Security Warnings.

The resulting warnings will be provided as part of the Device Info in the Authentication.

SDK Info

The ThreeDS2Service offers a getSDKInfo() method that retrieves information about the SDK, including the license expiry date, supported EMVCo 3DS protocol versions and details of the configured schemes with which the 3DS SDK currently operates. The getSDKInfo() method can be used to better understand the configuration that will be applied to transactions created by the same ThreeDS2Service in the future. This ensures that developers can verify the current license and certificates being used, helping to troubleshoot and configure the SDK appropriately.

Example:

Processing Screen

To indicate that a transaction is ongoing (such as ongoing Authentication Request or ongoing Challenge flow), a Processing Screen supplied by the 3DS SDK shall be shown by the requestor application. To get an instance of this processing screen, use Transaction.getProgressView(...).

Processing Screen use cases and requirements for the requestor application:

• (Required) EMVCo Requirement: While the 3DS Authentication Request is ongoing, the processing screen shall be shown for a minimum of two seconds by the requestor application, regardless of the authentication response time or result.
• (Recommended) Netcetera 3DS SDK Requirement: If a 3DS Challenge flow is required after the Authentication Request, do not invoke ProgressDialog.stop() before invoking Transaction.doChallenge(...) as this will lead to a flicker on the screen. The 3DS SDK uses the same processing screen for starting the challenge flow (invokes ProgressDialog.start() internally if it is hidden). This processing screen is shown by the 3DS SDK until the appearance of the first challenge screen. Furthermore, assuming no exception has been thrown when invoking Transaction.doChallenge(...), the 3DS SDK will hide the processing screen once the challenge is finished (when any of the ChallengeStatusReceiver methods have been called).

These requirements shall be implemented by the 3DS SDK integrator. For example, reference the Netcetera Demo Merchant application.

Authentication

The 3DS Authentication flow starts with the authentication request that the 3DS Requestor Environment (Application or Library) sends to the 3DS Server. The 3DS Server uses that data to compose the AReq that is sent to the DS and further forwarded to the appropriate ACS.

The ACS evaluates the data provided in the AReq and responds with an ARes message to the DS, which then forwards the message to the 3DS Server. At the end, the 3DS Server communicates the result of the ARes message back to the 3DS Requestor Environment.

The 3DS SDK generates authentication parameters that should be used for building the initial Authentication Request. All these parameters should be sent to the 3DS Server, in a format defined by the 3DS Server API. These parameters can be retrieved from the Transaction object.

To obtain instance of Transaction, ThreeDS2Service.createTransaction(...) method can be used.

Example:

After the Transaction object has been created, the AuthenticationRequestParameters can be obtained by calling Transaction.getAuthenticationRequestParameters().

Example:

The parameters that are part of the AuthenticationRequestParameters are defined in chapter 4.12 of the EMVCo 3DS SDK Specification.

Using Bridging Message Extension

The Bridging Message Extension describes how existing EMV® 3-D Secure v2.1 and v2.2 components can provide or consume additional data related to the EMV® 3-D Secure Protocol and Core Functions Specification v2.3.1.

When Bridging Message Extension is used, the 3DS SDK will process the Bridging Message Extension, and if the required elements are present it will enable the OOB Automatic Switching Feature for Out of Band v2.2 challenges and masking of the challenge input for TEXT v2.2 challenges.

The use of Bridging Message Extension is optional. To utilize it, developers should invoke the Transaction#useBridgingExtension method and specify the version of the Bridging Message Extension to be used. The Requestor App should determine the appropriate version through the Versioning call. If this method is not invoked, the Bridging Message Extension will not be used by the 3DS SDK.

Supported versions of the Bridging Message Extension are 1.0 and 2.0.

Example:

Note: Due to variances in the Bridging Message Extension Specification for version 1.0, different providers may implement the Bridging Message Extension API differently, potentially resulting in transaction failures.

Starting the Challenge Flow

If the ACS assesses the transaction as high-risk, above certain threshold or that it requires higher level of authentication, it forces a Challenge Flow communication.

In case of Challenge Flow, the 3DS Requestor calls Transaction.doChallenge(...), and the SDK takes over the Challenge process.

Once a challenge has been started, invocation on Transaction.doChallenge(...) and Transaction.close() will result in SDK Runtime Error, but the Challenge Flow won't be interrupted nor the Transaction will be put in an invalid state. Once a result comes through the ChallengeStatusReceiver, calling of Transaction.doChallenge(...) and Transaction.close() is allowed if required.

Note: The doChallenge method should be called on a background thread and should be handled as a long lasting operation in order to avoid UI unresponsiveness.

Requestor App URL

Starting with version 2.2.0 of the EMV 3DS Specification Protocol, the application (requestor) integrating the 3DS SDK can be called from another (authentication) application during an OOB challenge flow to indicate completed OOB authentication. To use this feature, the requestor application should define its app url and provide it to the 3DS SDK.

The app url can be provided to the 3DS SDK in the challenge parameters via the setThreeDSRequestorAppURL(threeDSRequestorAppURL: String) method.

The passed URL should be a universal link that is configured for the application. The inclusion of this value in the challenge parameters is optional. If the app url is provided for an irrelevant version of the 3DS Specification Protocol (example version 2.1.0), the 3DS SDK will ignore it.

For further information on how to define the threeDSRequestorAppURL value, you can check the documents provided by EMVCo.

If the threeDSRequestorAppURL is set and the app is opened with this url in 2.2.0 transactions the OOB flow automatically continues. The transID query parameter in the URL must be the same as the current ongoing transaction. In this case the SDK knows that the authentication for that transaction has finished and can automatically send challenge request to the ACS.

In iOS the handling of events when the app was opened from a universal link is done in the main application delegate. In order for the SDK to be able to catch these events, the main application delegate needs to call the appropriate methods from ThreeDSSDKAppDelegate:

As an example on how to use and handle the app url on the application side, you can refer to the Netcetera Demo Merchant application.

Challenge Flow Results

After invoking Transaction.doChallenge(...), the Challenge Flow is started and the control of the UI is handed over to the 3DS SDK. The DS Requestor has the control back when any of the callback methods from the ChallengeStatusReceiver are invoked.

Implement a class that conform to the ChallengeStatusReceiver protocol.

When any of the callback methods of the ChallengeStatusReceiver are invoked, the challenge flow is considered finished. As a result, the 3DS SDK dismisses the challenge screen, closes the transaction, cleans up resources and gives the UI control over to the 3DS Requestor.

Closing of the Transaction

After the 3DS Authentication has finished, the 3DS Requestor should close the Transaction by calling Transaction.close() in order to clear references and avoid possible memory leaks.

This method should only be called when the Transaction.doChallenge(...) method is not called in a transaction. If invoked during an ongoing challenge, this method will throw SDK Runtime Error. At the end of the challenge flow, the 3DS SDK takes responsibility to cleanup resources and therefore this method is not required to be called.

After the transaction is closed and resources are cleaned up, any further operation on the Transaction object will result in a SDK Runtime Error.

Cleanup of the ThreeDS2Service

Similar to closing a Transaction, in order to free up resources which are used by the ThreeDS2Service, the ThreeDS2Service.cleanup() shall be used. Once an instance of ThreeDS2Service has freed up the used resources, the instance is in the same state as a newly created ThreeDS2Service and it can be used once again, though it should previously go through the Initialization process. After the ThreeDS2Service.cleanup() has been performed, previously created Transaction objects are in invalid state and shall not be used anymore. It is recommended to always create a new transaction object after initializing the service.

Objective-C class prefixes

To avoid conflicts of class/protocol names when using the SDK in Objective-C, all public classes and protocols of the SDK are prefixed with 'NCA'.

Example: NCAThreeDS2ServiceSDK, NCATransaction, NCAToolbarCustomization...

Note: This is only valid for Objective-C