Using the iOS SDK

A mobile SDK is available for integrating payer authentication services into mobile applications running on the iOS platform.

Downloading and Importing the SDK

Download the
CardinalMobile.framework
file using cURL in this example.

Download CardinalMobile.framework

    curl -L -u 
        : https://cardinalcommerceprod.jfrog.io/artifactory/ios/-/cardinalmobilesdk.zip
        -o 

#Example: 
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/cardinalmobilesdk.zip" -o cardinalmobile2.2.5-1.zip

Download the
CardinalMobile.xcframework
file using the cURL in this example.

Download CardinalMobile.xcframework

    curl -L -u 
        : https://cardinalcommerceprod.jfrog.io/artifactory/ios/-/CardinalMobileiOSXC.zip
        -o 

#Example: 
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/CardinalMobileiOSXC.zip" -o cardinalmobile2.2.5-1.zip

In your XCode project, drag the
CardinalMobile.framework
file into the Frameworks group in your Xcode Project. (Create the group if it doesn't already exist.) In the import dialog box, check the box to Copy items into the destinations group folder (or Destination: Copy items if needed). The iOS SDK files are now available for linking in your project.

Configuring Your Build Environment

Open Xcode and in the source list to the left of the main editor area, choose your project.

Under the Targets section, select your application and open the General tab.

Expand the Embedded Binaries section and click the small plus (+) at the bottom of the list.

Add
CardinalMobile.framework
from the list.

Configuring the iOS SDK

Create a new instance of the cardinal object by
CardinalSession
new. Use the default configuration options. Study these examples to complete the iOS SDK configuration.

For more details on configuration options, refer to the table after the examples.

CardinalSession new (iOS SDK - Objective-C)

    #import 

CardinalSession *session;

//Setup can be called in viewDidLoad
- (void)setupCardinalSession {
    session = [CardinalSession new]; 
    CardinalSessionConfiguration *config = [CardinalSessionConfiguration new];
    config.deploymentEnvironment = CardinalSessionEnvironmentProduction;
    config.timeout = CardinalSessionTimeoutStandard;
    config.uiType = CardinalSessionUITypeBoth;

    UiCustomization *yourCustomUi = [[UiCustomization alloc] init];
    //Set various customizations here. See "iOS UI Customization" documentation for detail.
    config.uiCustomization = yourCustomUi;
 
    CardinalSessionRenderTypeArray *renderType = [[CardinalSessionRenderTypeArray alloc] initWithObjects:
                               CardinalSessionRenderTypeOTP,
                               CardinalSessionRenderTypeHTML,
                               nil];
    config.renderType = renderType;
 
    config.enableQuickAuth = false;
    [session configure:config];
}

CardinalSession new (iOS SDK - Swift)

    import CardinalMobile

var session : CardinalSession!
 
//Setup can be called in viewDidLoad
func setupCardinalSession{
    session = CardinalSession()
    var config = CardinalSessionConfiguration()
    config.deploymentEnvironment = .production
    config.timeout = 8000
    config.uiType = .both
 
    let yourCustomUi = UiCustomization()
    //Set various customizations here. See "iOS UI Customization" documentation for detail.
    config.uiCustomization = yourCustomUi
 
    config.renderType = [CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML]
    config.enableQuickAuth = true
    session.configure(config)
}

iOS Configuration Options
Method	Description	Default Values	Possible Values
deploymentEnviron ment	The environment to which the SDK connects.	CardinalSessionEnviron mentProduction	CardinalSession Environment Staging CardinalSessionEnvi ronment Production
timeoutInMilli seconds	Maximum amount of time (in milliseconds) for all exchanges.	8000
uiType	Interface types that the device supports for displaying specific challenge user interfaces within the SDK.	CardinalSessionUIType Both	CardinalSessionUIT ypeBoth CardinalSessionUIT ypeNative CardinalSessionUIT ypeHTML
renderType	List of all the render types that the device supports for displaying specific challenge user interfaces within the SDK.	[CardinalSessionRend erTypeOTP, CardinalSessionRend erTypeHTML, CardinalSessionRend erTypeOOB, CardinalSessionRend erTypeSingleSelect, CardinalSessionRend erTypeMultiSelect]	CardinalSessionRen derType OTP CardinalSessionRen derType HTML CardinalSessionRen derType OOB CardinalSessionRen derType SingleSelect CardinalSessionRen derType MultiSelect
proxyServerURL	Proxy server through which the Cardinal SDK Session operates.	nil
enableQuickAuth	Enable Quick Authentication	false
uiCustomization	Set Custom UICustomization for SDK-Controlled Challenge UI.	nil
enableDFSync	Enable DF Sync to get onSetupCompleted called after collected device data is sent to the server.	false

Setting Up the Initial Call

Calling
cardinal session setup
begins the communication process, authenticates your credentials (server JWT), and completes the data collection process. By the time the customer is ready to check out, all necessary preprocessing is complete.

Each time a user begins a mobile transaction, a unique value is assigned to the

consumerSessionId

API field to identify the session. This

consumerSessionId

value ensures that the correct device data collection results is matched to each user request.

Cybersource

uses its

payerAuthEnrollService_referenceID

field to contain Cardinal's

consumerSessionId

value. You must assign the value of the

consumerSessionId

field to the

payerAuthEnrollService_referenceID

field so that

Cybersource

can also track the calls for each user session.

Study these code examples to understand how to complete the
cardinal session setup
. The function call must be placed in your Checkout ViewController.

Cardinal session setup (iOS SDK - Objective-C)

    NSString *accountNumberString = @"1234567890123456";
NSString *jwtString = @"INSERT_YOUR_JWT_HERE";
 
[session setupWithJWT:jwtString 
          didComplete:^(NSString * _Nonnull consumerSessionId){
//
    // You may have your Submit button disabled on page load. Once you are 
    // setup for CCA, you may then enable it. This will prevent users 
    // from submitting their order before CCA is ready.
    //
} didValidate:^(CardinalResponse * _Nonnull validateResponse) {
    // Handle failed setup
    // If there was an error with setup, cardinal will call this 
    // function with validate response and empty serverJWT
}];

Cardinal session setup (iOS SDK - Swift)

    let accountNumberString = "1234567890123456"
let jwtString = "INSERT_YOUR_JWT_HERE"

session.setup(jwtString: jwtString, completed: { (consumerSessionId: String) in
    //
    // You may have your Submit button disabled on page load. Once you 
    // are setup for CCA, you may then enable it. This will prevent 
    // users from submitting their order before CCA is ready.
    //
}) { (validateResponse: CardinalResponse) in
    // Handle failed setup
    // If there was an error with setup, cardinal will call this 
    // function with validate response and empty serverJWT
}