Last updated today

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.

Integration tagging is currently under development and is subject to change. It will become available in future releases.

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.

⚠️ Note: In cases where Klarna recognizes a partnership under a different name, Klarna agents may reach out to request the value provided be adjusted to remain consistent across multiple integrators
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 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”)
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.

Platform namePredefined string
24Nettbutikk24NETTBUTIKK
4webs4WEBS
Abicart ABABICART_AB
ACIWorldwideACIWORLDWIDE
AddisADDIS
Adobe Commerce (Magento)ADOBE_COMMERCE
AdyenADYEN
Aera Payment & IdentificationAERA_PAYMENT_AND_IDENTIFICATION
AirwallexAIRWALLEX
AlcalinkALCALINK
AlipayALIPAY
AlphabankALPHABANK
AltapayALTAPAY
AntomANTOM
ApexxAPEXX
AptosAPTOS
AQSAQS
ArtdinamicaARTDINAMICA
Askås I & RASKAS_I_AND_R
AurusAURUS
AutoPayAUTOPAY
AvantiCartAVANTICART
AvensiaAVENSIA
Axerve S.p.AAXERVE_SPA
Ayla Diseño y TecnologíaAYLA_DISENO_Y_TECNOLOGIA
Bank of AmericaBANK_OF_AMERICA
BanorteBANORTE
Banque PopulaireBANQUE_POPULAIRE
BBVABBVA
BigCommerceBIGCOMMERCE
Billwerk+BILLWERKPLUS
BlackPepperBLACKPEPPER
BlueSnapBLUESNAP
BlugentoBLUGENTO
BNPPBNPP
Bold CommerceBOLD_COMMERCE
BPCEBPCE
BraintreeBRAINTREE
BrinkCommerceBRINKCOMMERCE
BuckarooBUCKAROO
Cafe24CAFE24
CardinalCommerceCARDINALCOMMERCE
CardlinkCARDLINK
CCV Group B.V.CCV_GROUP_BV
CegidCEGID
CentraCENTRA
CheckoutCHECKOUT
CitconCITCON
CitibankCITIBANK
ClearHausCLEARHAUS
ClearisCLEARIS
CloudCartCLOUDCART
CodaPaymentCODAPAYMENT
CommerziaCOMMERZIA
ComerzziaCOMERZZIA
ComgateCOMGATE
CommerceToolsCOMMERCETOOLS
ComputopCOMPUTOP
Conecta SoftwareCONECTA_SOFTWARE
ConektaCONEKTA
ContentSpeed (Payten)CONTENTSPEED
CosinCOSIN
Credit AgricoleCREDIT_AGRICOLE
Credit MutuelCREDIT_MUTUEL
Crisp StudioCRISP_STUDIO
CS CartCS_CART
CybersourceCYBERSOURCE
DanalDANAL
DanDomainDANDOMAIN
DAPPDAPP
DEUNADEUNA
Deutsche BankDEUTSCHE_BANK
Digital RiverDIGITAL_RIVER
Digital TakeoutDIGITAL_TAKEOUT
DinteroDINTERO
Dir&GeDIR_AND_GE
DlocalDLOCAL
DNA PaymentsDNA_PAYMENTS
e-shop 360E-SHOP_360
EasypayEASYPAY
EbanxEBANX
eComm360ECOMM360
eCommerce newsECOMMERCE_NEWS
ecwidECWID
EglobaEGLOBA
EKMPowershopEKMPOWERSHOP
ElavonELAVON
EnactorENACTOR
epayEPAY
EpiServerEPISERVER
Eromnet*EROMNET
eServiceESERVICE
eShopWorldESHOPWORLD
eStudio 34ESTUDIO_34
EupagoEUPAGO
EuPlatescEUPLATESC
EurobankEUROBANK
eValentEVALENT
EximbayEXIMBAY
ExtendedEXTENDED
FAPSFAPS
FIKFIK
Finqu OyFINQU_OY
Fintk ConsultingFINTK_CONSULTING
First DataFIRST_DATA
FISFIS
FiServ (Clover, Telecash, AIB)FISERV
FlatPayFLATPAY
FlooidFLOOID
FreedomPayFREEDOMPAY
GetNetGETNET
GK SoftwareGK_SOFTWARE
Global Payments (Evo Payments)GLOBAL_PAYMENTS
GlobalEGLOBALE
GoDaddyGODADDY
GomagGOMAG
GoPayGOPAY
HiberusHIBERUS
HiPay SASHIPAY_SAS
HobexHOBEX
HolipayHOLIPAY
HostingerHOSTINGER
I’mwebIMWEB
ICGICG
Idosell/IAIIDOSELL_IAI
IfthenpayIFTHENPAY
IlionILION
IngenicoINGENICO
IntershopINTERSHOP
IxopayIXOPAY
J.P. MorganJP_MORGAN
JimdoJIMDO
JPMJPM
JTL ShopJTL_SHOP
JumpsellerJUMPSELLER
KG InicisKG_INICIS
KodmyranKODMYRAN
KushkiKUSHKI
KvantoKVANTO
LabelgrupLABELGRUP
LegendsLEGENDS
LemonwayLEMONWAY
LightspeedLIGHTSPEED
Línea GráficaLINEA_GRAFICA
LitiumLITIUM
LloydLLOYD
LMS-SportLMS-SPORT
LogpayLOGPAY
Lyra NetworkLYRA_NETWORK
MaktaggMAKTAGG
MangopayMANGOPAY
MarketpayMARKETPAY
MerchantProMERCHANTPRO
Microsoft Dynamics NavisionMICROSOFT_DYNAMICS_NAVISION
MobilePayMOBILEPAY
MODDOMODDO
MollieMOLLIE
MondidoMONDIDO
MoneiMONEI
MonerisMONERIS
MonextMONEXT
MultisafepayMULTISAFEPAY
myPOSMYPOS
MystoreMYSTORE
NBGNBG
NCRNCR
Netgiganten.dkNETGIGANTENDK
Nethit SystemsNETHIT_SYSTEMS
NetopiaNETOPIA
NetsiteNETSITE
Nexi Group (Nets, Concardis, Computop, Paytrail)NEXI_GROUP
NHN CommerceNHN_COMMERCE
NHN KCPNHN_KCP
Nice PaymentsNICE_PAYMENTS
Norce (Jetshop/Storm)NORCE
NordicwayNORDICWAY
NovalnetNOVALNET
NuveiNUVEI
OC Payment GmbHOC_PAYMENT
OceanpaymentOCEANPAYMENT
Odero (TOKEN)ODERO
OhdigitalOHDIGITAL
OkisamOKISAM
One.comONECOM
OneBoxONEBOX
OnilONIL
OnlinePaymentPlatformONLINEPAYMENTPLATFORM
OpenbravoOPENBRAVO
OpencartOPENCART
OpenpayOPENPAY
OptimizelyOPTIMIZELY
Oracle Commerce CloudORACLE_COMMERCE_CLOUD
Orbital RevolutionORBITAL_REVOLUTION
Outpayce (part of Amadeus)OUTPAYCE
OxidESalesOXIDESALES
P24P24
PacypayPACYPAY
Pay.nlPAYNL
PaybyrdPAYBYRD
PaycoPAYCO
PayCometPAYCOMET
PayerMaxPAYERMAX
PayGreenPAYGREEN
PayletterPAYLETTER
PaylikePAYLIKE
PaylinePAYLINE
Payment SensePAYMENT_SENSE
PaymentwallPAYMENTWALL
PayNowPAYNOW
PayonePAYONE
PayoneerPAYONEER
PayPlug Enterprise SaaSPAYPLUG
PayrexxPAYREXX
PaySafePAYSAFE
PaytrimPAYTRIM
PayUPAYU
PayxpertPAYXPERT
PensoPayPENSOPAY
PePPEP
PHCPHC
PingPongPINGPONG
Pireaus BankPIREAUS_BANK
Planet Payment (DataTrans)PLANET_PAYMENT
Plati.onlinePLATIONLINE
PolcardPOLCARD
PPROPPRO
PrestashopPRESTASHOP
PrimaveraPRIMAVERA
PrimerPRIMER
ProcessOutPROCESSOUT
ProsaPROSA
Pulse247 Oy (MyCashFlow)PULSE247_OY
PXP FinancialPXP_FINANCIAL
QentaQENTA
QuickbooksQUICKBOOKS
QuickbutikQUICKBUTIK
QuickPayQUICKPAY
RadialRADIAL
Razer Merchant ServiceRAZER_MERCHANT_SERVICE
ReachREACH
RedicomREDICOM
RedsysREDSYS
ReduncleREDUNCLE
ReduniqREDUNIQ
Rocket DigitalROCKET_DIGITAL
SabadellSABADELL
SageSAGE
Salesforce Commerce CloudSALESFORCE_COMMERCE_CLOUD
SAP (Hybris)SAP_HYBRIS
ScannetSCANNET
ScayleSCAYLE
SDi Digital GroupSDI_DIGITAL_GROUP
SeidorSEIDOR
Shift4SHIFT4
ShoperSHOPER
ShopifySHOPIFY
ShopLazzaSHOPLAZZA
ShoplineSHOPLINE
ShoptetSHOPTET
ShopwareSHOPWARE
SIBSSIBS
SimplerSIMPLER
Simply.comSIMPLYCOM
SipaySIPAY
Six SaferpaySIX_SAFERPAY
Smallpay S.r.l.SMALLPAY_SRL
solteqSOLTEQ
SquareSQUARE
Squarespace CommerceSQUARESPACE_COMMERCE
StratoSTRATO
StripeSTRIPE
Studioforty9STUDIOFORTY9
SumUpSUMUP
Swedbank PaySWEDBANK_PAY
TD Bank Merchant SolutionsTD_BANK_MERCHANT_SOLUTIONS
TelecashTELECASH
TencentTENCENT
ThunesTHUNES
TiendaNubeTIENDANUBE
Tier1TIER1
Toss PaymentsTOSS_PAYMENTS
TpayTPAY
Trevenque Sistemas de InflormaciónTREVENQUE_SISTEMAS_DE_INFLORMACION
TrilogiTRILOGI
TrustPayTRUSTPAY
Twice Commerce (prev. Rentle Oy)TWICE_COMMERCE
UnzerUNZER
Upstream payUPSTREAM_PAY
VerifoneVERIFONE
Vilkas GroupVILKAS_GROUP
VippsVIPPS
VismaPayVISMAPAY
VisualitVISUALIT
VisualSoftVISUALSOFT
VivaWalletVIVAWALLET
VR PaymentVR_PAYMENT
VtexVTEX
WalleeWALLEE
Way2ecommerceWAY2ECOMMERCE
Weasy.ioWEASYIO
WebimpactoWEBIMPACTO
WebmefyWEBMEFY
Wells FargoWELLS_FARGO
WestpayWESTPAY
WikinggruppenWIKINGGRUPPEN
WindcaveWINDCAVE
WixWIX
WizishopWIZISHOP
WoocommerceWOOCOMMERCE
woolmanWOOLMAN
WorldFirstWORLDFIRST
WorldlineWORLDLINE
WorldpayWORLDPAY
XsollaXSOLLA
xt commerceXT_COMMERCE
Young PixelYOUNG_PIXEL
Zettle by PaypalZETTLE

Data requirements

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

Implementation pathways

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:

const Klarna = await initiateKlarnaWebSdk({
  clientId: 'your_client_id_here',
  integrator: {
    name: 'AcquiringPartner',
    moduleName: 'SubIntegration',
    moduleVersion: '2.0',
    sessionReference: 'xxx',  },
});
Copy
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.

 Klarna.appendOriginator({
  name: 'ecommerceCompany',
  sessionReference: '5555-474',
  moduleName: 'ecommercePlugin',
  moduleVersion: '1.0'
})
Copy

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",
    "module_version": "2.0"
  }]
}
Copy
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. Below is an example of how this complexity could be expressed in a given transaction: Here

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.

ParameterDefinition
error_idA unique identifier for the request generated by Klarna. This ID will help you in investigations in case you need help from our support team.
error_typeType of the error. Different error types are ACCESS_ERROR, TECHNICAL_ERROR, RESOURCE_ERROR and INPUT_ERROR.
error_codeError code for further categorizing the error. We recommend using this error code for building your error handling logic.
error_messageA human readable error message. The error message is not meant to be displayable to customers shopping, but to assist in technical troubleshooting.
doc_urlLink to Klarna docs describing how to use the API to avoid the error, or a more detailed explanation of why the error occurred. To be provided when available.

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

Defined error types, and how to handle them

Error typeError codeHTTP Status codeDefinitionHandling
NOT_FOUND404The requested API route does not exist.Verify the API route.
ACCESS_ERRORUNAUTHORIZED401The presented credentials failed authentication.Verify the credentials, check the authentication method, and confirm the correct endpoint.
RATE_LIMITED429The caller was rate limited due to too many requests.See Rate Limiting for more details.
RESOURCE_ERRORRESOURCE_NOT_FOUND404The resource was not found.Verify the token provided in the request path. This issue may also occur if an attempt is made to update an expired shopping session.
RESOURCE_CONFLICT409There was a conflict in using the resource.The transaction details are conflicting with the request details. Might occur due to concurrent updates to the resource.
OPERATION_FORBIDDEN403The provided credentials (authorization) does not have enough privileges to perform the requested operation.Ensure that the credentials being used have the necessary permissions for the operation.
RATE_LIMITED429The specific resource was rate limited. For example creation of resources are rate limited, but it is still possible to run on already existing resources.See Rate Limiting for more details.
INPUT_ERRORVALIDATION_ERROR400One or more input parameters failed input validation. For example exceeding a max value, or failed pattern matching, invalid type.Verify that the request details and formats are correct. See the error message for more info.
INVALID_CONTENT_TYPE400The input does not conform to the expected content type syntax. For example invalid JSON.Verify that the content type is as expected.
TECHNICAL_ERRORINTERNAL_ERROR500An unknown error occurred.Reach out to your support contact and include the error message and the error id.
SERVER_CONFIGURATION_ERROR500The system is misconfigured. For example, price plan is misconfigured.Reach out to your support contact and include the error message and the error id.
TEMPORARY_UNAVAILABLE503The system is temporarily unavailable to process the request.Reach out to your support contact and include the error message and the error id.
Next to Versioning and Releases management