Cards SDK for Android¶

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

Features¶

Card Issuance
Digital Wallet
Incentives

Requirements¶

Android Studio Flamingo or above
Android 5.0 (API level 21) 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:cards:X.Y.Z'
}

Manual¶

1. Get the latest version of Cards 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:cards: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)
  }
}

Card Issuance¶

This section describes how to issue and manage cards with the Alviere platform. To start, get the CardsSdk service interface instance or use with Dependency Injection.

private val cardsService = CardsSdk.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(issuedCardDetails: IssuedCardDetailsModel) { /* handle success */ }

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

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

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

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

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

private val getCardImageSdkCallback = object : GetCardImageSdkCallback {
  override fun onSuccess(issuedCardImage: Bitmap) { /* handle success */ }

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

private val getCardSensitiveDataSdkCallback = object : GetCardSensitiveDataSdkCallback {
  override fun onSuccess(issuedCardSensitiveData: CardSensitiveDataModel) { /* handle success */ }

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

private val updateCardSdkCallback = object : UpdateCardSdkCallback {
  override fun onSuccess(issuedCardDetails: IssuedCardDetailsModel) { /* handle success */ }

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

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

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

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

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

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

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

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

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

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

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

onSuccess¶

This callback method is called when a request was successfully executed. Use this to issue and manage cards of a user's wallet with the Alviere API.

onEvent¶

This callback method is called when the user exited from the Cards SDK, when an error occurred, or when certain events in the Cards SDK flow have occurred. This allows your application to get more information about what is going on as the user goes through the Cards 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.

Create Card¶

To create a new issued card, use the Cards SDK service method cardsService.createCard. Pass the session_token, the wallet_uuid, the IssueCardRequest model and the CreateCardSdkCallback.

val model = IssueCardRequest(...)
cardsService.createCard(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    data = model,
    clientCallback = createCardSdkCallback
)

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

Create Non-Reloadable Prepaid Card¶

To create a new non-reloadable prepaid card, use the Cards SDK service method cardsService.createNonReloadablePrepaidCard. Pass the session_token, the account_uuid, the NonReloadablePrepaidCardRequest model and the CreateCardSdkCallback.

val model = NonReloadablePrepaidCardRequest(...)
cardsService.createCard(
    sessionToken = session_token,
    accountUuid = account_uuid,
    data = model,
    clientCallback = createCardSdkCallback
)

The result of this action will return the newly created IssuedCardDetailsModel on onSuccess(issuedCardDetails: IssuedCardDetailsModel) 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 from a wallet, use the Cards SDK service method cardsService.listCards. Pass the session_token, the wallet_uuid, the ListCardsSdkCallback and the limit/offset, optionally.

cardsService.listCards(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    clientCallback = listCardsSdkCallback
)

The result of this action will return the user's wallet cards List<IssuedCardDetailsModel> on onSuccess(issuedCards: List<IssuedCardDetailsModel>) 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 Cards SDK service method cardsService.getCard. Pass the session_token, the wallet_uuid, the card_uuid and the GetCardSdkCallback.

cardsService.getCard(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    cardUuid = card_uuid,
    clientCallback = getCardSdkCallback
)

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

Get Card Image¶

To get a card image, use the Cards SDK service method cardsService.getCardImage. Pass the session_token, the wallet_uuid, the card_uuid and the GetCardImageSdkCallback.

cardsService.getCardImage(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    cardUuid = card_uuid,
    clientCallback = getCardImageSdkCallback
)

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

Get Card Sensitive Data¶

To get a card sensitive data, use the Cards SDK service method cardsService.getCardSensitiveData. Pass the session_token, the wallet_uuid, the card_uuid and the GetCardSensitiveDataSdkCallback.

cardsService.getCardSensitiveData(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    cardUuid = card_uuid,
    clientCallback = getCardSensitiveDataSdkCallback
)

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

Update Card¶

To update a card, use the Cards SDK service method cardsService.updateCard. Pass the session_token, the wallet_uuid, the card_uuid, the CardUpdateRequest model and the UpdateCardSdkCallback.

val model = CardUpdateRequest(...)
cardsService.updateCard(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    cardUuid = card_uuid,
    data = model,
    clientCallback = updateCardSdkCallback
)

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

Activate Card¶

To activate a card, use the Cards SDK service method cardsService.activateCard. Pass the session_token, the wallet_uuid, the card_uuid, the ActivateCardRequest model and the ActivateCardSdkCallback.

val model = ActivateCardRequest(...)
cardsService.activateCard(
    sessionToken = session_token,
    walletUuid = wallet_uuid,
    cardUuid = card_uuid,
    data = model,
    clientCallback = activateCardSdkCallback
)