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 ConfigParameters

To define the API key without the use of a ConfigurationBuilder, use ConfigParameters.addParam(...) with the following arguments:

ArgumentValue
groupnull
paramName"api_key"
paramValueThe 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 following can be obtained from each scheme respectively:

  • Encryption Public Key or Certificate
  • ID corresponding to the Encryption Public Key or Certificate
  • Root Certificate

Following are the steps for the DS configuration:

  1. Schemes - Which schemes can be used.
  2. DS IDs - DS IDs that belong to a certain scheme.
  3. Scheme public key - Public key for each scheme used for encryption of the device data.
  4. Scheme public key ID - The value which identifies the Scheme Public Key to the Directory Server.
  5. Scheme root public key - Public key for each scheme used for verification of the certificate chain in the acsSignedContent during a challenge flow.
  6. Scheme logo Resource ID - Drawable Resource ID for each scheme that will be used as logo.
  7. 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 ConfigParameters

Configuring Schemes Directory Servers

To define the scheme DS, use the ConfigParameters.addParam(...) with the following arguments:

ArgumentValue
groupnull
paramName"schema_names"
paramValueComma 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:

ArgumentValue
group"schema_ds_ids"
paramNameThe name of the scheme to define for.
paramValueComma 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:

ArgumentValue
group"schema_public_key"
paramNameThe name of the scheme to define for.
paramValueASN.1 encoding of the public key or the certificate (DER/PEM) in Base64 encoded format.

Example:

Configuring DS Public Keys IDs

To define the Public Key ID that will be used for a certain scheme, use the ConfigParameters.addParam(...) with the following arguments:

ArgumentValue
group"schema_public_key_id"
paramNameThe name of the scheme to define for.
paramValueThe value which identifies the Scheme Public Key to the Directory Server.

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:

ArgumentValue
group"schema_root_public_key"
paramNameThe name of the scheme to define for.
paramValueComma 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:

ArgumentValue
group"schema_logo"
paramNameThe name of the scheme to define for.
paramValueString 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:

ArgumentValue
group"schema_logo_dark"
paramNameThe name of the scheme to define for.
paramValueString 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:

Scheme
RIDs
DS Public Key
DS Root Public Key
Mastercard
A000000004

3ds2.directory.mastercard.com
Expiry: 15.07.2026
Key ID: 116f90eee124062e2ca9c8efeb54802c34d963a0

PRD MasterCard Identity Check Root CA
Expiry: 15.07.2030
Visa
A000000003

3ds2.rsa.encryption.visa.com
Expiry: 26.02.2027
Key ID: 747da056-476c-4296-a7c4-7e853e235ef0

Visa Public RSA Root CA
Expiry: 15.03.2041
Amex
A000000025

sdk.safekey.encryptkey.com
Expiry: 24.05.2025
Key ID: e61eba5c0dee8d641ea0998b28f2b7250bdb4073

American Express Private Certification Authority
Expiry: 11.08.2029
Diners
A000000152

Discover SDK Key
Expiry: 07.03.2027
Key ID: N/A

ProtectBuy Root
Expiry: 03.02.2027
JCB
A000000065

ds2apr.jcb-tds.com
Expiry: 03.03.2051
Key ID: N/A

JCB DS Root CA EMV 3-D Secure
Expiry: 09.01.2036
Union
A000000333

CFCA@UnionPay International@N9131000005455878X6@1
Expiry: 08.07.2025
Key ID: 6b764f94ff7450e94ca908c85a0dfe88f717d710

CFCA ACS CA
Expiry: 28.09.2035
Cartes Bancaires
A000000042

CartesBancaires SDK Key
Key ID: N/A

Root 3DS CB CA
Expiry: 31.07.2048
EFTPOS
A000000384

EFTPOS SDK Key
Expiry: 31.08.2025
Key ID: a636bc0f47eb3b8862d3084cb8fd5c537f4a9712

eftpos Prod Root CA
Expiry: 06.10.2030

Pre-configured logos:

Scheme
DS Logo
DS Dark Logo
Mastercard

R.drawable.ds_logo_mastercard

R.drawable.ds_logo_mastercard_dark
Visa

R.drawable.ds_logo_visa

R.drawable.ds_logo_visa
Amex

R.drawable.ds_logo_amex

R.drawable.ds_logo_amex_dark
Diners

R.drawable.ds_logo_diners

R.drawable.ds_logo_diners
JCB

R.drawable.ds_logo_jcb

R.drawable.ds_logo_jcb
Union

R.drawable.ds_logo_union

R.drawable.ds_logo_union
Cartes Bancaires

R.drawable.ds_logo_cb

R.drawable.ds_logo_cb
EFTPOS

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.

Button Customization

The ButtonCustomization allows integrators to customize the buttons presented on the challenge screens. There are 7 button types utilized by the challenge screens: SUBMIT, CONTINUE, NEXT, RESEND, OPEN_OOB_APP, ADD_CH and CANCEL. Each button can be customized separately. A single ButtonCustomization can be used for multiple buttons. If needed, the integrator can configure a separate UiCustomization for each UI appearance (DEFAULT and DARK).

To customize a challenge button, invoke setButtonCustomization(...) on a UiCustomization object and pass the ButtonCustomization as well as the ButtonType on which that customization should be applied.

ButtonCustomization API:

Method NameCustomizesDefault Value
setTextFontNameButton text fontsans-serif
setTextColorButton text colorOutlined per Button Type in the table below
setTextFontSizeButton text font size16
setBackgroundColorButton background colorOutlined per Button Type in the table below
setCornerRadiusButton corner curvature4

Color defaults per Button Type:

Button TypeDefault Text Color LIGHTDefault Background Color LIGHTDefault Text Color DARKDefault Background Color DARK
SUBMIT#ffffff#006dff#006dff#ffffff
CONTINUE#ffffff#006dff#006dff#ffffff
NEXT#ffffff#006dff#006dff#ffffff
RESEND#000000#bbdbff#697587#ffffff
OPEN_OOB_APP#ffffff#006dff#006dff#ffffff
ADD_CH#000000#bbdbff#697587#ffffff
CANCEL#000000#00000000#ffffff#00000000

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 NameCustomizesDefault LIGHTDefault DARK
setTextFontNameContent text font namesans-serifsans-serif
setTextColorContent text color#000000#ffffff
setTextFontSizeContent text font size1616
setHeadingTextFontNameHeading text font namesans-serifsans-serif
setHeadingTextColorHeading text color#000000#ffffff
setHeadingTextFontSizeHeading text font size2424

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 NameCustomizesDefault LIGHTDefault DARK
setTextFontNameToolbar header text font namesans-serifsans-serif
setTextColorToolbar header text color#000000#ffffff
setTextFontSizeToolbar header text font size1818
setBackgroundColorToolbar background color#fbfbfb#000000
setHeaderTextToolbar title text"SECURE CHECKOUT""SECURE CHECKOUT"
setButtonTextToolbar 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 NameCustomizesDefault LIGHTDefault DARK
setTextFontNameInput text font namesans-serifsans-serif
setTextColorInput text color#565a5c#ffffff
setTextFontSizeInput text font size1616
setBorderWidthText field border width44
setBorderColorText field border color#565a5c#ffffff
setCornerRadiusText field corner curvature44

View Customization

The ViewCustomization allows integrators to customize the challenge screen and progress screen.

To customize the challenge or progress screen, invoke setViewCustomization(...) on a UiCustomization object and pass the ViewCustomization object as a parameter.

ViewCustomization API:

Method NameCustomizesDefault LIGHTDefault DARK
setChallengeViewBackgroundColorChallenge Screen background#ffffff#121212
setProgressViewBackgroundColorProgress Screen background#ffffff#121212

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 ConfigParameters

To define which device info parameters shall be considered as restricted and thus not collected, use the ConfigParameters.addParam(...) with the following arguments:

ArgumentValue
groupnull
paramName"restricted_device_info_parameters"
paramValueComma separated values of IDs of the device info parameters.

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.

PermissionMandatoryDescription
android.permission.INTERNETYesRequired for communication with the ACS in Challenge Flow. Must be permitted before Starting of Challenge Flow.
android.permission.ACCESS_COARSE_LOCATIONNoRequired for collecting the device coarse location that will be provided as device info parameter. Should be permitted before Initialization.
android.permission.ACCESS_FINE_LOCATIONNoRequired for collecting the device fine location that will be provided as device info parameter. Should be permitted before Initialization.
android.permissions.ACCESS_NETWORK_STATENoRequired for collecting device's IP Address that will be provided as device info parameter. Should be permitted before Initialization.
android.permission.BLUETOOTHNoRequired for collecting bluetooth hardware info that will be provided as device info parameter. Should be permitted before Initialization.
android.permission.READ_PHONE_STATENoRequired for collecting Telephony information that will be provided as device info parameters. Should be permitted before Initialization.
android.permission.SEND_SMSNoRequired for collecting Telephony information that will be provided as device info parameters. Should be permitted before Initialization.
android.permission.ACCESS_WIFI_STATENoRequired 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

TypeDescriptionEMVCo RequirementAmexEnforceability
ModificationMaximum duration of the challenge process provided in Transaction.doChallenge(..., timeout)Minimum 5 minutesRecommended 10 minutesRecommended