Model your Partner Accounts

Model Partner Accounts so they reflect how a Partner’s business is structured, including legal entities, MCCs, brands, and stores. Correct modeling simplifies onboarding, supports accurate settlement, and keeps integrations easier to maintain over time.

Accurate Partner Account modeling ensures a smooth onboarding experience, simplifies account management, and supports flexible integration patterns — from small retailers to complex multi-entity organizations.

This article explains how to structure Partner Accounts within Klarna’s ecosystem and how to align them with a Partner’s business structure and internal systems.

Overview

flowchart LR subgraph Partner direction TB PA(Partner Account) PAY_PRO(Payment Product) PA_BRANDS_STORES(Brands & Stores) PA_PBE(Partner Business Entity) PA_PORTAL(Portal Users) AP(Access Policy) PA -->|1| PAY_PRO PA -->|1..n| PA_PBE PA -->|1..n| PA_BRANDS_STORES PA -->|1..n| PA_PORTAL PA -->|0..n| AP PA -->|0..n| PAR(Partner Account Relationships) AP -.->|0..n| PA_PORTAL end subgraph Acquirer direction TB PA_AP(Partner Account) ACQ_PRO(Payment Acquiring Product) PA_AP_API_KEY(API Keys) PA_AP_WEBHOOK_CONFIG(Webhook Configuration) PA_AP -->|1| ACQ_PRO PA_AP -->|1..n|PA_AP_API_KEY PA_AP -->|1..n|PA_AP_WEBHOOK_CONFIG end Acquirer -->|onboards| Partner class PA primaryEntity class PA_AP primaryEntity

A Partner Account represents a Partner company in Klarna. Under a single Partner Account, you can configure:

Partners should use a single Partner Account per company and model complexity with Payment Accounts, Partner Business Entities, and Stores. This article shows modeling patterns for common business structures and provides sample onboard API

requests for each.

For more details about Klarna's account structure, see here.

Key terminology

Before modeling your Partner Accounts, it's essential to understand How Partner Accounts Work and become familiarized with some key terminology:

Term	Definition
Partner Account	Represents a Partner company that uses Klarna’s offering. In this context, it represents your own Partners.
Partner Account contact	Information about the main representative of the Partner for Klarna. Klarna uses these details if we need to reach out to the Partner directly.
Partner Business Entity	Represents a legal entity related to the Partner, including information Klarna needs for compliance, fraud prevention, and settlement.
Payment Product	Represents the Partner Account’s ability to use Klarna’s payment offering, including pricing and configuration.
Payment Account	Connects attributes such as the Partner Business Entity, the Payment Acquiring Account(s) configured for the Acquiring Partner, and the default Merchant Category Code for that Partner Business Entity. For each legal entity used by the Acquiring Partner to distribute Klarna as a payment method to their Partners, Klarna configures a unique Payment Acquiring Account*. Each Payment Acquiring Account contains the settlement configuration Klarna uses to pay out the Acquiring Partner.
Stores & Branding	Represents websites, mobile apps, or physical stores where Klarna products are available, as well as the related branding data.
MCC (Merchant Category Code)	Defines the type of goods or services sold by the Partner.
Access Policy	Controls which resources (Payment Accounts, Store Groups, Brands) a Portal User, API Credential, or Klarna webhook can access within a Partner Account. Use `SCOPED` policies to restrict groups of Portal Users to specific subsets of the account's resources.
Partner Account Relationship	Describes structural or organizational connections between Partner Accounts that aren't expressed through products.

Modeling patterns by business scenario

The following examples show how to combine Partner Accounts, Payment Products, Payment Accounts, Partner Business Entities, and stores to match different business structures.

RetailUse this model when the Partner has:

One legal entity
One MCC
One website or store
Unified settlement configuration

flowchart TB subgraph ACC[Partner Account: CoolBrand] CON[Contact: Julia] end subgraph PBE[Partner Business Entity] LE[Legal Entity: CoolBrand s.r.l] ST[Stakeholder: Julia] BA[Bank Account: Julia's BA] end subgraph SG[Store Group] S1[Store: coolbrand.com] end PROD[Payment Product] PA[Payment Account CB003-1] ACC --> PROD PROD --> PA PA --> PBE PA --> SG

Example 1: Retail SME company

A small clothing brand, CoolBrand, operates one online store in Italy. The setup includes one Partner Account, one Payment Product, and one store. Their online shop URL is Coolbrand.com, and the company is owned by a single owner, Julia Doe. The store operates under MCC 5691.

This store receives all their payouts from their Acquiring partner in a single bank account. They operate under the same address to which they are registered in Milan.

This is an example of a basic Partner Account set up. It’s a single account, with a single Payment Product, and a single store.

Sample request

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M123786123412",
  "partner_account_name": "CoolBrand",
  "partner_account_contact": {
    "given_name": "Julia",
    "family_name": "Doe",
    "email": "julia.doe@CoolBrand.com",
    "phone": "+15555555555"
  },
  "products": [

Multiple Legal Entities

Larger enterprises often manage several legal entities under a single Partner Account. Use this when you have multiple legal entities for the same partner.

Example 2: Multi-brand enterprise

flowchart TD ACCT --> PRO ACCT --> AP1 ACCT --> AP2 PA1 --> PBE1 PA1 -->|default| SG1 PA2 --> PBE2 PA2 -->|default| SG2 AP1 -.-> PA1 AP1 -.-> SG1 AP2 -.-> PA2 AP2 -.-> SG2 %% Account subgraph ACCT[Partner Account] CON[Contact: Jan] end PRO[Payment Product] PRO --> PA1 PRO --> PA2 PA1[Payment Account: M33341] PA2[Payment Account: M33342] %% Access Policies AP1[Access Policy: AP-SUPERAUTO] AP2[Access Policy: AP-AUTOSTART] %% Partner Business Entities subgraph PBE1[Partner Business Entity #1] LE1[Legal Entity: Super Auto] ST1[Stakeholder: Hans] BA1[Bank account: Super Auto's BA] end subgraph PBE2[Partner Business Entity #2] LE2[Legal Entity: Auto Start] ST2[Stakeholder: Giulia] BA2[Bank account: Auto Start BA] end %% Store Groups subgraph SG1[Store Group #1] S1[Store: SuperAuto.de] end subgraph SG2[Store Group #2] S2[Store: AutoStart.it] end

AutoMakers operates multiple brands, each with its own legal entity and website. Klarna configures one Payment Account per legal entity, allowing transactions to be attributed correctly at payment time.

In this case, both legal entities have to be created at Klarna, and two different Payment Accounts have to be onboarded connected to the different Partner Business Entities. These Payment Accounts are later utilized on the Payments API, and allow us to differentiate which legal entity is taking the purchase.

Given pricing is the same across the different legal entities, one Payment Product contains both Payment Accounts.

Because both brands share a single Partner Account, Access Policies control which Portal Users can manage each brand. In this example, the Acquiring Partner creates two SCOPED policies during onboarding:

AP-SUPERAUTO — contains rules granting access to Payment Account M33341 and Store Group SUPERAUTO. Portal Users assigned to this policy only see and manage Super Auto resources in the portal.
AP-AUTOSTART — contains rules granting access to Payment Account M33342 and Store Group AUTOSTART, scoping a separate group of Portal Users to Auto Start resources.

This keeps both brands under one account while ensuring each team only manages their own brand.

Sample request

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "E494442",
  "partner_account_name": "AutoMakers",
  "partner_account_contact": {
    "given_name": "Jan",
    "family_name": "Doe",
    "email": "jan.doe@automakers.de",
    "phone": "+15555555555"
  },
  "products": [

Multiple Merchant Category Codes

Payment Accounts can also be used to support multiple Merchant Category Codes (MCCs) under the same Partner Account. The configuration attached to the payment accounts can be the same, but they may have different default_merchant_category_code s and must have different references.

Example 3: Multi MCC company

flowchart TD ACCT --> PRO PA1 --> PBE1 PA1 -->|default| SG1 PA2 --> PBE1 PA2 -->|default| SG1 %% Account subgraph ACCT[Partner Account] CON[Contact: Mathias] end PRO[Payment Product] PRO --> PA1 PRO --> PA2 PA1[Payment Account: A4421-1 MCC: 5691] PA2[Payment Account: A4421-2 MCC: 5641] %% Partner Business Entity subgraph PBE1[Partner Business Entity] LE1[Legal Entity: AstroxSox GmbH.] ST1[Stakeholders: Mathias & Debora] BA1[Bank account: AstroxSox BA] end %% Store Group subgraph SG1[Store Group] S1[Store: astroxsox.de] end

Consider a Partner called “AstroxSox”. This business sells new socks to its customers, but also provides a subscription service so their customers never run out of socks. This means that AstroxSox operates both under MCC 5691, but also 5641.

AstroxSox is owned by Mathias and his sister, Debora, and operates under a single website, astroxsox.de.

Sample request

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M12378999999",
  "partner_account_name": "AstroSox",
  "partner_account_contact": {
    "given_name": "Mathias",
    "family_name": "Doe",
    "email": "Mathias@AstroSox.de",
    "phone": "+49555555555"
  },
  "products": [

Multiple stores (websites, physical stores, etc)

Partners operating across several physical or digital locations can group them under a single Partner Account.

Example 4: Multi physical store company

A French bakery, called “Ivette Croissanterie”, operates two physical stores and one website under the same MCC.

The pastry shop is owned by Ivette, and the physical stores are located in Marseille, France. Ivette also sells pastries through an on-line store.

The Partner Account is therefore configured with a payment product with the MCC 5462, with three stores. Two physical stores, and one website.

When initiating a payment request, the specific store where the purchase is being made needs to be passed to the Partner Payments API.

flowchart TD ACCT --> PRO PA1 --> PBE1 PA1 -->|default| SG1 %% Account subgraph ACCT[Partner Account] CON[Contact: Ivette] end PRO[Payment Product] PRO --> PA1 PA1[Payment Account: I59923 MCC: 5462] %% Partner Business Entity subgraph PBE1[Partner Business Entity] LE1[Legal Entity: Ivette Croissants SARL] ST1[Stakeholder: Ivette] BA1[Bank account: Ivette Croissants BA] end %% Store Group subgraph SG1[Store Group] S1[Store: IvetteCroissanterie.fr] S2[Store: Joliette] S3[Store: Port] end

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "994323",
  "partner_account_name": "Ivette Croissanterie",
  "partner_account_contact": {
    "given_name": "Ivette",
    "family_name": "Doe",
    "email": "Ivette@IvetteCroissanterie.fr",
    "phone": "+49555555555"
  },
  "products": [

Franchising

Franchise networks can be modeled according to how they are structured and managed in your systems

Multiple Payment Accounts: When all franchisees have their own identifier towards you and your system but you have an overarching entity to group them, you can manage them separately by having individual Payment Accounts. They still share the same Partner Accounts
Multiple Stores: When all franchisees share the same identifier but are represented as different physical addresses on your systems, you can use one Partner Account with one Payment Account and multiple stores. The stores can be passed on the Payments API integrations
Multiple Partner Accounts: When each franchisee has their own account with you and doesn't share any data, create separate Partner Accounts to manage each company individually. To capture that these Partner Accounts belong to the same franchise network, use Partner Account Relationships with the ORGANIZATION_MEMBER type to link them under a shared organization Partner Account.

The shape the Klarna account structure takes should be reflective of the structure of the business.

Example 5: Franchise

Consider a burger chain called William’s Top Burger. William’s operates under a franchise model, where currently they have three franchisees, owned by Maja (store 1), Liam (store 2) and Vera. Out of the three, Vera was able to run a really successful business and now owns four different burger locations, stores 3, 4, 5 and 6.

In this case, if the franchises are managed as separate accounts on your side and settlements are received separately from the Acquiring Partner, they can be modeled using a combination of the Retail and the Multi Store examples, as below:

In the Partner Product API, the specific Payment Account and Store identifiers must be sent as part of the payload so Klarna can properly identify from which specific store the payment request originates.

Applied to our example, Maja, Liam, and Vera would each have a separate Partner Account. Maja and Liam would have a single store each, and Vera would have four stores, one for each of her physical stores. By passing the correct identifiers in the request, Klarna can present to the customer different store details and an experience personalized to the originating store.

flowchart TD %% Relationships ACCT1 --> PRO1 ACCT2 --> PRO2 ACCT3 --> PRO3 PA1 --> PBE1 PA1 -->|default| SG1 PA2 --> PBE2 PA2 -->|default| SG2 PA3 --> PBE3 PA3 -->|default| SG3 %% Partner Account – Maja subgraph ACCT1[Partner Account] CON1[Contact: Maja] end PRO1[Payment Product] PRO1 --> PA1 PA1[Payment Account: MW2351 MCC: 5812] %% Partner Business Entity – Maja subgraph PBE1[Partner Business Entity] LE1[Legal Entity: Maja WTB] ST1[Stakeholder: Maja] BA1[Bank account: Maja WTB BA] end %% Store Group – Maja subgraph SG1[Store Group] S1[Store: wtb_maja] end %% Partner Account – Liam subgraph ACCT2[Partner Account] CON2[Contact: Liam] end PRO2[Payment Product] PRO2 --> PA2 PA2[Payment Account: MW2352 MCC: 5812] %% Partner Business Entity – Liam subgraph PBE2[Partner Business Entity] LE2[Legal Entity: Liam WTB] ST2[Stakeholder: Liam] BA2[Bank account: Liam WTB BA] end %% Store Group – Liam subgraph SG2[Store Group] S2[Store: wtb_liam] end %% Partner Account – Vera subgraph ACCT3[Partner Account] CON3[Contact: Vera] end PRO3[Payment Product] PRO3 --> PA3 PA3[Payment Account: MW2353 MCC: 5812] %% Partner Business Entity – Vera subgraph PBE3[Partner Business Entity] LE3[Legal Entity: Vera WTB] ST3[Stakeholder: Vera] BA3[Bank account: Vera WTB BA] end %% Store Group – Vera (4 stores) subgraph SG3[Store Group] S3[Store: wtb_vera_3] S4[Store: wtb_vera_4] S5[Store: wtb_vera_5] S6[Store: wtb_vera_6] end

To onboard, we would need three onboard API

calls.

First sample request: One Store

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M123789922222",
  "partner_account_name": "Maja WTB",
  "partner_account_contact": {
    "given_name": "Maja",
    "family_name": "Doe",
    "email": "maja.franchisee@wtb.se",
    "phone": "+49555555555"
  },
  "products": [

Second sample request: One Store

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M123789922223",
  "partner_account_name": "Liam WTB",
  "partner_account_contact": {
    "given_name": "Liam",
    "family_name": "Doe",
    "email": "liam.franchisee@wtb.se",
    "phone": "+49555555555"
  },
  "products": [

Third sample request: Four Stores

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "M123789922224",
  "partner_account_name": "Vera WTB",
  "partner_account_contact": {
    "given_name": "Vera",
    "family_name": "Doe",
    "email": "vera.franchisee@wtb.se",
    "phone": "+49555555555"
  },
  "products": [

Organizational and platform relationships

When Partner Accounts are related to each other — for example, as members of the same corporate group or as Partners on a platform — use Partner Account Relationships to capture those connections. These relationships are informational and don't affect product configuration or access.

Partner Account Relationships can be created during onboarding or added afterwards with createPartnerAccountRelationship API

. For details on the available relationship types, resource properties, and lifecycle, see Partner Account Relationships.

The following diagrams illustrate the three relationship types:

Corporate hierarchy — Use ORGANIZATION_MEMBER when multiple Partner Accounts belong to the same corporate group:

flowchart LR subgraph Organization direction TB ORG(Partner Account: HQ) M1(Partner Account: Region A) M2(Partner Account: Region B) end M1 -->|ORGANIZATION_MEMBER| ORG M2 -->|ORGANIZATION_MEMBER| ORG class ORG primaryEntity

Managed platform — Use MANAGED_PLATFORM_MEMBER when a platform fully manages its Partners' accounts through the Acquiring Partner:

flowchart LR subgraph Platform direction TB PLAT(Partner Account: Platform) P1(Partner Account: Partner A) P2(Partner Account: Partner B) end P1 -->|MANAGED_PLATFORM_MEMBER| PLAT P2 -->|MANAGED_PLATFORM_MEMBER| PLAT class PLAT primaryEntity

Aggregating platform — Use AGGREGATING_PLATFORM_MEMBER when Partners operate independently but also route some payments through the platform:

flowchart LR subgraph Aggregator direction TB AGG(Partner Account: Aggregator) A1(Partner Account: Partner X) A2(Partner Account: Partner Y) end A1 -->|AGGREGATING_PLATFORM_MEMBER| AGG A2 -->|AGGREGATING_PLATFORM_MEMBER| AGG class AGG primaryEntity

Example 6: Organization with regional subsidiaries

Consider a company called GlobalTech with two regional subsidiaries: GlobalTech US and GlobalTech EU. Each subsidiary has its own Partner Account, legal entity, and settlement configuration. The parent company also has a Partner Account to represent the organization.

If the organization Partner Account doesn't exist yet, create it with createPartnerAccount API

Sample request: create the organization Partner Account

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "GT-HQ",
  "partner_account_name": "GlobalTech",
  "partner_account_contact": {
    "given_name": "John",
    "family_name": "Smith",
    "email": "john@globaltech.com",
    "phone": "+15550000000"
  }
}

Then onboard each subsidiary and include the relationship in the onboarding request so it's established from the start.

Sample request: onboard a subsidiary with an organization relationship

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "GT-US-001",
  "partner_account_name": "GlobalTech US",
  "partner_account_contact": {
    "given_name": "Sarah",
    "family_name": "Doe",
    "email": "sarah@globaltech-us.com",
    "phone": "+15555555555"
  },
  "products": [

Repeat the onboarding call for each additional subsidiary, linking them to the same organization Partner Account.

Example 7: Managed e-commerce platform

Consider an e-commerce platform called ShopEasy that fully manages payments for its Partners. ShopEasy activates and configures each Partner's account through the Acquiring Partner — the Partners themselves don't interact with the Acquiring Partner directly.

If the platform Partner Account doesn't exist yet, create it with createPartnerAccount API

. Sample request: create the platform Partner Account

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "SHOPEASY-PLATFORM",
  "partner_account_name": "ShopEasy",
  "partner_account_contact": {
    "given_name": "Alex",
    "family_name": "Chen",
    "email": "alex@shopeasy.com",
    "phone": "+15559876543"
  }
}

Then onboard each Partner and include a MANAGED_PLATFORM_MEMBER relationship in the onboarding request.

Sample request: onboard a Partner managed by a platform

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "SE-PARTNER-001",
  "partner_account_name": "Bella's Boutique",
  "partner_account_contact": {
    "given_name": "Bella",
    "family_name": "Martin",
    "email": "bella@bellasboutique.com",
    "phone": "+15551234567"
  },
  "products": [

Example 8: Aggregating platform

Consider a marketplace called OpenMarket that routes payments for its Partners but doesn't exclusively manage them. Partners on OpenMarket may also process payments directly with the Acquiring Partner or through other platforms.

If the platform Partner Account doesn't exist yet, create it with createPartnerAccount API

. Sample request: create the platform Partner Account

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "OPENMARKET-PLATFORM",
  "partner_account_name": "OpenMarket",
  "partner_account_contact": {
    "given_name": "Lisa",
    "family_name": "Andersson",
    "email": "lisa@openmarket.se",
    "phone": "+46709876543"
  }
}

Then onboard each Partner with an AGGREGATING_PLATFORM_MEMBER relationship.

Sample request: onboard a Partner on an aggregating platform

JSON

1 2 3 4 5 6 7 8 9 10

{
  "partner_account_reference": "OM-PARTNER-042",
  "partner_account_name": "Nordic Crafts",
  "partner_account_contact": {
    "given_name": "Erik",
    "family_name": "Lindgren",
    "email": "erik@nordiccrafts.se",
    "phone": "+46701234567"
  },
  "products": [

Partner Accounts

Payment Accounts

Partner Business Entities

Partner Stores and Brands

How Partner Accounts work

API & SDK references

Onboard a merchant