payments

Payments SDK for Android

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

Features

  • Cards Tokenization

  • Payment Checkout

Requirements

  • Android Studio 4.0 or above

  • Android 5.0 (API level 21) or above

  • Java 8+

Integration

Manual

1. Get the latest versions of payments.aar and alcore.aar, and open up the project structure by right-clicking on your project and choosing Open Module Settings or choosing File Project Structure…. Click the + button in the top left to add a new module.

image

2. Choose Import .JAR/.AAR Package and click the Next button.

image

3. Find your payments.aar file using the folder button beside the File name field. Android Studio will automatically create a subproject name. Just click Finish and repeat the process for the alcore.aar file.

image

4. Gradle will sync, which may take a few minutes. You should have the following implementation statements on your module's build.gradle file. Please note that sometimes Android Studio generates these statements on the project's build.gradle file. In that case, move them to the module's one.

...
dependencies {
implementation fileTree(dir: "libs", include: ["*.jar"])
...
implementation project(path: ':alcore')
implementation project(path: ':payments')
}

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

...
android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
kotlinOptions {
jvmTarget = "1.8"
}
}

6. Now that you have added the .aar modules, you need to add its dependencies as shown below. Once complete, sync gradle again.


apply plugin: 'com.android.application'
apply plugin: 'kotlin-kapt'
...
dependencies {
implementation fileTree(dir: "libs", include: ["*.jar"])
...
implementation project(path: ':alcore')
implementation project(path: ':payments')
...
implementation "androidx.constraintlayout:constraintlayout:2.0.1"
implementation "androidx.fragment:fragment-ktx:1.2.5"
implementation "com.google.android.material:material:1.2.1"
implementation "com.squareup.retrofit2:retrofit:2.9.0"
implementation "com.squareup.retrofit2:adapter-rxjava3:2.9.0"
implementation "com.squareup.retrofit2:converter-moshi:2.9.0"
implementation "com.squareup.moshi:moshi-kotlin:1.11.0"
kapt "com.squareup.moshi:moshi-kotlin-codegen:1.11.0"
implementation "com.squareup.okhttp3:okhttp:4.9.0"
implementation "io.reactivex.rxjava3:rxkotlin:3.0.1"
implementation "io.reactivex.rxjava3:rxjava:3.0.6"
}

Implementation

Payments SDK Add Card for Tokenization

Declare the CardSdkAddCardCallback callback

The CardSdkAddCardCallback callback is the main communication back channel to your application for the Payments SDK for Android.


val callbackAdd = object : CardSdkAddCardCallback {
override fun onSuccess(token: String) {
// Handle success, e.g. by storing card token with your service
Log.d("ALVIERE:", "Successfully tokenized card with token $token")
}

override fun onEvent(event: String, metadata: Map<String, String>?) {
Log.d("ALVIERE:", "Received event:$event metadata:${metadata.toString()}")
}
}

onSuccess

This callback method is called when the user successfully linked their card with Alviere. Use this to upload and store the card token with your service for use with the Alviere API.


onEvent

This delegate 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 enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error you may want to display error related information to the user and have them try linking their card again.

Presentation

Starting the Payments SDK for Android is as simple as creating a new auth_token and using it to create a CardsActivity instance. You can also use the card tokenization with your own UI.

Presenting Activity

To present CardsActivity, we need to create an Intent using getCardsActivityIntent, pass a new auth_token, set the Environment, and pass the current activity along with the CardSdkAddCardCallback callback instance. Optionally, you can also pass a customization object with the style you want to apply. You can then present the activity with startActivity.


val intent = CardsActivity.getCardsActivityIntent(
environment = Environment.SND,
sessionToken = authToken,
parentActivity = this,
callback = callbackAdd
)
startActivity(intent)

Usage without UI

If you want to call the tokenization service directly, you first need to set up the environment on HeadlessCardSdk. Keep in mind that the process of setting up the environment is asynchronous so you should set it as soon as you can.


HeadlessCardSdk.create(
environment = Environment.SND
)

When you want to call the tokenization, use createCard to create a new auth_token, set the Environment, pass the CreateCardPojo model with the card data, and pass the CardSdkAddCardCallback callback instance. You also have the option to pass a customization object with a custom validation for the zip/postal code field.


val model = CreateCardPojo( ... )
HeadlessCardSdk.createCard(
token = authToken,
data = model,
callbackAdd = callbackAdd
)

Payments SDK Payment Checkout

Declare the CardSdkCardDebitCallback callback

The CardSdkCardDebitCallback callback is the main communication back channel to your application for the Payments SDK for Android.


val callbackCardDebit = object : CardSdkCardDebitCallback {
override fun onSuccess() {
Log.d("ALVIERE:", "Payment checkout successful")
}

override fun onEvent(event: String, metadata: Map<String, String>?) {
Log.d("ALVIERE:", "Received event:$event metadata:${metadata.toString()}")
}
}

onSuccess

This delegate method is called when the payment checkout is successful.


onEvent

This delegate method is called when certain events in the Payments SDK flow have occurred. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display error related information to the user.

Presentation

Starting the Payments SDK for iOS is as simple as creating a new auth_token, using it to initialize PaymentsSDK, get a CardDebitFragment instance, and provide the card debit data. You can also use the payment checkout with your own UI.

Presenting Fragment

To present CardDebitFragment, you first need to put a placeholder view on your xml so we can replace it with the correct fragment. Once complete, create a new CardDebitFragment instance by calling newInstance and pass the auth_token, the Environment, the card debit data, and the CardSdkCardDebitCallback callback instance. Finally, call replaceFragment to replace the placeholder with the one you just created.


val fragment = CardDebitFragment.newInstance(
environment = Environment.SND,
sessionToken = authToken,
cardToken = cardToken,
transactionAmount = 1,
transactionCurrency = USD,
authType = AUTHCAP,
orderId = orderId,
billingDetails = BillingDetails( ... ),
callback = callbackCardDebit
)
replaceFragment(fragment, placeholderViewId, fragmentIdTag)

Usage without UI

If you want to call the payment checkout service directly, you first need to set up the environment on HeadlessCardSdk. Keep in mind that the process of setting up the environment is asynchronous, so you should set it as soon as possible.


HeadlessCardSdk.create(
environment = Environment.SND
)

When you want to call the payment checkout service, use createCardDebit to create a new auth_token, set the Environment, pass the CardDebitPojo model with the card data, and pass the CardSdkCardDebitCallback callback instance.


val model = CardDebitPojo( ... )
HeadlessCardSdk.createCardDebit(
token = authToken,
data = model,
callbackAdd = callbackCardDebit
)

Customization

The Payments SDK for Android provides a set of UI styling and field validation customizations to allow you to adjust the the provided UI to fit your needs. To customize the UI, you can pass the customizations, setup a custom validation, or override the colors.xml and strings.xml keys. You can also select the card brands that you wish to support on validations; the default includes all brands. You can check the supported brands on the PaymentCard model.

Styling

Below are the styling options that can be used to override style.

.------------------------.-------------------.-----------------------------------.
| Class | Attribute | Description |
:------------------------+-------------------+-----------------------------------:
| CardActivityCustomize | showBackButton | controls back button visibility |
| :-------------------+-----------------------------------:
| | showCloseButton | controls close button visibility |
'------------------------'-------------------'-----------------------------------'

Fields

Below are the field customizations that can be used standalone or in style models like AddCardValidation.

.--------------------.------------------.---------------------------------.
| Class | Attribute | Description |
:--------------------+------------------+---------------------------------:
| AddCardValidation | regex | validation regex |
| :------------------+---------------------------------:
| | minChars | minimum allowed characters |
| :------------------+---------------------------------:
| | maxChar | maximum allowed characters |
| :------------------+---------------------------------:
| | keyboardType | InputType for field |
| :------------------+---------------------------------:
| | validCardTypes | list of supported card brands |
'--------------------'------------------'---------------------------------'

Colors

The Payments SDK for Android allows you to customize the UI colors. To do so, you will need to redefine the color key that you want to change on your colors.xml file. Below is a list of the current color keys.

.-----------------------------------------------------------------.-------------.
| Key | ARGB Color |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_add_card_form_background | #FFFFFFFF |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_add_card_edit_text_error | #FFFF0000 |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_add_card_submit_button_background | #FFF6F9F9 |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_add_card_submit_button_background_pressed | #FFAAAAAA |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_add_card_submit_button_text | #FF212121 |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_card_debit_checkout_button_background | #FFF6F9F9 |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_card_debit_checkout_background_pressed | #FFAAAAAA |
:-----------------------------------------------------------------+-------------:
| alviere_sdk_payments_card_debit_checkout_button_text | #FF212121 |
'-----------------------------------------------------------------'-------------'

Text and Localization

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

.------------------------------------------------------------------.------------------------------.
| Key | English Value |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_title | Add card |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_pan_hint | Card Number |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_expire_date_hint | MM/YY |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_cvv_hint | CVV |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_cardholder_name_hint | Cardholder’s Name |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_zipcode_hint | Zip Code |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_submit_button_text | Add |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_error_required_field | Required |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_error_invalid | Invalid |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_error_invalid_or_unsupported_card | Invalid or unsupported card |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_error_message | An error has occurred |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_add_card_error_btn_text | Try again |
:------------------------------------------------------------------+------------------------------:
| alviere_sdk_payments_card_debit_checkout_btn_text | Checkout |
'------------------------------------------------------------------'------------------------------'

Packages

com.alviere.android.payments.callback
Link copied to clipboard
com.alviere.android.payments.events
Link copied to clipboard
com.alviere.android.payments.repository
Link copied to clipboard
com.alviere.android.payments.utils
Link copied to clipboard