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

Declare the callback¶

These callbacks are the main communication back channel to your application. For each action there is one method associated as follows. In addition to these methods, there is also an event method for handling events. Callbacks will always run on main thread.

private val createCardSdkCallback = object : CreateCardSdkCallback {
    override fun onSuccess(card: CardModel) { /* handle success */ }

    override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val listCardsSdkCallback = object : ListCardsSdkCallback {
  override fun onSuccess(cards: List<CardDetailsModel>) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val getCardSdkCallback = object : GetCardSdkCallback {
  override fun onSuccess(card: CardDetailsModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val deleteCardSdkCallback = object : DeleteCardSdkCallback {
  override fun onSuccess() { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val createBankAccountSdkCallback = object : CreateBankAccountSdkCallback {
  override fun onSuccess(bank: BankAccountModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val listBankAccountsSdkCallback = object : ListBankAccountsSdkCallback {
  override fun onSuccess(banks: List<BankAccountModel>) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val getBankAccountSdkCallback = object : GetBankAccountSdkCallback {
  override fun onSuccess(bank: BankAccountModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val deleteBankAccountSdkCallback = object : DeleteBankAccountSdkCallback {
  override fun onSuccess() { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val deleteBankAccountSdkCallback = object : CreatePlaidBankAccountSdkCallback {
  override fun onSuccess(pBank: BankAccountModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val activatePlaidBankAccountSdkCallback = object : ActivatePlaidBankAccountSdkCallback {
  override fun onSuccess() { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

onSuccess¶

This callback method is called when a payment method was successfully executed. Use this to manage the payment methods of a user's account with the Alviere API.

onEvent¶

This callback method is called when the user exited from the Payments SDK, when an error occurred, or when certain events in the Payments SDK flow have occurred. This allows your application to get more information about what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display information related to the error to the user and have them try doing the action again.

[UI] Create Card¶

The Create Card is possible to implement through Activity or through the navigation controller. To get started, set the Payments SDK event listener.

PaymentsSdk.setEventListener(createCardSdkCallback)

Activity¶

To start using this feature on an activity, create an Intent using paymentsService.createCardByIntent, pass the parent_activity, the session_token and the account_uuid. Optionally, it can be passed the external_id, and a validation object AddCardValidation with the rules to be further applied.

val intent = paymentsService.createCardByIntent(
  parentActivity = parent_activity,
  sessionToken = session_token,
  externalId = external_id,
  accountUuid = account_uuid,
  customAddCardValidation = AddCardValidation(
    minChars = 0,
    maxChar = 5,
    keyboardType = InputType.TYPE_CLASS_NUMBER,
    validCardTypes = listOf(PaymentCard.VISA, PaymentCard.MASTERCARD)
  )
)
startActivity(intent)

To start using this feature on a navigation controller, add the destination PaymentsActivity to your navigation graph and connect it. An action will be generated that will have to have the arguments embedded, as follows.

<fragment
    android:id="@+id/payments_create_card_fragment"
    android:name="com.example.app.CreateCardFragment">
    <action
        android:id="@+id/action_payments_create_card_fragment_to_create_card_by_activity"
        app:destination="@id/create_card_by_activity" />
</fragment>

<activity
    android:id="@+id/create_card_by_activity"
    android:name="com.alviere.android.payments.activity.PaymentsActivity">
    <argument
        android:name="payments_extra_feature"
        app:argType="com.alviere.android.payments.PaymentsSdk$Features" />
    <argument
        android:name="payments_extra_session_token"
        app:argType="string" />
    <argument
        android:name="payments_extra_external_id"
        app:argType="string"
        android:defaultValue="@null"
        app:nullable="true" />
    <argument
        android:name="payments_extra_account_uuid"
        app:argType="string"
        android:defaultValue="@null"
        app:nullable="true" />
    <argument
        android:name="payments_extra_card_token_custom_validation_tag"
        app:argType="com.alviere.android.payments.customize.AddCardValidation" />
</activity>

Using Safe Args a class is created for each destination where an action originates. The name of this class is the name of the originating destination, appended with the word "Directions". For example, if the originating destination is a fragment that is named CreateCardFragment, the generated class would be called CreateCardFragmentDirections. This class has a method for each action defined in the originating destination, such as actionPaymentsCreateCardFragmentToCreateCardByActivity() that returns a NavDirections object. This returned NavDirections object can then be passed directly to navigate(), as shown in the following example:

view.findNavController().navigate(
  CreateCardFragmentDirections.actionPaymentsCreateCardFragmentToCreateCardByActivity(
    paymentsExtraFeature = PaymentsSdk.Features.CREATE_CARD,
    paymentsExtraSessionToken = session_token,
    paymentsExtraAccountUuid = account_uuid,
    paymentsExtraCardTokenCustomValidationTag = AddCardValidation(
      minChars = 0,
      maxChar = 5,
      keyboardType = InputType.TYPE_CLASS_NUMBER,
      validCardTypes = listOf(PaymentCardModel.VISA, PaymentCardModel.MASTERCARD)
    )
  )
)

Create Card¶

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

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

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

List Cards¶

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

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

The result of this action will return the token card list List<CardDetailsModel> on onSuccess(cards: List<CardDetailsModel>) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Get Card¶

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

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

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

Delete Card¶

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

paymentsService.deleteCard(
  sessionToken = session_token,
  accountUuid = account_uuid,
  paymentMethodUuid = payment_method_uuid,
  clientCallback = deleteCardSdkCallback
)

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

Create Bank Account¶

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

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

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

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, the ListBankAccountsSdkCallback and the limit/offset, optionally.

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

The result of this action will return the user's bank accounts List<BankAccountModel> on onSuccess(banks: List<BankAccountModel>) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

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, the payment_method_uuid and the GetBankAccountSdkCallback.

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

The result of this action will return the user's bank account BankAccountModel on onSuccess(bank: BankAccountModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Delete Bank Account¶

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

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

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

Create Plaid Bank Account¶

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

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

The result of this action will return the Plaid's bank BankAccountModel on onSuccess(pBank: BankAccountModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

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, the payment_method_uuid and the ActivatePlaidBankAccountSdkCallback.

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

The result of this action will activate a Plaid bank account in the Alviere system after an update in authentication credentials and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

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

Declare the callback¶

These callbacks are the main communication back channel to your application. For each action there is one method associated as follows. In addition to this methods, there is also an event method for handling events. Callbacks will always run on main thread.

private val listWalletsSdkCallback = object : ListWalletsSdkCallback {
  override fun onSuccess(wallets: List<WalletDetailsModel>) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val getWalletSdkCallback = object : GetWalletSdkCallback {
  override fun onSuccess(wallet: WalletDetailsModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val listWalletTransactionsSdkCallback = object : ListWalletTransactionsSdkCallback {
  override fun onSuccess(walletTransactions: List<TransactionDetailsModel>) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val loadFundsSdkCallback = object : LoadFundsSdkCallback {
  override fun onSuccess(loadTransaction: TransactionModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val withdrawFundsSdkCallback = object : WithdrawFundsSdkCallback {
  override fun onSuccess(withdrawTransaction: TransactionModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val sendFundsSdkCallback = object : SendFundsSdkCallback {
  override fun onSuccess(sendTransaction: TransactionModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val transferFundsSdkCallback = object : TransferFundsSdkCallback {
  override fun onSuccess(transferFund: TransferFundModel) { /* handle event */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

onSuccess¶

This callback method is called when a wallets request was successfully executed. Use this to manage the wallets of an user's account with the Alviere API.

onEvent¶

This callback method is called when the user exited from the Payments SDK, when an error occurred, or when certain events in the Payments SDK flow have occurred. This allows your application to get more information about what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display information related to the error to the user and have them try doing the action again.

List Wallets¶

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

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

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

Get Wallet¶

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

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

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

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, the ListWalletTransactionsSdkCallback and the limit/offset/startDate/endDate/type/status, optionally.

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

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

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, the LoadFundsRequest and the LoadFundsSdkCallback.

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

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

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, the WithdrawFundsRequest and the WithdrawFundsSdkCallback.

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

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

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, the SendFundsRequest and the WithdrawFundsSdkCallback.

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

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

Transfer Funds¶

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

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

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

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

Declare the callback¶

These callbacks are the main communication back channel to your application. For each action there is one method associated as follows. In addition to this methods, there is also an event method for handling events. Callbacks will always run on main thread.

private val listChildTransactionsSdkCallback = object : ListChildTransactionsSdkCallback {
  override fun onSuccess(childTransactions: List<TransactionDetailsModel>) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val getTransactionDetailsSdkCallback = object : GetTransactionDetailsSdkCallback {
  override fun onSuccess(walletTransaction: TransactionDetailsModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val getReceiptSdkCallback = object : GetReceiptSdkCallback {
  override fun onSuccess(receipt: ReceiptModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val cancelTransactionCallback = object : CancelTransactionSdkCallback {
  override fun onSuccess() { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

onSuccess¶

This callback method is called when a wallets request was successfully executed. Use this to manage the wallets of an user's account with the Alviere API.

onEvent¶

This callback method is called when the user exited from the Payments SDK, when an error occurred, or when certain events in the Payments SDK flow have occurred. This allows your application to get more information about what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display information related to the error to the user and have them try doing the action again.

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, the ListChildTransactionsSdkCallback and the limit/offset/type/status, optionally.

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

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

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, the transaction_uuid and the getTransactionDetailsSdkCallback.

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

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

Get Receipt¶

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

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

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

Cancel Transaction¶

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

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

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

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()

Declare the callback¶

These callbacks are the main communication back channel to your application. For each action there is one method associated as follows. In addition to this methods, there is also an event method for handling events. Callbacks will always run on main thread.

private val depositCheckSdkCallback = object : DepositCheckSdkCallback {
  override fun onSuccess(check: CheckDetailsModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val checkCaptureSdkCallback = object : CheckCaptureSdkCallback {
  override fun onSuccess(checkCapture: CheckCaptureDetailsModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val listChecksSdkCallback = object : ListChecksSdkCallback {
  override fun onSuccess(checks: List<CheckDetailsModel>) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

private val getCheckSdkCallback = object : GetCheckSdkCallback {
  override fun onSuccess(check: CheckDetailsModel) { /* handle success */ }

  override fun onEvent(event: String, metadata: Map<String, String>?) { /* handle event */ }
}

onSuccess¶

This callback method is called when a payment method was successfully executed. Use this to manage the payment methods of a user's account with the Alviere API.

onEvent¶

This callback method is called when the user exited from the Payments SDK, when an error occurred, or when certain events in the Payments SDK flow have occurred. This allows your application to get more information about what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display information related to the error to the user and have them try doing the action again.

[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(...)

Activity¶

To start using this feature on an activity, create an Intent using paymentsService.depositCheckByIntent, pass the parent_activity, the session_token, the camera_token, the wallet_uuid, the external_id, the CurrencyModel, the amount and the Array<CheckServiceFeeModel>, optionally.

val intent = paymentsService.depositCheckByIntent(
  parentActivity = parent_activity,
  sessionToken = session_token,
  cameraToken = camera_token,
  walletUuid = wallet_uuid,
  externalId = external_id,
  currency = CurrencyModel.USD,
  amount = 100,
)
startActivity(intent)

To start using this feature on a navigation controller, add the destination PaymentsActivity to your navigation graph and connect it. An action will be generated that will have to have the arguments embedded, as follows.

<fragment
    android:id="@+id/deposit_check_fragment"
    android:name="com.example.app.DepositCheckFragment">
    <action
        android:id="@+id/action_deposit_check_fragment_to_deposit_check_by_activity"
        app:destination="@id/deposit_check_by_activity" />
</fragment>

<activity
    android:id="@+id/deposit_check_by_activity"
    android:name="com.alviere.android.payments.activity.PaymentsActivity">
    <argument
        android:name="payments_extra_feature"
        app:argType="com.alviere.android.payments.PaymentsSdk$Features" />
    <argument
        android:name="payments_extra_session_token"
        app:argType="string"
        android:defaultValue="@null"
        app:nullable="true" />
    <argument
        android:name="payments_extra_camera_token"
        android:defaultValue="@null"
        app:argType="string"
        app:nullable="true" />
    <argument
        android:name="payments_extra_check_wallet_uuid"
        app:argType="string"
        android:defaultValue="@null"
        app:nullable="true" />
    <argument
        android:name="payments_extra_external_id"
        app:argType="string"
        android:defaultValue="@null"
        app:nullable="true" />
    <argument
        android:name="payments_extra_check_currency"
        app:argType="com.alviere.android.payments.sdk.model.common.CurrencyModel"
        android:defaultValue="USD" />
    <argument
        android:name="payments_extra_check_amount"
        app:argType="long"
        android:defaultValue="0L"/>
    <argument
        android:name="payments_extra_check_service_fees"
        app:argType="com.alviere.android.payments.sdk.model.common.CheckServiceFeeModel[]"
        android:defaultValue="@null"
        app:nullable="true" />
    <argument
        android:name="payments_extra_check_capture_only"
        app:argType="boolean"
        android:defaultValue="false" />
</activity>

Using Safe Args a class is created for each destination where an action originates. The name of this class is the name of the originating destination, appended with the word "Directions". For example, if the originating destination is a fragment that is named DepositCheckFragment, the generated class would be called DepositCheckFragmentDirections. This class has a method for each action defined in the originating destination, such as actionDepositCheckFragmentToDepositCheckByActivity() that returns a NavDirections object. This returned NavDirections object can then be passed directly to navigate(), as shown in the following example:

view.findNavController().navigate(
  DepositCheckFragmentDirections.actionDepositCheckFragmentToDepositCheckByActivity(
    paymentsExtraFeature = PaymentsSdk.Features.DEPOSIT_CHECK,
    paymentsExtraSessionToken = session_token,
    paymentsExtraCameraToken = camera_token,
    paymentsExtraCheckWalletUuid = wallet_uuid,
    paymentsExtraExternalId = external_id,
    paymentsExtraCheckCurrency = CurrencyModel.USD,
    paymentsExtraCheckAmount = 100,
  )
)

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, the checkCapture from paymentsService.checkCaptureByIntent and the DepositCheckSdkCallback.

and the List<CheckServiceFeeModel>, optionally.

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

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

[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(...)

Activity¶

To start using this feature on an activity, create an Intent using paymentsService.checkCaptureByIntent, pass the parent_activity and the camera_token.

val intent = paymentsService.checkCaptureByIntent(
  parentActivity = parent_activity,
  cameraToken = camera_token,
)
startActivity(intent)

To start using this feature on a navigation controller, add the destination PaymentsActivity to your navigation graph and connect it. An action will be generated that will have to have the arguments embedded, as follows.

<fragment
    android:id="@+id/check_capture_fragment"
    android:name="com.example.app.CheckCaptureFragment">
    <action
        android:id="@+id/action_check_capture_fragment_to_check_capture_by_activity"
        app:destination="@id/check_capture_by_activity" />
</fragment>

<activity
    android:id="@+id/check_capture_by_activity"
    android:name="com.alviere.android.payments.activity.PaymentsActivity">
    <argument
        android:name="payments_extra_feature"
        app:argType="com.alviere.android.payments.PaymentsSdk$Features" />
    <argument
        android:name="payments_extra_camera_token"
        android:defaultValue="@null"
        app:argType="string"
        app:nullable="true" />
    <argument
        android:name="payments_extra_check_capture_only"
        app:argType="boolean"
        android:defaultValue="false" />
</activity>

Using Safe Args a class is created for each destination where an action originates. The name of this class is the name of the originating destination, appended with the word "Directions". For example, if the originating destination is a fragment that is named CheckCaptureFragment, the generated class would be called CheckCaptureFragmentDirections. This class has a method for each action defined in the originating destination, such as actionCheckCaptureFragmentToCheckCaptureByActivity() that returns a NavDirections object. This returned NavDirections object can then be passed directly to navigate(), as shown in the following example:

view.findNavController().navigate(
  DepositCheckFragmentDirections.actionCheckCaptureFragmentToCheckCaptureByActivity(
    paymentsExtraFeature = PaymentsSdk.Features.DEPOSIT_CHECK,
    paymentsExtraCameraToken = camera_token,
    paymentsExtraCheckCaptureOnly = true,
  )
)

List Checks¶

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

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

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

Get Check¶

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

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

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

Alternative Usage¶

Optionally for every SDK callback entry function without UI, there is an alternative suspend function with the same name without callback 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 = ...
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Customization¶

To start using the PaymentsCustomize create the custom object and set it by PaymentsSdk.setCustomize. This will override only the values that you want to customize.

First we have customization objects by features, as follows:

Class	Attribute	Description
PaymentsCustomize	cardTokenCustomize	Create Card customization
	captureCustomize	Capture customization

Then we have all the view components for each of these features. As follows:

Class	Attribute	Description
ToolbarCustomize	backgroundColorRes	Background color resource
	showBackButton	Back button visibility
	showCloseButton	Close button visibility

Class	Attribute	Description
LoadingCustomize	backgroundColorRes	Background color resource
	loadingBarColorRes	Loading bar color resource
	loadingTitleRes	Loading title text resource
	loadingTitleColorRes	Loading title color resource
	loadingTitleTextSizeRes	Loading title text size resource
	loadingMessageRes	Loading message text resource
	loadingMessageColorRes	Loading message color resource
	loadingMessageTextSizeRes	Loading message text size resource
	loadingBarColor	Loading bar color
	loadingTitle	Loading title text
	loadingTitleColor	Loading title color
	loadingTitleTextSize	Loading title text size
	loadingMessage	Loading message text
	loadingMessageColor	Loading message color
	loadingMessageTextSize	Loading message text size

Class	Attribute	Description
TryAgainCustomize	toolbarCustomize	Toolbar customization
	backgroundColorRes	Background color resources
	errorIcon	Error drawable
	errorMessageRes	Error message resources
	errorMessageColorRes	Error message color resources
	errorMessageTextSizeRes	Error message text size resources
	buttonBackgroundRes	Button background drawable
	buttonTextRes	Button text resources
	buttonTextColorRes	Button text color resources
	buttonMarginStartRes	Button margin start resources
	buttonMarginEndRes	Button margin end resources
	buttonMarginBottomRes	Button margin bottom resources
	buttonMarginTopRes	Button margin top resources
	buttonTextSizeRes	Button text size resources
	backgroundColor	Background color
	errorMessage	Error message
	errorMessageColor	Error message color
	errorMessageTextSize	Error message text size
	buttonText	Button text
	buttonTextColor	Button text color
	buttonTextSize	Button text size
	buttonMarginStart	Button margin start
	buttonMarginEnd	Button margin end
	buttonMarginBottom	Button margin bottom
	buttonMarginTop	Button margin top

Class	Attribute	Description
AlviereTextViewCustomize	textColorRes	text color resource
	textSizeRes	Text size resource
	textColor	Text color
	textSize	Text size

Class	Attribute	Description
AlviereButtonCustomize	textRes	Button text resource
	textColorRes	Button text color resource
	textSize	Button text size resource
	backgroundDrawable	Button background drawable
	marginStartRes	Button margin start resource
	marginEndRes	Button margin end resource
	marginBottomRes	Button margin bottom resource
	marginTopRes	Button margin top resource
	height	Button height resource
	text	Button text
	textColor	Button text color
	textSize	Button text size
	marginStart	Button margin start dimension
	marginEnd	Button margin end dimension
	marginBottom	Button margin bottom dimension
	marginTop	Button margin top dimension
	height	Button height dimension

Class	Attribute	Description
AlviereTextInputEditTextCustomize	textColorRes	Input text color resource
	textSizeRes	Input text size resource
	textColor	Input text color
	textSize	Input text size

Class	Attribute	Description
AlviereEditTextCustomize	textColorRes	Edit text color resource
	textSizeRes	Edit text size resource
	textColor	Edit text color
	textSize	Edit text size

View Resources¶

In addition to all Payments SDK functionalities, the Alviere SDKs also provides the ability to customize view resources.

Custom view components can be configured in two ways. The easiest (and recommended) method is by overriding _colors.xml__, strings.xml and dimens.xml resources, setting the key and value according to the following table. Alternatively, you can create customization object.

Override resources¶

To start using the customization by resources just override the keys that you want to customize.

Themes¶

The Payments SDK for Android allows you to customize the main UI Theme used by activities. To do so, you will need to override the theme key that you want to change on your themes.xml file from values and values-night folder. Some UI elements use specific colors that need to be override apart in values and values-night.

<style name="PaymentsSdkTheme" parent="Theme.MaterialComponents.DayNight.DarkActionBar">
    <item name="colorPrimary">@color/alviere_sdk_payments_color_primary</item>
    <item name="colorPrimaryVariant">@color/alviere_sdk_payments_color_primary_variant</item>
    <item name="colorOnPrimary">@color/alviere_sdk_payments_color_on_primary</item>
    <item name="colorSecondary">@color/alviere_sdk_payments_color_secondary</item>
    <item name="colorSecondaryVariant">@color/alviere_sdk_payments_color_secondary_variant</item>
    <item name="colorOnSecondary">@color/alviere_sdk_payments_color_on_secondary</item>
    <item name="android:statusBarColor">@color/alviere_sdk_payments_color_status_bar</item>
    <item name="android:navigationBarColor">@color/alviere_sdk_payments_color_navigation_bar</item>
    <item name="android:windowBackground">@color/alviere_sdk_payments_color_background</item>
    <item name="android:fontFamily">@string/alviere_sdk_payments_font</item>
    <item name="android:windowLightNavigationBar" tools:targetApi="o_mr1">true</item>
</style>

<style name="PaymentsSdkTheme.NoActionBar">
    <item name="windowActionBar">false</item>
    <item name="windowNoTitle">true</item>
</style>

Fonts¶

The Payments SDK for Android allows you to customize the UI font. To do so, you will need to override the font key that you want to change on your strings.xml file. The next section details a list of the current available keys.

Key	PaymentsCustomize Support
alviere_sdk_payments_font	No

Colors¶

The Payments SDK for Android allows you to customize the UI colors. To do so, you will need to override the color key that you want to change on your colors.xml file from values and values-night folders. The next section details a list of the current available keys.

Key	PaymentsCustomize Support
alviere_sdk_payments_color_primary	No
alviere_sdk_payments_color_primary_variant	No
alviere_sdk_payments_color_on_primary	No
alviere_sdk_payments_color_secondary	No
alviere_sdk_payments_color_secondary_variant	No
alviere_sdk_payments_color_on_secondary	No
alviere_sdk_payments_color_status_bar	No
alviere_sdk_payments_color_navigation_bar	No
alviere_sdk_payments_color_background	No

Key	PaymentsCustomize Support
alviere_sdk_payments_card_token_form_background	Yes
alviere_sdk_payments_card_token_edit_text_color	Yes (alviereTextInputEditText)
alviere_sdk_payments_card_token_edit_hint_color	No
alviere_sdk_payments_card_token_edit_hint_focused_color	No
alviere_sdk_payments_card_token_edit_error_text_color	No
alviere_sdk_payments_card_token_submit_button_background	Yes (submitButton)
alviere_sdk_payments_card_token_submit_button_background_pressed	No
alviere_sdk_payments_card_token_submit_button_text	Yes (submitButton)

Key	PaymentsCustomize Support
alviere_sdk_payments_capture_surround_overlay_color	No
alviere_sdk_payments_capture_success_text_color	No
alviere_sdk_payments_manual_capture_title_color	Yes (manualCaptureOptionsTv)
alviere_sdk_payments_manual_capture_option_color	Yes (manualCaptureOptionsTv)

Key	PaymentsCustomize Support
alviere_sdk_payments_loading_background	Yes
alviere_sdk_payments_loading_bar	Yes
alviere_sdk_payments_loading_title	Yes
alviere_sdk_payments_loading_message	Yes

Key	PaymentsCustomize Support
alviere_sdk_payments_try_again_background	Yes
alviere_sdk_payments_try_again_error_message_text_color	Yes
alviere_sdk_payments_try_again_button_background	Yes
alviere_sdk_payments_try_again_button_background_pressed	Yes
alviere_sdk_payments_try_again_button_text	Yes

Key	PaymentsCustomize Support
alviere_sdk_payments_toolbar_background	Yes
alviere_sdk_payments_toolbar_title_text_color	No
alviere_sdk_payments_toolbar_buttons_color	No

Text and Localization¶

The Payments SDK for Android allows you to customize the UI text. To do so, you will need to override the string key that you want to change on your strings.xml file. The next section details a list of the current available keys. Currently, the SDK only supports english.

Key	English Value	PaymentsCustomize Support
alviere_sdk_payments_card_token_title	Add card	Yes
alviere_sdk_payments_card_token_pan_hint	Card Number	Yes
alviere_sdk_payments_card_token_expire_date_hint	MM/YY	Yes
alviere_sdk_payments_card_token_cvv_hint	CVV	Yes
alviere_sdk_payments_card_token_cardholder_name_hint	Cardholder’s Name	Yes
alviere_sdk_payments_card_token_postal_code_hint	Zip Code	Yes
alviere_sdk_payments_card_token_submit_button_text	Add	Yes
alviere_sdk_payments_card_token_error_required_field	Required	Yes
alviere_sdk_payments_card_token_error_invalid	Invalid	Yes
alviere_sdk_payments_card_token_error_invalid_or_unsupported_card	Invalid or unsupported card	Yes

Key	English Value	PaymentsCustomize Support
alviere_sdk_payments_documents_title_check_deposit_front	Check Front	Yes
alviere_sdk_payments_documents_title_check_deposit_back	Check Back	Yes
alviere_sdk_payments_documents_title_preview	Photo preview	Yes
alviere_sdk_payments_documents_step	Step %1$d of %2$d	Yes
alviere_sdk_payments_documents_is_photo_ok	Accept photo?	Yes
alviere_sdk_payments_documents_accept_photo	Accept	Yes
alviere_sdk_payments_documents_retake	Cancel	Yes
alviere_sdk_payments_documents_success	Success	Yes

Key	English Value	PaymentsCustomize Support
alviere_sdk_payments_capture_hint_too_dark	Too dim	No
alviere_sdk_payments_capture_hint_too_bright	Too bright	No
alviere_sdk_payments_capture_hint_hold_still	Hold Still	No
alviere_sdk_payments_capture_hint_too_far	Too far	No
alviere_sdk_payments_capture_hint_too_close	Too close	No
alviere_sdk_payments_capture_hint_reduce_glare	Reduce glare	No
alviere_sdk_payments_capture_hint_use_plain_background	Busy background	No
alviere_sdk_payments_capture_hint_use_dark_background	Low contrast	No
alviere_sdk_payments_capture_hint_wrong_check_front	Not check front	No
alviere_sdk_payments_capture_hint_wrong_check_back	Not check back	No
alviere_sdk_payments_capture_hint_not_found	Nothing detected	No
alviere_sdk_payments_capture_hint_mrz_not_found	Nothing detected	No
alviere_sdk_payments_capture_hint_press_manual_button	Press button when ready	No
alviere_sdk_payments_capture_hint_straighten	Angle too large	No

Key	English Value	PaymentsCustomize Support
alviere_sdk_payments_loading_title		Yes
alviere_sdk_payments_loading_message		Yes

Key	English Value	PaymentsCustomize Support
alviere_sdk_payments_try_again_error_message	An error has occurred	Yes
alviere_sdk_payments_try_again_error_button_text	Try again	Yes

Dimensions¶

The Payments SDK for Android allows you to customize the UI dimensions. To do so, you will need to override the dimension key that you want to change on your dimens.xml file. The next section details a list of the current available keys.

Key	PaymentsCustomize Support
alviere_sdk_payments_card_token_button_height	Yes
alviere_sdk_payments_card_token_button_margin_start	Yes
alviere_sdk_payments_card_token_button_margin_end	Yes
alviere_sdk_payments_card_token_button_margin_bottom	Yes
alviere_sdk_payments_card_token_button_margin_top	Yes
alviere_sdk_payments_card_token_button_corner_radius	No
alviere_sdk_payments_card_token_button_text_size	Yes
alviere_sdk_payments_card_token_input_text_size	Yes

Key	PaymentsCustomize Support
alviere_sdk_payments_documents_title_max_size	Yes
alviere_sdk_payments_capture_overlay_bar_padding	No
alviere_sdk_payments_capture_subtitle_text_size	No
alviere_sdk_payments_capture_text_padding	No
alviere_sdk_payments_manual_capture_title_size	Yes (manualCaptureTitleTv)
alviere_sdk_payments_manual_capture_option_size	Yes (manualCaptureOptionsTv)

Key	PaymentsCustomize Support
alviere_sdk_payments_loading_title_text_size	Yes
alviere_sdk_payments_loading_message_text_size	Yes

Key	PaymentsCustomize Support
alviere_sdk_payments_try_again_button_margin_start	Yes
alviere_sdk_payments_try_again_button_margin_end	Yes
alviere_sdk_payments_try_again_button_margin_bottom	Yes
alviere_sdk_payments_try_again_button_margin_top	Yes
alviere_sdk_payments_try_again_button_corner_radius	No
alviere_sdk_payments_try_again_button_text_size	Yes
alviere_sdk_payments_try_again_message_text_size	Yes

Payments SDK for Android¶

Features¶

Requirements¶

Installation¶

Maven Central¶

Manual¶

Java Version Support¶

Usage¶

Payment Methods¶

Declare the callback¶

onSuccess¶

onEvent¶

[UI] Create Card¶

Activity¶

Navigation Controller¶

Create Card¶

List Cards¶

Get Card¶

Delete Card¶

Create Bank Account¶

List Bank Accounts¶

Get Bank Account¶

Delete Bank Account¶

Create Plaid Bank Account¶

Activate Plaid Bank Account¶

Wallets¶

Declare the callback¶

onSuccess¶

onEvent¶

List Wallets¶

Get Wallet¶

List Wallet Transactions¶

Load Funds¶

Withdraw Funds¶

Send Funds¶

Transfer Funds¶

Transactions¶

Declare the callback¶

onSuccess¶

onEvent¶

List Child Transactions¶

Get Transaction Details¶

Get Receipt¶

Cancel Transaction¶

Check Deposits¶

Declare the callback¶

onSuccess¶

onEvent¶

[UI] Deposit Check¶

Activity¶

Navigation Controller¶

Deposit Check¶

[UI] Capture Check¶

Activity¶

Navigation Controller¶

List Checks¶

Get Check¶

Alternative Usage¶

Customization¶

View Resources¶

Override resources¶

Themes¶

Fonts¶

Colors¶

Text and Localization¶

Dimensions¶