Configure account lifecycle webhooks to receive real-time notifications on status changes for Partner Accounts and Payment Products, ensuring timely actions and seamless transaction management.
The onboard call is a single API call that receives all relevant data about a partner and produces a fully functional Partner Account.
- Understand Klarna’s Partner Account data model
- Have configured your integration infrastructure
- Have the list of Payment Profiles and Acquiring Accounts available
As explained in the Understand your own account, pick the specific Payment Profile and Acquiring Account that is going to be used to onboard the partner.
The Payment Profile will impact the prices and programs applied to the partner, while the acquiring account will link the partner to a specific legal entity of your choice and its settlement configuration and contractual details.
Build the onboard payload as explained by the guide and prepare the payload. Make sure to utilize your own references on the relevant properties so the newly created Partner Account can be connected to your own data.
The response will indicate whether the request succeeded or not. In case the response resulted in failure, parse the error and retry if possible. Read more below on Handling rejected onboardings.
In case the account was successfully created, it's crucial to store the partner_account_id received and the combination of payment_acquiring_account_id and payment_account_reference used to onboard this partner. These are required later in order to integrate to the Payments APIs
At this moment, the created account is ready to transact, but might still be set up in Klarna systems.
The account may take a few seconds to be fully set up in all Klarna’s systems. In order to know exactly when the account setup is completed and then continue managing or updating the partner accounts, you should subscribe to the partner.account.state-change.operational . Learn more about managing the partner account lifecycle here.
Integrating Klarna Payment Services requires accurate and complete Partner data to ensure seamless transaction processes and fraud prevention. This section covers the essential steps and protocols activated when discrepancies in Partner data are detected during the onboarding process.
Klarna's Partner Management API performs real-time validations on all incoming data. In most of the cases when data fields are missing or incorrect, the system triggers an automated response outlining the specific issues. These validations cover critical information such as business details, tax IDs, and contact information.
Whenever incomplete or invalid data for a brand is submitted during the onboarding, Klarna will trigger an account brand data incomplete webhook to which you can subscribe to: I think this should be :
| Parameter | Definition |
|---|---|
| Represents an account that was just onboarded and is currently being set up in our systems. The account can 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. The account cannot be managed by the partner or have any new products added to it. All products within an account are fully disabled as a part of this status |
It is essential to configure account lifecycle webhooks to receive notifications about status changes in Partner accounts and Payment Products. Below is a table describing the events supported by Klarna webhooks for account management, which allows immediate notification and action on certain events.
| Use case | When | Event name |
|---|---|---|
| Account fully onboarded webhooks | An account is fully set up on Klarna’s side |
|
The following example reflects the payload structure for partner.account.state-change.operational event webhook event triggered once the Partner Account is ready to transact.
It differs slightly from the general webhook format as it doesn’t specify the product_id, given this event affects the whole account.
{
"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",