Integration guide

This section includes detailed tutorials on how to integrate ActiveSDK with Android and iOS apps. All 3DS SDK authentication processes and their work flows are covered.

Security Guidance and Best Practices¶

Before starting development using the 3DS SDK, it is important to consider the security implications, and how to best protect sensitive data. While the SDK takes care of many security functions, as detailed in the EMVCo 3DS SDK specification, there are other considerations that need to be taken into account.

Communication with the 3DS Server¶

While communication with the 3DS Server is outside the scope of the 3DS SDK itself, the data transmitted, both generated from the 3DS SDK and otherwise, should be properly secured according to payment system security standards. Annex D of the EMVCo Protocol and Core Functions Specification provides guidance that has been summarized below. These standards would be appropriate for communication between the 3DS SDK and 3DS Server:

TLS 1.2 or higher should be used, with key lengths as follows:

• RSA: 2048 bits or longer.
• ECC: 256 bits or longer.

One of the following cipher suites should be used:

• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

Curve P-256 shall be used and indicated in the cipher suite extension.

Protection of Sensitive Cardholder Data¶

Much of the data used for authentication is outside the scope of the 3DS SDK, and is transmitted to the 3DS Server outside any authentication parameters. This sensitive data includes anything from the card number itself to cardholder contact details.

Protection includes the above secure transmission, as well as protection on the device itself. This may include either not saving the data locally, or encrypting it properly if stored.

Cleanup the ThreeDS2Service Instance¶

Make sure to cleanup the SDK after you are finished with 3-D Secure. This can be done using the cleanup method like below:

ThreeDS2Service.INSTANCE.cleanup(applicationContext);

threeDS2Service.cleanup();

Downloads and Updates¶

Updates to the 3DS SDK are made available on the GPayments repository. Builds there are updated periodically, as well as when critical security updates are made. When the builds are updated, an email notification will be sent out to SDK clients.

No updates are pushed directly to deployed applications. It would instead be required to obtain the latest builds and integrate them into the application. When updating, care should be taken to ensure the integrity of transactions already in progress.

Security Updates¶

The Security Checks sections below contain details on the security checks performed during initialization of the SDK, as well as checks made periodically at runtime. The guidance in that section should be followed to make sure your application knows about these issues, and responds accordingly.

3DS SDK Flow¶

ActiveSDK can be used to support 3-D Secure V2 authentication natively in a mobile application. This SDK is built according to the 3DS V2 (2.1.0, 2.2.0) specification released by EMVCo. The EMV 3-D Secure specification, as well as more information on 3-D Secure V2 in general, can be found on the EMVCo website.

For a general overview of the sequence of 3DS SDK calls required to progress through 3-D Secure authentication, see the authentication sequence page.

Getting Started¶

The SDK binaries are available via the GPayments repository server. As part of the enrolment process, the credentials for the repository will be provided.

There are two versions of the 3DS SDK included with the installation: one to be used for development and one for production. The production version includes more strict security measures that would not allow for common development processes to occur, including running with attached debuggers or using simulators/emulators.

PCI 3DS SDK imposes requirements on 3DS SDKs that severely restrict development. For example, running on an emulator or debugging are forbidden in a production 3DS SDK. As such, the GPayments 3DS SDKs include both development and deployment versions, with the main differences being related to the security checks performed and resulting behavior. More details can be found in the Security Checks section.

Android¶

The following code snippet demonstrates how to add GPayments repository to the Android app.

1. Put the following in the main build.gradle file, inside the repositories element:

   Gradle

   repositories {
       maven {
           url "https://repository.gpayments.com/repository/mvn-sdk"
           credentials {
               username = "put your username here"
               password = "put your password here"
           }
       }
   }
   

2. Then add these lines inside the dependencies in the app's build.gradle file:

   Production SDK

   dependencies {
      ...
      // Production SDK
      implementation 'com.gpayments.3ds2:activesdk-android:<version>@aar'       
      ...
   }
   

   Development SDK

   dependencies {
      ...
      // Development SDK
      implementation 'com.gpayments.3ds2:activesdk-android-dev:<version>@aar'       
      ...
   }
   

For the version number to use for this release, refer to the SDK build version numbers on the Release note page.

iOS¶

There are two ways of obtaining the SDK binaries for iOS, either through the GPayments repository server or via CocoaPods.

Downloading from the GPayments repository¶

Download the framework binary from the GPayments repository server and then follow these steps:

1. Place the framework directory into your project directory
2. In Xcode, click on your project. Then click on the target you want to link to. Finally, click on Build Phases.
3. Expand the Link Binary With Libraries section.
4. Click the +
5. Then click Add Other and choose Add Files
6. Navigate to framework directory
7. Click Open

Installing via CocoaPods¶

If you have not already installed CocoaPods, you can do so with the following command:

$ sudo gem install cocoapods

Then, navigate to the root of your project and run $ pod init

You will now see a generated Podfile in your root folder. This is where you can list all pods you wish to add to your project. Our currently available pods are listed below:

ActiveSDKDev
ActiveSDKProd
ActiveSDKSwift4.2Dev
ActiveSDKSwift4.2Prod

The pods are uploaded as an XCFramework for the versions of Swift that support it. An XCFramework is a single dependency for all target platforms and architectures, which means you do not need to specify the individual target platforms Device or Simulator separately anymore, as was the case in previous versions.

All pods without the specific version of Swift in their name are compiled with Swift 5. ActiveSDKSwift4.2Dev and ActiveSDKSwift4.2Prod are compiled using Swift 4.

In order to use an ActiveSDK pod, your podfile should be formatted like the following example:

source 'https://github.com/gpayments/activesdk-ios.git'

target 'ExampleProjectName' do
  pod 'ActiveSDKDevSimulator', '~> 2.2.7889'
end

For the version number to use for this release, refer to the SDK build version numbers on the Release note page.

Before running the next command you must ensure that you are logged into the correct Git account on the command line, which has been granted access to the GPayments private Git repository.

You can use any method for this, such as using Keychain Access in macOS, Git Credential Manager Core, or just ensuring that your Git configuration is set to the correct account. If you are using an account that has not been granted access to the private repository, the error No `Podfile' found in the project directory. will be thrown.

Finally, run $ pod install in your root folder and the pod will be downloaded and integrated into your project.

Initializing the SDK¶

Depending on the 3DS Requestor application implementation, a ThreeDS2Service instance is created either during startup of the 3DS Requestor app (as a background task), or when a transaction is initiated. The state of the service is maintained until the cleanup method is called. To create an instance of the ThreeDS2Service, call the initialize method like so:

ThreeDS2Service.INSTANCE.initialize(applicationContext,
    configParameters,
    locale,
    uiCustomization,
    new MyClientEventListener(),
    new MySecurityEventListener());

try threeDS2Service.initialize(
    configParameters: configParameters,
    locale: nil,
    uiCustomization: uiCustom,
    clientEventListener: clientEventListener,
securityEventListener: securityEventListener)

The parameters this initialize method takes are as follows:

Android Parameters

iOS Parameters

Config Parameters¶

The ConfigParameters class is used to provide details required by the 3DS SDK for initialization, as well as additional optional settings. The ConfigParameters.Builder class helps with organizing these parameters which can be used as follows:

//adding the license
String runtimeLicense = ".....";


List<ConfigParameters.DirectoryServerInfo> directoryServerInfoList = new ArrayList<>();
directoryServerInfoList.add(new ConfigParameters.DirectoryServerInfo(DSInfo.DS_ID, KID, DSInfo.DS_CERT, DSInfo.DS_CA_CERT));

List<String> deviceParameterBlacklist = new ArrayList<>();
    deviceParameterBlacklist.add("A009");
    deviceParameterBlacklist.add("A010");  

List<String> maliciousApps = new ArrayList<>();
    maliciousApps.add("de.robv.android.xposed");

List<String> trustedAppStores = new ArrayList<>();
    trustedAppStores.add("com.xiaomi.market");

String appsignature = ParseAppSignature(HTTP.Get("https://www.example.com/signature"));

List<String> clientConfigs = new ArrayList<>();
    clientConfigs.add("logLevel=3");
    clientConfigs.add("MaskSensitive=false");

ConfigParameters configParameters = new ConfigParameters.Builder(directoryServerInfoList, runtimeLicense)
.deviceParameterBlacklist(deviceParameterBlacklist)
.maliciousApps(maliciousApps)
.trustedAppStores(trustedAppStores)
.appSignature(appsignature)
.clientConfig(clientConfigs)
.OOBAppURLSupported(true)
        .build();

var directoryServerInfoList = [DirectoryServerInfo]()
directoryServerInfoList.append(DirectoryServerInfo(RID: DSInfo.DS_ID, publicKey: DSInfo.DS_CERT, CA: DSInfo.DS_CA_CERT))

let deviceParameterBlacklist = ["C005", "I010"]
let clientConfigs = ["LogLevel=3", "MaskSensitive=false"]

let builder = ConfigParametersBuilder.init(directoryServerInfoList: directoryServerInfoList, runtimeLicense: "....", deviceParameterBlacklist: deviceParameterBlacklist, clientConfig: clientConfigs, appBundleId: appBundleId)
let configParameters = try builder.build()

Parameters fall into a few groups:

Android Parameters

After building the ConfigParameters object, the addParams method can be used to add additional parameters. This method accepts a group, parameter name, and parameter value. There are no specific groups associated with the SDK at this time, so the group can be set to a null value. For example:

configParameters.addParam(null, "ParameterName", "ParameterValue");

Available additional parameters are as follows:

iOS Parameters

After building the ConfigParameters object, the addParams method can be used to add additional parameters. This method accepts a group, parameter name, and parameter value. There are no specific groups associated with the SDK at this time, so the group can be set to a null value. For example:

try configParameters.addParam(group: nil, paramName: "ParameterName", paramValue: "ParameterValue")

Available additional parameters are as follows:

UI Customization Options¶

The UICustomization class exposes functionality to customize the 3DS SDK UI elements. This allows the 3DS Requestor application to have its own look-and-feel in the native challenge pages. The customization of Buttons, Labels, TextBoxes, and Toolbars is enabled via the various classes and subclasses outlined below.

UI Customization¶

Main class for configuring the customization of UI elements.

public class UiCustomization {
    enum ButtonType (VERIFY, CONTINUE, NEXT, CANCEL, RESEND, ADDITIONAL, OOB_OPEN_APP)
    enum LabelType (INFO_HEADER, INFO_TEXT, INFO_LABEL, WHITELIST, DEVICE_TYPE, WHY_INFO, WHY_INFO_TEXT, EXPANDABLE_INFO, EXPANDABLE_INFO_TEXT, SELECTION_LIST, DATA_ENTRY_LABEL, DATA_ENTRY_LABEL_2)

    void setButtonCustomization(ButtonCustomization buttonCustomization, ButtonType buttonType)
    void setToolbarCustomization(ToolbarCustomization toolbarCustomization)
    void setLabelCustomization(LabelCustomization labelCustomization)
    void setTextBoxCustomization(TextBoxCustomization textboxCustomization)
    void setBackground(String hexColorCode)
    void setInformationZoneIconPosition(int position) // 0: right, 1: left, 2: hide

    ButtonCustomization getButtonCustomization(ButtonType buttonType)
    ToolbarCustomization getToolbarCustomization()
    LabelCustomization getLabelCustomization()
    TextBoxCustomization getTextBoxCustomization()
    TextBoxCustomization getTextBoxTwoCustomization()
    String getBackground(String hexColorCode)
    int getInformationZoneIconPosition(int position)
}

public class UiCustomization {
    enum ButtonType (VERIFY, CONTINUE, NEXT, CANCEL, RESEND, ADDITIONAL, OOB_OPEN_APP)
    enum LabelType (INFO_HEADER, INFO_TEXT, INFO_LABEL, WHITELIST, DEVICE_TYPE, WHY_INFO, WHY_INFO_TEXT, EXPANDABLE_INFO, EXPANDABLE_INFO_TEXT, SELECTION_LIST, DATA_ENTRY_LABEL, DATA_ENTRY_LABEL_2)

    void setButtonCustomization(ButtonCustomization buttonCustomization, ButtonType buttonType)
    void setToolbarCustomization(ToolbarCustomization toolbarCustomization)
    void setLabelCustomization(LabelCustomization labelCustomization)
    void setTextBoxCustomization(TextBoxCustomization textboxCustomization)
    void setBackground(UIColor color)
    void setInformationZoneIconPosition(int position) // 0: right, 1: left, 2: hide
    void setBrandingZoneLogoGap(CGFloat value)

    ButtonCustomization getButtonCustomization(ButtonType buttonType)
    ToolbarCustomization getToolbarCustomization()
    LabelCustomization getLabelCustomization()
    TextBoxCustomization getTextBoxCustomization()
    TextBoxCustomization getTextBoxTwoCustomization()
}

Button Customization¶

The ButtonCustomization class enables the customization of various buttons presented to the cardholder during the challenge process.

public class ButtonCustomization {
    void setBackgroundColor(String hexColorCode)
    void setCornerRadius(int cornerRadius)
    void setTextFontName(String fontName)
    void setTextFontSize(int fontSize)
    void setTextColor(String hexColorCode)
    void setHeight(int pixels)
    void setPadding(int start, int top, int end, int bottom) // applicable only for ButtonType of CANCEL

    String getBackgroundColor()
    int getCornerRadius()
    String getTextFontName()
    int getTextFontSize()
    String getTextColor()
    int getHeight()
    int[] getPadding() // applicable only for ButtonType of CANCEL
}

public class ButtonCustomization {
    void setBackgroundColor(UIColor color)
    void setCornerRadius(int cornerRadius)
    void setTextFontName(String fontName)
    void setTextFontSize(int fontSize)
    void setTextColor(String hexColorCode)
    void setTextColor(UIColor color)
    void setHeight(CGFloat height)
    void setPadding(UIEdgeInsets edge) // applicable only for ButtonType of CANCEL

    UIColor getBackgroundColor()
    int getCornerRadius()
    String getTextFontName()
    int getTextFontSize()
    UIColor getTextColor()
    String getTextColorHex()
    CGFloat getHeight()
}

For example, the following code will configure buttons with red backgrounds and white font:

UiCustomization uiCustomization = new UiCustomization();

ButtonCustomization customButton = new ButtonCustomization();
customButton.setTextColor("#FFFFFF"); // White
customButton.setBackgroundColor("#951728"); // Dark red

uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.CANCEL);
uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.CONTINUE);
uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.NEXT);
uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.RESEND);
uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.SUBMIT);

let uiCustom = UiCustomization()

let customButton = ButtonCustomization()
customButton.setTextColor(color: UIColor.white)
customButton.setBackgroundColor(color:UIColor.red)

try uiCustom.setButtonCustomization(buttonCustomization: customButton, buttonType: .CANCEL)
try uiCustom.setButtonCustomization(buttonCustomization: customButton, buttonType: .CONTINUE)
try uiCustom.setButtonCustomization(buttonCustomization: customButton, buttonType: .NEXT)
try uiCustom.setButtonCustomization(buttonCustomization: customButton, buttonType: .RESEND)
try uiCustom.setButtonCustomization(buttonCustomization: customButton, buttonType: .SUBMIT)

This results in the following Submit button for a Single-Select challenge:

Label Customization¶

The LabelCustomization class enables the customization of various labels displayed throughout the challenge process.

public class LabelCustomization {
    void setHeadingTextAlignment(int textAlignment)
    void setHeadingTextColor(String hexColorCode)
    void setHeadingTextFontName(String fontName)
    void setHeadingTextFontSize(int fontSize)
    void setInputTextColor(String hexColorCode)
    void setInputTextFontName(String fontName)
    void setInputTextFontSize(int fontSize)
    void setTextColor(String hexColorCode)
    void setTextColor(LabelType labelType, String hexColorCode)
    void setTextFontName(String fontName)
    void setTextFontName(LabelType labelType, String fontName)
    void setTextFontSize(int fontSize)
    void setTextFontSize(LabelType, labelType, int fontSize)
    void setBackgroundColor(LabelType labelType, String hexColorCode)
    void setPadding(LabelType labelType, int start, int top, int end, int bottom)

    int getHeadingTextAlignment()
    String getHeadingTextColor()
    String getHeadingTextFontName()
    int getHeadingTextFontSize()
    String getInputLabelTextColor()
    String getInputLabelTextFontName()
    int getInputLabelTextFontSize()
    String getTextColor()
    String getTextColor(LabelType labelType)
    String getTextFontName()
    String getTextFontName(LabelType labelType)
    int getTextFontSize()
    int getTextFontSize(LabelType labelType)
    String getBackgroundColor(LabelType labelType)
    int[] getPadding(LabelType labelType)
}

public class LabelCustomization {
    void setHeadingTextAlignment(NSTextAlignment textAlignment)
    void setHeadingTextColor(UIColor color)
    void setHeadingTextFontName(String fontName)
    void setHeadingTextFontSize(int fontSize)
    void setTextColor(String hexColorCode)
    void setTextColor(UIColor color)
    void setTextColor(LabelType labelType, UIColor color)
    void setTextFontName(String fontName)
    void setTextFontName(LabelType labelType, String fontName)
    void setTextFontSize(int fontSize)
    void setTextFontSize(LabelType, labelType, int fontSize)
    void setBackgroundColor(LabelType labelType, UIColor color)
    void setPadding(LabelType LabelType, UIEdgeInsets edge)

    NSTextAlignment getHeadingTextAlignment()
    UIColor getHeadingTextColor()
    String getHeadingTextFontName()
    int getHeadingTextFontSize()
    UIColor getTextColor()
    String getTextColorHex()
    String getTextFontName()
    int getTextFontSize()
}

Text Box Customization¶

The TextBoxCustomization class enables the customization of text boxes displayed throughout the challenge process.

public class TextBoxCustomization {
    void setBorderColor(String hexColorCode)
    void setBorderWidth(int borderWidth)
    void setCornerRadius(int cornerRadius)
    void setTextColor(String hexColorCode)
    void setTextFontName(String fontName)
    void setTextFontSize(int fontSize)

    String getBorderColor()
    int getBorderWidth()
    int getCornerRadius()
    String getTextColor()
    String getTextFontName()
    int getTextFontSize()
}

public class TextBoxCustomization {
    void setBorderColor(UIColor color)
    void setBorderWidth(int borderWidth)
    void setCornerRadius(int cornerRadius)
    void setTextColor(String hexColorCode)
    void setTextColor(UIColor color)
    void setTextFontName(String fontName)
    void setTextFontSize(int fontSize)

    UIColor getBorderColor()
    int getBorderWidth()
    int getCornerRadius()
    UIColor getTextColor()
    String getTextColorHex()
    String getTextFontName()
    int getTextFontSize()
}

Toolbar Customization¶

The ToolbarCustomization class enables the customization of the toolbar displayed throughout the challenge process.

public class ToolbarCustomization {
    void setBackgroundColor(String hexColorCode)
    void setButtonText(String buttonText)
    void setHeaderText(String headerText)
    void setTextColor(String hexColorCode)
    void setTextFontName(String fontName)
    void setTextFontSize(int fontSize)

    String getBackgroundColor()
    String getButtonText()
    String getHeaderText()
    String getTextColor()
    String getTextFontName()
    int getTextFontSize()
}

public class ToolbarCustomization {
    void setBackgroundColor(UIColor color)
    void setButtonText(String buttonText)
    void setHeaderText(String headerText)
    void setTextColor(String hexColorCode)
    void setTextColor(UIColor color)
    void setTextFontName(String fontName)
    void setTextFontSize(int fontSize)

    UIColor getBackgroundColor()
    String getButtonText()
    String getHeaderText()
    UIColor getTextColor()
    String getTextColorHex()
    String getTextFontName()
    int getTextFontSize()
}

Icon Customization¶

iOS Only

Along with the customization of the look-and-feel of the UI via the UI Customization class detailed above, it may be desirable to also customize the images utilized by the SDK. There are seven images used by iOS for this that can be customized via a Bundle of images with the following names:

• CollapsedLabelIndicator The icon used to indicate a section that can be collapsed.
• ExpandedLabelIndicator The icon used to indicate a section that can be expanded.
• MultiSelection The icon used for a multi selection option.
• MultiSelectionSelected The icon used for selected multi selection option(s).
• SingleSelection The icon used for a single selection option.
• SingleSelectionSelected The icon used for the selected single selection option.
• WarningIndicator: The icon used (as indicated by the ACS) to draw attention to challenge information text being displayed.

The bundle containing these images can be passed to the ThreeDS2Service constructor like so:

let threeDS2Service = ThreeDS2Service(bundle: Bundle.main)

Dark Mode¶

The 3DS SDK supports Dark Mode based on settings configured at the system level. Nothing additional needs to be done in the code. Dark mode images can be configured for each of the above as well.

Client Event Listener¶

The ClientEventListener class exposes a number of events that are fired at certain points during the SDK's operation. Below is a list of the available events:

Data Packet In¶

Fired when receiving a data packet from the server.

public class MyClientEventListener implements ClientEventListener {
    ...
    public void fireDataPacketIn(byte[] dataPacket) {
        Log.i("ClientDataPacketIn", new String(dataPacket));
    }
    ...
}

class MyClientEventListener: ClientEventListener {
    ...
    func onDataPacketIn(_ dataPacket: Data) {
        //...
    }
    ...
}

This event fires when a packet is received. The entire data packet (including all framing and error detection characters) is contained in the dataPacket parameter. This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this component.

Data Packet Out¶

Fired when sending a data packet to the server.

public class MyClientEventListener implements ClientEventListener {
    ...
    public void fireDataPacketOut(byte[] dataPacket) {
        Log.i("ClientDataPacketOut", new String(dataPacket));
    }
    ...
}

class MyClientEventListener: ClientEventListener {
    ...
    func onDataPacketOut(_ dataPacket: Data) {
        //...
    }
    ...
    }

This event fires right before each data packet is sent. The entire data packet (including all framing and error detection characters) is contained in the dataPacket parameter. This parameter may be inspected for advanced troubleshooting.

Log¶

Fires once for each log message.

public class MyClientEventListener implements ClientEventListener {
    ...
    public void fireLog(int logLevel, String message, String logType) {
        Log.i("ClientLog", logType + " - " + message);
    }
    ...
}

class MyClientEventListener: ClientEventListener {
    ...
    func onLog(_ logLevel: Int32, _ message: String, _ logType: String) {
        print("[\(logType)]\(message)")
    }
    ...
}

Logging is handled through the Log event. This will fire any time a message is built or a response is parsed, including error messages.

When the Log event is fired, the message in question is made available via the message event parameter. The other event arguments are logType and logLevel.

The logType parameter indicates the type of the log entry. Possible values are:

• Info
• RequestHeaders
• ResponseHeaders
• RequestBody
• ResponseBody
• ProxyRequest
• ProxyResponse
• FirewallRequest
• FirewallResponse
• CReq
• CRes
• Erro
• EphemeralKey
• DeviceParams
• SW

A logType of SW indicates a Security Warning. When this value is present, the message parameter will contain a code to indicate a more specific cause of the warning. Below is a list of possible warning message values and their meanings:

Android Security Warnings

iOS Security Warnings

The LogLevel configuration setting can be used to specify the detail of the logs raised through the Log event. The logLevel parameter in the event indicates the log level to which the current message belongs. Possible values are:

• 0 - None
• 1 - Info
• 2 - Verbose
• 3 - Debug

Info level logs are available by default. The LogLevel configuration setting, specified in the Client Config settings, can be used to instruct the SDK to raise more or less detailed logs.

It is recommended to output all messages raised in this event to a file for record keeping or troubleshooting purposes.

SSL Server Authentication¶

Fired after the server presents its certificate to the client.

public class MyClientEventListener implements ClientEventListener {
    ...
    public void fireSSLServerAuthentication(byte[] certEncoded, String certSubject, String certIssuer, String status, boolean[] accept) {
        //...
    }
    ...
}

class MyClientEventListener: ClientEventListener {
    ...
    func onSSLServerAuthentication(_ certEncoded: Data, _ certSubject: String, _ certIssuer: String, _ status: String, _ accept: UnsafeMutablePointer<Int32>) {
        //...
    }
    ...
}

This event fires when establishing a TLS connection and provides information about the server's certificate. The accept parameter indicates whether the certificate is trusted by default.

When accept is False, status shows why the verification failed (otherwise, status contains the string "OK"). If it is decided to continue, you can override and accept the certificate by setting the accept parameter to True.

SSL Status¶

Shows the progress of the secure connection.

public class MyClientEventListener implements ClientEventListener {
    ...
    public void fireSSLStatus(String message) {
        Log.i("ClientSSLStatus", message);
    }
    ...
}

class MyClientEventListener: ClientEventListener {
    ...
    func onSSLStatus(_ message: String) {
        //...
    }
    ...
}

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

Security Event Listener¶

The SecurityEventListener class exposes a way to be notified of security issues that occur both during initialization of the SDK and at runtime. This is done via a single alarm event:

Alarm¶

Fired when a security issue is detected.

public class MySecurityEventListener implements SecurityEventListener {
    ...
    public void alarm(Severity severity, SecurityEvent event) {
        TransactionManager.getInstance().showToast("[Security Alarm] Severity: " + severity + ", Event: " + event);
    }
    ...
}

class MySecurityEventListener: SecurityEventListener {
    ...
    func alarm(_ severity: Severity, _ event: SecurityEvent) {
        TransactionManager.transactionManager.showToast("Security alarm: [" + severity.description + "] " + event.description)
    }
    ...
}

If a security issue is detected, the Alarm event will be raised. The severity of the error will be indicated by the severity event parameter. Possible values are:

• LOW
• MEDIUM
• HIGH

The event parameter will indicate which issue was encountered. Possible values are:

• ROOT
• TAMPERED
• INSTALLED_FROM_UNTRUSTED_STORE
• HOOK
• EMULATOR
• DEBUGGING
• DEBUG_ENABLED

For more information on the security checks performed by the component, and recommendations on handling detected issues, see the Security Checks section below.

Directory Server Info¶

DirectoryServerInfo parameters are used to specify certificate details for the various supported directory servers (DS). When creating a Transaction, the DS_ID is used to specify the certificates to be used for that transaction. Each DirectoryServerInfo consists of three pieces of information:

• DS_ID: An identifier used internally in the SDK to match the transaction with a particular DS. Also referred to as a RID.
• KID: Key Identifier. There may be multiple keys for each DS with the keys each having an individual identifier.
• DS_CERT: Encryption certificate provided by the DS. Used to encrypt the DeviceInfo and generate keys to use for Challenge security.
• DS_CA_CERT: The root CA certificate used to issue the DS_CERT. This is used to verify the signature on the response from the DS (ARes packet), and can include the intermediate certificate as well.

The DS_CERT and DS_CA_CERT certificates are PEM encoded. When implementing the DSInfo class, the PEM encoded certificate content can be used as the static variable values. This is demonstrated with the example below for the GPayments TestLabs certificates:

public class DSInfo {

    public static final String DS_ID = "DS_RSA_TESTLAB_PROD";

    public static final String DS_CERT = "-----BEGIN CERTIFICATE-----\n" +
                "MIIDyzCCArOgAwIBAgIUWcqKLMtnejuVbszZM00DLPZRqO4wDQYJKoZIhvcNAQEL\n" +
                "BQAwdzELMAkGA1UEBhMCQVUxGDAWBgNVBAgMD05ldyBTb3V0aCBXYWxlczEPMA0G\n" +
                "A1UEBwwGU3lkbmV5MRIwEAYDVQQKDAlHUGF5bWVudHMxEjAQBgNVBAsMCUFjdGl2\n" +
                "ZVNESzEVMBMGA1UEAwwMQWN0aXZlU0RLLkNBMB4XDTIxMDcxNTA4MDMwOVoXDTIz\n" +
                "MTAxODA4MDMwOVowcTELMAkGA1UEBhMCQVUxGDAWBgNVBAgMD05ldyBTb3V0aCBX\n" +
                "YWxlczEPMA0GA1UEBwwGU3lkbmV5MRIwEAYDVQQKDAlBY3RpdmVTREsxEjAQBgNV\n" +
                "BAsMCUFjdGl2ZVNESzEPMA0GA1UEAwwGU0RLIHYxMIIBIjANBgkqhkiG9w0BAQEF\n" +
                "AAOCAQ8AMIIBCgKCAQEAzxcnpOaV9lGE4XWiafXtnYynlEMqrN65cqlovSd73nL4\n" +
                "WaAgl36lBVHb2/vYEjIQLcf8VNme8bb9EvQmNulyva3ifBbQKRZT96XRVAzpj5qb\n" +
                "47rpfskQ4gemR3XZZbqH2zMBPPTdXEKwkYbXPVE9riHkciLcbDO686zjsLLpTcmN\n" +
                "mqnFcJbSDggZfntKsTDro/deenKKJd8q9yDlqO8KaZkXD1M2AWBF+aOEW5QINUg4\n" +
                "C4n89Q30Wva2c1q4S9DBczBHcSQntl9xIcOKrp3//OJBP0Bl00S6CgxzpSnel1+J\n" +
                "en6cuDjbEm2WsOJrt5Nsjc+8LlYwIsuII3qd3Nuf/QIDAQABo1UwUzAfBgNVHSME\n" +
                "GDAWgBTXgOf2gz2c4gvLTz6WbTL4/QgKajAJBgNVHRMEAjAAMAsGA1UdDwQEAwIE\n" +
                "8DAYBgNVHREEETAPgg1hY3RpdmVzZGsuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCx\n" +
                "8q1JOdZub+Obv/GABj/eh4+3fSBdIuDQrCsNRC+uGWX7rfzWRQ0Px9qcK4cGbdVM\n" +
                "SVek6zpF7m8LrX7AQBSXk6CgFWrjJqkwo8OzXddE4FTXdbBYKAIb5slhIXMVzPhu\n" +
                "3DnJ/QnXc2QfwrAaXSe/vJ0eUNMm37dbJlGsLrJHFBWkZ9LphYg4Ji2TKYLIx5ek\n" +
                "3vxfj3iIFgCc/RdAHKX38sG2+cASCKxonkK8SKgcqo5rKt+b4gny9yqSMEqfvT6j\n" +
                "4CyitN6ggL3nPnecc2MFpCSIYA+ZMf0UeLREOcVSg4o8rDB/T8ZmGbDaz43E7AiB\n" +
                "sMcXGlVMEVh1isB/3SrW\n" +
                "-----END CERTIFICATE-----\n";

    public static final String DS_CA_CERT = "-----BEGIN CERTIFICATE-----\n" +
                "MIIDzzCCAregAwIBAgIUcfdJYkaK8cGVC8JX2RfP/gWKHc4wDQYJKoZIhvcNAQEL\n" +
                "BQAwdzELMAkGA1UEBhMCQVUxGDAWBgNVBAgMD05ldyBTb3V0aCBXYWxlczEPMA0G\n" +
                "A1UEBwwGU3lkbmV5MRIwEAYDVQQKDAlHUGF5bWVudHMxEjAQBgNVBAsMCUFjdGl2\n" +
                "ZVNESzEVMBMGA1UEAwwMQWN0aXZlU0RLLkNBMB4XDTIxMDcxNTA3NTc0NFoXDTI2\n" +
                "MDcxNDA3NTc0NFowdzELMAkGA1UEBhMCQVUxGDAWBgNVBAgMD05ldyBTb3V0aCBX\n" +
                "YWxlczEPMA0GA1UEBwwGU3lkbmV5MRIwEAYDVQQKDAlHUGF5bWVudHMxEjAQBgNV\n" +
                "BAsMCUFjdGl2ZVNESzEVMBMGA1UEAwwMQWN0aXZlU0RLLkNBMIIBIjANBgkqhkiG\n" +
                "9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxG68SctQctVCM1L/CIoFOr6W2TYbrx5Wj12Q\n" +
                "PTy/MWF0XZK8780iwI7xAjHeeyEMFPv/BOL6dzVtQYA/3pNCdi5uhwqBhfvxeN0V\n" +
                "jo7A8zxFLH6/JkF4PUyffn10d3rvqKddOW/0/gv1A32earnOVfhJympe1jfqgQbt\n" +
                "Za8ryOxLVujP3OSyDL9hobTevd1ffYpnFyCHC4mqJVAELEoLEFWEp4ixlRh9yvUh\n" +
                "j2icv4vHO6gE3MDWGjNoMwix3hsv6p1gQbzsUAWspg3UkjIALO3GnCY4U6Ml11jN\n" +
                "cnp9cIP33madxY93vb0oKmJHCHsdBdVGLgcXFD2+gVAroN05pwIDAQABo1MwUTAd\n" +
                "BgNVHQ4EFgQU14Dn9oM9nOILy08+lm0y+P0ICmowHwYDVR0jBBgwFoAU14Dn9oM9\n" +
                "nOILy08+lm0y+P0ICmowDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOC\n" +
                "AQEAXtGL3CI9K2QugLv0HAPL2Jj0k9JMiV8RpQbMUVPmLQm9Tk48o3RKxZpCGizN\n" +
                "VKt3Lk5ryNAWkzypYfparZow8s/fRA0dXmZtq/1Fjnj8ZJRmnYmKpIssdi+0NPr1\n" +
                "7V+2Y8g7wpinQ9w0tyMc7CVcqjlD3p++djiocjQ70HA6FdepxHF9Uj0Kzu71RecF\n" +
                "a7bqX9hdoS4dg9AkZzOQ6JF7NBcW225vhHJkQUekojW/vloJPjnR7wDTaLrQVqq3\n" +
                "gIDwo2TgF/W1rIG9bf0hNx5V3fuOk1+Pv/8SE1tMnSj/KwHEeRKIWYrVn/+sHKGQ\n" +
                "95DBV5KDrrNt5lr8CK5XhisHoQ==\n" +
                "-----END CERTIFICATE-----\n";

}

Using pre-configured Directory Server DS_ID's¶

In addition to adding the DirectoryServerInfo parameters above, the SDK comes pre-configured with DirectoryServerInfo for some card schemes production Directory Servers. Supported card schemes are:

To use the above pre-configured DS_DS's, just specify the DS_ID in the Creating a Transaction section. When using this pre-configured DS_ID no certificate is required for the DirectoryServerInfo parameter.

Client Config¶

The SDK accepts additional optional configuration settings which alter the behavior of the SDK. These are set as SETTING=VALUE pairs, and set as the clientConfig when building the ConfigParameters.

Log Level¶

This setting specifies the level of logging enabled in the component. Possible values include:

This is set to 1 (Info) by default.

Mask Sensitive¶

This setting controls whether sensitive data is masked in the Log event. When set to True (default) the card number value will be replaced with the value *************.

Note: DataPacketOut will always contain the raw unmasked value regardless of this setting. This setting only applies to the Log event.

The default value is True.

Security Checks¶

The SDK performs security checks and collects device information during initialization. Warnings produced during the 3DS SDK initialization process can be retrieved using the getWarnings method, which returns a list of Warning objects. These can be checked by the app to determine whether to proceed with the checkout process or not:

/* check warnings */
List<Warning> warnings = ThreeDS2Service.INSTANCE.getWarnings();
if (warnings.size() > 0) {
    // process warnings
    // abort the checkout if necessary
}

// check warnings
let warnings = try threeDS2Service.getWarnings()
if warnings.count > 0 {
    // process warnings
    // abort the checkout if necessary
}

The Warning object consists of the following fields:

The following warnings are documented in the EMVCo specification:

To be notified of security issues both at initialization and at runtime, it is recommended to use the Security Event Listener as well.

Security Checks Performed During Initialization¶

The following security checks are performed during initialization of the SDK:

• Root detection: several ways of detecting if the device is rooted
• SDK tampering detection: including app signer fingerprint validation, hook detection, and malicious app detection
• Checks to make sure the app was installed from trusted app stores
• Emulator detection
• Detection of an attached debugger
• OS version detection

These initialization checks result in warnings accessible via the getWarnings detailed above. The message will contain a description of the issue encountered.

Security Checks Performed at Runtime¶

The following security checks are performed at runtime:

Android Security Checks

• Emulator detection (high severity): during Transaction.getAuthenticationRequestParameters()
• Debugging detection (medium severity): during Transaction.doChallenge()
• Root detection (high severity): during Transaction.doChallenge()
• Hook detection (high severity): during ThreeDS2Service.createTransaction(), and during the challenge process when the Submit/Resend/Cancel buttons are clicked
• Debug enabled detection (low severity): during Transaction.doChallenge()

iOS Security Checks

• Emulator detection (high severity): during Transaction.doChallenge()
• Debugging detection (medium severity): during Transaction.doChallenge()
• Method Swizzle Hook detection (high severity): during Transaction.getAuthenticationRequestParameters() and Transaction.doChallenge()
• Fishhook detection (high severity): during Transaction.getAuthenticationRequestParameters() and Transaction.doChallenge()
• Anti-debug (preventative): during Transaction.getAuthenticationRequestParameters()

These runtime checks result in firing of the Security Event Listener alarm event, and the activity closing for high severity issues. In the development version of the SDK (without _deploy in the file name), these checks are not performed.

Creating a Transaction¶

Call the createTransaction method to start a transaction. A reference should be kept for this transaction throughout the entire 3-D Secure process. This method takes the directory server ID, which points to a DirectoryServerInfo configuration parameter added during SDK initialization. The second parameter is a protocol version as a string. Supported version strings are 2.1.0 and 2.2.0.

sdkTransaction = ThreeDS2Service.INSTANCE.createTransaction(DSInfo.DS_ID, "2.2.0");

sdkTransaction = try threeDS2Service.createTransaction(DSInfo.DS_ID, "2.2.0")

For information regarding the DS_ID, refer to the Directory Server Info section.

Later, when the transaction is complete, it should be closed via the Transaction object's close method.

Displaying Progress¶

A progress dialog must be displayed to the end user at certain points in the 3-D Secure process. While performing the challenge, the 3DS SDK will automatically display a progress dialog when appropriate.

A progress dialog must also be displayed to the user while the application is communicating with the 3DS Server and waiting for the authentication request results. The dialog used by the 3DS SDK is available to be used by the application if desired, and can be obtained from the Transaction object via the getProgressView method like so:

// The progress dialog is an instance of android.app.ProgressDialog
ProgressDialog sdkProgressDialog;

// Retrieve the progress dialog from the transaction object instance
sdkProgressDialog = sdkTransaction.getProgressView(mActivity);
sdkProgressDialog.show();

// Later, to hide/dismiss:
sdkProgressDialog.dismiss();

// The progress dialog is an instance of ProgressView
var sdkProgressDialog: ProgressView?

// Retrieve the progress dialog from the transaction object instance
sdkProgressDialog = try sdkTransaction?.getProgressView()
sdkProgressDialog?.show()

// Later, to hide/dismiss if desired:
sdkProgressDialog?.close()

The 3DS SDK will automatically hide the dialog when starting the challenge process, so there is no need to explicitly dismiss the dialog in the application code.

Authenticating¶

The authentication process starts with a call to the Transaction object's getAuthenticationRequestParameters method. When this method is called, the 3DS SDK will encrypt the device information it collected during initialization and make it, along with other SDK information required by the 3DS Server, available in the returned AuthenticationRequestParameters object. This AuthenticationRequestParameters object consists of the following fields:

The AuthRequest property is a packaged form of the other properties. The app would transmit this to the 3DS Server via a communication channel outside the scope of the 3DS SDK itself. Please refer to 3DS Requestor for the authentication message exchange implementation with ActiveServer. For other 3DS Server implmentations, please consult their documentation for details

Response Handling¶

The 3DS Server is responsible for reading the authentication response from the directory server and indicating to the client (in this case, the app) whether a challenge is required or not. For ActiveServer, check the TransStatus property after the authentication message exchange has been completed. If this is a value of C or D, a challenge is required.

If no challenge is required (frictionless flow), or authentication cannot be performed for some reason, no further action is required from a 3-D Secure standpoint. Proceed to the Completing Authentication section for details on closing the transaction.

If a challenge is required, the 3DS Server should return the required parameters to the app for use when starting the challenge process. The Performing a Challenge section details how to perform the challenge.

Performing a Challenge¶

If a challenge is required, the challenge is performed by creating the Challenge Parameters (using the authentication response from the 3DS Server) and following the steps in the Starting the Challenge section. The SDK will take care of all communication with the ACS while performing the challenge, as well as prompting the user as needed for the required input. When the challenge process is complete, the relevant Challenge Status Receiver callback will fire.

Challenge Status Receiver¶

ChallengeStatusReceiver is an interface used to obtain the result of the SDK challenge process. This should be implemented in the application and passed to the doChallenge method when Starting the Challenge. When the challenge process has finished, either successfully or in error, one of the following corresponding methods will be called:

Example implementations of these methods can be found below:

@Override
public void completed(CompletionEvent completionEvent) {
    showToast("Challenge completed with transactionStatus " + completionEvent.getTransactionStatus());
    closeTransaction();
}

@Override
public void cancelled() {
    showToast("Challenge cancelled.");
    closeTransaction();
}

@Override
public void timedout() {
    showToast("Challenge timed out.");
    closeTransaction();
}

@Override
public void protocolError(ProtocolErrorEvent protocolErrorEvent) {
    showToast("Challenge protocolError: " +
        protocolErrorEvent.getErrorMessage().getErrorDescription() + "\t" +
        protocolErrorEvent.getErrorMessage().getErrorDetails());
    closeTransaction();
}

@Override
public void runtimeError(RuntimeErrorEvent runtimeErrorEvent) {
    showToast("Challenge runtimeError: " + runtimeErrorEvent.getErrorMessage());
    closeTransaction();
}

// Helper method  
public void closeTransaction() {
    if (sdkTransaction != null) {
        sdkTransaction.close();
        sdkTransaction = null;
    }
    sdkProgressDialog = null;
}

func completed(_ completionEvent: CompletionEvent) {
  showToast("Challenge completed with transactionStatus " + completionEvent.getTransactionStatus())
  try? closeTransaction()
}

func cancelled() {
  showToast("Challenge cancelled.")
  try? closeTransaction()
}

func timedout() {
  showToast("Challenge timed out.")
  try? closeTransaction()
}

func protocolError(_ protocolErrorEvent: ProtocolErrorEvent) {
  showToast("Challenge protocolError: " +
    protocolErrorEvent.getErrorMessage().getErrorDescription() + "\t" +
    protocolErrorEvent.getErrorMessage().getErrorDetails());
  try? closeTransaction()
}

func runtimeError(_ runtimeErrorEvent: RuntimeErrorEvent) {
  showToast("Challenge runtimeError: " + runtimeErrorEvent.getErrorMessage());
  try? closeTransaction()
}
// Helper method
func closeTransaction() throws {
  if sdkTransaction != nil {
    try sdkTransaction?.close()
    sdkTransaction = nil
  }
}

Challenge Parameters¶

The ChallengeParameters class holds parameters that are required to conduct the challenge process. This is passed to the doChallenge method when Starting the Challenge. Available properties, accessible via getters and setters, are:

These properties can be set individually based on what comes back from the 3DS Server. If using the 3DS Server component, the ThreeDSServerAuthResponse can be set to the generated ClientAuthResponse value, and the other properties will be set automatically based on this value.

ChallengeParameters challengeParameters = new ChallengeParameters();
challengeParameters.setThreeDSServerAuthResponse(authResponse);

let challengeParameters = ChallengeParameters(threeDSServerAuthResponse: authResponse)

Starting the Challenge¶

If the response from the 3DS Server indicates that a challenge is required, the challenge process is initiated using the doChallenge method. When this is called, control of the UI is handed over to the 3DS SDK. The challenge will be performed by the SDK, and when finished the appropriate Challenge Status Receiver event will fire (completed, cancelled, etc.)

sdkTransaction.doChallenge(currentActivity, challengeParameters, this, 5);

try sdkTransaction?.doChallenge(rootViewController: navigationController, challengeParameters: challengeParameters, challengeStatusReceiver: self, timeout: 5)

The doChallenge method takes the following parameters:

Android Challenge Parameters

iOS Challenge Parameters

Completing Authentication¶

If the completed callback fires, the CompletionEvent parameter will contain more details on the authentication results. This has two properties: sdkTransactionID, and transactionStatus. The transactionStatus contains the transStatus from the last CRes packet, which would be one of the values below:

• Y: Order completed successfully / Authentication successful
• A: Order completed successfully / Attempts processing performed
• N: Order denied / Not authenticated (denied)
• R: Order denied / Authentication rejected
• U: Order failed due to technical reasons / Authentication could not be performed

Managing Resources¶

The cleanup method frees up resources that are used by the 3DS SDK. It is called only once during a single 3DS Requestor App session:

ThreeDS2Service.INSTANCE.cleanup(applicationContext);

threeDS2Service.cleanup();

Get authentication result¶

For frictionless flow, the authentication result will return to the mobile App at the end of the authentication process. For challenge flow, a transStatus=C will be returned to the mobile App and a challenge process will be executed between Active SDK and the ACS. After the challenge is complete, for ActiveServer, the mobile App should call getResult endpoint to get the authentication result. Check the Requestor section for details of the getResult endpoint.

Application Permission Notes¶

The SDK itself does not require any specific permissions outside of internet access, and it will use only the permissions that the application has requested. The app should require permission before the SDK is initialized. This is required by the specification and some device parameters will not be available if permission is not granted.

For a full list of required permissions for each device parameter, see the EMV 3-D Secure SDK Device Information document, which can be obtained from EMVCo directly.