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 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:

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 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.

Requirements

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.5.21
Gradle, minimum version 7.0.3

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

In your project's build.gradle file, add the following repositories:

    allprojects {
        repositories {

            ...

            mavenCentral()
            maven { url "https://jitpack.io" }

            ...
        }
    }

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).

In your app's build.gradle, also add the following dependency:

    dependencies {
        ...

        implementation 'com.aptopayments.sdk:ui:3.17.1'

        ...
    }

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.

class YourApp: Application() {
   override fun onCreate() {
      super.create()
      AptoUiSdk.initializeWithApiKey(this, "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:

In the onCreate method of your Application class, invoke AptoUiSdk.initialize initialize the SDK for your application.

class YourApp: Application() {
   override fun onCreate() {
      super.create()
      AptoUiSdk.initialize(this)
     ...
   }
  ...
}

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)

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.

object MyWebTokenProvider() : AptoPlatformWebTokenProvider {
  override fun getToken(payload: String, callback: (Either<WebTokenFailure, String>) -> Unit) {
    // This is an example that uses okhttp to fetch the JWT from your server
    val request = Request.Builder()
      .url("http://localhost/sign")
      .post(payload)
      .build()

    client.newCall(request).enqueue(object : Callback {
      override fun onFailure(call: Call, e: IOException) {
        // let SDK know an error happened
        callback(Either.Left(WebTokenFailure))
      }

      override fun onResponse(call: Call, response: Response) {
        response.use {
          if (!response.isSuccessful) {
            // let SDK know an error happened
            callback(Either.Left(WebTokenFailure))
          } else {
            // send the JWT back to the SDK
            callback(Either.Right(response.body!!.token))
          }
        }
      }
    })
  }
}

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.

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

To start the cardholder onboarding flow:

Initialize a CardOptions object.

    val cardOptions = CardOptions()

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:

Parameter	Required?	Description
`activity`	Yes	This is the Android `Activity` object from which the SDK will be started.
`cardOptions`	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.
`initializationData`	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.
`onSuccess` (optional)	No	This is the callback closure called once the Apto UI SDK has been initialized.
`onError` (optional)	No	This is the callback closure called if there was a failure during the SDK initialization process.

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.

val cardOptions = CardOptions(...)

The available parameters are:

Parameter	Default Value	Description
`showStatsButton`	`false`	Controls 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.
`showNotificationPreferences`	`false`	Controls if the notification preferences menu is displayed on the Card settings screen.
`showDetailedCardActivityOption`	`false`	Controls 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.
`showMonthlyStatementsOption`	`true`	Controls if the Monthly Statements menu is displayed on the Card settings screen. The menu enables users to view their monthly statements.
`authenticateOnStartup`	`false`	Controls 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.
`authenticateOnPCI`	`CardOptions.PCIAuthType.NONE`	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 `CardOptions.PCIAuthType` setting are: `PIN_OR_BIOMETRICS` `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.
`darkThemeEnabled` Note: Only available on devices with Android 10+ / API 29+.	`true`	Controls 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
`openingMode`	`CardOptions.OpeningMode.STANDALONE`	Defines 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 fonts`	Specifies 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">

        ...

    </style>

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:

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).
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​

One-step Initialization​

Two-step Initialization​

Signed Payloads​

Start the Cardholder Onboarding Flow​

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

CardOptions Parameters​

darkThemeEnabled Parameter​

FontOptions Parameter​

Contributions & Development​