SDK Configuration
This section describes how the Netcetera iOS 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 iOS 3DS SDK, the API key must be added in the ConfigParameters which are passed in the Initialization of the ThreeDS2Service.
Using ConfigurationBuilder (Recommended)
The easiest way to configure the API key is through the ConfigurationBuilder. This is done by using the api(key: String) function. The builder helps to populate the ConfigParameters in a less error-prone manner.
After setting all of the values in the builder, simply call .configParameters() to generate the ConfigParameters object that can be passed in the initialize method of ThreeDS2Service class.
Example:
Configuration with ConfigParameters
To define the API key without the use of a ConfigurationBuilder, use ConfigParameters.addParameters(...) with the following arguments:
| Argument | Value |
|---|---|
group | nil |
paramName | "api-key" |
paramValue | The 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 (or in some cases multiple root certificates) 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 keys - Public keys for each scheme used for verification of the certificate chain in the
acsSignedContentduring a challenge flow. - Scheme logo Resource ID - Image Asset for each scheme that will be used as logo.
- Scheme dark logo Resource ID - Image Asset for each scheme that will be used as dark mode logo.
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 iOS 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.
Example:
Predefined values can be overridden. To load a Scheme object for a certain scheme, call the static functions from the Scheme class with the scheme name.
Example:
If the SDK is configured with both a property list and the ConfigurationBuilder, the later one will have priority. Moreover, if part of the parameters for a Scheme, or the same parameters are configured in both places, the values from the ConfigurationBuilder will take priority and will override the values from the property list.
Note: If both configurations are used for a given scheme, make sure the same name is used in both places.
Configuring with property list file
When configuring with property list configuration file it should be named DSsConfiguration.plist. In the DSsConfiguration.plist keys that need to be defined are:
- 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 keys - Public keys for each scheme used for verification of the certificate chain in the
acsSignedContentduring a challenge flow. - Schemes logo names - Logo image name for the scheme.
Some of the values can be omitted, please check Pre-configured Directory Servers for the pre-configured values that will be used instead.
Configuring Schemes Directory Servers
To define a scheme DS, simply create a dictionary from the root of the DSsConfiguration.plist where the name of the scheme is the dictionary key. Each scheme DS dictionary contains the following:
dsPublicKey- public key in PEM format, certificate in PEM format, or filename of certificate.dsRootCertificates- certificates in PEM format, or filenames of certificates.IDs- an array containing String representations of the DS IDs.logoImageName- string value representation of the scheme logo image name.
Please note that the key names shall be set exactly as stated above for the configuration to be valid.
Configuring DS IDs
To define the DS IDs that belong to a certain scheme DS, create a new array named IDs containing string values of the DS IDs. Repeat for each scheme DS.
| DS IDs | |
|---|---|
parent | Scheme Dictionary |
key | IDs |
value | ID of the scheme, each in a new row |
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 file for more RID values.
Configuring Scheme public key
To define the public key that will be used for encryption of Device Info, create a new element in the selected scheme name. The key should be dsPublicKey while the value can be the filename of the DS certificate, a PEM string of the certificate or a PEM string of the key.
| DS Public Key | |
|---|---|
parent | Scheme Dictionary |
key | dsPublicKey |
value | Filename, certificate or public key PEM string. |
Note: If public keys are provided, the keys can be either EC or RSA in PEM format and in ASN1 notation. If certificates are provided, they need to be in the X.509 standard in either PEM or DER format. In case a Certificate chain is provided, the leaf certificate will be used. Make sure that the certificate is part of the application bundle.
Configuring DS Root Certificates
To define the root certificates that will be used for a certain scheme DS, create a new element in the selected scheme name. The key should be dsRootCertificates while the value should be an array with the filenames of the DS Root certificates or a PEM strings of the certificates.
| DS Root Certificate | |
|---|---|
parent | Scheme Dictionary |
key | dsRootCertificates |
value | Array of filenames or PEM strings of the certificates. |
Note: The certificate files need to be in the X.509 standard in either PEM or DER format. Make sure that the certificates are a part of the application bundle. To ensure a higher percentage of successful transactions, in the event where none of the configured root certificates can verify the acsSignedContent, the Netcetera 3DS SDK will try to use the corresponding Pre-configured DS Root Public Key instead.
Configuring Logos
To define the logo that will be used for a certain scheme DS, create a new element in the scheme DS dictionary. The key should be logoImageName, while the value should be the name of the logo image for the scheme DS. Make sure that the logo image is in the application bundle. Repeat the process for each scheme DS.
| DS Logo image | |
|---|---|
parent | Scheme Dictionary |
key | logoImageName |
value | Name of image filename. |
DSsConfiguration.plist example:
Pre-configured Directory Servers
The Netcetera iOS 3DS SDK comes bundled with configuration for the following directory servers, listed in the table below.
3ds2.directory.mastercard.com Expiry: 15.06.2024 | PRD MasterCard Identity Check Root CA Expiry: 15.07.2030 | mastercard.png | ||
3ds2.rsa.encryption.visa.com Expiry: 22.08.2024 | Visa Public RSA Root CA Expiry: 15.03.2041 | visa.png | ||
sdk.safekey.encryptkey.com Expiry: 24.05.2025 | American Express Private Certification Authority Expiry: 11.08.2029 | amex.png | ||
Discover SDK Key | ProtectBuy Root Expiry: 03.02.2027 | diners.png | ||
ds2apr.jcb-tds.com Expiry: 03.03.2051 | JCB DS Root CA EMV 3-D Secure Expiry: 09.01.2036 | jcb.png | ||
mir.png | ||||
CFCA@UnionPay International@N9131000005455878X6@1 Expiry: 08.07.2025 | CFCA ACS CA Expiry: 28.09.2035 | union.png | ||
CartesBancaires SDK Key | Root 3DS CB CA Expiry: 31.07.2048 | cartesBancaires.png | ||
EFTPOS SDK Key Expiry: 31.08.2025 | eftpos Prod Root CA Expiry: 06.10.2030 | eftpos.svg |
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 iOS 3DS SDK has a utility API DsRidValues that contains the DS RIDs for the SDK Pre-configured schemes.
Example:
Configuring Logo Appearances
Some logos might not be easily visible in dark mode on iOS. If light mode logo is configured, it is recommended to configure a dark mode appearance of the logo as well for a better visual experience. To add different appearances for a logo, insert the default logo into the Assets catalog (Assets.xcassets) and change the Appearances property of the Image Set to Any, Dark or Any, Light, Dark.
Note: The Any appearance is the only appearance supported for older iOS versions (below iOS 13), therefore it is recommended to use the Any appearance for the default logo and the optional Dark appearance for the dark mode logo.
UI Customization
The Netcetera iOS 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. If needed, the integrator can configure a separate UiCustomization for each UI appearance (DEFAULT and DARK).
Note: The dark mode UiCustomization will only be applied if the device is running iOS 13 or higher.
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 | Helvetica | Helvetica |
setTextColor | Content text color | #000000 | #ffffff |
setTextFontSize | Content text font size | 16 | 16 |
setHeadingTextFontName | Heading text font name | Helvetica | Helvetica |
setHeadingTextColor | Heading text color | #000000 | #ffffff |
setHeadingTextFontSize | Heading text font size | 28 | 28 |
Toolbar Customization
The ToolbarCustomization allows integrators to customize the navigation bar presented at the top of each challenge screen.
To customize the navigation bar, invoke setToolbarCustomization(...) on a UiCustomization object and pass the ToolbarCustomization object as a parameter.
ToolbarCustomization API:
| Method Name | Customizes | Default LIGHT | Default DARK |
|---|---|---|---|
setTextFontName | Navigation bar header text font name | Helvetica | Helvetica |
setTextColor | Navigation bar header text color | #000000 | #ffffff |
setTextFontSize | Navigation bar header text font size | 16 | 16 |
setBackgroundColor | Navigation bar background color | #fcfcfc | #282828 |
setHeaderText | Navigation bar title text | "SECURE CHECKOUT" | "SECURE CHECKOUT" |
setButtonText | Navigation bar 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 | Helvetica | Helvetica |
setTextColor | Input text color | #000000 | #ffffff |
setTextFontSize | Input text font size | 16 | 16 |
setBorderWidth | Text field border width | 2 | 2` |
setBorderColor | Text field border color | #565a5c | #565a5c |
setCornerRadius | Text field corner curvature | 5 | 5 |
UI Customization Example
Restricted Device Info Parameters Configuration
Using ConfigurationBuilder (Recommended)
The ConfigurationBuilder can be used to configure the restricted parameters. A list of restricted parameters should be passed to the restrictedParameters([String]) function of the ConfigurationBuilder object.
When all values are set in the ConfigurationBuilder, the configParameters() functions will generate ConfigParameters object that can be used when calling the initialize method of ThreeDS2Service class.
Example:
Using 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 | nil |
paramName | "restricted-device-info-parameters" |
paramValue | Comma separated values of IDs of the device info parameters. |
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 InvalidInput error is thrown.
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 iOS 3DS SDK should support the Bridging Message Extension, use the ConfigurationBuilder.bridgingMessageExtensionEnabled(...) method with the following arguments:
| Argument | Value |
|---|---|
enabled | Boolean value as string, such as "true" to support it or "false" to not support it. |
Example:
Configuration with ConfigParameters
To define if the Netcetera iOS 3DS SDK should support the Bridging Message Extension, use the ConfigParameters.addParam(...) method with the following arguments:
| Argument | Value |
|---|---|
group | nil |
paramName | "bridging-message-extension-enabled" |
paramValue | Boolean value as string, such as "true" to support it or "false" to not support it. |
Example:
Log level
There are 4 log levels defined in the SDK:
- debug
- info
- error (default log level)
- noLog
You can change the log level of the SDK by setting the parameter in ConfigurationBuilder.
Example:
Permissions
This section describes which iOS Permissions should be granted.
| Permission | Mandatory | Description |
|---|---|---|
Location | No | Needed during the device info collection process, for better risk calculation. Request permission from the user before calling initialize. |
Scheme Specific Requirements
This section lists additional requirements that the integrator of the Netcetera iOS 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 |