​Integration tagging is a crucial mechanism for improving the integration experience by providing detailed and consistent data to support customer experience, performance tracking, and incident resolution. All operations and interactions with Klarna should be tagged with associated integration Partners to ensure granular monitoring and performance. To provide this level of detail, Klarna requires that Partners provide all available information with each interaction.

To enable Acquiring Partners to provide all integrated Partners without additional validation, and avoid unnecessary rejections of requests when a new Partnership is provided, the naming parameters in Klarna’s tagging solution are unvalidated strings, not enums. As such it is required that naming conventions are followed whenever a new application name is provided.

To maximize the possibility of alignment in naming conventions without maintaining a list of all possible applications, Please ensure that your name parameters follow the below naming conventions:

• Base any name used off of the commonly used naming convention for the application - what they call themselves externally towards customers.
• Use UPPER_CASE SNAKE_CASE where multiple words are involved in an application name.
• Standardize language-specific characters and convert characters with diacritics or accents to their base form for consistent handling. (e.g “Rénault” becomes “Renault”)
• Strip out spaces and punctuation
• Separate the company name from it’s legal form (e.g. “Klarna Inc.” and “Klarna AB” both become “Klarna”)
• Do not include regions or countries within an application name where it doesn’t express fundamental differences in the performance of the product. (e.g. “Klarna US” and “Klarna SE” both become “Klarna”)

Below is a list of key platforms with predefined strings. All tagging requests involving these Partners must match their name parameter to the strings below. More information on these Partnerships can be found in the links provided alongside the list. In this context, the term “platform” is used to describe any specific layer within the integration. Acquiring Partners are considered “platform” in this context. Contact Klarna Solutions Engineers if the platforms are not in the list.

The X-Klarna-Integration-Metadata header object encapsulates information about all known integration pathways involved in a given request.

Integrator object

integratorprovides details of the client responsible for the request, and Acquiring Partners are required to pass this object with every request.

• Name: The name of the integrator sending the request to Klarna. Values are not validated, but Klarna may request the value provided be adjusted to remain consistent across multiple integrators. See predefined platformsAPI for a list of accepted strings for defined platforms.
• Module name: The name of the software module sending the request to Klarna. This allows Klarna to recognize different modules under the same integrator. Values are not validated.
• Module version: The version of the integration indicated by the module_name parameter.
• Session reference: A long-lived, unique identifier assigned by the application associated with an overall transaction or session. This identifier is stored within Klarna’s logs, empowering agents to investigate issues with downstream applications.

Originators array

originators is an array of objects representing all applications or platforms involved in providing information included within the request. This metadata provides a detailed view of the specific software platforms, programs or modules leveraged by the Partner.

• Name: The name of the platform providing data passed towards Klarna in the request. Values are not validated, but Klarna may request the value provided be adjusted to remain consistent across multiple integrators. See predefined platformsAPI for a list of accepted strings for defined Partners.
• Module name: The name of the software module providing the data passed in the request to Klarna.
• Module version: An optional parameter indicating the version of the integration indicated by the module_name parameter.
• Session reference: An optional parameter containing a long-lived, unique identifier assigned by the application associated with an overall transaction or session. This identifier is stored within Klarna’s logs, empowering agents to investigate issues with downstream applications.

WebSDK

Integrator object integration

When initializing the Klarna WebSDK, integrators can include the integrator context within the configuration object to ensure the application metadata is correctly registered:

  clientId: 'your_client_id_here',
  integrator: {
    name: 'AcquiringPartner',
    moduleName: 'SubIntegration',
    moduleVersion: '2.0',
    sessionReference: 'xxx',  },
});

Originators array registration

For clients built on Klarna’s WebSDK, the WebSDK exposes an interface that allows developers to register their request originator information. Plugins that use WebSDK must call this interface to register their application information. The WebSDK should include this information on every call to the server.

  name: 'ecommerceCompany',
  sessionReference: '5555-474',
  moduleName: 'ecommercePlugin',
  moduleVersion: '1.0'
})

The originator metadata array will be bound to a specific instance and should be limited to no more than 6 objects, retaining the final 6 items in case of any conflict.

APIs

The Klarna-integratation-metadata header object will allow for the passing of integration tagging information in all server-side requests. Although this field is technically optional, Acquiring Partners must send this information in every request towards Klarna, indicating both the version of their integration which triggers the request within the integrator object, in addition to any services which provide relevant data passed within the request in the originators array.

  "integrator": {
    "name": "AcquiringPartner",
    "session_reference": "xxx",
    "module_name": "subIntegrationPath",
    "module_version": "1.0"
  },
  "originators": [{
    "name": "ecommerceCompany",
    "session_reference": "xxx",
    "module_name": "subIntegrationPath",

Plugins and platforms

For any plugin or platform managed by an Acquiring Partner, Partner tagging information should be included by default without additional effort from the Partner. Any plugin provisioning data directly towards Klarna should include information on the specific integration within the integrator object, and any plugin passing information via an Acquiring Partner must be included within the originators array - with the Acquiring Partner passed as the integrator. As Partners are required to provide this information across all integration paths, the result allows monitoring of performance across multiple integrations.

​