Skip to main content

Getting Started on Android

1.0.0 (Latest)

Introduction​

The Software Development Kit for Android is a library with a simple set of tools that allow you to easily communicate with the Paysafe Wallet API. The SDK is written in Kotlin 1.9 using coroutines but Java is fully supported as well, using callback functions.

Requirements​

  • Android 7 (API Level 24) and above
  • Android Gradle Plugin 7.4 and above
  • Gradle 7.5 and above
  • AndroidX

Integration​

Update root-level settings.gradle.kts file to include the Paysafe Maven repository:

settings.gradle.kts
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url = uri("https://repository.paysafe.com/") }
  }
}

Then add the dependency in your module-level build.gradle.kts:

build.gradle.kts
dependencies {
  implementation("com.paysafe:paysafe-wallet-saas-android:<latest-version>")
}

Usage​

All wallet operations are provided via the Wallet singleton:

val wallet = Wallet.getInstance()

Configure the SDK​

The SDK needs to be configured before first use. The configuration should be performed only once in the lifetime of the application by calling the configure method of the Wallet instance. Mind that configure is a suspend function that has to be called inside a coroutine scope.

lifecycleScope.launch {
  // issue a <config-token> from your backend server
  val configureResult = wallet.configure(
    SdkConfiguration(
      configToken = "<config-token>", /* the config token you have just issued */
      apiEnvironment = ApiEnvironment.Production, /* set to Production or Test to direct API calls to the appropriate environment */
      context = this@MainActivity /* the activity context */
    )
  )
  // use configureResult.digitalFingerprint for the authentication step
}

The configuration token is issued from your backend server. The steps to generate it are explained in SDK Configuration.

The available ApiEnvironment values and the corresponding base urls are:

Authenticate User​

To ensure secure access to customer data by the SDK, it is necessary to provide a customer token. Customer tokens exclusively permit access to resources linked to the specific customer for whom the token was generated. Call the authenticate method of the Wallet instance to set the customer token:

// issue a <customer-token> from your backend server, passing configureResult.digitalFingerprint
wallet.authenticate(AuthenticationConfiguration("<customer-token>"))

The customer token is issued from your backend server passing the digitalFingerprint value from the configuration result. More details on getting the customer token are available in SDK User Authentication.

Wallet Operations​

If the Configure SDK and the Authenticate operations were successful, you can start using the SDK for wallet operations.

try {
  val profile = wallet.getProfileService().getProfile(emptyList())
  Log.d(TAG, profile.toString())
} catch (exception: Exception) {
  Log.d(TAG, exception.toString())
}

UI Theme Configuration​

Appearance for the UI elements provided by the SDK can be customized completely or partially by extending the default theme. Mind that it also supports dark mode and you have to override the values-night as well.

themes.xml
<resources>
    <style name="Theme.MyApp" parent="Theme.PaysafeWallet">

        <!-- typography -->
        <item name="pswFontRegular">@font/regular</item>
        <item name="pswFontLight">@font/light</item>
        <item name="pswFontSemibold">@font/semibold</item>

        <!-- corner radius -->
        <item name="pswCornerRadiusSmall">2dp</item>
        <item name="pswCornerRadiusMedium">4dp</item>
        <item name="pswCornerRadiusLarge">8dp</item>

        <!-- border stroke width -->
        <item name="pswBorderStrokeWidth">1dp</item>

        <!-- drawables -->
        <item name="pswIconClose">@drawable/ic_close_template</item>
        <item name="pswIconErrorTriangle">@drawable/ic_error_triangle_template</item>
        <item name="pswIconInfo">@drawable/ic_ui_info_template</item>
        <item name="pswSelectorDrawableCheckbox">@drawable/bg_checkbox</item>

        <!-- base app background color. -->
        <item name="pswColorBaseDefault">#F8F8F8</item>

        <!-- surface background color over the base. -->
        <item name="pswColorSurfaceDefault">#0D141414</item>
        <item name="pswColorSurfaceElevated">#FFFFFF</item>
        <item name="pswColorSurfaceDisabled">#0D141414</item>
        <item name="pswColorSurfaceFocused">#14141414</item>
        <item name="pswColorSurfacePressed">#1F141414</item>

        <!-- text color. -->
        <item name="pswColorTextPrimary">#141414</item>
        <item name="pswColorTextPrimaryInverted">#F5F5F5</item>
        <item name="pswColorTextSecondary">#424542</item>
        <item name="pswColorTextSecondaryInverted">#C9CAC8</item>
        <item name="pswColorTextActive">#054AB2</item>
        <item name="pswColorTextActiveInverted">#B1D2FF</item>
        <item name="pswColorTextPressed">#0860E3</item>
        <item name="pswColorTextFocused">#003F9D</item>
        <item name="pswColorTextDisabled">#787D78</item>
        <item name="pswColorTextDisabledInverted">#B1B2AF</item>

        <!-- all graphic elements that are clickable - buttons. icons, parts of atoms. etc. Do not use for active text! -->
        <item name="pswColorActionActive">#0455CD</item>
        <item name="pswColorActionSupportiveActive">#4771ED</item>
        <item name="pswColorActionPressed">#0860E3</item>
        <item name="pswColorActionSelected">#E2ECF9</item>
        <item name="pswColorActionFocused">#003F9D</item>
        <item name="pswColorActionActiveInverted">#B1D2FF</item>
        <item name="pswColorActionInactive">#2C2E2C</item>
        <item name="pswColorActionInactiveSubtle">#5F615D</item>
        <item name="pswColorActionDisabled">#969896</item>
        <item name="pswColorActionDisabledSubtle">#C9CAC8</item>

        <!-- icons and visual indicative elements. Can be clickable. but only when used for special occasions. -->
        <item name="pswColorContentInformativeIntense">#004370</item>
        <item name="pswColorContentInformative">#075BC3</item>
        <item name="pswColorContentInformativeSubtle">#66C0ECFA</item>
        <item name="pswColorContentPositiveIntense">#005C20</item>
        <item name="pswColorContentPositive">#179743</item>
        <item name="pswColorContentPositiveSubtle">#66BCF1AC</item>
        <item name="pswColorContentAttentionIntense">#934A00</item>
        <item name="pswColorContentAttention">#D66000</item>
        <item name="pswColorContentAttentionSubtle">#66FFE8A6</item>
        <item name="pswColorContentNegativeIntense">#990D00</item>
        <item name="pswColorContentNegative">#D31D33</item>
        <item name="pswColorContentNegativeSubtle">#66FFA5A5</item>
        <item name="pswColorContentBrandPrimaryIntense">#003F9D</item>
        <item name="pswColorContentBrandPrimary">#0455CD</item>
        <item name="pswColorContentBrandPrimarySubtle">#4DF492F7</item>
        <item name="pswColorContentBrandSecondaryIntense">#076580</item>
        <item name="pswColorContentBrandSecondary">#1CB535</item>
        <item name="pswColorContentBrandSecondarySubtle">#4DBAF1BF</item>
        <item name="pswColorContentBrandAccent">#FCE72C</item>
        <item name="pswColorContentBrandAccentModerate">#FFF681</item>
        <item name="pswColorContentBrandAccentSubtle">#FFFCD9</item>
        <item name="pswColorContentElementIntense">#61141414</item>
        <item name="pswColorContentSeparator">#C9CAC8</item>
        <item name="pswColorContentBlack">#141414</item>
        <item name="pswColorContentBlackSubtle">#61141414</item>
        <item name="pswColorContentWhite">#F5F5F5</item>
    </style>
</resources>

Specify the newly created theme Theme.MyApp in the initial SDK configuration:

wallet.configure(
    SdkConfiguration(
        configToken = "<config-token>",
        apiEnvironment = ApiEnvironment.Production,
        context = this@MainActivity,
        customThemeResId = R.style.Theme_MyApp
    )
)

The customThemeResId field in the SdkConfiguration object is optional. If not provided, the default theme will be used.

Java Support​

Java Android applications are fully supported. Each asynchronous operation has a version with suffix Async which takes the same arguments with two additional: cancellation signal to allow cancellation and a callback upon completion. All Async functions complete on the main thread.