Klarna’s Mobile SDK is the official toolkit for integrating Klarna products into native iOS apps. It enables you to offer Klarna’s payment methods with a seamless in-app user experience. The SDK is designed to provide the optimal integration and, under the hood, the SDK handles web-based flows in a mobile-friendly way to reduce friction and ensures that all the features listed below are fully supported for a superior customer experience across all mobile platforms.

Feature support with Klarna’s Mobile SDK:

• Remember Returning Customers: enable faster checkouts and improved conversion by reducing friction for returning users.
• Device-Wide Login Experience: simplify repeat purchases by enabling customers to remain logged in to Klarna across merchant apps on the same device.
• Passkey Support: offer biometric-based login for enhanced security and a frictionless user authentication experience.
• Application Redirects: seamlessly redirect users to external apps (e.g. bank or identity verification apps) and ensure a smooth return back into your app to complete payments without disruption.
• Camera Access for ID Verification: improve acceptance by enabling secure and instant identity verification within the app.
• Secure Browser Context: provide a secure, embedded browser environment for displaying Klarna-hosted content (payment pages or terms).
• File Sharing and Download for T&Cs: Let customers download or share terms and conditions directly from the app for full transparency.

For a Mobile SDK integration your Payment Server and Mobile App must work together to complete the purchase flow:

1. Prepare: Make sure you have the credentials for Klarna Payments.
2. Initiate payment (Server-side): Create a payment session from your backend and pass client_token to your app.
3. Set up your app (Mobile App): Install the Klarna SDK using your package manager.
4. Render payment view (Mobile App): Present Klarna’s native view to display Klarna in your checkout.
5. Authorize the session (Mobile App): Trigger the authorization through the SDK and handle the callback.
6. Create an order (Server-side): Pass the resulting authToken to your backend to finalize the payment and create an order.

Presenting Klarna in your mobile checkout

To maximize conversion and usability, you must dynamically retrieve Klarna’s branding, payment descriptors, and payment widget via Klarna’s API and SDK to present accurate, localized, and up-to-date payment options.

1. Payment Descriptor: Dynamically populated in Klarna Payment session response, in the payment_method_categories.name field.
2. Payment Sub header: Added by merchant.
3. Widget: Provided with the KlarnaPaymentView from the Mobile SDK.
4. Klarna Badge: Dynamically populated in Klarna Payment session response, in the payment_method_categories.asset_urls.standard field.

{{#lst:Prepare your integration web|introduction}}

Before you start integrating Klarna payments, there are a few things you need to prepare in advance:

• Access to the Merchant portal
  
  • To access the test Merchant portal, you can sign up to create a new test account or log in with a test existing account.
  
• API keys for the Klarna Payments API
  
  • To test your Klarna API integration, you need a set of test credentials.
  
• The API reference. You can download the Open API specification for the Klarna payments API and use the specification to generate an API SDK for your programming language.
• Sample customer data and sample payment data

When your customer wants to pay with Klarna, you have to open a payment session and share the shopping cart details in a POST request to the {apiURL}/payments/v1/sessions endpoint. In that request, you also specify if the payment is one-time or recurring.

Once you start a payment session, it stays open for 48 hours or until you place an order. You can also send a separate POST request to cancel the session.

Authentication

Klarna payments API uses HTTP basic authentication. To authenticate, use your API credentials that consist of:

• A username linked to your Klarna merchant ID (MID)
• A password associated with your username

If you're using an API platform that lets you store your credentials, you can add them in relevant fields. Otherwise, make sure to include the Base64-encoded username:password in the Authorization header field of each API request, as shown below.

Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==

A sample authorization request header with Base64-encoded credentials.

Common Parameters

To get a success response, include the following required parameters in your POST {apiURL}/payments/v1/sessions request.

To open a one-time payment session, include all common parameters in the request body and set intent to buy.

{
"acquiring_channel": "ECOMMERCE",
"intent": "buy",
"purchase_country": "SE",
"purchase_currency": "SEK",
"locale": "en-SE",
"order_amount": 9500,
"order_tax_amount": 1900,
"order_lines": [
{

A sample POST request to create a one-time payment session.

Success Response

In response to a create session call, you receive:

• session_id, a payment session identifier you can use to [ update the session] and [ retrieve session] details
• client_token, a token you pass to the JavaScript SDK or Mobile SDK(Android, iOS and React Native) to launch the Klarna widget
• payment_method_categories, an array that lists the grouped Klarna payment methods available for the session. We can respond with one or more categories depending on the market and account configuration.

{
"session_id": "068df369-13a7-4d47-a564-62f8408bb760",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAwMDAwMDAwMDAtMDAwMDAtMDAwMC0wMDAwMDAwMC0wMDAwIiwidXJsIjoiaHR0cHM6Ly9jcmVkaXQtZXUua2xhcm5hLmNvbSJ9.A_rHWMSXQN2NRNGYTREBTkGwYwtm-sulkSDMvlJL87M",
"payment_method_categories": [
{
"identifier": "klarna"
"name" : "Pay with Klarna",
"asset_urls" : {
"descriptive" : "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
"standard" : "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"

A sample success response to the create session call.

Error Response

If your request doesn't pass our validation, you'll receive an error response.

{
"correlation_id": "6a9b1cb1-73a3-4936-a030-481ba4bb203b",
"error_code": "BAD_VALUE",
"error_messages": [
"Bad value: order_lines"
]
}

A sample error response caused by incorrect order line details.

​Go to Error Handling to learn more about common errors and troubleshooting suggestions. You can use the value in correlation_id to find entries related to the request under Logs in the Merchant portal.

Add the Repository

Add the Klarna Mobile SDK maven repository:

Add the Dependency

Add the SDK as a dependency to your app:

Return URL

Klarna purchase flows might require authorizations in other applications (e.g. bank apps) or do a handover to the Klarna app. In such cases, a return URL to your application ensures seamless return to the flow in your app, hence setting up a return URL is required. It is expected that redirects to this URL should only open your application without any changes in the UI state, ensuring the customer can continue the flow prior to external navigation.

You can read more about how deep links and intent filters work on the Android Developers site.

You can set up a Return URL app scheme for your application by registering an intent-filter for the Activity you integrated Klarna, in your app’s AndroidManifest.xml:

<application...>
    <activity...>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="<your-custom-scheme>" />
            <data android:host="<your-custom-host>" />
        </intent-filter>
    </activity>

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { uri ->
        if (uri.host == Contants.klarnaReturnUrl.host && uri.host == Contants.klarnaReturnUrl.host) {
            // This is a return URL for Klarna – skip deep linking
            return
        }
        // This was not a return URL for Klarna
    }
}

Payment View is an instance of KlarnaPaymentView, which is a native view intended to be used natively in your checkout screen.

Inflate from XML

You can add the view to your layout as shown below:

<com.klarna.mobile.sdk.api.payments.KlarnaPaymentView
    ...
    android:id="@+id/paymentView"/>

You should then be able to set up the view in code by setting a category and registering a callback:

val paymentView: KlarnaPaymentView = findViewById(R.id.paymentView)
paymentView.category = "klarna"
paymentView.registerPaymentViewCallback(callback)

Create programmatically

If you instead want to create the view in code, you can use its constructor to set it up with a single line.

val paymentView = KlarnaPaymentView(
   context = this,
   category = "klarna",
   callback = callback,
   returnURL = Constants.klarnaReturnUrl
)
paymentView.layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT)
view.addView(paymentView)

Before content is rendered into a payment view or an authorization, payment session with it's client token needs to be initialized. This can be done by calling initialize and handling result in onInitialized.

// initilize with clientToken for session created from server-side
paymentView.initialize(clientToken)

If successful, onInitialized from KlarnaPaymentViewCallback will be called in the callback you supplied. If it’s not successful, onErrorOccurred will be called instead.

override fun onInitialized(view: KlarnaPaymentView) {
    view.load() // optionally load payment widget upon initialize
}

1. Payment Descriptor: Dynamically populated in Klarna Payment session.
2. Payment Sub header: Added by merchant.
3. Widget: Dynamically populated in Klarna Payment session.
4. Klarna Badge: Dynamically populated in Klarna Payment session.

Once you’ve initialized the view and you’re ready to display the payment widget, simply by calling load.

// load optional payment widget
paymentView.load(null)

If successful, onLoaded will be called in KlarnaPaymentViewCallback and for errors onErrorOccurred will be called instead.

override fun onLoaded(view: KlarnaPaymentView) {
    // content has finished loading and if you have any loader you could hide it here
}

Your native checkout screen before the customer chooses to Continue with Klarna.	Klarna purchase flow after the customer clicked your Continue with Klarna button and you called authorize.

Once the user has confirmed that they want to pay with Klarna, it’s time to authorize the session. This is done by calling authorize, and similar to load, you can supply an optional JSON string with sessionData parameter to update the session. You can also specify whether auto-finalization should be turned off(on by default) and in that case you might be required to finalize the session after.

// authorize the payment session
paymentView.authorize(sessionData = null)

If the session needs to be finalized, you’ll need to perform this last step to get an authorization token, simply call finalize in order to get the authentication token. Similar to authorize you can supply an optional JSON string with sessionData parameter to update the session.

paymentView.finalize(null)

To continue with the purchase, you have to create an order in Klarna's system. This step takes place in the server side through the Klarna payments API.

To create an order for a one-time payment, send a POST request to the {apiUrl}/payments/v1/authorizations/{authorizationToken}/order endpoint and include authorization_token in the path.

For example, if the authorization_token is b4bd3423-24e3, send your request to the {apiUrl}/payments/v1/authorizations/b4bd3423-24e3/order endpoint.

{
"purchase_country": "US",
"purchase_currency": "USD",
"billing_address": {
"given_name": "John",
"family_name": "Doe",
"email": "john@doe.com",
"title": "Mr",
"street_address": "Lombard St 10",
"street_address2": "Apt 214",

A POST request to create an order for a one-time payment.

Success response

When you receive a success response, the customer gets charged and the Klarna payments session is closed.

As part of the response, you receive the following details:

• order_id, an order identifier that you can later use to capture or refund the order using the Order management API
• redirect_url, a URL to which you redirect the customer. This isn't included in the response received if you didn't include the URL when initiating a payment
• fraud_status, an indicator of whether the transaction is suspected to be legitimate or fraudulent
• authorized_payment_method, the payment method selected by your customer for this purchase

{
"order_id": "3eaeb557-5e30-47f8-b840-b8d987f5945d",
"redirect_url": "https://payments.klarna.com/redirect/...",
"fraud_status": "ACCEPTED",
"authorized_payment_method": "invoice"
}

A success response to the order creation request for a one-time payment.

Error response

If your request doesn't pass our validation, you'll receive an error response. The most common reasons why creating an order fails are:

• placing the order more than 60 minutes after authorization
• modifying purchase details after authorization without updating the payment session

{
"correlation_id": "6a9b1cb1-73a3-4936-a030-481ba4bb203b",
"error_code": "ERROR_CODE",
"error_messages": [
"ERROR_MESSAGE"
]
}

An error response to the order creation request for a one-time payment.

Here are examples of common errors with troubleshooting suggestions. You can use the value in correlation_id to find entries related to the request under Logs in the Merchant portal.

The SDK will log events and errors while it’s running, which you can read in logcat console. You can set the logging level for the SDK through the loggingLevel property of integration instance.

klarnaPaymentView.loggingLevel = KlarnaLoggingLevel.Verbose

KlarnaLoggingLevel

Klarna Mobile SDK provides a full suite of mobile-first integrations, including Klarna products like:

Sign in with Klarna	On-site Messaging	Express Checkout

• On-site Messaging: Show contextual messaging let your customers know about the available payment options in pre-checkout: click here to learn more.
• Sign in with Klarna: Seamlessly identify and let users login via their Klarna account: click here to learn more.
• Express Checkout: Accelerate your checkout process and boost conversion by offering a one-click checkout, click here to learn more (Mobile SDK support available soon).

Complete your integration with

• Order management
• Settlements
• End-to-end testing
• Prepare for go live