Skip to main content

Android SDK

Integration options

Activity mode

The SmartPay Activity Mode provides you with a complete checkout screen. The user can navigate back to the previous activity by just pressing the back button.

activity mode

Fragment mode

The SmartPay Fragment Mode allows you to integrate the SmartPay fragments directly into your app experience and gives you maximum control over the various checkout elements.

fragment mode

Add the SmartPay SDK to your app

To integrate the SmartPay libraries into your project, there is a necessity to perform a few basic tasks to prepare the project. This tutorial assumes your IDE for application development is Android Studio.

First, copy SDK files (listed below) to the module “libs” folder (usually the app/libs/):

  • smartpay.arr
  • kontocloud-sdk.aar
  • kontocloud-apiclient.aar
  • kontocloud-uicomponents.aar

Then, in your module Gradle file (usually the app/build.gradle), add the dependencies for the SmartPay libraries:

apply plugin: 'kotlin-android'
apply plugin: 'kotlin-android-extensions'

android {

compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}

kotlinOptions {
jvmTarget = JavaVersion.VERSION_1_8.toString()
}

}

repositories {
flatDir {
dirs 'libs'
}
}

dependencies {
// …
implementation 'androidx.core:core-ktx:1.3.0'
implementation 'com.google.android.material:material:1.1.0'
implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
implementation "androidx.fragment:fragment:1.2.5"
implementation "androidx.fragment:fragment-ktx:1.2.5"

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.google.code.gson:gson:2.8.6'

implementation 'net.danlew:android.joda:2.10.6'
implementation 'com.samskivert:jmustache:1.15'

implementation(name: 'smartpay', ext: 'aar')
implementation(name: 'kontocloud-apiclient', ext: 'aar')
implementation(name: 'kontocloud-uicomponents', ext: 'aar')
implementation(name: 'kontocloud-sdk', ext: 'aar')
}

Add the INTERNET permission to the AndroidManifest file (usually the app\src\main\AndroidManifest.xml):

// ...

<uses-permission android:name="android.permission.INTERNET" />

//...

To initialize the SmartPay:

class App : Application() {
override fun onCreate() {
super.onCreate()
SmartPay.init(this)

Make sure to set the correct environment / smartPayMode in the smartPayOptions:

EnvironmentSmartPayMode
SandboxCONS
LivePROD
class App : Application() {


override fun onCreate() {
super.onCreate()

val smartPayOptions: SmartPayOptions = SmartPayOptions()
smartPayOptions.smartPayMode = SmartPayMode.Live
SmartPay.init(this, smartPayOptions)

Complete payment in activity mode

Initialize SmartPay

To initialize SmartPay SDK forward transaction-ID to the startActivityForResult method.

SmartPayCheckoutActivity.startActivityForResult(Context, TRANSACTION_ID)

Process Payment Results

To receive the transaction results, please override the method in Activity.onActivityResult. In the response requestCode == SmartPayConst.SMART_PAY_PAYMENT_REQUEST_CODE you can recieve the following results codes:

Result CodeDescription
SmartPayConst.SMART_PAY_RESULT_CODE_CANCELThe end-customer has canceled the transaction (i.e. closed the payment form window).
SmartPayConst.SMART_PAY_RESULT_CODE_ERRORTransaction has failed.
SmartPayConst.SMART_PAY_RESULT_CODE_SUCCESSSuccessful transaction execution

To get the transaction-ID related to the processed payment extract the key SmartPayConst.SMART_PAY_TRANSACTION_ID.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)

if (requestCode == SmartPayConst.SMART_PAY_PAYMENT_REQUEST_CODE) {
val transactionId = data?.getStringExtra(SmartPayConst.SMART_PAY_TRANSACTION_ID) ?: ""
when (resultCode) {
SmartPayConst.SMART_PAY_RESULT_CODE_SUCCESS -> {
...
}
SmartPayConst.SMART_PAY_RESULT_CODE_CANCEL -> {
...
}
SmartPayConst.SMART_PAY_RESULT_CODE_ERROR -> {
...
}
}
}
}

The SmartPay Activity Mode can inherit the main application's theme by adding the following attribute (for more details see the Styling section):

<style name="AppTheme" parent="Theme.MaterialComponents.Light.DarkActionBar">
<item name="smartPayStyle">@style/MySmartPayStyle</item>

</style>
SmartPayCheckoutActivity.startActivityForResult(Context, TRANSACTION_ID, R.style.AppTheme)

Complete payment in fragment mode

Initialize SmartPay

To initialize SmartPay widget forward transaction-ID to the getInstance method.

SmartPayCheckoutFragment.getInstance(TRANSACTION_ID)

Callbacks

To receive response callback from the fragment, your activity must be inherited from the Interface OnSmartPayEventListener.

CallbackDescription
onSmartPayApiError()There was an error during payment process. In case the payment must be continued, open the screen from the beginning.
onSmartPayPaymentOptionStored()The payment option has been successfully stored. Return to the SmartPayCheckoutFragment screen and call SmartPayCheckoutFragment.reloadPaymentOptions() method or add a fragment again.
onSmartPayPaymentFinishSuccess()Payment has been successfully processed. The screen can be closed.
onSmartPayPrepareFragment()Preparation of the screen, please disable buttons which lead to payment.
onSmartPayReadyFragment()The next step of the payment process can be performed.
interface OnSmartPayEventListener {
fun onSmartPayApiError()
fun onSmartPayPaymentOptionStored()
fun onSmartPayPaymentFinishSuccess()

fun onSmartPayPrepareFragment()
fun onSmartPayReadyFragment()
}

To override the 'Continue' button in SmartPayCheckoutFragment use the following method:

SmartPayCheckoutFragment.setOnClickConfirmButton(onClick: View.OnClickListener?)
info

Please note, in case you override the 'Continue' button and add additional steps/screens to the payment flow, you need to return to the SmartPayPaymentFragment.

To add SmartPayPaymentFragment screen:

SmartPayPaymentFragment.getInstance()

Buttons

Confirmation Button

The Fragment Mode allows to change text of standard buttons. Please note, that only @StringRes is supported. Moreover you can hide standard buttons in order to use your main application buttons (e.g. to add additional steps / screens).

SmartPayCheckoutFragment.setTextConfirmButton(@StringRes textRes: Int)
SmartPayPaymentFragment. setTextConfirmButton(@StringRes textRes: Int)

To hide the 'Confirm' button in SmartPayCheckoutFragment/SmartPayPaymentFragment:

visibility -> View.VISIBLE, View.INVISIBLE, View.GONE


SmartPayCheckoutFragment.setVisibilityConfirmButton(visibility: Int)
SmartPayPaymentFragment. setVisibilityConfirmButton(visibility: Int)

SEPA Mandate Buttons

While the end-customer pays with SEPA payment option, the mandate with terms and conditions is shown. While the end-customer clicks 'Agree' or 'Cancel' buttons, you will receive the callback with the result. If the end-customer clicks 'Cancel' it is necessary to return to the payment selection screen.

Your activities must inherit the properties of the OnSmartPayMandateListener interface to receive callbacks.

interface OnSmartPayMandateListener  {
fun onSmartPayMandateCancel()
fun onSmartPayMandateAccept()
}
interface OnSmartPayClickPaymentMethod  {
fun onSmartPayClickStoredPaymentMethod(transactionId : String, storedPaymentOption: SmartPayStoredPaymentOption)
fun onSmartPayClickGuestPaymentMethod(transactionId : String, guestPaymentOption: SmartPayGuestPaymentOption)
}

Methods

Method/ClassDescription
onSmartPayClickStoredPaymentMethodCalled when the end-customer selects already stored payment option or default payment option
onSmartPayClickGuestPaymentMethodCalled when the end-customer selects payment option that hasn't been already stored or after updating of the screen when there is no stored payment options
SmartPayStoredPaymentOptionClass contains information about stored payment option
GuestPaymentOptionClass contains information about the new initiated payment

OnSmartPayClickPaymentMethod – Activity must inherit properties of OnSmartPayClickPaymentMethod, to receive callbacks.

Payment Option Selection

SmartPayPaymentView is implemented to show already selected payment option by the end-customer to pay the order. This element can be designed separately from the main theme. To have everything working correctly this element need to be shown only after the end-customer has selected a payment option to pay on the SmartPayCheckoutFragment screen. Both, adding from the code or the markup is supported.

interface OnSmartPayClickPaymentMethod  {
fun onSmartPayClickStoredPaymentMethod(transactionId : String, storedPaymentOption: SmartPayStoredPaymentOption)
fun onSmartPayClickGuestPaymentMethod(transactionId : String, guestPaymentOption: SmartPayGuestPaymentOption)
}

Payment Option View

There is a SmartPayPaymentView implemented to show already selected payment options by the end-customer to pay for the order. This element can be designed separately from the main theme. To have everything working correctly this element must be shown only after the end-customer has selected a payment option to pay on the SmartPayCheckoutFragment screen. Both adding from the code or from the markup is supported.

payment option view

--Adding from the code--

val paymentView = SmartPayPaymentView(Context)
ViewGroup.addView(paymentView)

--Standard style from the activity theme--

<com.fspay.smartpay.sdk.ui.custom.SmartPayPaymentView/>

--Changed theme--

<com.fspay.smartpay.sdk.ui.custom.SmartPayPaymentView
style="@style/SmartPayStyleView"
/>

<style name="MyStylePaymentOption">
<item name="smartPayStyle">@style/MySmartPayStyle</item>
</style>

<style name="MySmartPayStyle" parent="SmartPayDefaultStyle">
<item name="smartPaySi... >
</style>

To update SmartPayPaymentView:

val smartPayPaymentView = SmartPayPaymentView(this)
smartPayPaymentView.updateView()

Apply own styling (both integrations)

Inherit Main Application Style

By default, the checkout theme will be inherited from the basic colors defined in main application.

Basic Properties:

  • android:colorBackground
  • colorControlActivated
  • colorOnBackground
  • colorOnPrimary
  • colorOnSurface
  • colorPrimary
  • colorPrimaryDark
  • colorSecondary

To inherit the main applications theme for the SmartPayPaymentView it is necessary to set the following attribute:

<style name="AppTheme" parent="Theme.MaterialComponents.Light.DarkActionBar">
<item name="smartPayStyle">@style/MySmartPayStyle</item>
</style>

<style name="MyStylePaymentOption">
<item name="smartPayStyle">@style/MySmartPayStyle</item>
</style>

It is recommended to inherit from SmartPayDefaultStyle theme to avoid mistakes with missing reference attributes.

<style name="MySmartPayStyle" parent="SmartPayDefaultStyle">

Style Attributes

Below you can find used style attributes.

<declare-styleable name="SmartPayAttrStyle">

    <attr name="smartPayColorBackgroundFragment" format="color" /> <!-- background color fragment/activity -->

    <!-- Button Confirm -->

    <attr name="smartPayColorButtonConfirm" format="color" />

    <attr name="smartPayColorButtonConfirmSelected" format="color" />

    <attr name="smartPayColorButtonConfirmRipple" format="color" /> <!-- button click -->

    <attr name="smartPayColorButtonConfirmCorners" format="dimension" />

    <attr name="smartPayColorButtonConfirmText" format="color" />

    <attr name="smartPayColorButtonConfirmSelectedText" format="color" />

    <attr name="smartPayColorButtonConfirmDeactivatedText" format="color" />

    <attr name="smartPayColorButtonConfirmDeactivated" format="color" />

    <!-- text -->

    <attr name="smartPayColorPrimaryTextColor" format="color" />

    <attr name="smartPayColorSecondaryTextColor" format="color" />

    <attr name="smartPayColorSelectedText" format="color" />

    <attr name="smartPayColorShowAll" format="color" />

    <attr name="smartPaySizePrimaryText" format="dimension" /> <!-- 14sp -->

    <attr name="smartPaySizeSecondaryText" format="dimension" /> <!-- 13sp -->

    <attr name="smartPayColorImageShowBackground" format="color" /> <!-- background image arrow (show all) -->

    <!-- card -->

    <attr name="smartPayColorSelectedCardImageTint" format="color" />

    <attr name="smartPayColorSelectedCardBackground" format="color" />

    <attr name="smartPayColorCardBackground" format="color" />

    <attr name="smartPayColorCardBorder" format="color" />

    <attr name="smartPayColorSelectedCardBorder" format="color" />

    <attr name="smartPayColorCardRipple" format="color" /> <!-- card click -->

    <attr name="smartPaySizeCardBorder" format="dimension" />

    <attr name="smartPaySizeCardRadius" format="dimension" /> <!-- default 0dp -->

    <attr name="smartPayRetryButtonBorder" format="color" />

    <attr name="smartPaySelectedRetryButtonBorder" format="color" />

    <attr name="smartPayRetryButtonBackground" format="color" />

    <attr name="smartPaySelectedRetryButtonBackground" format="color" />

    <attr name="smartPayRetryButtonSizeBorder" format="dimension" />

    <attr name="smartPayRetryButtonSizeRadius" format="dimension" />

</declare-styleable>

Attribute nameDescription
smartPayColorBackgroundFragmentBackground color
Button
smartPayColorButtonConfirm'Confirm' button color
smartPayColorButtonConfirmSelectedPressed 'Confirm' button color
smartPayColorButtonConfirmRippleColor of the ripple effect of the 'Confirm' button
smartPayColorButtonConfirmCornersCurving of the 'Confirm' button borders
smartPayColorButtonConfirmText'Confirm' button text color
smartPayColorButtonConfirmSelectedText'Confirm' button text color while the button is pressed
smartPayColorButtonConfirmDeactivatedTextButton text color with condition: Enabled = false
smartPayColorButtonConfirmDeactivatedButton color with condition: Enabled = false
Payment Option
smartPayColorPrimaryTextColorColor of the main text of the payment option
smartPayColorSecondaryTextColorColor of the additional text of the payment option
smartPayColorShowAllText color for labels: 'Show all', 'Show less', 'OR'
SmartPaySizePrimaryTextMain font size
smartPaySizeSecondaryTextAdditional font size
smartPayColorImageShowBackgroundArrow background color; 'Show all/less' background color
smartPayColorSelectedCardImageTint'Check mark' color
smartPayColorCardBackgroundPayment option background color
smartPayColorSelectedCardBackgroundSelected payment option background color
smartPayColorCardBorderPayment option border color
smartPayColorSelectedCardBorderSelected payment option color
smartPayColorCardRippleRipple effect color
smartPaySizeCardBorderPayment option border size
smartPaySizeCardRadiusPayment options border curving size