sdk-android: A Java repository from mohammed-io

Getting started with iZettle Payments SDK for Android

Intro

The SDK is compatible with apps supporting Android API level 19 and above. The SDK itself is written in Kotlin which is the preferred language, however, we provide examples both in Kotlin and in Java.

The SDK requires location permission to function properly. It is needed to scan and connect Bluetooth devices, in this case, the iZettle Readers. During the integration process, you will be required to present your Github access token and your oAuth credentials. It is best to have these in advance.

Generating your Github token

Click on your profile picture in Github
Go to Settings
Click on Developer Settings
Select Personal access token and Generate a new token
Select the scope read:packages and generate your token

Generating OAuth credentials for your app

User authorization in the SDK is perfomed through the implementation of OAuth 2.0. This means that the SDK requires Client ID and a Redirect URI from your integrating app.

To obtain Client ID, create an account in the iZettle Developer Portal and create an Android SDK developer application by completing the following steps:

Go to https://developer.izettle.com/register and create an account
Verify your email address to be able to create new apps
Create a new app from the Dashboard and choose Payments SDK for Android option
Once you submitted the form, you'll be given a Client ID which can be used to initialize the SDK

Step 1: Add a dependency

First of all you need to add a dependency

maven {
    url = uri("https://maven.pkg.github.com/iZettle/sdk-android")
    credentials(HttpHeaderCredentials) {
        name "Authorization"
        value "Bearer <Your GitHub Token>" // More about auth tokens https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
    }
    authentication {
        header(HttpHeaderAuthentication)
    }
}

dependencies {
    implementation 'com.izettle.payments:android-sdk-ui:1.8.4'
}

Also you may face some conflicts in the .kotlin_module META-INF, so we suggest to exclude META-INF by adding

android {
    packagingOptions {
        exclude 'META-INF/*.kotlin_module'
    }
}

We are using AndroidX in some libraries so you will get them as dependencies as well.

Step 2: Configure your app

To be able to login a user through iZettle you must add callback activity to your manifest. The snippet below shows how you should do it, but don't forget to replace the redirect url data with your own in the intent filter.

<activity 
    android:name="com.izettle.android.auth.OAuthActivity" 
    android:launchMode="singleTask"
    android:taskAffinity="@string/oauth_activity_task_affinity"> 
    <intent-filter> 
        <data 
            android:host="[redirect url host]" 
            android:scheme="[redirect url scheme]" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

Step 3: Initialize SDK

The best place to initialize SDK is your Application class. If you don't have one, we recommend that you create one.

class MyApplication : Application() {
    
    // ...
        
    fun onCreate() {
        
        // Initialize SDK by your credentials    
        IZettleSDK.init(this, <Client ID>, <Redirect URL>)
            
        // Attach SDK lifecycle observer to your lifecycle. It allows SDK to
        // manage bluetooth connection in a more graceful way                   
        ProcessLifecycleOwner.get().lifecycle.addObserver(SdkLifecycle(IZettleSDK))
      
    }    
    
        // ...    
    
}

Step 4: Authorize user

Your application is responsible for user authorization. The SDK itself doesn't track auth state, but will return NotAuthorized errors if you try to take payments or make refunds without valid user authorization.

It's quite easy to track if the user is authorized or not. To do so you need to create an observer first.

private val authObserver = object : StateObserver<User.AuthState> {
    override fun onNext(state: User.AuthState) {
        when (state) {
            is User.AuthState.LoggedIn -> // User authorized
            is User.AuthState.LoggedOut -> // There is no authorized use 
        }
    }
}

And then subscribe to user state

fun onStart() {
    super.onStart()    
    IZettleSDK.user.state.addObserver(authObserver)
}

And unsubscribe if you need to

override fun onStop() {
    super.onStop()
    IZettleSDK.user.state.removeObserver(authObserver)
}

Or you can use LiveData and Observer from AndroidX

private val authObserver = Observer<User.AuthState> {
    when (it) {
        is User.AuthState.LoggedIn -> // User authorized
        is User.AuthState.LoggedOut -> // There is no authorized use
    }
}
    
override fun onCreate(savedInstanceState: Bundle?) {
    // ...
        
    IZettleSDK.user.state.toLiveData().observe(this, authObserver)
        
    //...        
}

User.AuthState.LoggedIn has info object with usable fields.

publicName - public company or merchant public name
imageUrl - profile image in small, medium and large size
userId - unique user id. can be used to join iZettle user and your data for it
organizationId - unique organisation id
timeZone - merchant time zone
country - merchant country
currency - currency used for all payments & refunds

Authorizing a user is simple. Just call login method from your Activity and provide a toolbar color compatible with your color theme.

private fun doLogin() {
    IZettleSDK.user.login(this, ResourcesCompat.getColor(resources, R.color.colorAccent, null))
}

Step 5: Starting payment

First of all you need to create a TransactionReference object using the builder provided.

IMPORTANT: The transaction reference object must contain at least one unique field

val internalTraceId = UUID.randomUUID().toString()
val reference = TransactionReference.Builder(internalTraceId)
    .put("PAYMENT_EXTRA_INFO", "Started from home screen")
    .build()

In the constructor builder you can provide your own id with a maximum of 128 characters to identify this payment, which can be used to perform payment refunds.

Using the put method you can add whatever you want to this object, but keep in mind that the total data size (including key names) in this object can't be bigger than 4 kilobytes. You will get this reference back with transaction data and can always request it back from our servers.

Then you need to start CardPaymentActivity. To do so you may use our helper which creates configured Intent object

val intent = CardPaymentActivity.IntentBuilder(this)
    // MANDATORY: Transaction amount in account currency 
    .amount(20000L)
    // MANDATORY, Reference object created in previous step        
    .reference(reference)
    // MANDATORY, you can enable login prompt in the payment flow if user is not yet logged-in
    .enableLogin(enableLogin)
    // OPTIONAL, you can enable tipping (disabled by default)       
    // This option will only work for markets with tipping support
    .enableTipping(true)
    // OPTIONAL, you can enable installments (enabled by default)
    // This option will only work for markets with installments support
    .enableInstalments(enableInstallments)
    .build()
            
// Start activity with the intent        
startActivityForResult(intent, 0)

Step 6: Processing payment result

You will receive the payment result as an activity result. Result Bundle contains two values:

CardPaymentActivity.RESULT_EXTRA_REQUEST contains all extras from request intent
CardPaymentActivity.RESULT_EXTRA_PAYLOAD contains payment result

The payment result is an instance of one of the following classes:

CardPaymentResult.Canceled

Payment was canceled by merchant or customer. Doesn't contain any additional data.

CardPaymentResult.Failed

Payment failed. The failure reason is defined by reason field and be one of the following:

FailureReason.TechnicalError - payment failed because of technical issues. Can happen because of bluetooth communication problem or other technical issue
FailureReason.NetworkError - Communication with iZettle servers failed
FailureReason.NotAuthorized - There is no authorized user to process payment request
FailureReason.AboveMaximum - Requested amount is greater than account limit
FailureReason.BellowMinimum - Requested amount is smaller than allowed minimum

CardPaymentResult.Completed

Card payment was successfully completed. Contains transaction info in payload field.

amount - Total transaction amount (also includes tip amount if applicable)
gratuityAmount - Contains total tip amount if tipping is performed, null otherwise
cardType - card brand: VISA, MASTERCARD and so on
cardPaymentEntryMode - EMV, CONTACTLESS_EMV, MAGSTRIPE_CONTACTLESS, MAGSTRIPE etc. More entry modes might be added independent of SDK version
tsi - EMV tags
tvr - EMV tags
applicationIdentifier - EMV tags (aid)
cardIssuingBank - card issuing bank if provided
maskedPan - e.g. "**** **** **** 1111"
applicationName
authorizationCode
installmentAmount - Value of each installment
nrOfInstallments - Number of installment chosen
mxFiid - Mexico specific data
mxCardType - Mexico specific data
reference - your reference object

Step 7: Performing refund

To perform a refund you first need to find a CardPayment that matches a given id provided in the TransactionReference.Builder(internalTraceId).

IZettleSDK.refundsManager.retrieveCardPayment(internalTraceId, object : RefundsManager.Callback<CardPaymentPayload, RetrieveCardPaymentFailureReason> {
    override fun onFailure(reason: RetrieveCardPaymentFailureReason) {
        // ...
    }

    override fun onSuccess(cardPaymentPayload: CardPaymentPayload) {
        // ...
    }
})

First of all you need to create a TransactionReference object using the builder provider since a refund is basically a transaction with negative value.

IMPORTANT: The transaction reference object must contain at least one unique field

val internalTraceId = UUID.randomUUID().toString()
val reference = TransactionReference.Builder(internalTraceId)
    .put("REFUND_EXTRA_INFO", "Started from home screen")
    .build()

In the constructor builder you must provide the CardPayment retrieved from previous step

Then you need to start RefundsActivity. To do so you may use our helper which creates configured Intent object

val intent = RefundsActivity.IntentBuilder(cardPaymentPayload)
    // Refund amount in account currency
    // This amount must be less or equal to the original card payment.
    // If not provided it will use original card payment amount
    .refundAmount(20000L)
    // Reference object created in previous step        
    .reference(reference)
    // Optional, you can provide tax amount of this card payment to be displayed in the UI
    .taxAmount(100L)
    // Optional, you can provide the receipt number of this card payment to be displayed in the UI
    .receiptNumber("#12345")
    .build()
            
// Start activity with the intent        
startActivityForResult(intent, 0)

Step 8: Processing refund result

You will receive the payment result as activity result. Result Bundle contains two values:

RefundsActivity.RESULT_EXTRA_REQUEST contains all extras from request intent
RefundsActivity.RESULT_EXTRA_PAYLOAD contains refund result