Submit the onboarding request

Run the onboard API call to create a fully functional Partner Account in Klarna Network, 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 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.

• 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).

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:

{
  "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": [
    {
      "type": "PAYMENT",

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

Call the onboard 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.

You can call the onboard 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.

Use the onboard 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.

1. 1.
   Prepare the payload with the same partner_account_reference as the existing Partner Account.
2. 2.
   Include only new resources you want to add (for example, a new Store Group). You do not need to resend existing resources.
3. 3.
   Reference existing resources if needed (for example, an existing Brand for a new Store Group). Ensure the referenced resource's payload matches exactly what Klarna has stored.
4. 4.
   Call the onboard operation with the same process as for creating a Partner Account, including a unique Klarna-Idempotency-Key.
5. 5.
   Handle the response: On success, the new resources are added. On 409 Conflict, check that any existing resources in your payload match exactly what is stored in Klarna.

• 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.

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

1. 1.
   Initial state: Partner Account M123786123412 exists with Store Group STORE_NY004.
2. 2.
   Prepare payload: Create a payload with the same partner_account_reference and include only the new Store Group STORE_EU005.
3. 3.
   Execute the call: Send the onboard request with a new Klarna-Idempotency-Key.
4. 4.
   Klarna processes: Klarna identifies the existing Partner Account and adds the new Store Group and Store.
5. 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.

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 and only new resources (for example, a new Store Group) and 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.

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 different reference for the new resource, or omit the resource from the payload if it already exists.
  • Resource mismatch: An existing resource in the payload has different field values than what is stored in Klarna.

    • Action: Ensure that any existing resources in your payload exactly match what Klarna has stored. Either remove the existing resource from the payload (it will remain unchanged) or correct the field values to match. For example, if you're adding a new Store Group and referencing an existing Brand, make sure the Brand's display_name and other fields match exactly.
• 5xx Server Error: Internal Server Error

  • Action: Retry with exponential backoff and the same Klarna-Idempotency-Key.