# Android integration

This page provides instructions for integrating Kustom Checkout into an Android application.

## Before you start

This guide assumes Kustom Checkout has already been set up and is available at a specified API endpoint. For detailed setup, refer to the general Kustom Checkout Integration guide.

## Overview

Adding Kustom Checkout to your application involves adding a view and performing a few operations. This guide explains how to:

* Create and add a Kustom Checkout view to your app
* Initialize the view with a Kustom Checkout snippet value
* Use available APIs for Kustom Checkout
* Handle events and errors


The mobile SDK presents the Kustom Checkout view, requiring you to fetch a Checkout HTML snippet from your web server, and set the snippet on the view.  The guide assumes this setup is already completed at an API endpoint (`<YOUR-URL>`).  If needed, refer to the general Kustom Checkout integration guide for details.

## Setup your app

### Import the SDK

#### Add the repository

Add the KustomMobileSDK Maven repository:


```kotlin
repositories {
  maven("https://x.kustomcdn.co/mobile-sdk/android/")
  maven("https://x.klarnacdn.net/mobile-sdk/")
}
```

Add the SDK as a dependency to your app:


```kotlin
dependencies {
    implementation("com.kustom.mobile.sdk:kustom-mobile-sdk:1.0.0")
}
```

## Adding Kustom Checkout to your app

The Checkout View in Android is `KustomCheckoutView`. You can initialize it in your activity using XML or programmatically.

### Using XML


```xml
<com.kustom.mobile.sdk.api.checkout.KustomCheckoutView
    ...
    app:kustomEnvironment="production"
    app:kustomRegion="eu"
    app:kustomReturnUrl="test://"
    android:id="@+id/checkoutView"/>
```

### Programmatic initialization


```kotlin
val checkoutView: KustomCheckoutView = findViewById(R.id.checkoutView)
checkoutView.eventHandler = myEventHandler
```

## Creating the View from code


```kotlin
val checkoutView = KustomCheckoutView(
   activity = this,
   returnURL = "test://",
   eventHandler = myEventHandler,
   environment = KustomEnvironment.PRODUCTION,
   region = KustomRegion.EU,
   theme = KustomTheme.LIGHT
)
```

## Initialize SDK with the Checkout snippet

Initialize Kustom Checkout by providing a Checkout HTML snippet from `YOUR-URL`:


```kotlin
checkoutView.setSnippet(snippet)
```

## Configure event handler


```kotlin
checkoutView.eventHandler = object : KustomEventHandler {
    override fun onEvent(kustomComponent: KustomComponent, event: KustomProductEvent) {
        if (event.action == "complete") {
            try {
                val confirmationURL = event.params["uri"]
                loadConfirmationSnippet(confirmationURL)
            } catch (e: JSONException) {
                Log.e(TAG, e.message, e)
            }
        }
	    override fun onError(kustomComponent: KustomComponent, error: KustomMobileSDKError) {
	        Log.e(TAG, "Received error: ${error.name}. Message: ${error.message}")
	    }
    }
}
```

## Suspend and Resume Checkout

The suspend() and resume() actions control user interaction with the KustomCheckoutView.


```kotlin
checkoutView.suspend()
```


```kotlin
checkoutView.resume()
```

## Handling External Payment Methods


```kotlin
override fun onEvent(kustomComponent: KustomComponent, event: KustomProductEvent) {
   if (event.action == "external") {
      val externalPaymentUrl = event.params["uri"]
      openExternalPayment(externalPaymentUrl)
   }
}
```

## Handling Validation Errors


```kotlin
override fun onEvent(kustomComponent: KustomComponent, event: KustomProductEvent) {
   if (event.action == "validation_error") {
      val errorType = event.params["error_type"]
      val errorText = event.params["error_text"]
      handleValidationError(errorType, errorText)
   }
}
```

## Return URL

Some payment methods require authorization through third-party applications, which will return to your application upon completion.  You must provide a return URL for this process. No special handlers are required on application load; the user will be returned to your app by the third-party application.