SDK Configuration
This section describes how the Netcetera Android 3DS SDK should be configured.
API Key Configuration
An API key is distributed along with the SDK. In order to be able to use the Netcetera Android 3DS SDK, the API key must be added in the ConfigParameters which are passed in the Initialization of the ThreeDS2Service.
Configuration with ConfigurationBuilder (Recommended)
The ConfigurationBuilder feature of the Netcetera Android 3DS SDK can be used for setting the API key. This feature provides easier integration and configuration of the SDK.
To define the API key use ConfigurationBuilder.apiKey(...) with the following arguments
| Argument | Value |
|---|---|
apiKey | The provided API key as a String |
Example:
Configuration with ConfigParameters
To define the API key without the use of a ConfigurationBuilder, use ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | null |
paramName | "api_key" |
paramValue | The provided API key as a String |
Example:
Directory Server Configuration
When a transaction is initiated, the SDK gets the information about the Directory Server that will participate in the message flow. With that, the SDK determines which DS public key should be used for data encryption and which DS logo should be shown.
The SDK uses the DS public key and the DS logo. These are configured in the ConfigParameters in Initialization.
The encryption key or certificate and the root certificate can be obtained from each scheme respectively.
Following are the steps for the DS configuration:
- Schemes - Which schemes can be used.
- DS IDs - DS IDs that belong to a certain scheme.
- Schemes public key - Public key for each scheme used for encryption of the device data.
- Schemes root public key - Public key for each scheme used for verification of the certificate chain in the
acsSignedContentduring a challenge flow. - Scheme logo Resource ID - Drawable Resource ID for each scheme that will be used as logo.
- Scheme dark logo Resource ID - Drawable Resource ID for each scheme that will be used as dark mode logo.
If public keys are provided, the keys can be either EC or RSA in PEM format. If certificates are provided, they need to be in the X.509 standard in either PEM or DER format.
Integrator defined schemes will take priority over Pre-configured Directory Server Configurations (which are subject to automatic updates).
If the integrator wishes to utilise the automatic updates of the Pre-configured Directory Servers, they should not be updated/overridden.
Configuration with ConfigurationBuilder (Recommended)
The ConfigurationBuilder is a feature that is not defined in the specification, but has been provided by the Netcetera Android 3DS SDK to allow easier configuration of the ConfigParameters. It provides ease of use methods to set the required fields for new or existing schemes, as to prevent possible misconfigurations.
Configuring schemes
To define the scheme, use the ConfigurationBuilder.configureScheme(...) with the following arguments
| Argument | Value |
|---|---|
schemeConfiguration | The configuration of the scheme |
SchemeConfiguration
The Netcetera Android 3DS SDK provides a utility class to help with the configuration of the scheme. To define a new scheme use SchemeConfiguration.newSchemeConfiguration... with the following arguments:
| Argument | Value |
|---|---|
schemeName | The name of the current scheme |
schemeIds | List containing the DS ids for the scheme. |
schemeLogo | String value of Drawable Resource ID for the standard logo |
schemeLogoDark | String value of Drawable Resource ID for the dark logo |
encryptionPublicKey | ASN.1 encoding of the public key or the certificate (DER/PEM) in Base64 encoded format |
rootPublicKey | ASN.1 encoding of the public root key or the certificate (DER/PEM) in Base64 encoded format. Multiple root keys or certificates can be included. |
certificatePath | The path of the certificate (DER/PEM) in Base64 encoded format placed in the "assets" directory. |
Example:
The utility class also includes the option to modify a pre-configured scheme. For that purpose use SchemeConfiguration.{DSName}SchemeConfiguration..., with the aforementioned arguments, where {DSName} is the name of the scheme corresponding with a directory server from Pre-configured Directory Servers. The argument values that won't be specified shall be taken from Pre-configured Directory Servers.
Example:
Configuration with ConfigParameters
Configuring Schemes Directory Servers
To define the scheme DS, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | null |
paramName | "schema_names" |
paramValue | Comma separated values of schemes. |
Example:
Configuring DS IDs
To define the DS IDs that belong to certain scheme, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | "schema_ds_ids" |
paramName | The name of the scheme to define for. |
paramValue | Comma separated values of each DS id for the scheme. |
The 3DS Requestor App uses the Cardholder Account Number and optionally other cardholder information to identify the DS ID. A DS ID is the Scheme's Card RID (Registered application provider identifier). The identifier, usually 5 bytes in length, is issued by the ISO/IEC 7816-5 registration authority and is used to address an application in the card. For example, an RID could be: A000000003. Please refer to the configuration for more RID values.
Example:
Configuring DS Public Keys
To define the public key that will be used for certain scheme, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | "schema_public_key" |
paramName | The name of the scheme to define for. |
paramValue | ASN.1 encoding of the public key or the certificate (DER/PEM) in Base64 encoded format. |
Example:
Configuring DS Root Public Keys
To define the root public keys that will be used for certain scheme, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | "schema_root_public_key" |
paramName | The name of the scheme to define for. |
paramValue | Comma separated values of ASN.1 encoding of the public key or the certificate (DER/PEM) in Base64 encoded format. |
Note: To ensure a higher percentage of successful transactions, in the event where the configured root certificate cannot verify the acsSignedContent, the Netcetera 3DS SDK will try to use the corresponding Pre-configured DS Root Public Key instead.
Example:
Configuring Logos
A scheme can have 2 logos configured - standard and dark logo. The standard logo is mandatory for each scheme and therefore must be present either in the 3DS SDK preconfigured data or configured by the Requestor Application. On the other hand, the dark logo is optional and will only be used in case the Requestor Application enables dark mode on the 3DS SDK and necessary system conditions are met. If the 3DS SDK needs to use a dark logo that is missing, it will use the standard logo displayed under white surface as a fallback instead.
To define the standard logo that will be used for a certain scheme, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | "schema_logo" |
paramName | The name of the scheme to define for. |
paramValue | String value of Drawable Resource ID. |
To define the dark logo that will be used for a certain scheme, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | "schema_logo_dark" |
paramName | The name of the scheme to define for. |
paramValue | String value of Drawable Resource ID. |
Example:
Pre-configured Directory Servers
The Netcetera Android 3DS SDK comes bundled with configuration for the following directory servers, listed in the tables below.
Pre-configured certificates:
3ds2.directory.mastercard.com Expiry: 15.06.2024 | PRD MasterCard Identity Check Root CA Expiry: 15.07.2030 | ||
3ds2.rsa.encryption.visa.com Expiry: 22.08.2024 | Visa Public RSA Root CA Expiry: 15.03.2041 | ||
sdk.safekey.encryptkey.com Expiry: 24.05.2025 | American Express Private Certification Authority Expiry: 11.08.2029 | ||
Discover SDK Key | ProtectBuy Root Expiry: 03.02.2027 | ||
ds2apr.jcb-tds.com Expiry: 03.03.2051 | JCB DS Root CA EMV 3-D Secure Expiry: 09.01.2036 | ||
CFCA@UnionPay International@N9131000005455878X6@1 Expiry: 08.07.2025 | CFCA ACS CA Expiry: 28.09.2035 | ||
CartesBancaires SDK Key | Root 3DS CB CA Expiry: 31.07.2048 | ||
EFTPOS SDK Key Expiry: 31.08.2025 | eftpos Prod Root CA Expiry: 06.10.2030 |
Pre-configured logos:
R.drawable.ds_logo_mastercard | R.drawable.ds_logo_mastercard_dark | |
R.drawable.ds_logo_visa | R.drawable.ds_logo_visa | |
R.drawable.ds_logo_amex | R.drawable.ds_logo_amex_dark | |
R.drawable.ds_logo_diners | R.drawable.ds_logo_diners | |
R.drawable.ds_logo_jcb | R.drawable.ds_logo_jcb | |
R.drawable.ds_logo_mir | R.drawable.ds_logo_mir | |
R.drawable.ds_logo_union | R.drawable.ds_logo_union | |
R.drawable.ds_logo_cb | R.drawable.ds_logo_cb | |
R.drawable.ds_logo_eftpos | R.drawable.ds_logo_eftpos |
The binding between the configuration and the pre-configured values is done with the RID value of the Directory Server.
The configuration has precedence over pre-configured values and overwrites them i.e. if a configuration is provided for a parameter, that one will be used, instead of the pre-configured one.
Note: The pre-configured DS Public Key and DS Root Public Key serve for convenience, while the integrators have to verify their compatibility to the Directory Server. The integrators are encouraged to complete the configuration.
DS RID Values
The Netcetera Android 3DS SDK has a utility API DsRidValues that contains the DS RIDs for the SDK Preconfigured Schemes.
UI Customization
The Netcetera Android 3DS SDK supports customization of the challenge UI elements that are being shown by the SDK. The UI Customization API offers Button, Label, Toolbar and TextBox customization. For this purpose the UiCustomization class shall be configured and passed in the initialize method of the SDK. If a challenge UI element is not configured, the SDK will use the default values for that element.
Note: The "UiCustomizationType.DARK" customization will only be applied when the device is running Android 10 or higher, and dark mode is active in the system settings.
Label Customization
The LabelCustomization allows integrators to customize the format of the texts presented on the challenge screens. There are two different types of texts that can be customized through the LabelCustomization API: Heading and content texts.
To customize challenge labels, invoke setLabelCustomization(...) on a UiCustomization object and pass the LabelCustomization object as a parameter.
LabelCustomization API:
| Method Name | Customizes | Default LIGHT | Default DARK |
|---|---|---|---|
setTextFontName | Content text font name | sans-serif | sans-serif |
setTextColor | Content text color | #000000 | #ffffff |
setTextFontSize | Content text font size | 16 | 16 |
setHeadingTextFontName | Heading text font name | sans-serif | sans-serif |
setHeadingTextColor | Heading text color | #000000 | #ffffff |
setHeadingTextFontSize | Heading text font size | 24 | 24 |
Toolbar Customization
The ToolbarCustomization allows integrators to customize the toolbar presented at the top of each challenge screen.
To customize the toolbar, invoke setToolbarCustomization(...) on a UiCustomization object and pass the ToolbarCustomization object as a parameter.
ToolbarCustomization API:
| Method Name | Customizes | Default LIGHT | Default DARK |
|---|---|---|---|
setTextFontName | Toolbar header text font name | sans-serif | sans-serif |
setTextColor | Toolbar header text color | #000000 | #ffffff |
setTextFontSize | Toolbar header text font size | 18 | 18 |
setBackgroundColor | Toolbar background color | #fbfbfb | #000000 |
setHeaderText | Toolbar title text | "SECURE CHECKOUT" | "SECURE CHECKOUT" |
setButtonText | Toolbar cancel button text | "Cancel" | "Cancel" |
TextBox Customization
The TextBoxCustomization allows integrators to customize the text fields presented on the challenge screens.
To customize the text fields, invoke setTextBoxCustomization(...) on a UiCustomization object and pass the TextBoxCustomization object as a parameter.
TextBoxCustomization API:
| Method Name | Customizes | Default LIGHT | Default DARK |
|---|---|---|---|
setTextFontName | Input text font name | sans-serif | sans-serif |
setTextColor | Input text color | #565a5c | #ffffff |
setTextFontSize | Input text font size | 16 | 16 |
setBorderWidth | Text field border width | 4 | 4 |
setBorderColor | Text field border color | #565a5c | #ffffff |
setCornerRadius | Text field corner curvature | 4 | 4 |
UI Customization Example
Accessibility Recommendation
The Netcetera Android 3DS SDK follows the latest guidelines and best practices defined by Google for building accessible apps.
If a custom UiCustomization is provided to the 3DS SDK, we recommend that a tool such as the Accessibility Scanner is used to check for any accessibility improvements on the custom UI.
Restricted Device Info Parameters Configuration
Configuration with ConfigurationBuilder (Recommended)
To define which device info parameters shall be considered as restricted and thus not collected, use the ConfigurationBuilder.restrictedParameters(...) with the following arguments:
| Argument | Value |
|---|---|
restrictedParameters | List containing the IDs of the device info parameters. |
Example:
List of device info parameters and their corresponding IDs can be found in EMVCo's 3DS SDK Device Info specification. If a entry in the restricted device info parameters configuration has value that doesn't correspond to any predefined device info parameter ID, an InvalidInputException is thrown.
Configuration with ConfigParameters
To define which device info parameters shall be considered as restricted and thus not collected, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | null |
paramName | "restricted_device_info_parameters" |
paramValue | Comma separated values of IDs of the device info parameters. |
Example:
Bridging Message Extension Configuration
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.
Due to inconsistencies in the Bridging Message Extension Specification, different providers might have different implementations on the Bridging Message Extension API, which might lead to failed transactions.
If support for the Bridging Message Extension is enabled, 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.
Support for the Bridging Message Extension is disabled by default.
Configuration with ConfigurationBuilder (Recommended)
To define if the Netcetera Android 3DS SDK should support the Bridging Message Extension, use the ConfigurationBuilder.supportBridgingMessageExtension(...) with the following arguments:
| Argument | Value |
|---|---|
supportBridgingMessageExtension | boolean value of true or false. |
Example:
Configuration with ConfigParameters
To define if the Netcetera Android 3DS SDK should support the Bridging Message Extension, use the ConfigParameters.addParam(...) with the following arguments:
| Argument | Value |
|---|---|
group | null |
paramName | "bridging_message_extension_support" |
paramValue | String representation of boolean value "true" or "false". |
Example:
Logging Configuration
The Netcetera Android 3DS SDK uses SLF4J for logging purposes, logging only messages on level WARN and ERROR. The logging of these log levels can be configured by using any logging implementation on top of SLF4J.
Sample implementation that uses logback-android can be found in the guide for the demo reference application and the source code itself.
Permissions
This section describes which Android permissions are required to be granted and which are optional.
| Permission | Mandatory | Description |
|---|---|---|
android.permission.INTERNET | Yes | Required for communication with the ACS in Challenge Flow. Must be permitted before Starting of Challenge Flow. |
android.permission.ACCESS_COARSE_LOCATION | No | Required for collecting the device coarse location that will be provided as device info parameter. Should be permitted before Initialization. |
android.permission.ACCESS_FINE_LOCATION | No | Required for collecting the device fine location that will be provided as device info parameter. Should be permitted before Initialization. |
android.permissions.ACCESS_NETWORK_STATE | No | Required for collecting device's IP Address that will be provided as device info parameter. Should be permitted before Initialization. |
android.permission.BLUETOOTH | No | Required for collecting bluetooth hardware info that will be provided as device info parameter. Should be permitted before Initialization. |
android.permission.READ_PHONE_STATE | No | Required for collecting Telephony information that will be provided as device info parameters. Should be permitted before Initialization. |
android.permission.SEND_SMS | No | Required for collecting Telephony information that will be provided as device info parameters. Should be permitted before Initialization. |
android.permission.ACCESS_WIFI_STATE | No | Required for collecting WiFi and Network related information that will be provided as device info parameters. Should be permitted before Initialization. |
Scheme Specific Requirements
This section lists additional requirements that the integrator of the Netcetera Android 3DS SDK needs to fulfill in order to be compliant with the requirements of a specific scheme.
Amex
| Type | Description | EMVCo Requirement | Amex | Enforceability |
|---|---|---|---|---|
| Modification | Maximum duration of the challenge process provided in Transaction.doChallenge(..., timeout) | Minimum 5 minutes | Recommended 10 minutes | Recommended |