SDK Integration

This section provides detailed information on how to integrate the Netcetera 3DS SDK.

Cocoapods Setup

Steps to include the SDK into the project:

  1. Install Cocoapods following the instructions on the Cocoapods website.
  2. In your Podfile add the 3DS SDK private spec repo as source, and add the ThreeDS SDK as dependency. There are two subspecs available.
Subspec Description
ThreeDS_SDK/iphoneos SDK build with device only (default option if no subscpec is specified).
ThreeDS_SDK/universal SDK build for device and simulator. Should be used only for development.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/ios-3ds-sdk/Specs.git'
 
target 'test-project' do
  # Comment the next line if you're not using Swift
  use_frameworks!
 
  pod 'ThreeDS_SDK', '2.3.10'
  # pod 'ThreeDS_SDK/iphoneos', '2.3.10'
  # pod 'ThreeDS_SDK/universal', '2.3.10'
 
  # For development you can use the 'universal' subspec to be able to run the app on simulator
  # pod 'ThreeDS_SDK/universal', '2.3.10'
end
  1. Add the credentials provided by Netcetera to the ~/.netrc file. If such file does not exist, it should be created.

Note: For example <hostname> can be merchant-plug-in.extranet.netcetera.biz.

1
2
3
machine <hostname>
login <myUsername>
password <myPassword>
  1. To install the pods run pod install.

Manual Setup

  1. Extract the Netcetera iOS 3DS SDK zip archive that is part of the delivery. Inside there are two frameworks, iphoneos and universal.

    • iphoneos - contains the SDK that is built only for iOS devices and shall be used for builds in productions.
    • universal - contains the SDK that is built for both iOS devices and iOS simulators and can be used for development

  2. In your project, add the framework (iphoneos or universal) in the “Frameworks, Libraries, and Embedded Content” section in the General target’s tab.

License Setup

A license file containing a license key is distributed along with the SDK. In order to be able to use the Netcetera iOS 3DS SDK, the license key must be added in ConfigParameters which are passed upon Initialization of the ThreeDS2Service.

To define the license, use the ConfigParameters.addParameters(...) with the following arguments:

Argument Value
group nil
paramName "license-key"
paramValue The content of the license file.
1
2
let configParameters = ConfigParameters()
try configParameters.addParam(group:nil, paramName:"license-key", paramValue:"eyJhbGciOiJ...")

Using ConfigurationBuilder (Recommended)

An easier way to pass the license key is to use the ConfigurationBuilder. This is done by using the license(key: String) function. The builder helps populate ConfigParameters easier.

After setting all values in the builder, simply call .configParameters() to generate the ConfigParameters object that can be passed in the initialize method of ThreeDS2Service class.

1
2
3
4
5
let configurationBuilder = ConfigurationBuilder()
 
try configurationBuilder.license(key: "sample_key")
 
let configParameters = configurationBuilder.configParameters()

Dependencies

Several external dependencies are used by the Netcetera iOS 3DS SDK. These libraries are integrated inside the SDK. The full list of dependencies is:

Name Description Website License Version
ASN1Decoder Used to parse keys and certificates in ASN1 structure https://github.com/filom/ASN1Decoder MIT license 1.2
SwCrypt Library with crpto functions used in the SDK for JWS validation and signing, used only in iOS 10 https://github.com/soyersoyer/SwCrypt MIT license 5.1.3
GMEllipticCurveCrypto Security framework used for Elipctic Curve keys https://github.com/ricmoo/GMEllipticCurveCryptо BSD 2-Clause “Simplified” License 1.1

App Transport Security - HTTP Loads

EMVCo 3DS Specification requires the communication between the 3DS SDK and the ACS to go through HTTPS, but there is no such requirement for what protocol to be used when downloading the Payment System and Issuer logo images that shall be shown in the challenge screens. The URLs of these images are provided as parameters by the ACS in the CRes and it is expected they will be HTTPS URLs. The SDK doesn’t have influence over this and if HTTP URLs are provided, the images will not be shown on the challenge screens.

More information about this and how to ensure that these images will be downloaded and shown on the challenge screen even if they are served using unsecured connection, please check Preventing Insecure Network Connections