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
- Start the Cardholder Onboarding Flow
- Override Configurations and Keys
You can access the iOS UI SDK on GitHub.
To contribute to the SDK development, see Contributions & Development
- 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.
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.
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
platform :ios, '12.0'...
- At the top of the file, ensure the platform specified is set to iOS 12 and frameworks are enabled:
platform :ios, '12.0'target '<YourApp>' douse_frameworks!pod 'AptoUISDK'...end
- Add the Apto and AptoPCI iOS SDK pod dependencies to your app's target and save the file:
Open your Terminal app, and navigate to your project's directory containing the
cdand install the SDK by running the following
pod installcommand:cd <PATH_TO_YOUR_PROJECT_FOLDER>pod install
Follow the steps below to initialize the SDK:
Open the workspace (.xcworkspace) for your app with Xcode.
UIViewControllersubclass for a view in your app.
Initialize the Apto UI SDK by invoking
<MOBILE_API_KEY>in the following example with your API key from the Apto Developer Portal. This fully initializes the SDK for your application:
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
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. For an example of the cardholder onboarding UI/UX screens, view the Apto Developer Guides.
To start the cardholder onboarding flow, initiate the card UI flow process by invoking
startCardFlow() and passing in your
UIViewController subclass and
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. For more information, see the Getting Started guides
startCardFlow method has two required parameters and two optional parameters:
|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.|
|No||The initialization data that will be stored on the Apto servers.|
Note: The first three values may be a string up to 256 characters.
|No||String up to 30 characters||The identifier for the design which will be applied to the card.|
|No||String up to 256 characters||The URL for the QR code image which will be printed on the card.|
|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.)|
|No||String up to 256 characters||The image that will be printed on the card.|
|No||String up to 256 characters||The secondary image that will be added to the card.|
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
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
- Funding Source
- Notification Preferences
- Detailed Card Transaction Activity
- Monthly Statements
UI opening display mode
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 969px × 612px png file of the entire card, including the background, company logo, and network logo (i.e., Visa, Mastercard, etc.). 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.
CardOptions object can accept multiple unordered parameters. No parameters are required to create a
The available parameters are:
CardOptions object has two parameters:
|This parameter accepts a dictionary of |
See FeatureKey Options for more information.
|This is a |
FeatureKey options are:
|Controls if the UI's dark theme is enabled.|
|Controls if the Stats button is displayed. This enables the user to see their monthly consumption statistics.|
|Controls if the Account Settings button is displayed. This enables the user to see the account settings screen.|
|Controls if the SDK displays the Enable your physical card button. This button enables the user to activate a physical card.|
|Controls if the user can customize their notification preferences.|
|Controls if the user can view detailed transaction activity (i.e., declined transactions).|
|Controls if the user can view their monthly statements.|
|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.|
|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 |
Note: If biometric authentication is enabled, it will appear first. The user may choose to cancel biometric authentication and use their passcode instead.
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.
fontCustomizationOptions parameter specifies custom fonts for the UI. A
ThemeFontDescriptors object can have up to four typeface parameters:
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:
Use the resulting
ThemeFontDescriptors object as the
fontCustomizationOptions parameter for the
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
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.
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!