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 Management 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.

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.

Map data points to the onboard payload

Once the structure is defined, map all data points from your system to the onboard Klarna Icon payload.

It is essential that you send all relevant and available Partner information as defined in your data transfer and cooperation agreement with Klarna. 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

Sample 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": [

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 as.

While the initial state received in the response may be "PARTIALLY_OPERATIONAL", the Partner Account is ready to process payments in all markets where Klarna is enabled for that Partner. This initial state means that some setup steps still continue in Klarna systems in the background. For more detail about state changes after onboarding, see Account Lifecycle Webhooks.

Store identifiers for later use

Several identifiers in the onboarding payload and response are required in later integrations. Storing these identifiers at onboarding time makes it easier 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

Data immutability

Some data points become immutable after onboarding, this means that you cannot change these fields by sending another onboarding payload, therefore is critical to ensure these values are correct before you send the onboard Klarna Icon request.

Payment Account

Linked Partner Business Entity
Linked Acquiring Account

Payment Product

Linked Payment Profile

Partner Legal Entity

Legal registration name
Registration country