Prepare the onboarding payload

Use onboard operation to streamline Partner onboarding, ensuring accurate data submission, compliance, and seamless access to Klarna Payment Services.

Overview

The onboard payload is the request body you send when you call the onboard API

request in the Klarna's API. It creates the Partner Account and related structures (Partner Business Entities, Payment Products and Payment Accounts, Brands, Store Groups, and Stores) that Klarna needs to process payments on behalf of the Partner.

This article explains how to:

Align your account structure with Klarna’s model.
Map your internal data to the onboard request payload.
Decide which fields are required, recommended, or optional.
Store the identifiers returned by Klarna for later API integrations.
Understand which data fields become immutable after onboarding.
Use the onboard operation to create new resources on an existing Partner Account.

Before you build the onboarding payload, define the Partner’s account structure in your own system and align it with Klarna’s model. Once the account structure is defined, you should map all data points collected by your system to Klarna’s onboard API

payload.

Before you build the onboarding payload, define the Partner’s account structure in your own system and align it with Klarna’s model. Follow Modeling your Partner Account to decide how to represent:

Partner Account
Partner Business Entities (legal entities)
Payment Products and Payment Accounts
Brands, Store groups and Stores
Partner Account Relationships when the new Partner Account belongs to a corporate group or platform represented by another Partner Account

Once this model is clear, you can map each data point in your system to Klarna’s onboarding payload.

Map data points to the onboard payload

After the structure is defined, map all Partner data points from your system to the onboard API

payload.

Each property in the payload falls into one of three categories:

Required: Must be provided for the onboarding to succeed.
Recommended: Improves Klarna’s risk assessment and may be required based on your agreement with Klarna.
Optional: Used for additional configuration or display.

It is essential for you to provide all relevant and available Partner information as specified in the data transfer and cooperation agreement with Klarna.

Always include available company registration data in supplementary_business_data.legal_registration, including:

Registration number
Registration authority
Entity type
Tax identifiers
Registration address

The stakeholders object in supplementary_business_data should always be provided. For Partners without formal registration information, such as sole traders, stakeholders is especially important as it serves as the primary identification data when legal_registration fields are not available.

Read Legal Registration Number for detailed instructions to be compliant with Klarna Network Rules.

Whenever the new Partner Account belongs to a corporate group or platform that is also represented by an existing Partner Account, register the connection during onboarding by including the partner_account_relationships array in the payload. Klarna requires Acquiring Partners to keep these connections registered so monitoring and changes can be applied consistently across related accounts.

Read Partner Account Relationships for the available relationship types and lifecycle.

Example request

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M123786123412",
  "partner_account_name": "John Doe Stakehouse",
  "partner_account_contact": {
    "given_name": "John",
    "family_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+18445527621"
  },
  "partner_business_entities": [

The example provided here is for illustrative purposes only. The parameters required for onboarding may vary based on your commercial agreement and the parameters available to you.

Sample response

JSON

1 2 3 4 5 6 7 8

{
  "partner_account_id": "krn:partner:global:account:test:MABCDEFG",
  "partner_account_reference": "M123786123412",
  "partner_account_name": "John Doe Stakehouse",
  "state": "PARTIALLY_OPERATIONAL",
  "state_reason": "INITIAL_SETUP"
}

When Klarna successfully completes onboarding, Klarna creates the Partner Account and returns a partner_account_id in the response. Store this identifier so you can use it in later API integrations, including the Payments API.

After a successful onboarding run, the Partner Account will be in the PARTIALLY_OPERATIONAL state and is ready to process payments in all markets where Klarna is enabled for that Partner. Some setup steps still continue in Klarna systems in the background. For more detail about state changes after onboarding, see the Partner Account lifecycle.

Acquiring Partners that operate through third-party agents (TPAs) must share TPA information with Klarna, as required by Klarna Network Rules. The supporting API — the nested Partner / TPA model — will be introduced in a later release, so the onboard API

payload doesn't yet expose fields to declare TPAs.

Klarna is delivering the nested Partner / TPA model in a later release. Until then, this onboarding flow does not yet support Partners operating in a nested structure under a Third Party Agent.

This documentation will be updated when the model ships, including the payload extensions and any migration steps.

Store identifiers for later use

Several identifiers in the onboarding payload and response are required in later integrations. Storing these identifiers at onboarding time is essential to integrate the Payments API and other Klarna APIs consistently.

partner_account_id: Returned by Klarna in the onboard response. Required when you integrate the Payments API and other APIs that act on the Partner Account.
payment_acquiring_account_id and payment_account_reference : Sent in the onboard payload. Use this combination later when the Partner has multiple payment accounts under the same Partner Account and you need to route payments correctly. Other references, such as for Stores, Store Groups and similar, may also be relevant later on when integrating with other APIs, which emphasize the importance of setting the correct identifiers during onboarding. If you later need to recover a Klarna *_id from a stored reference, see Resolve identifiers.

Creating new resources on an existing Partner Account

The onboard API

operation can be used to create new resources on an existing Partner Account. When you call onboard API

with an existing partner_account_reference, Klarna identifies the existing Partner Account and adds any new resources included in the payload.

This capability is useful when:

You want to onboard a Partner with minimal initial data and add more details later.
You need to add new Brands, Store Groups, Stores, Payment Accounts, or Partner Business Entities to an existing Partner Account.
Your Partner's information becomes available progressively during your onboarding workflow.
A Partner expands to new markets or adds new store locations.

How it works

1.
Call onboard with an existing partner_account_reference.
2.
Klarna identifies the existing Partner Account instead of creating a new one.
3.
Any new resources in the payload (with references that don't exist) are created and added to the Partner Account.
4.
Any existing resources (with references that already exist) must have an identical payload to what is stored in Klarna. If the payload differs, the request fails with a 409 Conflict error.
5.
Resources that are not included in the payload are left unchanged—you don't need to resend existing resources.

Important considerations

Existing resources must match exactly: For example, If you include an existing brand_reference, the display_name and all other fields must match what Klarna has stored. Any mismatch results in a 409 Conflict error.
Immutable fields still cannot be changed: Data points listed in the Data immutability section cannot be modified by calling onboard again.
Missing resources are ignored: You only need to send new resources you want to add. Existing resources that are not included in the payload remain unchanged.

Incremental onboarding example

The following example demonstrates how to add a new Store Group and Store to an existing Partner Account.

Scenario: The Partner Account with reference M123786123412 already exists. You want to add a new Store Group for a different market without resending all existing data.

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M123786123412",
  "partner_account_name": "John Doe Stakehouse",
  "store_groups": [
    {
      "store_group_reference": "STORE_EU005",
      "brand_reference": "d7e26b06-8fe0-4702-91fb-9d4a65068dec",
      "stores": [
        {
          "store_reference": "eu-store-001",

In this example:

The partner_account_reference matches an existing Partner Account.
Only the new Store Group (STORE_EU005) is included in the payload.
The brand_reference (d7e26b06-8fe0-4702-91fb-9d4a65068dec) already exists and is being referenced for the new Store Group.
Existing Store Groups, Brands, Business Entities, and Payment Accounts are not included—they remain unchanged.
If the Brand reference had different properties than what's stored (for example, a different display_name), the request would fail with a 409 Conflict.

Data immutability

Some data points become immutable after onboarding. You cannot change these fields by sending another onboarding payload or an update call, therefore is critical to ensure these values are correct before you send the onboard API

request.