Integration resilience

Idempotency

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.

Tagging

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.

This section provides in-depth instructions and examples for partners on how to implement integration tagging to ensure effective data provision with Klarna.

Naming standardization

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.

Conventions when providing integrator names

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 PascalCase 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”)

Predefined platforms

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.

Data requirements

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

Request context object

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

• Platform name : The name of the platform 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.
• Application name : The name of the application sending the request to Klarna. This allows Klarna to recognize different applications under the same platform. Values are not validated.
• Application 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.
• Version : The version of the integration indicated by the name parameter.

**Application metadata

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

• Platform 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.
• Application name : The name of the application providing the data passed in the request to Klarna.
• Application 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.
• Version : An optional parameter indicating the version of the integration indicated by the name parameter.

Implementation pathways

WebSDK

For clients built on Klarna’s WebSDK, the WebSDK exposes an interface that allows developers to register their application 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.appendAppInfo({
     name: 'Woocommerce',
     version: '1.0'
     applicationReference: 'Woo_5555-474'
})

If multiple parties trigger individual instances of the WebSDK, the data will be appended within the application_metadata array. The WebSDK will limit this array to no more than 6 objects, retaining the final 6 items in case of any conflict.

APIs

The 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 requestcontext, in addition to any services which provide relevant data passed within the request in the applicationmetadata array.

integration_metadata: {
  application_metadata: [{
    platform_name: "WooCommerce",
    application_name: "StripePlugin",
    application_reference: "xxx"
    version: "1.0",
  }],
  request_context: {
    platform_name: "Stripe",
    application_name: "PaymentElement",
    application_reference: "xxx"
    version: "2.0",
  }
}

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 itself within the requestcontext field, and any plugin passing information via an acquiring partner must be included within the `applicationmetadatafield - with the acquiring partner passed as therequest_context`. As partners are required to provide this information across all integration paths, the result allows monitoring of performance across multiple integrations.

Monitoring and alerting

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

Error handling

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/....."
    }
  ]}

Defined error types, and how to handle them