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.

Who should read this: Solution and software engineers implementing a server-side integration with Klarna Network.

• 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.
• The Payment Acquiring Account links the legal entity and its settlement configuration.

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": [

Call the onboard operation from your backend (never from a client app).

• Send an Klarna-Idempotency-Key header for safe retries.
• On success, store:
  • partner_account_id
  • the pair payment_acquiring_account_id and payment_account_reference

The Partner Account is provisioned immediately for transactions, but some updates may be restricted until setup finalizes across Klarna systems.

If the call fails with validation errors, correct the payload and retry with the same Klarna-Idempotency-Key when appropriate.

Subscribe to the following webhooks:

• partner.account.state-change.operational — Signals that Partner Account setup across Klarna systems is complete. Continue management operations only after receiving this event.
• partner.account.brand.data-incomplete — Informs you when submitted brand data (for example, logo_url) is invalid or incomplete. The event is informational and doesn’t block onboarding; update the data promptly for accurate brand representation.

• Use your test environment to send an onboard request with valid data and confirm a 2xx response.
• Trigger the informational brand event by submitting a deliberately broken logo_url (for example, a 404 URL) 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.

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: Duplicate payment_account_reference for the selected payment_acquiring_account_id.
  • Action: Update the existing Partner Account instead or choose a different reference.
• 5xx Server Error: Internal Server Error
  • Action: Retry with exponential backoff and the same Klarna-Idempotency-Key.