Skip to main content

iOS SDK Setup

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

Generate Your API Key

Create Credentials

Before you can implement payer authentication services, your business team must contact your acquirer and to establish the service. Your software development team should become familiar with the API fields and technical details of this service.

Creating a mobile application with the SDK implementation requires that you perform some preliminary procedures before starting the actual payer authentication implementation process. This section describes the processes involving JWTs.

API keys are required to create the JSON Web Token (JWT). For further information, contact customer support.

You receive an email with your username and a temporary password. Your username is in this format:

companyname_merchant name_contact name

For example:

mycompany_petairways_peter

Generate API Key

After you receive your credentials, log in to your JFrog account and update your temporary password. Complete these steps to generate your API key.

  1. Log in to your JFrog account.
  2. In the top-right of the JFrog Platform, select the Welcome drop-down menu and select Edit Profile
  3. Enter your password and select Unlock
  4. Under Authentication Settings, select Generate API Key

Download and Import the SDK

Download the CardinalMobile.framework or CardinalMobile.xcframework file using the cURL program in this example.

curl -L -u <USER_NAME>:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/cardinalmobilesdk.zip \    -o <LOCAL_FILE_NAME.EXT># Example:curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/cardinalmobilesdk.zip" -o cardinalmobile2.2.5-1.zip
curl -L -u <USER_NAME>:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/CardinalMobileiOSXC.zip \    -o <LOCAL_FILE_NAME.EXT># 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 does not 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.

Configure Your Build Environment

  1. Open Xcode and choose your project.
  2. Under the Targets section, select your application and open the General tab.
  3. Expand the Embedded Binaries section and select the small plus (+) at the bottom of the list.
  4. From the list, add the CardinalMobile.framework file.

Configure the iOS SDK

Use CardinalSession new to create a new instance of the cardinal object. 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.

#import <CardinalMobile/CardinalMobile.h>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];}
import CardinalMobilevar session : CardinalSession!//Setup can be called in viewDidLoadfunc 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

MethodDescriptionDefault ValuesPossible Values
deploymentEnvironmentThe environment to which the SDK connects.CardinalSessionEnvironmentProductionCardinalSessionEnvironmentStaging, CardinalSessionEnvironmentProduction
timeoutInMillisecondsMaximum amount of time (in milliseconds) for all exchanges.8000
uiTypeInterface types that the device supports for displaying specific challenge user interfaces within the SDK.CardinalSessionUITypeBothCardinalSessionUITypeBoth, CardinalSessionUITypeNative, CardinalSessionUITypeHTML
renderTypeList of all the render types that the device supports for displaying specific challenge user interfaces within the SDK.[CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML, CardinalSessionRenderTypeOOB, CardinalSessionRenderTypeSingleSelect, CardinalSessionRenderTypeMultiSelect]CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML, CardinalSessionRenderTypeOOB, CardinalSessionRenderTypeSingleSelect, CardinalSessionRenderTypeMultiSelect
proxyServerURLProxy server through which the Cardinal SDK Session operates.nil
enableQuickAuthEnable Quick Authentication.false
uiCustomizationSet Custom UICustomization for SDK-Controlled Challenge UI.nil
enableDFSyncEnable DF Sync to get onSetupCompleted called after collected device data is sent to the server.false

Set Up the Initial Request

Requesting the cardinal session setup process 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 value ensures that the correct device data collection results are matched to each user request. 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 can also track the requests for each user session.

Study these code examples to understand how to complete setting up the cardinal session process. The function request must be placed in your Checkout ViewController.

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}];
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}

Next Steps

See Implementing Payer Authentication with the SDK for the next steps.

Last published: September 29, 2026