Kustom Checkout in an Android app

This guide adds Kustom Checkout to an Android app with the Kustom Mobile SDK. You create a KustomCheckoutView, set the checkout snippet your server returns on it, and handle the events it dispatches. Kustom Checkout in a mobile app explains what’s common to every platform.

Before you start

You need:

• A server endpoint that returns a checkout snippet. Your backend, not the app, creates the order with your API credentials and returns its html_snippet. See Create and update an order. This guide calls the endpoint <YOUR-URL>.
• A return URL. A custom URL scheme your app is registered for, such as myapp://. It brings the customer back after a payment method sends them to a third-party app. See the return URL.

Step by step

1. Add the SDK

Add the KustomMobileSDK Maven repositories and the dependency to your Gradle build:

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

dependencies {
  implementation("com.kustom.mobile.sdk:kustom-mobile-sdk:1.x.x")
}

The second repository is required because KustomMobileSDK still resolves shared artifacts from the Klarna Mobile SDK’s Maven host. Keep it until Kustom says otherwise.

2. Create the checkout view

The checkout view is KustomCheckoutView. Declare it in your layout or build it in code.

In XML. Declare the view with its environment, region and return URL:

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

Then look it up in your activity and attach an event handler (step 4):

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

In code. Build the view with everything at once. This is also where you set the theme:

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

3. Set the snippet

Fetch the html_snippet from <YOUR-URL> and set it on the view. This is what renders the checkout:

checkoutView.setSnippet(snippet)

4. Handle events and errors

The event handler implements KustomEventHandler: onEvent receives product events and onError receives SDK errors. Act on each event by its action:

checkoutView.eventHandler = object : KustomEventHandler {
    override fun onEvent(component: KustomComponent, event: KustomProductEvent) {
        when (event.action) {
            "complete" -> loadConfirmationSnippet(event.params["uri"])
            "external" -> openExternalPayment(event.params["uri"])
            "validation_error" -> handleValidationError(
                event.params["error_type"],
                event.params["error_text"],
            )
        }
    }

    override fun onError(component: KustomComponent, error: KustomMobileSDKError) {
        Log.e(TAG, "Received error: ${error.name}. Message: ${error.message}")
    }
}

The complete action means the customer has paid, and params["uri"] is the confirmation URL to load next. external carries the URL of an external payment method to send the customer to, and validation_error carries the error’s type and text. Events and errors lists every action and error field.

Check that it works

Point the app at a Playground order and run the flow end to end:

1. The checkout renders in the view after setSnippet, rather than staying blank.
2. Paying with Playground test data dispatches a complete event carrying a uri.
3. Your confirmation screen loads from that uri.
4. Turning off the network mid-checkout produces an error in onError, with isFatal telling you whether to recover or bail out.

A blank view almost always means the snippet never arrived. Check the response from <YOUR-URL> before suspecting the SDK.

Variations

Pausing the checkout while you update the order. suspend() stops the customer from interacting with the checkout and resume() lets them continue. Suspend before you change the order and resume afterwards, so the customer never sees stale totals:

checkoutView.suspend()
checkoutView.resume()

Troubleshooting

The customer is left in the bank app after BankID. BankID may not return the customer automatically after authentication. They might have to switch back to your app themselves.

Related

• Confirmation and push — what your server must do once complete fires
• Create and update an order — the call behind <YOUR-URL>
• Kustom Checkout in a mobile app — native or hybrid, the return URL and migrating from the Klarna Mobile SDK
• iOS and React Native — the same integration on the other platforms
• Test data — Playground customers and cards to pay with