Skip to main content
Version: Next

Android VipasoSDK

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.

When initializing the SDK, you need to:

  1. Initialize the SDK
  2. Set the configuration parameters
// Step 1: Initialize the SDK
VipasoSdkInitializer.initialize(context)

// Step 2: Create and set the SDK configuration
val sdkConfig = VipasoSdkConfig(
    baseUrl = "https://your.base.path",
    bleUuidService = UUID.fromString("your-service-uuid"),
    emailSupport = "support@example.com", // Optional
    timeoutPaymentStatusBackendPollingDuration = 60.seconds // Optional, defaults to 60 seconds
)

// Set the SDK configuration, you need to set this before using any of the SDK features
VipasoSdkInitializer.setSdkConfig(sdkConfig)

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: