Skip to main content

KlarnaWidget

This page provides an overview of the payments methods provided by the KlarnaWidget adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating KlarnaWidget within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.

Klarna is a payment provider that offers its own payment methods, but also supports businesses by offering a large selection of the most popular payment methods on the market.

Payment Methods

Payment MethodTransaction FlowsTransaction Types
InvoiceWidget - payment-widget.jsDebit, Authorize, Refund
InstallmentWidget - payment-widget.jsDebit, Authorize, Refund
SofortWidget - payment-widget.jsDebit, Authorize, Refund

Connector Config

KeyRequiredValuesDescription
regiontrueeu, na, ocKlarna's Api is available through different base URLs depending on the underlying region. eu = Europe, na = North America, oc = Oceania

Integration Guide

To activate the Klarna Widget you will first have to include the payment-widget.js.

​1. Embed the payment-widget.min.js in your page

<script data-main="payment-widget-js" src="https://gateway.ixopay.com/js/integrated/payment-widget.min.js"></script>
note

It is important to set the data-main="payment-widget-js" attribute on the script tag.

​2. Provide Container for the Klarna Widget.

<div id="klarna-payments-container"></div>

​3. Retrieve a Widget-Token via a Prepare Call (Prepare-Debit or Prepare-Preauthorize). This Call is required to initialize a Klarna Session and provide it with all the checkout data.

  • Endpoint: POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/prepare-(debit or preauthorize)

Prepare Transaction Parameters

NameTypeRequiredDescription
amountstringtrueAmount of transaction, decimals separated by a "." (dot)
currencystringtrue3 letter currency code
descriptionstringfalseIf there is no Item given, the Description will be mandatory
successUrlstringtrueredirect to URL on success/pending
callbackUrlstringtrueendpoint to receive status notifications
customerobjecttruesee Customer
↳customer.billingAddress1stringtruerequired for Klarna's authorization process
↳customer.billingCitystringtruerequired for Klarna's authorization process
↳customer.billingPostcodestringconditionalRequired if the customer.billingCountry is any of SE, NO, FI, DK, GB, US, DE, AT, CH, NL, BE, AU, FR, PT, PL, GR, CZ, HU, RO, SK, IT, ES
↳customer.billingCountrystringtruerequired for session initialization
↳customer.billingStatestringconditionalrequired if customer.billingCountry is any of US,AU,IE,RO,IT
↳customer.birthDatestringfalsecustomer birth Date
↳customer.emailstringtruerequired for session initialization
↳customer.shippingFirstNamestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingLastNamestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingAddress1stringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingCitystringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingPostCodestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingStatestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingCountrystringfalseIn case of divergent Billing-/ShippingAddress
↳customer.extraData.shippingEmailstringfalseIn case of divergent Billing-/ShippingAddress
extraDataobjectfalseobject containing key-value pairs (string-to-string)
↳extraData.orderTaxAmountstringfalseTotal tax amount of the order. The value should be in non-negative minor units. Eg: 25 Euros should be 2500.
itemsobjectfalseobject containing Items - If no Item is given, a default Item will be generated with the transaction description as name
↳items.item.namestringtrueName of the item
↳items.item.descriptionstringfalseDescription of the item
↳items.item.identificationstringfalseIdentification of the item, will be passed as 'reference'
↳items.item.quantitystringtrueQuantity of the item
↳items.item.pricestringtruePrice of item, decimals separated by a "." (dot)
↳items.item.currencystringtrueCurrency of the item - has to identical to the transaction currency
↳items.item.extraDataobjectfalseobject containing key-value pairs (string-to-string)
↳items.item.extraData.totalAmountstringtrueThe total amount of the Item (item.price * item.quantity)
↳items.item.extraData.typestringfalseType of the order line item. The possible values are: physical discount shipping_fee sales_tax digital gift_card store_credit surcharge. Default Value is 'physical'
↳items.item.extraData.taxRatestringfalseTax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals. I.e 1900 = 19%.
↳items.item.extraData.totalTaxAmountstringfalseTotal tax amount of the order line. Must be within ±1 of total_amount - total_amount 10000 / (10000 + tax_rate). Negative when type is discount.
↳items.item.extraData.productUrlstringfalseA Url String that points to your Product
↳items.item.extraData.merchantDatastringfalseInformation about the Product
↳items.item.extraData.imageUrlstringfalseA Url String that points to your Product Image
note

Note that even though Customer Data is required to create the Session, they won't be emitted until the Klarna's Authorization Call (EU Regulation)

​4. Initialize the Klarna Widget with the following parameters:

  • The "Public Integration Key" of your Connector
  • The "Widget-Token" that you received from the Prepare Call
  • Javascript function to handle payment completion
  • Javascript function to handle error events
<script>
var widget = new WidgetJs();

errorHandler = function (error) {
//handle error events here
}

completeHandler = function (initResult) {
//Klarna init result
}

widget.initKlarna(
'Public Integration Key',
'Widget-Token',
'klarna-payments-container',
completeHandler,
errorHandler
);
</script>

​4. Authorize / Finalize the Klarna Widget with the following parameters:

  • The "Public Integration Key" of your Connector
  • The "Widget-Token" that you received from the Prepare Call
  • Javascript function to handle payment completion
  • Javascript function to handle error events
  • Auto-Finalize Option (only available for the Sofort pay_now payment method - default = true), as described in the Klarna Documentation: finalize is a special call that is needed for the Pay Now payment method category in multistep checkouts. In a multistep checkout scenario the authorize() call can be triggered when the consumer selects the payment method and then presses the "continue" button to go to the next step of the checkout. With Pay Now as payment method category however transferring the funds should only happen once the consumer has pressed the "buy" button to finalize the purchase. To cater for such a scenario authorize() can still be called when the consumer has selected the payment method, but with the auto_finalize property set to false.
<script>
var widget = new WidgetJs();

errorHandler = function (error) {
//handle error events here
}

completeHandler = function (authToken) {
//send the received authToken in the extraData for a debit or preauthorize call
}

widget.authKlarna(
'Public Integration Key',
'Widget-Token',
'klarna-payments-container',
completeHandler,
errorHandler,
true // or false (optional)
);

// Depending on Auto-Finalize Option from widget.authKlarna
widget.finalizeKlarna(
'Public Integration Key',
'Widget-Token',
'klarna-payments-container',
completeHandler,
errorHandler
);
</script>

​5. Send Debit / Preauthorize Request with the received Auth-Token from Step 4.

Send the authorization_token in the extraData object to place the order.

Transaction Request Debit, Preauthorize, Capture

Transaction Parameters

NameTypeRequiredDescription
merchantTransactionIdstringtrueyour unique transaction ID
amountstringtrueAmount of transaction, decimals separated by a "." (dot)
currencystringtrue3 letter currency code
descriptionstringfalseIf there is no Item given, the Description will be mandatory
successUrlstringtrueredirect to URL on success/pending
callbackUrlstringtrueendpoint to receive status notifications
withRegisterbooleanfalsestore customers payment instrument for recurring transactions
referenceUuidstringfalseUUID of an initial transaction
transactionIndicatorstringfalsepossible value: RECURRING
customerobjecttruesee Customer
↳customer.billingAddress1stringtruerequired to create Klarna Order
↳customer.billingCitystringtruerequired to create Klarna Order
↳customer.billingPostcodestringtruerequired to create Klarna Order
↳customer.billingCountrystringtruerequired to create Klarna Order
↳customer.birthDatestringfalsecustomer birth Date
↳customer.emailstringtruerequired to create Klarna Order
↳customer.shippingFirstNamestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingLastNamestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingAddress1stringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingCitystringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingPostCodestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingStatestringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingCountrystringfalseIn case of divergent Billing-/ShippingAddress
↳customer.shippingEmailstringfalseIn case of divergent Billing-/ShippingAddress
extraDataobjecttruerequired to create Klarna Order
↳extraData.authorizationTokenstringtruerequired to create Klarna Order
↳extraData.orderTaxAmountstringfalse / trueTotal tax amount of the order. Depending if you declared a totalTaxAmount on an item, this will be required or not
itemsobjectfalseobject containing Items - If no Item is given, a default Item will be generated with the transaction description as name
↳items.item.namestringtrueName of the item
↳items.item.descriptionstringfalseDescription of the item
↳items.item.identificationstringfalseIdentification of the item, will be passed as 'reference'
↳items.item.quantitystringtrueQuantity of the item
↳items.item.pricestringtruePrice of item, decimals separated by a "." (dot)
↳items.item.currencystringtrueCurrency of the item - has to identical to the transaction currency
↳items.item.extraDataobjectfalseobject containing key-value pairs (string-to-string)
↳items.item.extraData.totalAmountstringtrueThe total amount of the Item (item.price * item.quantity)
↳items.item.extraData.typestringfalseType of the order line item. The possible values are: physical discount shipping_fee sales_tax digital gift_card store_credit surcharge. Default Value is physical
↳items.item.extraData.taxRatestringfalseTax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals. I.e 1900 = 19%.
↳items.item.extraData.totalTaxAmountstringfalseTotal tax amount of the order line. Must be within ±1 of total_amount - total_amount 10000 / (10000 + tax_rate). Negative when type is discount.
↳items.item.extraData.productUrlstringfalseA Url String that points to your Product
↳items.item.extraData.merchantDatastringfalseInformation about the Product
↳items.item.extraData.imageUrlstringfalseA Url String that points to your Product Image

Recurring Transactions

Klarna supports recurring Orders. To create a recurring Order you will have to send your Debit or Preauthorize with the extra "withRegister" flag. For every following recurring Transaction you will have to provide the initial Transaction Uuid as referenceUuid and the transactionIndicator with RECURRING.

Klarna Partial Capturing / Release remaining authorization

Klarna supports partial capturing of created orders. Therefore, send a regular Capture call with the desired capture amount and the corresponding reference Transaction ID. If you did not fully capture the original order amount, you can either send another Capture Request to actually capture the remaining amount or release it with a "Final Capture". This will "release" the remaining amount and add it to your Klarna Merchant contingent. To release a remaining order amount, you will have to send a Capture with an amount of 0.

Klarna Discounts

Klarna supports transmit of Discount Data, these Data can be sent on either order level oder item level. For further information about this topic please visit the official Klarna Documentation. We assume to receive the correct Discount relevant Data and won't apply any validation to it. If your send that Data don't fit the Klarna convention you might be served with a Klarna provided Error.

On Order Level

To achieve an Order Level Discount, you will have to send an Item with the type discount.

NameTypeRequiredDescription
itemsobjectfalseobject containing Items
↳items.item.namestringtrueName of Discount
↳items.item.extraData.typestringtrueType 'discount' is required to actually create the discount Item

Item Level

If you like to send the discount information for a specific Item, you will have to send / add these on the corresponding Item Level as extraData.

NameTypeRequiredDescription
itemsobjectfalseobject containing Items
↳items.item.extraData.totalDiscountAmountstringtrueAmount of Item Discount (amount has to be positive), decimals separated by a "." (dot)