Partner Accounts

The Partner Account is the primary resource for interacting with Klarna’s APIs. It serves as the root entry point for all API operations and contains all metadata and configuration details that represent a company within the Klarna ecosystem.

A Partner Account represents a company that interacts with Klarna. It serves as the entry point to all Klarna APIs and holds essential company-level data. Regardless of how many legal entities, websites, or brands a company has, only one Partner Account is required to collaborate with Klarna.

A Partner Account does not have a specific type. Its relationship with Klarna is defined through the products it connects to:

An Acquirer, has a Partner Account with a Payment Acquiring Product, representing an Acquiring Partner.
A Partner has a Partner Account with a Payment Product, for example representing a merchant.

Partner Accounts also connect to multiple foundational resources, including API Credentials, Portal Users and Webhook configurations.

When multiple Partner Accounts belong to the same corporate group or platform, they can be linked together through Partner Account Relationships — for example, regional subsidiaries of the same company, or Partners onboarded by an e-commerce platform.

Relationships & Dependencies

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 User / Access) PAR(Partner Account Relationships) PA -->|1| PAY_PRO PA -->|1..n| PA_PBE PA -->|1..n| PA_BRANDS_STORES PA -->|1..n| PA_PORTAL PA -->|0..n| PAR 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 forms the foundation of a Partner’s relationship with Klarna. It contains the following dependent resources:

Partner Account Contact: The primary individual representing the Partner company in communications with Klarna.
Partner Products: Define the specific Klarna services accessible through the account, such as Payment Products or Payment Acquiring Products.
Partner Business Entities: Represent the legal entities associated with the company.
Partner Stores and Brands: Represent the online or physical retail channels tied to the account.
Partner Account Relationships: Links to other Partner Accounts that capture organizational or platform connections — for example, regional subsidiaries or Partners onboarded by an e-commerce platform.

These relationships determine how a Partner Account functions within Klarna’s ecosystem.

Resource Properties

Lifecycle

The Partner Account lifecycle is defined as:

Status	Definition
`PARTIALLY_OPERATIONAL`	Represents an account that was just onboarded and is currently being set up in our systems. If this account has a payment product, it can already process transactions, but can not yet be managed. This state is transitional, and typically moves to `OPERATIONAL` within seconds
`OPERATIONAL`	Represents an account that is fully operational and can both be managed and process transactions
`DISABLED`	Represents an account that is no longer operational in any respect. It cannot be managed or have new products added. All products within the account are disabled as part of this status.

Status transitions are handled internally by Klarna systems. Manual transitions to DISABLED are performed by Klarna Support and cannot be triggered via API.

Webhooks

Event name	When	Use cases
`partner.account.state-change.operational`	An account is fully set up on Klarna’s side	Should be used to know when it's possible to update Partner Accounts.

Only status transitions to OPERATIONAL will trigger webhooks to be dispatched. Status transitions to DISABLED are done manually and do not currently trigger any webhook.

The following example reflects the payload structure for partner.account.state-change.operational:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "metadata": {
    "event_id": "99bf6248-b3ed-42d9-b2b5-bf560668d42a",
    "event_type": "partner.account.state-change.operational",
    "event_version": "v1",
    "occurred_at": "2025-03-04T13:31:14.603057514Z",
    "account_id": "krn:partner:global:account:test:M48JTZF8",
    "recipient_account_id": "krn:partner:global:account:test:M48JTZF8",
    "subject_account_id": "krn:partner:global:account:test:M7UJ6WZ2",
    "webhook_id": "krn:partner:global:notification:webhook:8e3e2120-04fd-4975-88fa-fd26299c4280",

This payload differs slightly from general webhook events because it does not include a product_id, as the event applies to the entire account.

Frequent Use Cases

Create a Partner Account

Use the onboard API

operation to create a Partner Account together with products, brands, and other resources. Learn more about how to execute the onboard operation.

To create a Partner Account without products or other resources, use createPartnerAccount API

. This is necessary for accounts that represent an organizational entity — such as a corporate headquarters — that other Partner Accounts relate to through Partner Account Relationships.