UI SDK

caution

All card programs using APTO's SDKs or Mobile API are required to implement Signed Payloads. This is a mandatory update that must be completed to avoid program suspension. Please follow the Signed Payloads guide for more information, or contact programsupport@aptopayments.com with any questions.

Welcome to the Apto iOS UI SDK. This SDK provides access to Apto's mobile platform, and provides a pre-built / standard UI/UX flow to onboard cardholders and enable users to manage their cards.

Note: If you want to control the UI/UX, use the Mobile SDK.

You can quickly set up a UI/UX cardholder experience by dropping the SDK into your existing application or distributing it as a standalone mobile application. Some UI/UX elements may be configured to match your organization's branding look and feel, such as fonts, themes and enabled features.

Note: Branding features such as the card background image and colors of various UI elements (i.e. Buttons) require configuration changes on Apto Payment's backend. Please contact us for more information.

This document provides an overview of how to:

Install the SDK
Initialize the SDK
Signed Payloads
Start the Cardholder Onboarding Flow
Override Configurations and Keys

Note: The UI SDK automatically imports the PCI SDK. Therefore, the main screen will display a view provided by the PCI SDK.

You can access the iOS UI SDK on GitHub.

To contribute to the SDK development, see Contributions & Development

Requirements

iOS 12.0 (minimum version)
Xcode 12 (minimum version)
Swift 5 (minimum version)
CocoaPods. No minimum version is required, but version 1.8.3 or higher is recommended.

Get the Mobile API key

A Mobile API Key is required to run the SDK. To retrieve your Mobile API Key see Get the Mobile API Key for the SDKs.

Install the SDK

We suggest using CocoaPods to install the SDK.

Note: Ensure you have a Podfile created in your app's root project directory using pod init while Xcode is closed.

In your project's Podfile:
- At the top of the file, ensure the platform specified is set to iOS 12 and frameworks are enabled:
```
platform :ios, '12.0'

...
```
- Add the Apto and AptoPCI iOS SDK pod dependencies to your app's target and save the file:
```
platform :ios, '12.0'

target '<YourApp>' do

  use_frameworks!

  pod 'AptoUISDK'

  ...
end
```
Open your Terminal app, and navigate to your project's directory containing the Podfile using cd and install the SDK by running the following pod install command:
```
cd <PATH_TO_YOUR_PROJECT_FOLDER>
pod install
```

Initialize the SDK

Follow the steps below to initialize the SDK:

Open the workspace (.xcworkspace) for your app with Xcode.
Open the UIViewController subclass for a view in your app.
Initialize the Apto UI SDK by invoking initializeWithApiKey() and replacing <MOBILE_API_KEY> in the following example with your API key from the Apto Developer Portal. This fully initializes the SDK for your application:

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        AptoPlatform.defaultManager().initializeWithApiKey("<MOBILE_API_KEY>")
    }
}

The default environment selected is the production environment (.production). If you would like to use the sandbox environment, you must set the optional environment parameter to .sandbox:

AptoPlatform.defaultManager().initializeWithApiKey("<MOBILE_API_KEY>", environment: .sandbox)

Signed Payloads

Once you have finished setting up your server, as outlined in the Signed Payloads guide, you will need to create an AptoPlatformWebTokenProvider that fetches the JWT token from that server.

class MyWebTokenProvider : AptoPlatformWebTokenProvider {

  public func getToken(_ payload: [String: Any], callback: @escaping (Result<String, NSError>) -> ()) {

    var req = URLRequest(url: "http://localhost/sign")
    req.method = .post
    req.headers = ["Content-Type": "application/json", "Accept": "application/json"];
    
    do {
       req.httpBody = try JSONSerialization.data(withJSONObject: payload)
    } catch {
       print("HTTP Request Failed \(error)")
       // let SDK know an error happened
       callback(.failure(WebTokenError()))
    }
    
    let task = URLSession.shared.dataTask(with: req) { data, response, error in
        do {
            if let data = data {
                let result: JWTToken = try JSONDecoder().decode(JWTToken.self, from: data)
                // send the JWT back to the SDK
                callback(.success(result.token))
            } else if let error = error {
                print("HTTP Request returned bad data \(error)")
                // let SDK know an error happened
                callback(.failure(WebTokenError()))
            }
        } catch {
            print("HTTP Request Failed \(error)")
            // let SDK know an error happened
            callback(.failure(WebTokenError()))
        }
    }
   
    task.resume()
    
  }
}

You will then need to set the WebTokenProvider at the same time you initialize the SDK. This class will be called anytime a signed payload is needed.

AptoPlatform.defaultManager().webTokenProvider = MyWebTokenProvider()

Start the Cardholder Onboarding Flow

Once the SDK is initialized, you can implement our pre-built cardholder onboarding flow. The onboarding flow enables users to verify their credentials, log in, and manage their cardholder information.

To start the cardholder onboarding flow, initiate the card UI flow process by invoking startCardFlow() and passing in your UIViewController subclass and ShiftCardModuleMode values:

  AptoPlatform.defaultManager().startCardFlow(from: self, mode: .standalone) { [weak self] result in
    switch result {
    case .failure(let error):
      // handle error
    case .success(let module):
      // SDK successfully initialized
    }
  }

The callback closure has a single Result<UIModule, NSError> parameter. Use the result object for error handling, or to add additional features once the SDK is successfully initialized.

Note: When testing in the sandbox environment, you must use 000000 as the OTP code when prompted by the UI.

The startCardFlow method has two required parameters and two optional parameters:

Parameter	Required?	Description
`from`	Yes	The `UIViewController` subclass where the SDK is initialized. This is used to present the SDK to the user.
`mode`	Yes	A `ShiftCardModuleMode` value defining how the SDK is opened and closed. The available modes are: `embedded`: This mode displays a close option on the manage card screen, enabling the user to close the card UI and return to the main application view. We recommend using this mode when starting the Apto UI SDK from an existing app. `standalone`: This mode enables the SDK to only be closed via the logout process. We recommend using this mode if your application is only using the Apto UI SDK and no has other features.
`options`	No	The UI SDK has multiple features that can be enabled / disabled. This parameter is used to enable / disable card-management features and can be used to define the card theme and fonts. See CardOptions Parameters for more information.
`initialUserData`	No	The initialization data that will be stored on the Apto servers. `initializationData` can contain the following values values: `userMetadata` - A string attached to the user data after sign up. `cardMetadata` - A string attached to the card after issuance. `custodianUid` - A string attached to the user after sign up. The value refers to the user ID in your platform. `design` See Issue Card Design Parameters for more information. Note: The first three values may be a string up to 256 characters.

Issue Card Design Parameters (Blue or Orange Programs only)

Parameter	Required?	Type	Description
`designKey`	No	String up to 30 characters	The identifier for the design which will be applied to the card.
`qrCode`	No	String up to 256 characters	The URL for the QR code image which will be printed on the card.
`extraEmbossingLine`	No	String up to 25 characters	Text for the embossed line that will be applied to the card. (This is located under the cardholder name.)
`imageUrl`	No	String up to 256 characters	The image that will be printed on the card.
`additionalImageUrl`	No	String up to 256 characters	The secondary image that will be added to the card.

CardOptions Parameters

The UI SDK retrieves all card design configurations from our servers and applies the configurations to the included PCI SDK. This ensures the correct card styles and design are shown to the user, including:

Card Background
Card Text Colors

Use the CardOptions object to customize the card management features and card themes and fonts.

Some of the features that can be customized are:

Enable / Disable management of:
- Account Settings
- Stats
- Funding Source
- Notification Preferences
- Detailed Card Transaction Activity
- Monthly Statements
Authentication Settings
Card Theme
UI opening display mode
Font Options
Card logo and design
Note: If you need to customize the logo and/or card design, it will need to be configured on our servers. You will need to send us a PNG file of the company logo you would like to appear on the card. You may send the logo in any dimension size, but, once it has been uploaded, it will be resized to 130px x 165px. Once your PNG file is set up, the UI SDK will communicate with our servers to retrieve the PNG file and display it to the user. Please contact us for more information.

The CardOptions object can accept multiple unordered parameters. No parameters are required to create a CardOptions object.

let options = CardOptions(features:fontCustomizationOptions:)

The available parameters are:

The CardOptions object has two parameters:

Parameter	Description
`features`	This parameter accepts a dictionary of `FeatureKey`-`Bool` key-value pairs. Each key-value pair represents a feature. See FeatureKey Options for more information.
`fontCustomizationOptions` (optional)	This is a `ThemeFontDescriptors` object used to specify a custom font for the card UI. If no font customization options are specified, the SDK will use the system font. See The `fontCustomizationOptions` Parameter for more information.

FeatureKey Options

The available FeatureKey options are:

Parameter	Default Value	Description
`supportDarkMode`	`false`	Controls if the UI's dark theme is enabled.
`showStatsButton`	`false`	Controls if the Stats button is displayed. This enables the user to see their monthly consumption statistics.
`showAccountSettingsButton`	`true`	Controls if the Account Settings button is displayed. This enables the user to see the account settings screen.
`hideFundingSourcesReconnectButton`	`false`	Controls if the reconnect button for the funding sources is shown. This enables the user to refresh the list of funding sources for their card. Note: This is only available for certain enterprise programs.
`showActivateCardButton`	`true`	Controls if the SDK displays the Enable your physical card button. This button enables the user to activate a physical card.
`showNotificationPreferences`	`false`	Controls if the user can customize their notification preferences.
`showDetailedCardActivityOption`	`false`	Controls if the user can view detailed transaction activity (i.e., declined transactions).
`showMonthlyStatementsOption`	`true`	Controls if the user can view their monthly statements.
`authenticateOnStartup`	`false`	Controls if the user must authenticate their account (using a passcode or biometrics), when the app starts or after returning from background mode. Enabling this option will require the user to create a passcode when signing up.
`authenticateOnPCI`	`false`	Controls if the user must authenticate using their passcode instead of the SMS/email code, prior to viewing their full card data. The available options for this `PCIAuthType` setting are: `.pinOrBiometrics` `.biometrics` `.none` Note: If biometric authentication is enabled, it will appear first. The user may choose to cancel biometric authentication and use their passcode instead.
`fontCustomizationOptions` (optional)	`Phone fonts`	Specifies custom fonts for the UI. See FontOptions Parameter for more information.

The fontCustomizationOptions Parameter

The fontCustomizationOptions parameter specifies custom fonts for the UI. The parameter may be one of the following object types:

ThemeFontDescriptors - Use this object to specify pre-existing fonts.
Custom Font using UIFontProviderProtocol - Use this object to specify custom fonts.

ThemeFontDescriptors Object

The fontCustomizationOptions parameter specifies custom fonts for the UI. A ThemeFontDescriptors object can have up to four typeface parameters:

regular
medium
semibold
bold

Note: Although no parameters are required to create a ThemeFontDescriptors object, we recommend you use one of the following options:

Set no typefaces, and use the default phone fonts for the UI.
Set all four typefaces to provide consistent fonts throughout the UI.

To create a ThemeFontDescriptors object, pass in a UIFontDescriptor object for each font type:

let descriptors = ThemeFontDescriptors(regular: UIFontDescriptor(name:"XYZ-Regular", size: 10),
                                       medium: UIFontDescriptor(name:"XYZ-Medium", size: 10),
                                       semibold: UIFontDescriptor(name:"XYZ-Semibold", size: 10),
                                       bold: UIFontDescriptor(name:"XYZ-Bold", size: 10))

Use the resulting ThemeFontDescriptors object as the fontCustomizationOptions parameter for the CardOptions object:

let options = CardOptions(features: [:], fontCustomizationOptions: .fontDescriptors(descriptors))

Custom Font using UIFontProviderProtocol

To use a custom font, create a custom class that implements UIFontProviderProtocol. This protocol enables you to have complete control over the fonts types and sizes shown in the card UI.

Note: You will need to modify the protocol within one of your classes to implement the different styles, but handle with care, as it may break the look and feel of the card UI.

To specify the fontCustomizationOptions parameter with a custom class implementing the UIFontProviderProtocol, wrap the provider in the .fontProvider() method:

let provider = MyCustomFontProvider()
let options = CardOptions(features: [:], fontCustomizationOptions: .fontProvider(provider))

Google Maps API Key parameter

The Google Maps API key is an optional parameter (googleMapsApiKey) in the startCardFlow method. The parameter's default value is nil and enables you to specify a Google Maps API Key to be used by the SDK.

Note: This parameter is required if you are using our UI to collect an address from your user, otherwise you can disregard it.

Contributions & Development

We look forward to receiving your feedback, including new feature requests, bug fixes, and documentation improvements.

If you would like to help:

Refer to the issues section of the repository first, to ensure your feature or bug doesn't already exist (the request may be ongoing, or a newly-finished task).
If your request is not in the issues section, please feel free to create one. We'll get back to you as soon as possible.

If you want to help improve the SDK by adding a new feature or bug fix, we'd be happy to receive pull requests!

UI SDK

Requirements​

Get the Mobile API key​

Install the SDK​

Initialize the SDK​

Signed Payloads​

Start the Cardholder Onboarding Flow​

Issue Card Design Parameters (Blue or Orange Programs only)​

CardOptions Parameters​

FeatureKey Options​

The fontCustomizationOptions Parameter​

ThemeFontDescriptors Object​

Custom Font using UIFontProviderProtocol​

Google Maps API Key parameter​

Contributions & Development​