Skip to main content
Version: Android-10.0.0

Android Vipaso SDK

The main entry point for the Vipaso Android SDK, organized into user and payment namespaces for clear separation of functionality.

User APIs​

Handles user authentication and account management, organized by user type:

  • customer: Customer user APIs for account signup, login/logout, and account recovery.

  • business: Business user APIs for login and logout operations.

  • delegated: External authentication APIs for third-party identity providers.

Payment APIs​

Manages payment processing and transaction handling, organized by user type:

  • customer: Customer payment APIs for handling payment requests, and viewing transaction history.

  • customer.instrument: Customer payment instrument APIs for adding, managing, and removing payment methods.

  • business: Business payment APIs for sending payment requests, canceling transactions, and accessing payment records.

Namespaces and entry points​

All public APIs are accessed through Vipaso and grouped by domain and perspective.

// User domain
val customerUser = Vipaso.user.customer
val businessUser = Vipaso.user.business
val delegatedUser = Vipaso.user.delegated

// Payment domain
val customerPayment = Vipaso.payment.customer
val businessPayment = Vipaso.payment.business

// Customer payment instruments
val customerInstrument = Vipaso.payment.customer.paymentInstrument

SDK Version Requirements​

  • Android Compile SDK: 35 (Your app App Compile SDK must be 34 or higher)
  • Android Target SDK = 35
  • Android Min SDK: 26 (Your app App Min SDK must be 26 or higher)

Required Permissions​

Add the following permissions to your app's AndroidManifest.xml:

<!-- BLE feature requirement -->
<uses-feature
    android:name="android.hardware.bluetooth_le"
    android:required="true" />

<!-- Bluetooth permissions -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- Location permissions (for Android 10 and below) -->
<uses-permission
    android:name="android.permission.ACCESS_FINE_LOCATION"
    android:maxSdkVersion="30" />
<uses-permission
    android:name="android.permission.ACCESS_COARSE_LOCATION"
    android:maxSdkVersion="30" />

<!-- Bluetooth permissions for Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission
    android:name="android.permission.BLUETOOTH_ADVERTISE"
    android:usesPermissionFlags="neverForLocation"
    tools:targetApi="s" />

<!-- Network permission -->
<uses-permission android:name="android.permission.INTERNET" />

For Android 12 (API level 31) and above, request runtime permissions for BLUETOOTH_ADVERTISE and BLUETOOTH_CONNECT. For Android 11 and below, ACCESS_FINE_LOCATION permission is required for BLE scanning. Make sure to properly request these permissions in your app before using the BLE payment functionality.

Setup​

Initialize the Vipaso SDK using the VipasoSdkInitializer singleton object. The SDK is always full-capable; there is no mode to select.

It is recommended to call VipasoSdkInitializer.initialize() in your Android Application's onCreate() method or in your first activity.

The SDK initializes asynchronously. Internet access is required only the first time; subsequent runs can be offline. Pass a callback to receive the result:

import io.vipaso.vipaso.sdkApi.core.vipasoSdkCallback
import io.vipaso.vipaso.sdkApi.core.SdkInitializationError

VipasoSdkInitializer.initialize(
    context = this,
    url = "https://your.vipaso.backend.url", // URL provided by Vipaso support team
    env = "production", // Environment value provided by Vipaso support team
    onResult = vipasoSdkCallback(
        onSuccess = {
            // SDK is ready - you can now use all Vipaso APIs
        },
        onError = { error ->
            // Handle initialization error
            when (error) {
                is SdkInitializationError.NetworkError -> {
                    // SDK requires internet connection for first-time setup to establish connection
                }
                is SdkInitializationError.ConfigFetchError -> {
                    // Failed to fetch configuration from backend
                }
                is SdkInitializationError.InvalidUrlError -> {
                    // The URL provided is not valid
                }
                is SdkInitializationError.UnexpectedError -> {
                    // Unexpected error occurred
                }
            }
        }
    ),
    disableTelemetry = false // Optional: recommended to leave as default, set to true to disable telemetry
)

Important Notes:

  • The url and env parameters are provided by the Vipaso support team.
  • Any SDK APIs (e.g., establishAuthentication, fetchUser) can be called immediately after initialize()
  • After the first successful initialization, the SDK can operate without an internet connection on subsequent app launches.
  • The SDK includes built-in telemetry that allows us to support your integration and troubleshoot issues more effectively. It does not collect any information from the host app. Telemetry collection is controlled on the server side (disabled by default in production and enabled only on demand for debugging). If you disable telemetry in the client, that setting takes precedence over any backend setting.

Error Handling​

When calling SDK methods, wrap them in try/catch blocks to handle exceptions properly. All SDK operations may throw appropriate exceptions when an unexpected error occurs. Implementing proper error handling ensures your application responds gracefully to network issues, BLE connection errors, or other errors.

try {
    val user = Vipaso.user.customer.fetchUser()
    // Process user data
} catch (e: Throwable) {
    // Handle unexpected errors
}

Use Cases​

Practical implementation guides for common business scenarios: