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 Klarna Icon 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.

Define account structure

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 Klarna Icon 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

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 Klarna Icon 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.

Onboard

POST:/v2/distribution/onboard

Show recommended

Parameter	Required	Description
`partner_account_reference`	Yes	Provide a unique string reference for the Partner account to identify it within the integrator system without relying on Klarna-generated IDs. This reference is used to associate requests with the correct Partner account. Ensure the referen... Show more
`partner_account_name`	Yes	A human-readable name that represents the current partner, such as the company conglomerate name, a brand, or similar. Not used for customer interactions.
`partner_account_contact`	Yes	Provide the key contact details for the Partner account. The server validates that this field contains a non-empty, valid object representing the contact. Ensure the object includes the required contact attributes.
`-email`	Yes	E-mail address. Regex ^(?=.{1,64}@.{1,255}$)(?:[a-zA-Z0-9!#$%&'+/=?^_`{\|}~\p{IsLatin}\p{N}\p{S}-&&[^<>]]+(?:\.[a-zA-Z0-9!#$%&'+/=?^_`{\|}~\p{IsLatin}\p{N}\p{S}-&&[^<>]]+)*\|"(?:[\x01-\x08\x0B\x0C\x0E-\x1F\x21\x23-\x5B\x5D-\x7F]\|\[\x01-\x09... Show more
`partner_business_entities`	Yes	Provide details about the business entities associated with the Partner account, including legal entity information. This information is used to verify and manage the Partner’s legal identity and compliance status. Ensure the value is a non... Show more
`-partner_business_entity_reference`	Yes	Provide a unique reference used by the integrator to identify a specific Partner entity within their system. This reference is used to associate requests with the correct Partner entity.
`-legal_registered_entity_name`	Yes	Provide the official registered name of the Partner’s legal entity to identify the organization in legal and compliance contexts. The server stores this name as part of the Partner’s legal entity data. Ensure the value is a non-empty string... Show more
`-legal_registration_country`	Yes	Provide the two-letter country code in ISO 3166‑1 alpha‑2 format for the indicated address. The system accepts only predefined country codes such as US, DE, SE, and AU. Treat the country code as an opaque string, do not parse or interpret i... Show more
`products`	Yes	Information about which products are being configured for this merchant
`-type`	Yes	The type of product available to the merchant or partner. Values: PAYMENT: Klarna's payment services
`-payment_profile_id`	Yes	The payment profile identifier. Previously known as Distribution Profile ID
`-payment_accounts`	Yes	List of Payment Accounts. Payment accounts connect a set of configuration data points to an integrator-defined reference that can be used to operate Klarna's payment products.
`--payment_account_reference`	Yes	A unique string reference for the payment account, used by the partner to identify the payment account without relying on Klarna-generated IDs.
`--payment_acquiring_account_id`	Yes	Unique account identifier assigned by Klarna to the Acquiring Account.
`--default_merchant_category_code`	Yes	The Merchant Category Code (MCC) is a four-digit number that is used to classify the type of goods or services offered by a business. [Read more here]( https://docs.klarna.com/klarna-network-distribution/manage-partners/onboard-and-manage-p... Show more

Showing 15 of 27

Here you can find all required parameters for this operation onboard

Example request

JSON

{
  "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": [
    {
      "partner_business_entity_reference": "LE_US002",

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

{
  "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.

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

Creating new resources on an existing Partner Account

The onboard Klarna Icon operation can be used to create new resources on an existing Partner Account. When you call onboard 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

Call onboard with an existing partner_account_reference.
Klarna identifies the existing Partner Account instead of creating a new one.
Any new resources in the payload (with references that don't exist) are created and added to the Partner Account.
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.
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

{
  "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",
          "type": "WEBSITE",
          "url": "https://eu.example.com"

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 Klarna Icon request.