Skip to main content


Welcome to the Apto Android 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:

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 Android Mobile SDK details here.

To contribute to the SDK development, see Contributions & Development

Note: The Apto Mobile API has a request rate limit of 1 request per 30 seconds for the verification and login endpoints.


  • Android SDK, minimum API Level 23 (Marshmallow)
  • One of the following for testing:
    • Android device running Android 6.0 (API Level 23) or higher.
    • Android emulator running Android 7.0 (API Level 24) or higher.
  • Kotlin, minimum version 1.4.0
  • Gradle, minimum version 4.0.1

Note: The SDK is built using Kotlin, but is fully interoperable with Java. Code adjustments may be needed, if used within a Java project.

The following Android permissions are included with the UI SDK:

  • <uses-permission android:name="android.permission.INTERNET" />
  • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  • <uses-permission android:name="android.permission.USE_BIOMETRIC" />
  • <uses-permission android:name="android.permission.RECORD_AUDIO"/>

Note: The RECORD_AUDIO permission will only be invoked when needed. Depending on your Apto program configuration, this may occur when a user activates a card or requests a card's PIN.

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#

  1. In your project's build.gradle file, add the following repositories:
    allprojects {        repositories {
            jcenter()            mavenCentral()            maven { url "" }            maven { url '' }
            ...        }    }
  1. In your app's build.gradle, add the following compile options and build features:
android {
    compileOptions {        sourceCompatibility = 1.8        targetCompatibility = 1.8    }
    buildFeatures {        dataBinding = true    }

Note: The compileOptions block is required if your minimum Android SDK version is below Level 26 (Oreo).

  1. In your app's build.gradle, also add the following dependency:
    dependencies {        ...
        implementation 'com.aptopayments.sdk:ui:3.11.0'
        ...    }

This dependency already includes the Android Mobile SDK and the Android PCI SDK.

Initialize the SDK#

The SDK must be initialized using the onCreate method of your Application class, and requires your MOBILE_API_KEY:

  • One-step initialization (Recommended): Load your MOBILE_API_KEY in the onCreate method of your Application class.
  • Two-step initialization: Initialize the SDK, and set up the MOBILE_API_KEY prior to interacting with the SDK methods.

One-step Initialization#

In the onCreate method of your Application class, invoke initializeWithApiKey and pass in the MOBILE_API_KEY from the Apto Developer Portal. This fully initializes the SDK for your application.

AptoUiSdk.initializeWithApiKey(application, "MOBILE_API_KEY")

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

AptoUiSdk.initializeWithApiKey(application, "MOBILE_API_KEY", AptoSdkEnvironment.SBX)

Two-step Initialization#

If you want to defer setting your MOBILE_API_KEY, use the two-step initialization process:

  1. In the onCreate method of your Application class, invoke AptoUiSdk.initialize initialize the SDK for your application.
  1. Prior to your app's first interaction with the SDK, ensure you set your MOBILE_API_KEY. This fully initializes the SDK for your application.

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

AptoUiSdk.setApiKey("MOBILE_API_KEY", AptoSdkEnvironment.SBX)

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 login and to manage their cardholder information.

To start the cardholder onboarding flow:

  1. Initialize a CardOptions object.
    val cardOptions = CardOptions()
  1. Invoke the startCardFlow method, passing in the activity and cardOptions values. Ensure you replace the activity parameter with the Android Activity where the UI SDK will start from.
    AptoUiSdk.startCardFlow(activity, cardOptions,        onSuccess = {            // SDK successfully initialized        },        onError = {            // SDK initialized with errors        }    )

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

The startCardFlow method has one required parameter and four optional parameters:

activityYesThis is the Android Activity object from which the SDK will be started.
cardOptionsNoThe 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.
initializationDataNoThe 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.
onSuccess (optional)NoThis is the callback closure called once the Apto UI SDK has been initialized.
onError (optional)NoThis is the callback closure called if there was a failure during the SDK initialization process.

Issue Card Design Parameters (Enterprise Only)#

designKeyNoString up to 30 charactersThe identifier for the design which will be applied to the card.
qrCodeNoString up to 256 charactersThe URL for the QR code image which will be printed on the card.
extraEmbossingLineNoString up to 25 charactersText for the embossed line that will be applied to the card. (This is located under the cardholder name.)
imageUrlNoString up to 256 charactersThe image that will be printed on the card.
additionalImageUrlNoString up to 256 charactersThe 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.

val cardOptions = CardOptions(...)

The available parameters are:

ParameterDefault ValueDescription
showStatsButtonfalseControls the Stats button is displayed. This enables the user to see their monthly consumption statistics.

Stats button
showAccountSettingsButtontrueControls if the Account Settings button is displayed. This enables the user to see the account settings screen.

Account Settings button
hideFundingSourcesReconnectButtonfalseControls 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.

Account Settings button
showNotificationPreferencesfalseControls if the notification preferences menu is displayed on the Card settings screen.
showDetailedCardActivityOptionfalseControls if the Detailed Card Activity selector is displayed on the Card settings screen. If the selector is activated, all transactions are shown, including declines, balance inquiries, etc.
showMonthlyStatementsOptiontrueControls if the Monthly Statements menu is displayed on the Card settings screen. The menu enables users to view their monthly statements.
authenticateOnStartupfalseControls if the user must authenticate their account (using a Passcode or Biometrics) when the app opens or after returning from background mode. Enabling this option will require the user to create a Passcode when signing up.
authenticateOnPCICardOptions.PCIAuthType.NONEControls 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 CardOptions.PCIAuthType setting are:
  • NONE

Note: If biometric authentication is enabled, it will appear first. The user may choose to cancel biometric authentication and use their Passcode instead.

Note: Only available on devices with Android 10+ / API 29+.
trueControls if the UI's dark theme is enabled.

Note: If this value is set to true, you should also change your app theme to support the DayNight Theme. See darkThemeEnabled Parameter
openingModeCardOptions.OpeningMode.STANDALONEDefines how the UI opens and closes.
  • CardOptions.OpeningMode.EMBEDDED: This displays a close button on the manage card screen, enabling the user to close the screen and return to the host app. This mode is recommended when starting the Apto UI SDK from an existing app.
  • CardOptions.OpeningMode.STANDALONE: This does not display a close button on the manage card screen. The card UI can only be closed when the user logs out of the app. Use this mode when the host app only uses the Apto UI SDK.
fontOptions (optional)Phone fontsSpecifies custom fonts for the UI. See FontOptions Parameter for more information.

darkThemeEnabled Parameter#

The darkThemeEnabled parameter controls if the UI's dark theme is enabled.

If you have darkThemeEnabled set to true, ensure you have also change your app theme to support the DayNight Theme.

For example, in your /src/main/res/values/styles.xml file, change the following:

    <style name="AppTheme" parent="Theme.AppCompat.DayNight.DarkActionBar">

You should also provide Apto the Dark theme color configuration.

FontOptions Parameter#

The fontOptions parameter specifies custom fonts for the UI. A FontOptions object and can have up to 4 type face parameters:

  • regularFont
  • mediumFont
  • semiBoldFont
  • boldFont

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

  • Set no type faces, and use the default phone fonts for the UI.
  • Set all 4 type faces to provide consistent fonts throughout the UI.
val fontOptions = FontOptions(        regularFont = Typeface.createFromAsset(assets, "regular-font.otf"),        mediumFont = Typeface.createFromAsset(assets, "medium-font.otf"),        semiBoldFont = Typeface.createFromAsset(assets, "semibold-font.otf"),        boldFont = Typeface.createFromAsset(assets, "bold-font.otf"))

Note: Ensure you replace the .otf file names with the files included in your project's assets folder.

Use the resulting FontOptions object as the fontOptions parameter for the CardOptions object:

val options = CardOptions(fontOptions: fontOptions)

Contributions & Development#

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

If you would like to help:

  1. 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 newly finished task).
  2. 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!