Android SDK

Everything you need to install, configure, and launch the Vrtx Android SDK, including supported Android versions, Maven Central installation, public setup contract, callbacks, and authentication behavior.

What this guide covers

Use this guide to add the Vrtx Android SDK to your app, configure the SDK with your credentials, and launch the wallet experience from your Android application.

Add Dependency

Add Maven Central and include the Vrtx Android SDK dependency in your Gradle configuration.

Configure SDK

Pass your client credentials, environment, language, theme mode, and optional font family.

Launch SDK

Call Vrtx.setup from your host app to authenticate and open the SDK experience.

Handle Result

Use onSuccess and onError callbacks to respond to launch status.

Overview

The Vrtx Android SDK provides a native Android wallet experience that can be embedded into your host application. It supports wallet authentication, payments, card management, and related wallet flows without requiring your app to build or maintain the underlying financial infrastructure.

The SDK is built with Jetpack Compose and follows modern Android architecture patterns, including ViewModel, DataStore, and Coroutines.

Supported OS Versions & Requirements

The Vrtx Android SDK targets modern Android devices and requires the following platform and tooling versions.

Tooling	Minimum Version
Android `minSdk`	29
Android `compileSdk`	36
Android Gradle Plugin	8.13
Kotlin	2.1
JVM target	17
Java version	17

Confirm project compatibility

Before installation, make sure your host app uses compatible Android Gradle Plugin, Kotlin, JVM, and Java versions.

Installation

Add Maven Central to your repositories, then add the Vrtx Android SDK dependency.

dependencyResolutionManagement { repositories { google() mavenCentral() } }

Dependency source

The SDK is installed from Maven Central using your app module Gradle dependency configuration.

Quick Start

Call Vrtx.setup to authenticate with Vrtx and launch the SDK UI.

kotlin

Vrtx.setup(
      clientId = "VRTX_CLIENT_ID",
      clientSecret = "VRTX_CLIENT_SECRET",
      environment = Environment.Sandbox,
      language = Language.English,
      mode = Mode.LIGHT,
      fontFamily = FontFamily.Default,
      onSuccess = { /* SDK UI launched */ },
      onError = { error -> /* surface to the user */ },*
   )

Security note

Never hard-code clientSecret or real production credentials in source control. Store and manage production credentials securely.

Contract

Vrtx.setup accepts the following public configuration values.

Parameter	Enum	Values
environment	`Environment`	`Sandbox`, `Staging`
language	`Language`	`English`, `Arabic`
mode	`Mode`	`Light`, `Dark`

Custom font

For appearance, pass mode and a Compose fontFamily built from a font already embedded in your app, such as Inter.

SDK Callbacks

Vrtx.setup provides callbacks so your host app can react to launch status.

Callback	Type	When It Runs	Recommended Host App Behavior
`onSuccess`	`() -> Unit`	Called when the SDK UI launches successfully	Continue normal host app behavior or track successful SDK launch
`onError`	`(error) -> Unit`	Called when setup, authentication, or launch fails	Show a user-friendly error message or retry option

Required setup callbacks

Best practice

Always implement onError so the host app can show a clear fallback message if the SDK cannot be launched.

Authentication

The SDK authenticates with the Vrtx backend using the client credentials passed to Vrtx.setup.

Field	Description
`clientId`	Identifies the calling application
`clientSecret`	Authenticates the calling application

The SDK uses these credentials to authenticate with Vrtx before launching the SDK UI.

Credential handling

Client credentials should be handled securely and should not be exposed in public repositories, logs, or client-side debug output.

Integration Checklist

Android SDK Integration Checklist

Troubleshooting

SDK dependency cannot be resolved

Ensure mavenCentral() is added to your repositories.
Confirm the dependency version is correct.
Sync Gradle after updating the dependency.

SDK does not launch

Confirm clientId and clientSecret are valid.
Confirm the selected environment is correct.
Implement onError and surface the returned error for debugging.

Build fails after adding the SDK

Confirm your project uses the required Kotlin, Android Gradle Plugin, Java, and JVM target versions.
Confirm your app’s minSdk is 29 or higher.

Custom font does not appear

Ensure the font is embedded in your app.
Confirm the FontFamily passed to the SDK is correctly configured.
Use FontFamily.Default as a fallback while testing.