Prepare the onboarding payload

The onboard payload is the request body you send when you call the onboard 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 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.

After the structure is defined, map all Partner data points from your system to the onboard 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.

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

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

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

The onboard 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.

1. 1.
   Call onboard with an existing partner_account_reference.
2. 2.
   Klarna identifies the existing Partner Account instead of creating a new one.
3. 3.
   Any new resources in the payload (with references that don't exist) are created and added to the Partner Account.
4. 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. 5.
   Resources that are not included in the payload are left unchanged—you don't need to resend existing resources.

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

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.

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

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

• Linked Partner Business Entity
• Linked Acquiring Account

• Linked Payment Profile

• Legal registration name
• Registration country