Skip to content

Payments SDK for Android

The Payments SDK is a solution to ease the integration with the Alviere services.

Features

  • Payment Methods
  • Wallets
  • Transactions
  • Check Deposits

Requirements

  • Android Studio Hedgehog or above
  • Android 6.0 (API level 23) or above
  • Java 11+

Installation

Maven Central

1. Add Maven Central to project repositories.

repositories {
    // ...
    mavenCentral()
}

2. Add SDK dependency to module's build.gradle file using the latest version.

dependencies {
    // ...
    implementation 'com.alviere.android:payments:X.Y.Z'
}

Manual

1. Get the latest version of Payments SDK provided by Alviere and add the files to your .m2 path location. Depending on your operation system, these are the default paths.

  • Windows: C:\Users\<User_Name>\.m2
  • Linux: /home/<User_Name>/.m2
  • Mac: /Users/<user_name>/.m2

2. Add a maven path to include the .m2 path location in project repositories. Add the new path before mavenCentral() to respect fetch order.

repositories {
    // ...
    maven { url "file:/path/to/repo/m2repository/" } // Or use mavenLocal() for default path.
    mavenCentral()
}

3. Add SDK dependency to module's build.gradle file using the version provided by Alviere.

dependencies {
    // ...
    implementation 'com.alviere.android:payments:X.Y.Z'
}

Java Version Support

Make sure you have enabled Java 11 language feature support. To do so, guarantee that the following configurations are on the module's build.gradle file.

android {
    // ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_11.toString()
    }
}

Usage

On your android application class, setup Alviere Initialization.

class AndroidApplication : Application() {

  override fun onCreate() {
    super.onCreate()

    Alviere.init(this)
  }
}

Request camera runtime permission for check deposit capture.

Payment Methods

This section outlines the integration with Alviere to manage payment methods. To start, get the PaymentsSdk service interface instance or use with Dependency Injection.

private val paymentsService = PaymentsSdk.service

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = paymentsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

Create Card

To create a card, use Payments SDK service method paymentsService.createCard. Pass the session_token, the account_uuid, the CardRequest model and the AddCardValidation, optionally.

val model = CardRequest(...)
paymentsService.createCard(
   sessionToken = session_token, 
   accountUuid = account_uuid,
   data = model,
)

The result of this action will return the card CardModel on Response.Success and any errors will be returned on Response.Error.

List Cards

To get a list of cards, use the Payments SDK service method paymentsService.listCards. Pass the session_token, the account_uuid and the limit/offset, optionally.

paymentsService.listCards(
   sessionToken = session_token,
   accountUuid = account_uuid,
)

The result of this action will return the token card list List<CardDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Get Card

To get a card, use the Payments SDK service method paymentsService.getCard. Pass the session_token, the account_uuid and the payment_method_uuid.

paymentsService.getCard(
   sessionToken = session_token,
   accountUuid = account_uuid,
   paymentMethodUuid = payment_method_uuid,
)

The result of this action will return the card CardDetailsModel on Response.Success and any errors will be returned on Response.Error.

Delete Card

To delete a card, use the Payments SDK service method paymentsService.deleteCard. Pass the session_token, the account_uuid and the payment_method_uuid.

paymentsService.deleteCard(
  sessionToken = session_token,
  accountUuid = account_uuid,
  paymentMethodUuid = payment_method_uuid,
)
The result of this action will return on Response.Success and any errors will be returned on Response.Error.

Create Bank Account

To create a bank account, use Payments SDK service method paymentsService.createBankAccount. Pass the session_token, the account_uuid and the BankTokenRequest model.

val model = BankTokenRequest(...)
paymentsService.createBankToken(
  sessionToken = session_token,
  accountUuid = account_uuid,
  data = model,
)

The result of this action will return the bank BankAccountModel on Response.Success and any errors will be returned on Response.Error.

List Bank Accounts

To get a list of bank accounts, use the Payments SDK service method paymentsService.listBankAccounts. Pass the session_token, the account_uuid and the limit/offset, optionally.

paymentsService.listBankAccounts(
   sessionToken = session_token,
   accountUuid = account_uuid,
)

The result of this action will return the user's bank accounts List<BankAccountModel> on Response.Success and any errors will be returned on Response.Error.

Get Bank Account

To get the user's bank account, use the Payments SDK service method paymentsService.getBankAccount. Pass the session_token, the account_uuid and the payment_method_uuid.

paymentsService.getBankAccount(
  sessionToken = session_token,
  accountUuid = account_uuid,
  paymentMethodUuid = payment_method_uuid,
)

The result of this action will return the user's bank account BankAccountModel on Response.Success and any errors will be returned on Response.Error.

Delete Bank Account

To delete the user's bank account, use the Payments SDK service method paymentsService.deleteBankAccount. the session_token, the account_uuid and the payment_method_uuid.

paymentsService.deleteBankAccount(
  sessionToken = session_token,
  accountUuid = account_uuid,
  paymentMethodUuid = payment_method_uuid,
)

The result of this action will return on Response.Success and any errors will be returned on Response.Error.

Create Plaid Bank Account

To create a plaid bank account, use Payments SDK service method paymentsService.createPlaidBankAccount. Pass the session_token, the account_uuid and the PlaidBankAccountRequest model.

val model = PlaidBankAccountRequest()
paymentsService.createPlaidBankAccount(
  sessionToken = session_token,
  accountUuid = account_uuid,
  data = model,
)

The result of this action will return the Plaid's bank BankAccountModel on Response.Success and any errors will be returned on Response.Error.

Activate Plaid Bank Account

To activate the user's Plaid bank account, use the Payments SDK service method paymentsService.activatePlaidBankAccount. Pass the session_token, the account_uuid and the payment_method_uuid.

paymentsService.activatePlaidBankAccount(
  sessionToken = session_token,
  accountUuid = account_uuid,
  paymentMethodUuid = payment_method_uuid,
)

The result of this action will activate a Plaid bank account in the Alviere system after an update in authentication credentials on Response.Success and any errors will be returned on Response.Error.

Wallets

This section outlines the integration with Alviere to manage user's account wallets. To start, get the PaymentsSdk service interface instance or use with Dependency Injection.

private val paymentsService = PaymentsSdk.service

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = paymentsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

List Wallets

To get the list of wallets, use the Payments SDK service method paymentsService.listWallets. Pass the session_token, the account_uuid and the limit/offset optionally.

paymentsService.listWallets(
  sessionToken = session_token,
  accountUuid = account_uuid,
)

The result of this action will return the wallets List<WalletDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Get Wallet

To get a wallet, use the Payments SDK service method paymentsService.getWallet. Pass the session_token, the account_uuid and the wallet_uuid.

paymentsService.getWallet(
  sessionToken = session_token,
  accountUuid = account_uuid,
  walletUuid = wallet_uuid,
)

The result of this action will return the wallet WalletDetailsModel on Response.Success and any errors will be returned on Response.Error.

List Wallet Transactions

To get a list of wallet transactions, use the Payments SDK service method paymentsService.listWalletTransactions. Pass the session_token, the wallet_uuid and the limit/offset/startDate/endDate/type/status, optionally.

paymentsService.listWalletTransactions(
  sessionToken = session_token,
  walletUuid = wallet_uuid,
)

The result of this action will return the wallet transactions List<TransactionDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Load Funds

To load funds into the user's account wallet, use the Payments SDK service method paymentsService.loadFunds. Pass the session_token, the wallet_uuid and the LoadFundsRequest model.

model = LoadFundsRequest(...)
paymentsService.loadFunds(
  sessionToken = session_token,
  walletUuid = wallet_uuid,
  data = model,
)

The result of this action will return the load transaction TransactionModel on Response.Success and any errors will be returned on Response.Error.

Withdraw Funds

To withdraw funds from the user's account wallet, use the Payments SDK service method paymentsService.withdrawFunds. Pass the session_token, the wallet_uuid and the WithdrawFundsRequest model.

model = WithdrawFundsRequest(...)
paymentsService.withdrawFunds(
  sessionToken = session_token,
  walletUuid = wallet_uuid,
  data = model,
)

The result of this action will return the withdraw transaction TransactionModel on Response.Success and any errors will be returned on Response.Error.

Send Funds

To send funds from the user's account wallet to another wallet, use the Payments SDK service method paymentsService.sendFunds. Pass the session_token, the wallet_uuid and the SendFundsRequest model.

model = SendFundsRequest(...)
paymentsService.sendFunds(
  sessionToken = session_token,
  walletUuid = wallet_uuid,
  data = model,
)

The result of this action will return the send transaction TransactionModel on Response.Success and any errors will be returned on Response.Error.

Transfer Funds

To transfer funds to a local beneficiary, use the Remit SDK service method paymentsService.transferFunds. Pass the session_token, the wallet_uuid and the TransferFundsRequest model.

val model = TransferFundsRequest(...)
remitService.transferFunds(
    token = session_token,
    walletUuid = wallet_uuid,
    data = model,
)

The result of this action will return the newly created TransferFundModel on Response.Success and any errors will be returned on Response.Error.

Transactions

This section outlines the integration with Alviere to manage user's account wallets transactions. To start, get the PaymentsSdk service interface instance or use with Dependency Injection.

private val paymentsService = PaymentsSdk.service

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = paymentsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

List Child Transactions

To get a list of child transactions, use the Payments SDK service method paymentsService.listChildTransactions. Pass the session_token, the transaction_uuid and the limit/offset/type/status, optionally.

paymentsService.listWalletTransactions(
  sessionToken = session_token,
  transactionUuid = transaction_uuid,
)

The result of this action will return the child transactions List<TransactionDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Get Transaction Details

To get a specific wallet transaction details, use the Payments SDK service method paymentsService.getTransactionDetails. Pass the session_token, the account_uuid and the transaction_uuid.

paymentsService.getTransactionDetails(
  sessionToken = session_token,
  accountUuid = account_uuid,
  transactionUuid = transaction_uuid,
)

The result of this action will return the wallet transaction detail TransactionDetailsModel on Response.Success and any errors will be returned on Response.Error.

Get Receipt

To get a specific wallet transaction receipt, use the Payments SDK service method paymentsService.getReceipt. Pass the session_token, the account_uuid and the transaction_uuid.

paymentsService.getReceipt(
  sessionToken = session_token,
  accountUuid = account_uuid,
  transactionUuid = transaction_uuid,
)

The result of this action will return the wallet transaction receipt ReceiptModel on Response.Success and any errors will be returned on Response.Error.

Cancel Transaction

To cancel a specific transaction, use the Payments SDK service method paymentsService.cancelTransaction. Pass the session_token and the transaction_uuid.

paymentsService.cancelTransaction(
  sessionToken = session_token,
  transactionUuid = transaction_uuid,
  data = model,
)

The result of this action will return on Response.Success and any errors will be returned on Response.Error.

Check Deposits

This section outlines the integration with Alviere to manage check deposits. To start, get the PaymentsSdk service interface instance or use with Dependency Injection.

private val paymentsService = PaymentsSdk.service
private val tokenRepository = TokenRepository()

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = paymentsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

[UI] Deposit Check

The Deposit Check is implemented through Activity or through the navigation controller. To get started, set the Payments SDK event listener and obtain a camera token.

PaymentsSdk.setEventListener(depositCheckSdkCallback)
tokenRepository.getCameraToken(...)

Compose

To start using this feature with Compose, wrap DepositCheckScreen inside a typical navigation composable, pass the camera_token, thesession_token, the external_id, the wallet_uuid, the CurrencyModel, the amount, the action to close the view and the List<CheckServiceFeeModel>, optionally.

DepositCheckScreen(
  cameraToken = camera_token,
  sessionToken = session_token,
  externalId = external_id,
  walletUuid = wallet_uuid,
  currency = CurrencyModel.USD,
  amount = 100,
  navController::navigateUp,
)

Compose From Activity

To start using this feature with Compose from an activity, create a new activity and set the composable content DepositCheckScreen inside onCreate, pass the camera_token, thesession_token, the external_id, the wallet_uuid, the CurrencyModel, the amount, the action to close the view and the List<CheckServiceFeeModel>, optionally.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  setContent {
    MaterialTheme {
      DepositCheckScreen(
        cameraToken = camera_token,
        sessionToken = session_token,
        externalId = external_id,
        walletUuid = wallet_uuid,
        currency = CurrencyModel.USD,
        amount = 100,
        onCloseAction = ::finish,
      )
    }
  }
}

The result of this action will return the check CheckDetailsModel on onSuccess(check: CheckDetailsModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Deposit Check

To deposit a check, use the Payments SDK service method paymentsService.depositCheck. Pass the session_token, the wallet_uuid, the external_id, the CurrencyModel, the amount, the serviceFees and the checkCapture.

paymentsService.depositCheck(
  sessionToken = session_token,
  walletUuid = wallet_uuid,
  externalId = external_id,
  currency = CurrencyModel.USD,
  amount = 100,
  serviceFees = serviceFees,
  checkCapture = checkCapture,
)

The result of this action will return a check CheckDetailsModel on Response.Success and any errors will be returned on Response.Error.

[UI] Capture Check

Capture Check Only, a Capture Mode through Activity or through the navigation controller. To get started, set the Payments SDK event listener and obtain a camera token.

PaymentsSdk.setEventListener(checkCaptureSdkCallback)
tokenRepository.getCameraToken(...)

Compose

To start using this feature with Compose, wrap CheckCaptureScreen inside a typical navigation composable, pass the camera_token and the action to close the view.

CheckCaptureScreen(
  cameraToken = camera_token,
  onCloseAction = navController::navigateUp,
)

Compose From Activity

To start using this feature with Compose from an activity, create a new activity and set the composable content CheckCaptureScreen inside onCreate, pass the camera_token and the action to close the view.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  setContent {
    MaterialTheme {
      CheckCaptureScreen(
        cameraToken = camera_token,
        onCloseAction = ::finish,
      )
    }
  }
}

The result of this action will return the check capture CheckCaptureDetailsModel on onSuccess(checkCapture: CheckCaptureDetailsModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

List Checks

To get a list of checks, use Payments SDK service method paymentsService.listChecks. Pass the session_token, the wallet_uuid and the limit/offset/startDate/endDate, optionally.

paymentsService.listChecks(
   sessionToken = session_token, 
   walletUuid = wallet_uuid,
)

The result of this action will return the checks List<CheckDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Get Check

To get a check, use the Payments SDK service method paymentsService.getCheck. Pass the session_token, the wallet_uuid and the check_uuid.

paymentsService.getCheck(
   sessionToken = session_token,
   walletUuid = wallet_uuid,
   checkUuid = check_uuid,
)

The result of this action will return a check CheckDetailsModel on Response.Success and any errors will be returned on Response.Error.

Customization Object

To start, create a PaymentsCustomize object and set it by PaymentsSdk.setCustomize.

This object has a default customizations for every UI feature of the SDK. Navigate through the object source code to check all possible configurations and change any value.

val customize = PaymentsCustomize(
  documentsCaptureCustomize = DocumentsCaptureCustomize(
    checkFrontTitle = R.string.title_check_front,
    titleTextStyle = alviereTitleXLRegular.copy(
      fontSize = 20.sp,
    )
  ),
)

PaymentsSdk.setCustomize(customize)

Text and Localization

The PaymentsCustomize by default uses String Resources from strings.xml. This allows string keys to be override directly in your string resources file and new languages can be added. Currently, the SDK only supports english.

Fonts

The PaymentsCustomize uses Compose TextStyle for every text configuration and this includes font family. Currently, the default value is FontFamily.SansSerif.

Customization Theme

The Payments SDK uses a color schema PaymentsSdkColors to customize the Colors of every UI feature and this allows a more robust implementation on top of MaterialTheme, including light and dark mode.

By default, the Payments SDK uses a default light mode color schema, but you can configure dark mode, or use a custom color schema PaymentsSdkColors as explained below.

@Composable
fun AppTheme(
  darkTheme: Boolean = isSystemInDarkTheme(),
  content: @Composable () -> Unit,
) {
  val colorScheme = if (darkTheme) darkScheme else lightScheme
  val paymentsSdkColors = if (darkTheme) darkPaymentsSdkColorPalette else lightPaymentsSdkColorPalette

  CompositionLocalProvider(
    LocalPaymentsSdkColorPalette provides paymentsSdkColors,
  ) {
    MaterialTheme(
      colorScheme = colorScheme,
      content = content,
    )
  }
}

The lightPaymentsSdkColorPalette and darkPaymentsSdkColorPalette can be recreated by using the same functions and changing the default colors.

val paymentsSdkColors = if (darkTheme) {
  PaymentsSdkColors(
    documentCaptureTokens = paymentsDocumentCaptureDarkColors(
      captureBackground = Color.Black,
    ),
  )
} else {
  PaymentsSdkColors(
    documentCaptureTokens = paymentsDocumentCaptureLightColors(
      captureBackground = Color.Black,
    ),
  )
}