Kustom Checkout in a mobile app

The Kustom Mobile SDK renders Kustom Checkout inside a native app. It works the same way as the web integration: your server creates the order and returns its html_snippet, you hand that snippet to a checkout view, and the view tells you what the customer did through an event handler. This page covers what’s common to every platform. The platform pages walk through the integration step by step.

Choose your platform

iOS

Swift, with the SDK from Swift Package Manager or CocoaPods.

iOS integration →

Android

Kotlin, with the view declared in XML or built in code.

Android integration →

React Native

A KustomCheckoutView component with props for events and errors.

React Native integration →

How it works

Your backend, not the app, creates the order. The SDK never holds your API credentials. Expose an endpoint that creates the order and returns its html_snippet, and have the app fetch from there. The platform pages call it <YOUR-URL>.

There are two ways to integrate, depending on who owns the screen.

Native. The app owns the screen, and the SDK renders the checkout in its own view. This is what the platform pages build, and what most apps want:

1. Fetch a Kustom Checkout html_snippet from your server.
2. Set the snippet on a KustomCheckoutView and display it.
3. Handle the events the view dispatches.

Hybrid. The app already renders your checkout page in a web view. The SDK attaches to that web view and reacts to the Kustom content inside the page rather than rendering its own:

1. Initialize the SDK with your web view.
2. Present your web page as usual.
3. Notify the SDK about the web view’s navigation events.
4. Handle the events the SDK dispatches.

The return URL

Some payment methods hand the customer to a third-party app, such as a bank or a wallet, to authorize the purchase. The return URL is what brings them back: a custom scheme your app is registered for, such as myapp://. Every platform requires one, and the value you pass to the SDK must be a scheme your app actually handles.

You don’t need a special handler for when the app reopens. The third-party app sends the customer back to your app by itself.

BankID may not return the customer automatically. After authenticating with BankID, the customer might have to switch back to your app themselves.

Events and errors

The SDK reports through two callbacks: one for product events and one for errors. The names are the same on every platform.

A product event (KustomProductEvent) carries:

Field	Type	Description
action	string	The event’s name.
params	map of string to any	The event’s parameters.

The actions you act on:

action	params	What it means
complete	uri	The customer has paid. uri is the confirmation URL to load next.
external	uri	The customer chose an external payment method. uri is where to send them.
validation_error	error_type, error_text	A validation error you’ve opted to handle yourself.

An error (KustomMobileSDKError) carries:

Field	Type	Description
name	string	The error’s name.
message	string	A description of the error.
isFatal	boolean	Whether the error stops the checkout.
sessionId	string	The session the error occurred in.

An error with isFatal set means the checkout can’t continue. Send the customer somewhere else rather than leaving them on a dead view.

Migrating from the Klarna Mobile SDK

KustomMobileSDK is built on the Klarna Mobile SDK and has feature parity with it for Kustom Checkout. It was branched from these versions:

Platform	Klarna Mobile SDK version it was migrated from
Android	2.6.29
iOS	2.7.0
React Native	2.4.10

Migrate straight to KustomMobileSDK even if you’re several minor versions behind those. There’s no benefit in stepping through the Klarna versions first. The migration itself is two changes:

1. Swap the dependency for KustomMobileSDK, as shown on your platform page.
2. Rename KlarnaCheckoutView to KustomCheckoutView wherever you construct or reference it. The event and error types follow the same rename.

Related

• iOS, Android and React Native integration guides
• Confirmation and push — what your server must do once complete fires
• Integration models — the SDK renders the same checkout as the web snippet
• Test data — Playground customers and cards to pay with