Integrate Klarna via Mobile SDK by embedding the payment form, tracking payment status, and completing authorization flows for a smoooth mobile checkout experience.
This guide will cover both iOS (Swift) and Android (Kotlin) integrations.
Here's an overview of all the steps to processing a payment with Klarna via the Mobile SDK:
1.
Present Klarna as a payment option in the payment form.
2.
Customer clicks the Klarna payment button in your checkout.
3.
You create either a server-side payment request with your Acquiring Partner or use the Klarna Mobile SDK to initiate the payment request, sharing all available interoperability data points.
4.
If customer interaction is required:
4.1.
The Klarna Purchase Journey is launched.
4.2.
The customer completes the Klarna Purchase Journey.
5.
Klarna returns a klarna_network_session_token via a webhook.
6.
You create an authorization request with your Acquiring Partner and share the required interoperability data points.
7.
Acquiring Partner responds with an approval and order completion.
8.
Customer is redirected to your confirmation page.
sequenceDiagram
participant C as Customer
participant P as Partner
participant K as Klarna
participant AP as Acquiring Partner
C->>P: Visit checkout page
P->>K: Initialize Klarna Mobile SDK
P->>K: Request presentation instructions
K->>P: Return assets and instructions
P->>P: Render payment selector
C->>P: Select Klarna payment method
P->>P: Update Klarna presentation<br>Show Klarna payment button
C->>P: Click Klarna payment button
Note over P,AP: Handle the "Pay with Klarna" button click
P->>K: Initiate Payment Request
K->>C: Start Klarna purchase flow
C->>K: Complete Klarna purchase flow
K->>P: Payment request completed event via webhook
Note over P,K: klarna_network_session_token
P->>AP: Authorize payment
Note over P,AP: Share interoperability data points
AP->>P: Respond with approval
Note over P,AP: Order completed
P->>C: Redirect to confirmation page
Integrate the Klarna Mobile SDK to display Klarna as a payment option within your own payment form. This approach lets you fully control the checkout experience while using Klarna’s ready-made UI components for secure payment handling.
This guide explains how to present Klarna in your payment form, both during the initial load and after the customer selects Klarna. By following these steps, you’ll ensure the payment flow meets Klarna’s design and functionality standards:
Initial presentation
When Klarna is selected
It's crucial that Klarna payment presentation is dynamic and not hardcoded on your server to deliver the best conversion outcome.
Klarna's best practice
To ensure the best user experience and optimal conversion rates when presenting Klarna as a payment option, please apply the following recommendations:
Present Klarna dynamically alongside other payment options in your payment form.
Embed Klarna’s UI elements directly in your frontend for a consistent and responsive design.
The next sections in this guideline will walk through how this can be achieved using Klarna Mobile SDK [link to public APIs].
The following table lists the properties of KlarnaConfiguration.
Name
Type
Presence
Description
clientId
String
required
The client ID of the partner account that is integrating the Mobile SDK. If the integration is done by a PSP/DP then this must be set to the distribution partners own client ID.
locale
String
optional
The default locale (ISO 3166-1 alpha-2) that will be used by the SDK. If not set, the locale of the device will be used.
sdkToken
String
optional
The SDK token allows the SDK to be initialized with an existing session. Token is only retrievable server-side via the Interoperability API.
This step is only applicable if you are in possession of a klarna_network_session_token.
The SDK token is a single-use, browser-bound credential that restores the customer’s checkout context when Klarna’s Mobile SDK is initialized. This token should be exchanged server-side before initializing the SDK and displaying the checkout view to the customer.
You must exchange the acquired klarna_network_session_token for a short-lived SDK token using the generateSdkToken endpoint.
Consult the API reference for generateSdkToken API call, to find a complete description of the parameters.
Klarna payment presentation provides all the visual assets, localized texts, and instructions needed to correctly display Klarna in your checkout screen.
To fetch the payment presentation, you need to call the KlarnaPaymentPresentation.fetch() method like below:
Specifies the intent of the payment presentation content for your use case. It can be used when you need presentation elements tailored to specific payment scenarios.
subscriptionBillingInterval
KlarnaInterval
optional
Specifies the interval of which the customer is charged for the subscription.
After a successful payment presentation fetch, you will get an instance of KlarnaPaymentPresentationContent containing the full Klarna branding package and instructions that can be used to present Klarna as a payment option.
This section explains how to handle Klarna’s payment presentation instructions, which define how Klarna should appear within the checkout form. Adhering to these instructions is essential to maintain a consistent and optimized user experience—whether Klarna is displayed alongside other payment methods, preselected, or shown as the only available option.
Compliance with Klarna’s presentation instructions is especially important when integrating Klarna Conversion Boost features, such as Express Checkout or Sign in with Klarna, to ensure a seamless and unified customer experience.
The instruction property available in KlarnaPaymentPresentationContent can have the following possible values:
Name
Description
SHOW_KLARNA
Show Klarna alongside other payment methods.
PRESELECT_KLARNA
Show Klarna pre-selected but still alongside other payment methods. This is returned when using the customer_token issued from the Sign in with Klarna feature or the tokenization flow.
SHOW_ONLY_KLARNA
Show Klarna as the only payment method. This is returned when the customer has finished the first step of multi-step Klarna Express Checkout.
Skip this section if you don't use any Conversion Boost features from Klarna such as Klarna Express Checkout, Sign-in with Klarna, Klarna Messaging or Klarna Prequalification.
Here are example outcomes illustrating how Klarna should be displayed for each instruction:
Show Klarna
Preselect Klarna
Show only Klarna
The presentation instructions are derived from possible customer purchase journeys described in the following article.
The following code snippet shows an example of how instruction can be used to decide how to present Klarna as a payment option.
SWIFT
1
2
3
4
5
6
7
8
9
10
privatefunc renderKlarnaPresentation(content: KlarnaPaymentPresentationContent) {
let instruction: KlarnaPaymentPresentationInstruction = content.instruction
switch instruction {
case .showKlarna:
// Show Klarna alongside other payment optionscase .preselectKlarna:
// Preselect Klarna as the default payment optioncase .showOnlyKlarna:
// Show only Klarna as the payment option
}
After fetching the payment presentation, you have access to an instance of KlarnaPaymentPresentationContent. It can be used to present Klarna as a payment option. The Klarna payment option must be rendered in the payment selector according to Klarna’s presentation guidelines.
The following table lists the properties of KlarnaPaymentPresentationContent.
Name
Type
Presence
Description
instruction
KlarnaPaymentPresentationInstruction
required
Specifies how Klarna should be displayed as a payment option (e.g., whether to show, preselect, or display as show-only). Adhering to these payment presentation instructions ensures customers have the best possible experience and optimizes conversion rates.
paymentOption
KlarnaPaymentPresentationPaymentOption
optional
Specifies the default payment option applicable to all purchase types. It includes the visual elements required to represent Klarna during checkout.
paymentStatus
KlarnaPaymentPresentationPaymentStatus
optional
Specifies the payment status of the presentation.
The KlarnaPaymentPresentationPaymentOption type has the following properties:
Name
Presence
Description
paymentOptionId
required
The identifier of the payment option. This value is required to be sent to the Payment Authorize API or the Payment Request API when initiating the payment.
header
optional
The main descriptor that introduces Klarna in the payment form. The value will be dynamically adjusted based on the locale provided when you initialized the Klarna SDK.
subheader
optional
The sub-header descriptor that must be loaded inline below the main descriptor header. It's a short and enriched descriptive text that provides transparency on available options like installments, pay later, etc.
message
optional
Enriched tailored description with link.
badge
optional
Badge used for saved options or promotions.
terms
optional
Defines terms/disclosures potentially with links.
1.
icon
2.
badge
3.
header
4.
subheader
5.
message
6.
terms
7.
button
Present the Klarna payment option elements within your Klarna payment method view to render them in the payment form. The code snippet below shows a very basic sample of how you can do so:
SWIFT
1
2
3
4
5
6
7
8
9
10
privatefunc renderKlarnaPresentation(content: KlarnaPaymentPresentationContent) {
iflet headerText = content.paymentOption?.header, case .plainText(let text) = headerText {
// Show the header text in the UI (for example in a UITextView)
}
iflet subheaderText = content.paymentOption?.subheader, case .plainText(let text) = subheaderText {
// Show the subheader text in the UI (for example in a UITextView)
}
iflet badgeText = content.paymentOption?.badge, case .plainText(let text) = badgeText {
// Show the badge text in the UI (for example in a UITextView)
}
When a Klarna payment option is selected/deselected, ensure the additional visual components are shown/hidden properly.
SWIFT
1
2
3
4
5
6
7
8
9
10
// UIKit approachfunc toggleKlarnaPaymentOptionSelection(isSelected: Bool) {
// In this example, klarnaPresentationContainer is a view containing// presentation message, terms and button
klarnaPresentationContainer.isHidden = !isSelected
}
// SwiftUI approachstructKlarnaPaymentOption: View {
@State var isSelected: Bool
The message contained within the payment object contains two different classifications of links as set forth by the context value.
Context Value
Purpose
info
This indicates that the content of the URL is purely informational.
auth
This value indicates that the content of the URL requires customer authentication.
Due to the authentication requirements associated with the auth context, it is necessary for the link to be opened in a non-ephemeral ASWebAuthenticationSession on iOS and a CustomTab on Android. By contrast, info context links can be opened in any WebView. To simply the requirements associated with properly handling these links, we have created the following method for you to call.
SWIFT
1
2
3
4
5
6
7
8
9
10
// Handle the presentation link
klarna.payment.presentation.handleLink(
content: <PAYMENT_PRESENTATION_CONTENT>,
url: <URL>)
{ (result: Result<KlarnaPaymentPresentationContent, KlarnaSDKError>) inswitch result {
case .success(let paymentPresentationContent):
// Payment presentation link handling was successful. paymentPresentationContent contains// the latest payment presentation information.print("Payment presentation link handling succeeded.")
The following table lists the parameters of KlarnaPaymentPresentation.handleLink() method.
Name
Type
Presence
Description
activity
Activity
required for Android only
The Activity instance of your app.
content
KlarnaPaymentPresentationContent
required
The presentation content that you've already fetched using the KlarnaPaymentPresentation.fetch() method.
url
String
required
The URL to handle.
callback
KlarnaPaymentPresentationCallback
required
The callback to get notified of the result of payment presentation link handling.
Choose the theme and shape of the payment button to best fit into your online store in a way that complements your brand and encourages user engagement. More details on the button styling can be found here.
When the payment button is tapped, you should initiate the payment request process. This is done by calling the KlarnaPayment.initiate() method. There are two options for initiating the payment request using the initiate() method:
Client-side, sharing the details of customer's checkout session (paymentRequestData) when calling the initiate() method.
Using the Klarna payment_request_id associated with the customer's checkout session that was generated server-side via your Acquiring Partner.
In client-side payment request initiation, you pass all the data needed to create and initiate a payment request to the Mobile SDK and the Mobile SDK takes care of creating and initiating the payment request.
The following table lists the parameters of KlarnaPayment.initiate() method.
Name
Type
Presence
Description
activity
Activity
required for Android only
The Activity instance of your app.
data
KlarnaPaymentRequestData
required
The data needed to create and initiate the payment request.
callback
KlarnaPaymentRequestCallback
required
The callback to get notified of the result of payment request initiation.
The table below lists all the properties of KlarnaPaymentRequestData.
Parameter
Presence
Description
currency
required
Three-letter ISO 4217 currency code (e.g., USD, EUR).
amount
required
Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500.
paymentRequestReference
optional
Reference to the payment session or equivalent resource created on the integrator's side.
supplementaryPurchaseData
optional
Provides additional details about the transaction to help reduce fraud risk and enhance transparency.
shippingConfig
optional
Configure how the shipping collection form will behave in the purchase flow. Without the shipping config, no shipping collection form will be displayed.
requestCustomerToken
optional
Object to request customer account linking to be set up, effectively returning a token called customer_token on successful confirmation of the payment request.
Call the Payment Request API to initiate a transaction. If customer verification is required, Klarna processes the request and creates a unique payment identifier for tracking. The payment request is then returned in the SUBMITTED state with the interaction details needed to complete the payment flow.
When integrating Klarna’s purchase flow, it’s essential to define how the customer should be redirected after completing or exiting the Klarna experience. Depending on whether the flow runs in a web or mobile app environment, Klarna uses one or both return URLs to ensure a seamless handoff back to the Partner’s experience.
The parameters return_url and app_return_url specify where Klarna should redirect the customer once the interaction ends—whether they’ve approved or aborted the purchase. Correctly configuring these URLs ensures that customers always return to the appropriate context (webpage or mobile app) and can smoothly continue the checkout or post-purchase process.
If the Klarna purchase flow is launched in a web environment, Klarna will redirect the customer to this URL after the customer finishes their interaction with Klarna, either by approving or aborting the purchase flow. This could either be a URL from the Acquiring Partner who will handle the redirection logic or a URL collected from the Partner.
The customer may be redirected to a third party app (bank app) or the Klarna app during the Klarna Purchase Journey on mobile environments. This URL enables Klarna to return the customer back to the Partner’s mobile app. Ensure the app_return_url is set up to register a URL scheme (e.g., partnerapp://klarna) or universal link that resumes the payment flow. The Partner is expected to open the integrating mobile application in its last state (no state changes or deeplink navigations).
Visual representations for Web flow and App handover flow:
Web handover
App handover
return_url and app_return_url are not mutually exclusive
In different scenarios, either or both of the return_url and app_return_url can be triggered:
Example 1: Onlyreturn_urlis triggered – Pure web flow
The customer starts the Klarna purchase flow in a web browser on a desktop. After approving the purchase, they are redirected to the return_url.
Example 2: Onlyapp_return_urlis triggered – App-to-app flow
The Partner’s native mobile app opens the Klarna purchase flow using a universal link. If the Klarna app is installed, the customer is taken directly into the Klarna app. After approval, they are redirected to the app_return_url, returning them to the Partner's app.
Example 3: Both URLs are triggered – WebView flow with app handover
The Partner’s native mobile app starts the Klarna purchase flow in a System WebView. If the customer needs to authenticate via an external banking app, they’re handed back to the Partner's app using app_return_url. They then resume the purchase flow in the WebView and, upon completion, are redirected to the return_url.
Provide supplementary purchase data
Supplementary Purchase Data refers to additional transaction details shared with Klarna that provide greater context about a purchase. These data points—such as line items, subscription details, or industry-specific attributes—help improve underwriting accuracy, fraud assessment, and the customer’s post-purchase experience. They may be required in certain industries and support multiple use cases, including better acceptance rates, enhanced fraud prevention, improved customer experiences within the Klarna app, and more effective risk monitoring.
Data requirements
Depending on the business type, certain supplementary_purchase_data fields are required under the Klarna Network Rules. However, purchase_reference, line_items, customer and shipping whenever available must always be submitted, as they enable transaction-level traceability, power Klarna’s fraud prevention and underwriting models, dispute handling, and ensure a consistent customer experience across Klarna’s ecosystem.
Once you have created the payment request, take the payment_request_id from the server-side response and provide it in the Mobile SDK initiate method as highlighted in the code below.
Name
Type
Presence
Description
activity
Activity
required for Android only
The Activity instance of your app.
paymentRequestId
String
required
The ID of the payment request that has been created server-side.
callback
KlarnaPaymentRequestCallback
required
The callback to get notified of the result of payment request initiation.
SWIFT
1
2
3
4
5
6
7
8
9
10
@objc func didTapPaymentButton() {
// Initiate the payment request
klarna.payment.initiate(paymentRequestId: <PAYMENT_REQUEST_ID>) { (result: Result<KlarnaPaymentRequest, KlarnaSDKError>) inswitch result {
case .success(let paymentRequest):
// Payment request initiation was successful. paymentRequest contains the// information about the payment request.print("Payment request initiation succeeded.")
case .failure(let error):
// Payment request initiation failed. More information about the failure
To get the information associated with a payment request, you can use the KlarnaPayment.fetch() method. The following code shows a sample implementation:
SWIFT
1
2
3
4
5
6
7
8
9
10
// Fetch the payment request
klarna.payment.fetch(paymentRequestId: <PAYMENT_REQUEST_ID>) { (result: Result<KlarnaPaymentRequest, KlarnaSDKError>) inswitch result {
case .success(let paymentRequest):
// Payment request fetch was successful. paymentRequest contains the// information about the payment request.print("Payment request fetch succeeded.")
case .failure(let error):
// Payment request fetch failed. More information about the failure// is available in the error object.
The following table lists the parameters of KlarnaPayment.fetch() method.
Name
Type
Presence
Description
paymentRequestId
String
required
The ID of the payment request to fetch.
callback
KlarnaPaymentRequestCallback
required
The callback to get notified of the result of payment request fetch.
To cancel a payment request, you can use the KlarnaPayment.cancel() method. The following code shows a sample implementation:
SWIFT
1
2
3
4
5
6
7
8
9
10
// Cancel the payment request
klarna.payment.cancel(paymentRequestId: <PAYMENT_REQUEST_ID>) { (result: Result<KlarnaPaymentRequest, KlarnaSDKError>) inswitch result {
case .success(let paymentRequest):
// Payment request cancelation was successful. paymentRequest contains the// information about the canceled payment request.print("Payment request cancelation succeeded.")
case .failure(let error):
// Payment request cancelation failed. More information about the failure// is available in the error object.
The following table lists the parameters of KlarnaPayment.cancel() method.
Name
Type
Presence
Description
paymentRequestId
String
required
The ID of the payment request to cancel.
callback
KlarnaPaymentRequestCallback
required
The callback to get notified of the result of payment request cancelation.