Prepare the onboarding payload

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

61 min read

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.

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

Integration requirement

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.

Integration requirement

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.

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.

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 and TPA model) will be introduced in a later release, so the onboard API

payload doesn't yet expose fields to declare TPAs.

Coming soon

Klarna is delivering the nested Partner and 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 need to add new Brands, Store Groups, Stores, Payment Accounts, or Partner Business Entities to an existing Partner Account.
A Partner expands to new markets or adds new store locations.

Integration requirement

Include these fields on every onboard API

request. Klarna checks a follow-up that adds a resource the same way as the first request:

partner_account_reference and partner_account_name
partner_account_contact, including email
partner_business_entities
brands
store_groups
products, with at least one Payment Account

Repeat the resources Klarna already stores, using the same field values, and add the new resource in that same payload. A request that sends only the new resource returns HTTP 400 with VALIDATION_ERROR, for example when brands is empty or products is missing. If you send an existing reference with different field values, the request fails with HTTP 409.

How it works

1.
Call onboard with the existing partner_account_reference and the full Partner Account payload.
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 in the payload (with references that already exist) must match what Klarna has stored. If a field differs, the request fails with HTTP 409.
5.
Send the stored resources again on every call, together with the new resource.

Important considerations

Send the full payload: partner_account_contact, partner_business_entities, brands, store_groups, and products are required on every call, together with partner_account_reference and partner_account_name.
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 HTTP 409.
Immutable fields still cannot be changed: Data points listed in the Data immutability section cannot be modified by calling onboard again.

Incremental onboarding example

The following example adds a new Store Group and Store to an existing Partner Account. The payload repeats the stored Partner Account and adds the new Store Group.

Scenario: The Partner Account with reference M123786123412 already exists, including Store Group STORE_NY004. You want to add Store Group STORE_EU005 for another market.

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@example.com",
    "phone": "+15555550100"
  },
  "partner_business_entities": [

In this example:

The partner_account_reference matches an existing Partner Account.
The payload repeats partner_account_contact, the stored Partner Business Entity, Brand, Payment Product, and Store Group STORE_NY004.
Store Group STORE_EU005 is new and is sent together with the stored Store Group.
The brand_reference (d7e26b06-8fe0-4702-91fb-9d4a65068dec) already exists. The Brand in the payload uses the same field values Klarna has stored.
If that Brand were sent with a different display_name, the request would fail with HTTP 409.

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.