Integration resilience

Idempotency is a key concept in system operations, ensuring that repeating the same action multiple times doesn't change the outcome after the first execution. This principle is crucial for maintaining consistency and reliability, particularly in payments integrations, enhancing customer experience and system stability.

Klarna requires idempotent integration of its systems for actions that could change a transaction's status. This safeguards against unwanted changes or duplications if a request is repeated. To manage this, you can use the Klarna-Idempotency-Key header in all POST and PATCH requests. An idempotency key should be created using the UUIDv5 standard, and is valid for 24 hours - outside of that window Klarna cannot guarantee the idempotency key will be honored with respect to an action.

This enables Klarna to recognize and ignore repeat requests to ensure an action is not unintentionally duplicated. In the case of a duplicate attempt, Klarna will respond with the initial result instead of processing a new one.

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.

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

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

const Klarna = await initiateKlarnaWebSdk({
  clientId: 'your_client_id_here',
  integrator: {
    name: 'AcquiringPartner',
    moduleName: 'SubIntegration',
    moduleVersion: '2.0',
    sessionReference: 'xxx',  },
});

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.

 Klarna.appendOriginator({
  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.

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",
    "module_version": "2.0"
  }]
}

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. Below is an example of how this complexity could be expressed in a given transaction:

To ensure compliance with integration best practices and data protection regulations, you must proactively monitor and share information about deviations from expected behaviors as outlined in the Partner-specific Solution Scope Document. This includes technical errors and unusual activities by customers or, where relevant, accounts or integrations occurring through your integration.

To support monitoring, you are required to meet the following criteria:

• Immediately escalate any events that disrupt business operations, compromise the integrity or security of information systems, or impact the availability, confidentiality, or integrity of digital assets.
• Address any disruptions or compromises affecting the operation and reputation of the Klarna payment system.
• Ensure that all integration approaches must include a specific parameter that uniquely identifies the specific integration being used on that request or transaction. This parameter must be traceable across all integrations to ensure comprehensive incident handling, behavioral tracking, and account management.
• Follow a release process that validates system functionalities and integration points in the test environment to detect and resolve issues before they impact system performance or customer experience.
• All interactions with Klarna are tagged with the appropriate integration details and versions as defined in Integration tagging.

When an error occurs on API request, Klarna responds with an error type, an error code, an error message and a corresponding HTTP status code.

Klarna's APIs use HTTP status codes together with error objects to handle errors. When an API call fails Klarna will respond with a 4xx or 5xx status code together with a response body containing an error object with the error code, an array of error messages and a unique error id to be used to identify the request.

Example of API response with an error details:

{
  "error_id": "abcd1234-12ab-1234-abcd-abcd12345678",
  "error_type": "INPUT_ERROR",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "parameter": "line_items[0].quantity",
      "error_message": "Parameter line_items[0].quantity must be greater than or equal to 1",
      "doc_url": "https://docs.klarna.com/....."
    }
  ]}