On-Site Messaging for React Native

Add On-Site Messaging and pre-qualification to a React Native app with Klarna's core and messaging packages.

5 min read

Add On-Site Messaging and pre-qualification to your React Native app

Show contextual Klarna payment messaging and let customers check their eligibility before completing a Payment Request.


Messaging on the homepage	Messaging on the product detail page	Messaging in the checkout

Prerequisites

Before you integrate On-Site Messaging, confirm that:

1.
You have Klarna enabled and access to the Klarna Partner Portal.
2.
In the Klarna Partner Portal, you have generated a client identifier with your domain URL allowlisted.
3.
Your app uses React Native 0.76 or later but earlier than 1.0, React 18.2 or later, and has the New Architecture enabled.
4.
Your app targets iOS 13 or later and Android API 21 or later.
5.
You have an appReturnUrl value for the required core SDK configuration. On iOS, register its scheme as a URL type in your app.

Integration overview

To add On-Site Messaging to your React Native app:

1.
Install the Klarna core and messaging packages.
2.
Initialize the Klarna SDK.
3.
Render a KlarnaMessagingPlacementView.
4.
Handle return URLs on iOS when a placement launches an external flow.

sequenceDiagram participant C as Customer participant P as Partner participant K as Klarna participant AP as Acquiring Partner P->>K: Initialize Klarna SDK P->>K: Get On-site messaging placement K->>P: Return messaging or pre-qualification content P->>C: Display messaging or pre-qualification content alt Pre-qualification approved C->>K: Start pre-qualification C->>K: Complete pre-qualification K->>P: Return updated messaging P->>C: Display updated placement alt Partner builds the checkout P->>K: Continue with preserved pre-qualification state else Acquiring Partner authorizes the payment P->>K: Fetch interoperability token P->>AP: Share interoperability token end end

Install packages

Install matching versions of the core and messaging packages. The current version of both packages is 2.8.2:

BASH

1 2

yarn add @klarna/react-native-klarna-network-core@2.8.2
yarn add @klarna/react-native-klarna-network-messaging@2.8.2

Initialize the SDK

Call Klarna.initialize once at app startup before rendering a placement. It returns the Klarna instance that you pass to the placement view.

TSX

1 2 3 4 5 6 7 8

import { Klarna } from '@klarna/react-native-klarna-network-core';

const klarna = await Klarna.initialize({
  clientId: 'your-client-id',
  appReturnUrl: 'your-app://return',
  accountId: 'account-id',
  locale: 'en-US',
});

The accountId and locale values are optional.

Handle return URLs

Klarna.handleReturnUrl is available only on iOS. Register the scheme from appReturnUrl as a URL type in your iOS app, then pass incoming app URLs to the SDK:

TSX

const handled = await Klarna.handleReturnUrl(url);

Don't call Klarna.handleReturnUrl on Android.

Render a messaging placement

Import the placement view and its configuration values from the messaging package. Pass the Klarna instance returned by Klarna.initialize.

TSX

1 2 3 4 5 6 7 8 9 10

import {
  KlarnaMessagingPlacementView,
  KlarnaMessagingPlacementType,
  KlarnaTheme,
} from '@klarna/react-native-klarna-network-messaging';
import type { Klarna } from '@klarna/react-native-klarna-network-core';

export function CheckoutMessaging({ klarna }: { klarna: Klarna }) {
  return (
    <KlarnaMessagingPlacementView

The placement uses a 60px minimum height until the first resize from the underlying view, then follows its content height. It collapses when no content is available or an error occurs.

Parameters

`KlarnaConfiguration`

Name	Type	Presence	Description
`clientId`	`string`	Required	The client identifier from the Klarna Partner Portal. If the integration is done by a PSP/distribution Partner, use the distribution Partner's own client ID.
`appReturnUrl`	`string`	Required	Core SDK configuration value. The Android bridge ignores this value. On iOS, register its scheme and handle incoming URLs when a placement launches an external flow.
`accountId`	`string`	Optional	Identifier of the account the action is performed on behalf of.
`locale`	`string`	Optional	BCP 47 locale string, such as `en-US`. The system default is used when omitted.

Placement configuration

Name	Type	Presence	Description
`type`	`KlarnaMessagingPlacementType`	Required	Placement variant to render.
`amount`	`number`	Required	Amount in minor currency units.
`currency`	`string`	Required	Three-letter ISO 4217 currency code.
`theme`	`KlarnaTheme`	Optional	Color theme for the placement. When omitted, the SDK selects the default.

KlarnaMessagingPlacementView requires an instance and configuration. It also accepts an optional style prop and an optional onError callback. The callback receives a KlarnaMessagingError with name and message fields.

Placement types

Value	Description
`CreditPromotionAutoSize`	Credit promotion placement that sizes itself based on its content.
`CreditPromotionBadge`	Credit promotion placement rendered as a badge.

Themes

Value	Description
`Light`	Light style.
`Dark`	Dark style.
`Automatic`	Follows the system's user interface style.

Jump to section...