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 Acquiring Partner has a Partner Account with a Payment Acquiring Product.
- A Merchant Partner has a Partner Account with a Payment Product.
Partner Accounts also connect to multiple foundational resources, including API Credentials, Portal Users and Webhook configurations.
A Partner Account forms the foundation of a Partner's relationship with Klarna. It contains the following dependent resources:
- Partner Account Contact: The 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.
These relationships determine how a Partner Account functions within Klarna's ecosystem.
/v2/accounts/{partner_account_id}| Parameter | Required | Description |
|---|---|---|
Copied state | Yes | The current state for the Partner Account |
Copied partner_account_id | Yes | Unique identifier assigned by Klarna to the onboarded partner. |
Copied 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 |
Copied 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. |
Copied 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. |
Copied -email | Yes | E-mail address.
Regex ^(?=.{1,64}@.{1,255}$)(?:[a-zA-Z0-9!#$%&'+/=?^_ |
Copied state_reason | Yes | Additional state information when the Account state is |
The Partner Account lifecycle is defined as:
| Status | Definition |
|---|---|
| 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 |
| Represents an account that is fully operational and can both be managed and process transactions |
| 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.
| Event name | When !Use cases |
|---|---|
| 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 :
{
"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.
Use the onboardAPIoperation to create a Partner Account. Learn more about how to execute the onboard here.
To update Partner Accounts, use the updateAccountAPIoperation. It follows as a RESTful PATCH approach, meaning that only the properties sent on the payload of the request will be affected. Read more about when to update here.
There is no support to delete a partner account. To disable new transactions on a Partner Account, disable the Payment Product instead.