Installation

Prerequisites: minimum supported Android version is 23 (Marshmallow) and device with NFC capabilities

Firstly, you need to integrate our kevin. mobile SDK which allows you to integrate Account Linking within your app. Instructions on how to do that can be found here:

Getting Started

Installation

Maven repository and credentials should be received together with other secrets.

Add kevin. maven repository

build.gradle.kts

repositories {
    // ...
    maven {
        url = uri("https://nexus-pos.kevin.eu/repository/<repository>/")
        credentials {
            username = "<username>"
            password = "<password>"
        }
    }
}

• <repository> - Maven repository name

• <username> - provided Maven repository username

• <password> - provided Maven repository password

Add kevin. dependency

build.gradle

dependencies {
    implementation("eu.kevin.pos:kevin-pay-merchant-android:1.3.0")
}

Initialisation

KevinPay serves as the primary interface class for interacting with the mobile SDK, offering a comprehensive set of methods for linking and managing accounts. Within this class, you will find essential functions, helper classes, and additional methods to tailor the SDK instance to the specific requirements.

kevin. mobile SDK must be initialised before it can be used in the mobile application, attempting to use the SDK without initialisation will trigger a KevinNfcSdkNotInitialisedException. Ensure that the initialisation process is carried out within the application's class onCreate() method to guarantee proper functionality.

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Kevin.setLocale(Locale("en"))
        //  setup your custom theme which extends Theme.Kevin.Base
        Kevin.setTheme(R.style.Theme_Kevin_Base)
        KevinAccountsPlugin.configure(
            KevinAccountsConfiguration.builder()
                .setCallbackUrl("https://your.callback.url")
                .build()
        )
        
        KevinPay.init(this, "clientId")
        // Payments can be enabled/disabled dynamically
        KevinPay.setPaymentsEnabled(true)
        // Locale can be overriden dynamically
        KevinPay.setLocale(Locale.ENGLISH)
        // Change theme of integrated UI
        KevinPay.setTheme(R.style.Theme_Kevin_Pay_Base)
    }
}

Only KevinPay.init() has to be called from Application class. This requirement doesn't extend to other methods. For instance, in a scenario where the user selects the app language on a screen, it is safe to call KevinPay.setLocale() within that specific screen.

For POS payments to work properly you will need to request permission for posting notifications on devices running api 33 or higher

Notifications are needed due to limitations of some device manufacturers. Having notification permission allows us to inform user about relevant information about the payment. If user doesn't allow posting notifications or disables our notification channel, payments might not work on certain devices. You can read here about Android notification permissions.

Handle user logout

After user logs out from the mobile application, KevinPay.clearProvisionedData() should be called. This action ensures that the previous user's data is effectively purged, preventing its availability to the new user. Importantly, upon clearing provisioned data, KevinPay will retain its initialised status, and configurations that are not user-specific will remain unaffected.

Set application as a default payment application

The default payment application on an Android device settings is the preferred app that device uses to make payments. When you set an app as the default payment app, the device will automatically use it when you make payments without any application being opened.

kevin. mobile SDK offers convenience methods for verifying whether the mobile application currently serves as the default payment application and for prompting the user to designate it as such. These methods are callable from any part of the application.

Upon the user's entry into an activity responsible for managing linked payment accounts, it's recommended to check if the application is set as the default payment app. If not, prompt the user to confirm if they would like to set it as the default payment application.

class SampleActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        if (!KevinPay.isDefaultPaymentApp(this)) {
            KevinPay.setAsDefaultPaymentApp(this)
            /* 
                Calling this method will show a system popup asking the user 
                whether he wants to set this app as their default payment app.
            */
        }
    }
}

Set preferred foreground payment application

Another alternative to setting application to use for payments is KevinPay.setAsPreferredForegroundPaymentService(). This will allow user to still use their default payment application when making payments from background, but will use your application when it's open.

class SampleActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // Use this to check if app is already set as prefered foreground payment app.
        // This can be used to display message to the user
        val isPreferedApp = KevinPay.isPreferForegroundForPaymentsEnabled()
    }
    
    // Set app as preferred foreground payment application when activity is resumed
    override fun onResume() {
        super.onResume()
        KevinPay.setAsPreferredForegroundPaymentService(this)
    }
    
    // Unset app as preferred foreground payment application when activity is paused
    override fun onPause() {
        super.onPause()
        KevinPay.unsetAsPreferredForegroundPaymentService(this)
    }
}