payments

Payments SDK for Android

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

Features

  • Card Token

  • Card Debit

Requirements

  • Android Studio 4.0 or above

  • Android 5.0 (API level 21) or above

  • Java 8+

Integration

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')
...
}

Usage

Before you can use the Payments Sdk, and if you want to call the user management services you need to first setup the environment on PaymentsSdk. Keep in mind that the process of setting up the environment is asynchronous, so you should set it as soon as possible.

PaymentsSdk.create()

Add Card for Tokenization

This section outlines the endpoints related to our card tokenization service.

Declare the callback

The AddPaymentsSdkCallback callback is the main communication back channel to your application. Callbacks will always run on main thread.

private val addPaymentsSdkCallback = object : AddPaymentsSdkCallback {
override fun onSuccess(token: String) { /* handle success */ }

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

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

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

PaymentsSdk.setEventListener(addPaymentsSdkCallback)
Activity

To start using this feature on an activity, create an Intent using PaymentsSdk.addCardByIntent, pass the parent_activity and the session_token. Optionally, it can be passed a customization object PaymentsActivityCustomize with the style to be applied and a validation object AddCardValidation with the rules to be further applied.


val intent = PaymentsSdk.addCardByIntent(
parentActivity = parent_activity,
sessionToken = session_token,
paymentsActivityCustomize = PaymentsActivityCustomize(),
customAddCardValidation = AddCardValidation(
minChars = 0,
maxChar = 5,
keyboardType = InputType.TYPE_CLASS_NUMBER,
validCardTypes = listOf(PaymentCard.VISA, PaymentCard.MASTERCARD)
)
)
startActivity(intent)
Navigation Controller

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/add_card"
android:name="com.example.app.AddCardFragment"
tools:layout="@layout/add_card_fragment">
<action
android:id="@+id/action_add_card_to_add_card_by_activity"
app:destination="@id/add_card_by_activity" />
</fragment>

<activity
android:id="@+id/add_card_by_activity"
android:name="com.alviere.android.payments.activity.PaymentsActivity">
<argument
android:name="extra_feature_frag"
app:argType="com.alviere.android.payments.PaymentsSdk$Features" />
<argument
android:name="extra_session_token"
app:argType="string" />
<argument
android:name="extra_card_token_custom_card_activity_tag"
app:argType="com.alviere.android.payments.activity.PaymentsActivityCustomize" />
<argument
android:name="extra_card_token_custom_validation_tag"
app:argType="com.alviere.android.payments.cardtoken.ui.customization.AddCardValidation" />
</activity>

Safe Args it will generate a AddCardFragmentDirections class with a single method, actionAddCardToAddCardByActivity() 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(
AddCardFragmentDirections.actionAddCardToCheckoutByActivity(
PaymentsSdk.Features.ADD_CARD,
session_token,
PaymentsActivityCustomize(),
AddCardValidation(
minChars = 0,
maxChar = 5,
keyboardType = InputType.TYPE_CLASS_NUMBER,
validCardTypes = listOf(PaymentCard.VISA, PaymentCard.MASTERCARD)
)
)
)

Without UI

To call the Card Tokenization service directly, use Payments Sdk service method PaymentsSdk.createCardToken. Pass the session_token, the CardToken model with the Card, and the CardSdkAddCardCallback callback. Optionally, it can be passed the validation object AddCardValidation.


val card = Card( ... )
PaymentsSdk.createCardToken(
token = session_token,
data = CardToken(
externalId = external_uuid,
card = card
),
clientCallback = addPaymentsSdkCallback
)

Card Debit

This section outlines a card debit payment transaction.

Declare the callback

The DebitPaymentsSdkCallback callback is the main communication back channel to your application. Callbacks will always run on main thread.

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

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

onSuccess

This method is called when the payment checkout is successful.


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

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

PaymentsSdk.setEventListener(debitPaymentsSdkCallback)
Activity

To start using this feature on an activity, create an Intent using PaymentsSdk.cardDebitByIntent, pass the parent_activity, the session_token and the the CardDebitPojo object.

val cardDebit = CardDebitPojo( ... )
val intent = PaymentsSdk.cardDebitByIntent(
parentActivity = parent_activity,
sessionToken = session_token,
data = cardDebit
)

startActivity(intent)
Navigation Controller

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/checkout"
android:name="com.example.app.CheckoutFragment"
tools:layout="@layout/checkout_fragment">
<action
android:id="@+id/action_checkout_to_checkout_by_activity"
app:destination="@id/checkout_by_activity" />
</fragment>

<activity
android:id="@+id/checkout_by_activity"
android:name="com.alviere.android.payments.activity.PaymentsActivity" >
<argument
android:name="extra_feature_frag"
app:argType="com.alviere.android.payments.PaymentsSdk$Features" />
<argument
android:name="extra_session_token"
app:argType="string" />
<argument
android:name="extra_card_debit_card_token"
app:argType="string" />
<argument
android:name="extra_card_debit_transaction_amount"
app:argType="integer" />
<argument
android:name="extra_card_debit_transaction_currency"
app:argType="com.alviere.android.payments.model.Currency" />
<argument
android:name="extra_card_debit_authz_type"
app:argType="com.alviere.android.payments.model.AuthorizationType" />
<argument
android:name="extra_card_debit_external_id"
app:argType="string" />
<argument
android:name="extra_card_debit_billing_details"
app:argType="com.alviere.android.payments.model.BillingDetails" />
</activity>

Safe Args it will generate a CheckoutFragmentDirections class with a single method, actionCheckoutToCheckoutByActivity() that returns a NavDirections object. This returned NavDirections object can then be passed directly to navigate(), as shown in the following example:

it.findNavController().navigate(
CheckoutFragmentDirections.actionCheckoutToCheckoutByActivity(
PaymentsSdk.Features.CARD_DEBIT,
session_token,
card_debit
)
)

Without UI

To call the Card Debit service directly, use Payments Sdk service method PaymentsSdk.createCardDebit. Pass the session_token, the CardDebitPojo and the CardSdkAddCardCallback callback. Optionally, it can be passed the validation object AddCardValidation.


val cardDebit = CardDebitPojo( ... )
PaymentsSdk.createCardDebit(
token = session_token,
data = cardDebit,
clientCallback = debitPaymentsSdkCallback
)

Customization

The Payments SDK for Android provides a set of UI styling and field validation customizations to allow you to adjust 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, strings.xml and dimens.xml values. 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 |
:---------------------------+-------------------+-----------------------------------:
| PaymentsActivityCustomize | showBackButton | controls back button visibility |
| :-------------------+-----------------------------------:
| | showCloseButton | controls close button visibility |
'---------------------------'-------------------'-----------------------------------'

To start using PaymentsCustomize set the object using PaymentsSdk.setCustomize. This will override some of the colors.xml, strings.xml and dimens.xml values.

.------------------------.--------------------.------------------------------------.
| Class | Attribute | Description |
:------------------------+--------------------+------------------------------------:
| PaymentsCustomize | cardTokenCustomize | CardTokenCustomize resource keys |
| :--------------------+------------------------------------:
| | cardDebitCustomize | CardDebitCustomize resource keys |
| '--------------------'------------------------------------'
| | loadingCustomize | LoadingCustomize resource keys |
| '--------------------'------------------------------------'
| | tryAgainCustomize | TryAgainCustomize resource keys |
'------------------------'--------------------'------------------------------------'

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 | PaymentsCustomize Support |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_token_form_background | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_token_edit_text_color | Yes |
:-----------------------------------------------------------------:----------------------------.
| 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. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_token_submit_button_background_pressed| Yes. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_token_submit_button_text | Yes |
'-----------------------------------------------------------------'----------------------------.

.-----------------------------------------------------------------.----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_background | Yes. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_debit_checkout_background_pressed | Yes. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_text | Yes |
'-----------------------------------------------------------------'----------------------------.

.-----------------------------------------------------------------.----------------------------.
| 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. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_try_again_button_background_pressed | Yes. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_try_again_button_text | Yes |
'-----------------------------------------------------------------'----------------------------.

.-----------------------------------------------------------------.----------------------------.
| alviere_sdk_payments_loading_background | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_loading_bar | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_loading_message | Yes |
'-----------------------------------------------------------------'----------------------------.

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 | 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_zipcode_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 |
'------------------------------------------------------------------'------------------------------'----------------------------.

.------------------------------------------------------------------.------------------------------.----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_text | Checkout | Yes |
'------------------------------------------------------------------'------------------------------'----------------------------.

.------------------------------------------------------------------.------------------------------.----------------------------.
| 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 redefine the localization key that you want to change on your dimens.xml file. The next section details a list of the current localization 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 | Yes. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_token_button_text_size | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_token_input_text_size | Yes |
:-----------------------------------------------------------------:----------------------------.

.-----------------------------------------------------------------.----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_height | Yes |
.-----------------------------------------------------------------.----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_margin_start | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_margin_end | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_margin_bottom | Yes |
'-----------------------------------------------------------------'----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_margin_top | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_corner_radius | Yes. Changing Drawable. |
'-----------------------------------------------------------------'----------------------------.
| alviere_sdk_payments_card_debit_checkout_button_text_size | Yes |
:-----------------------------------------------------------------:----------------------------.

.-----------------------------------------------------------------.----------------------------.
| alviere_sdk_payments_loading_text_size | Yes |
:-----------------------------------------------------------------:----------------------------.

.-----------------------------------------------------------------.----------------------------.
| 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 | Yes. Changing Drawable. |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_try_again_button_text_size | Yes |
:-----------------------------------------------------------------:----------------------------.
| alviere_sdk_payments_try_again_message_text_size | Yes |
:-----------------------------------------------------------------:----------------------------.

Packages