Structure Partner Accounts accurately in Klarna to streamline onboarding, optimize integration, and flexibly support everything from simple store setups to complex multi-entity configurations.
Accurate Partner Account modeling ensures a seamless onboarding experience, simplifies account management, and supports flexible integration patterns — from small stores to complex multi-entity organizations.
This article explains how to structure Partner Accounts within Klarna’s ecosystem and how to align them with the company’s business structure and systems.
| Term | Definition |
|---|---|
| Partner Account | Represents a company using Klarna's offering. In this context, it represents your own Partners. |
| Partner Account contact | Information about the main representative of the Partner for Klarna. This data point is used in case we need to reach out to the Partner directly. |
| Partner Business Entity | Any information relevant for Klarna to efficiently run its fraud prevention functionality. |
| Payment Product | Represent the ability of the Partner Account to use Klarna's Payment offering. |
| Payment Account | Payment accounts connect various attributes, such as the Partner Business Entity, the Payment Acquiring Account(s) Klarna has configured for the Acquiring Partner, and the default Merchant Category Code for the Partner Business Entity.
|
| Stores & Branding | Lists containing the details of the website, mobile app or physical store where Klarna products are going to be made available as well as the related branding data. |
| MCC (Merchant Category Code) | Defines the type of goods or services sold by the Partner. |
A Partner Account aggregates all the information Klarna needs to operate payments, compliance, and settlement.
Each account can include:
- Partner Account contact details
- Klarna products and configurations
- Payment Accounts
- Partner Business Entities
- Stores and Branding information
Companies should maintain a single Partner Account, even if they operate multiple legal entities, brands, or stores.
For more details about Klarna's account structure, see here.
Now, let’s take a look into a few different examples of how Partner accounts can be used to represent Partners:
In a standard retail setup, a Partner has one account, one Product, and one Store.
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
{
"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": [Larger enterprises often manage several legal entities under a single Partner Account.
Example 2: Multi-brand enterprise
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 Account<nowiki/>s 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.
Sample request
{
"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": [Payment Accounts can also be used to support multiple 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
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
{
"partner_account_reference": "M12378999999",
"partner_account_name": "AstroSox",
"partner_account_contact": {
"given_name": "Mathias",
"family_name": "Doe",
"email": "Mathias@AstroSox.de",
"phone": "+49555555555"
},
"products": [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 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.
Sample request
{
"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": [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 all franchisees have their own account with you and don't share any data, then multiple Partner Accounts can be created to manage all companies as individual entities.
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 account ID and store ID 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 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 account ID and store ID in the request, Klarna can present to the customer different store details and an experience personalized to the originating store.
To onboard, we would need three /onboard calls.
First sample request: One Store
{
"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
{
"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
{
"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": [