This section describes how the Netcetera Android 3DS SDK should be configured.
When transaction is initiated, the SDK get the information about the Directory Server that will participate in the message flow. With that, the SDK determinate which DS public key to use for the data encryption and which DS logo to be shown.
The SDK uses the DS public key and the DS logo. These are configured in the ConfigParameters in Initialization.
Following are the steps for the DS configuration:
Some of the values can be omitted, please check Pre-configured Directory Servers for the pre-configured values that will be used instead.
Note: 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.
To define the scheme DS, use the ConfigParameters.addParameters(...) with the following arguments:
| Argument | Value |
|---|---|
| group | null |
| paramName | "schema_names" |
| paramValue | Comma separated values of schemes. |
Example:
1 | configParameters.addParam(null, "schema_names", "mastercard, visa"); |
To define the DS IDs that belong to certain scheme, use the ConfigParameters.addParameters(...) 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:
1 2 | configParameters.addParam("schema_ds_ids", "mastercard", "A000000004, B012345678");configParameters.addParam("schema_ds_ids", "visa", "315041592E, 325041592E, A000000003"); |
To define the public key that will be used for certain scheme, use the ConfigParameters.addParameters(...) 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:
1 2 | configParameters.addParam("schema_public_key", "mastercard", loadPublicKey("certificates/mastercard_rsa.cer"));configParameters.addParam("schema_public_key", "visa", loadPublicKey("certificates/visa_ec.cer")); |
Note: loadPublicKey(...) is function that loads ASN.1 encoding of the public key in Base64 encoded format from a certificate file.
To define the root public key that will be used for certain scheme, use the ConfigParameters.addParameters(...) with the following arguments:
| Argument | Value |
|---|---|
| group | "schema_root_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. |
Note: In case the provided certificate is a chain of certificates, the first certificate in the list will be used.
Example:
1 2 | configParameters.addParam("schema_root_public_key", "mastercard", loadPublicKey("certificates/root_mastercard_rsa.cer"));configParameters.addParam("schema_root_public_key", "visa", loadPublicKey("certificates/root_visa_ec.cer")); |
Note: loadPublicKey(...) is function that loads ASN.1 encoding of the public key in Base64 encoded format from a certificate file.
To define the logo that will be used for certain scheme, use the ConfigParameters.addParameters(...) 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. |
Example:
1 2 | configParameters.addParam("schema_logo", "mastercard", Integer.toString(R.drawable.schema_logo_mastercard_1));configParameters.addParam("schema_logo", "visa", Integer.toString(R.drawable.schema_logo_visa)); |
The Netcetera Android 3DS SDK comes bundled with configuration for the following directory servers, listed in the table below.
| Scheme | RIDs | DS Public Key | DS Root Public Key | DS Logo |
|---|---|---|---|---|
| Mastercard | B012345678 |
|
|
R.drawable.ds_logo_mastercard |
| Visa | 325041592E A000000003 |
|
|
R.drawable.ds_logo_visa |
| Amex | |
|
|
R.drawable.ds_logo_amex |
| Diners | |
|
|
R.drawable.ds_logo_diners |
| JCB | |
|
|
R.drawable.ds_logo_jcb |
| MIR | |
|
|
R.drawable.ds_logo_mir |
| Union | |
|
|
R.drawable.ds_logo_union |
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 and the ACS in use. The integrators are encouraged to complete the configuration.
The Netcetera Android 3DS SDK supports customization of the UI elements that are being shown by the SDK itself. For this purpose UiCustomization is used.
For detailed information of the UiCustomization API and how to be used, refer to 4.5 in the EMVCo 3DS SDK Specification.
The Netcetera Android 3DS SDK uses SLF4J for logging purposes, logging only messages on level WARN and ERROR. The logging of this 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.
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. |