Submit the onboarding request

Onboard your first Partner to Klarna, submit all required data, store the response and configure account lifecycle webhooks to receive real-time notifications about your Partner Account.

8 min read

Run the onboard API

API call to create a fully functional Partner Account with Klarna, then subscribe to the account lifecycle webhook to know exactly when setup completes. This guide focuses on the asynchronous nature of onboarding and clarifies what to store, what to expect from responses, and which webhooks to use.

The onboard API

operation can also be used to create new resources on an existing Partner Account. See Creating new resources on an existing Partner Account for details.

Prerequisites

Understand Klarna's Partner Account data model
Your integration infrastructure is configured for outbound HTTPS and inbound webhook delivery.
Configure your integration infrastructure.
A Payment Profile and Payment Acquiring Account are available and selected for use.
Ability to store persistent identifiers (for example, in a database).

Step by Step

Identify the correct Payment Profile and Payment Acquiring Account for the Partner you're onboarding:

The Payment Profile determines prices and programs applied to the Partner's payment transactions. Select this according to how your profiles were configured together with your Klarna representative.
The Payment Acquiring Account links the legal entity and its settlement configuration. Select the Acquiring Account connected to your Legal Entity that will be the counterparty for this Partner.

Build the onboard payload using your system's references so the Partner Account maps cleanly to your internal records.

Example request payload:

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"
  },
  "products": [

Adjust the references and identifiers to match your own business entities, Brands, and stores.

Call the onboard API

operation from your backend (never from a client app).

Include an unique Klarna-Idempotency-Key header for each logical onboarding request so that safe retries do not create duplicate Partner Accounts.
On a successful response, store at least:
- partner_account_id
- the pair payment_acquiring_account_id and payment_account_reference for each created Payment Account Avoid performing other Partner Account management actions until onboarding is confirmed operational by webhook (see Step 4).

If the call fails with validation errors (for example, 4xx responses), correct the payload and, when appropriate, retry with the same Klarna-Idempotency-Key to keep the onboarding idempotent.

Subscribe your webhook endpoint to the account lifecycle events so you know when onboarding is complete and when Brand data needs attention.

Recommended events:

partner.account.state-change.operational: Indicates that the Partner Account setup across Klarna systems is complete. Treat this as the signal that the Partner Account is fully operational for ongoing management actions.
partner.account.brand.data-incomplete: Indicates that submitted Brand data (for example, logo_url) is invalid or incomplete. This event is informational and does not block onboarding, but you should correct the Brand data promptly for accurate Brand representation.

Creating new resources on an existing Partner Account

You can call the onboard API

endpoint multiple times for the same Partner Account to create new resources (Brands, Store Groups, Stores, Payment Accounts, or Partner Business Entities). This is particularly useful when Partner information becomes available progressively or when you need to expand an existing Partner Account.

When to use this approach

Use the onboard API

operation to create new resources when you need to:

Add a new Store to an existing Store Group when a Partner expands to a new market.
Create additional Payment Accounts for different business entities under the same Partner Account.
Add new Brands when a Partner launches a new product line.
Provide new Partner resources that weren't available during the initial onboarding.

How to create new resources

Integration requirement

Include partner_account_reference, partner_account_name, partner_account_contact (with email), partner_business_entities, brands, store_groups, and products (with at least one Payment Account) on every onboard API

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

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.

1.
Prepare the payload with the same partner_account_reference as the existing Partner Account and the full set of required fields.
2.
Repeat the stored resources and add the new one, for example a new Store Group.
3.
Match existing resources exactly when you include them (for example, an existing Brand for a new Store Group). If a field differs from what Klarna has stored, the request fails with HTTP 409.
4.
Call onboard with the same process as for creating a Partner Account, including a unique Klarna-Idempotency-Key.
5.
Handle the response: On success, the new resources are added. On HTTP 409, check that every existing resource in the payload matches what is stored in Klarna. On HTTP 400, check that the required Partner Account fields are present.

Important considerations

Existing resources must match exactly: If you include a resource with an existing reference (for example, brand_reference), all fields must match what Klarna has stored. Any mismatch results in a 409 Conflict error.
Idempotency still applies: Use a unique Klarna-Idempotency-Key for each logical onboard request to enable safe retries.
Immutable fields still cannot change: Certain data points (see Data immutability) cannot be modified by calling onboard again.
Webhook events: You'll receive the same webhook events (partner.account.state-change.operational) when creating new resources as you do when creating a Partner Account.

Example workflow

Scenario: A Partner initially onboarded with one Store Group wants to add a new Store in a different market.

1.
Initial state: Partner Account M123786123412 exists with Store Group STORE_NY004.
2.
Prepare payload: Create a payload with the same partner_account_reference, repeat the stored Partner Account, and add the new Store Group STORE_EU005. See Creating new resources on an existing Partner Account for a full example.
3.
Run the call: Send the onboard request with a new Klarna-Idempotency-Key.
4.
Klarna processes: Klarna identifies the existing Partner Account and adds the new Store Group and Store.
5.
Store identifiers: Save any new identifiers returned in the response for future API calls.

For detailed payload examples, see Creating new resources on an existing Partner Account.

Testing

Use your test environment to validate the full onboarding flow:

Creating a Partner Account:'

Send an onboard request with valid data and confirm a 2xx response.
Verify that your system stores partner_account_id and the payment_acquiring_account_id and payment_account_reference pairs.
Confirm that your webhook endpoint receives partner.account.state-change.operational for the new Partner Account and that your logs include the full payload.
Trigger the informational Brand event by submitting a deliberately broken logo_url (for example, a URL that returns 404) and verify your webhook endpoint receives partner.account.brand.data-incomplete.
Validate signature or authentication on inbound webhooks and log the full payloads for reconciliation.

Creating new resources on an existing Partner Account:

Send an onboard request with an existing partner_account_reference, the full Partner Account payload, and the new Store Group. Confirm a 2xx response.
Verify that the new resources are added to the existing Partner Account without affecting existing resources.
Test the 409 Conflict scenario by sending an onboard request that includes an existing resource with different field values (for example, a Brand with a different display_name). Confirm you receive a 409 Conflict error.
Verify that your system can safely retry onboard requests with the same Klarna-Idempotency-Key without creating duplicate resources.

Troubleshooting

Common HTTP responses

400 Bad Request: Required field missing, type mismatch or general invalid field.
- Action: Fix the payload and retry with the same Klarna-Idempotency-Key.
409 Conflict: This error can occur in two scenarios:
- Duplicate reference: Duplicate payment_account_reference for the selected payment_acquiring_account_id, or duplicate reference for another resource type.
  - Action: Use a new reference when you mean to create a different resource. When the reference already exists, repeat that resource with the field values Klarna has stored.
- Resource mismatch: An existing resource in the payload has different field values than what is stored in Klarna.
  - Action: Correct the field values so they match what Klarna has stored, and keep the resource in the payload. For example, if you're adding a new Store Group and the payload includes the existing Brand, the Brand's display_name and other fields must match exactly. Dropping a required resource to avoid the mismatch returns HTTP 400.
5xx Server Error: Internal Server Error
- Action: Retry with exponential backoff and the same Klarna-Idempotency-Key.