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 Method	Transaction Flows	Transaction Types
Invoice	Widget - payment-widget.js	Debit, Authorize, Refund
Installment	Widget - payment-widget.js	Debit, Authorize, Refund
Sofort	Widget - payment-widget.js	Debit, Authorize, Refund

Connector Config

Key	Required	Values	Description
region	true	eu, na, oc	Klarna'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

Name	Type	Required	Description
amount	string	true	Amount of transaction, decimals separated by a "." (dot)
currency	string	true	3 letter currency code
description	string	false	If there is no Item given, the Description will be mandatory
successUrl	string	true	redirect to URL on success/pending
callbackUrl	string	true	endpoint to receive status notifications
customer	object	true	see Customer
↳customer.billingAddress1	string	true	required for Klarna's authorization process
↳customer.billingCity	string	true	required for Klarna's authorization process
↳customer.billingPostcode	string	conditional	Required 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.billingCountry	string	true	required for session initialization
↳customer.billingState	string	conditional	required if customer.billingCountry is any of US,AU,IE,RO,IT
↳customer.birthDate	string	false	customer birth Date
↳customer.email	string	true	required for session initialization
↳customer.shippingFirstName	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingLastName	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingAddress1	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingCity	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingPostCode	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingState	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingCountry	string	false	In case of divergent Billing-/ShippingAddress
↳customer.extraData.shippingEmail	string	false	In case of divergent Billing-/ShippingAddress
extraData	object	false	object containing key-value pairs (string-to-string)
↳extraData.orderTaxAmount	string	false	Total tax amount of the order. The value should be in non-negative minor units. Eg: 25 Euros should be 2500.
items	object	false	object containing Items - If no Item is given, a default Item will be generated with the transaction description as name
↳items.item.name	string	true	Name of the item
↳items.item.description	string	false	Description of the item
↳items.item.identification	string	false	Identification of the item, will be passed as 'reference'
↳items.item.quantity	string	true	Quantity of the item
↳items.item.price	string	true	Price of item, decimals separated by a "." (dot)
↳items.item.currency	string	true	Currency of the item - has to identical to the transaction currency
↳items.item.extraData	object	false	object containing key-value pairs (string-to-string)
↳items.item.extraData.totalAmount	string	true	The total amount of the Item (item.price * item.quantity)
↳items.item.extraData.type	string	false	Type 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.taxRate	string	false	Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals. I.e 1900 = 19%.
↳items.item.extraData.totalTaxAmount	string	false	Total 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.productUrl	string	false	A Url String that points to your Product
↳items.item.extraData.merchantData	string	false	Information about the Product
↳items.item.extraData.imageUrl	string	false	A 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

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
amount	string	true	Amount of transaction, decimals separated by a "." (dot)
currency	string	true	3 letter currency code
description	string	false	If there is no Item given, the Description will be mandatory
successUrl	string	true	redirect to URL on success/pending
callbackUrl	string	true	endpoint to receive status notifications
withRegister	boolean	false	store customers payment instrument for recurring transactions
referenceUuid	string	false	UUID of an initial transaction
transactionIndicator	string	false	possible value: RECURRING
customer	object	true	see Customer
↳customer.billingAddress1	string	true	required to create Klarna Order
↳customer.billingCity	string	true	required to create Klarna Order
↳customer.billingPostcode	string	true	required to create Klarna Order
↳customer.billingCountry	string	true	required to create Klarna Order
↳customer.birthDate	string	false	customer birth Date
↳customer.email	string	true	required to create Klarna Order
↳customer.shippingFirstName	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingLastName	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingAddress1	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingCity	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingPostCode	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingState	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingCountry	string	false	In case of divergent Billing-/ShippingAddress
↳customer.shippingEmail	string	false	In case of divergent Billing-/ShippingAddress
extraData	object	true	required to create Klarna Order
↳extraData.authorizationToken	string	true	required to create Klarna Order
↳extraData.orderTaxAmount	string	false / true	Total tax amount of the order. Depending if you declared a totalTaxAmount on an item, this will be required or not
items	object	false	object containing Items - If no Item is given, a default Item will be generated with the transaction description as name
↳items.item.name	string	true	Name of the item
↳items.item.description	string	false	Description of the item
↳items.item.identification	string	false	Identification of the item, will be passed as 'reference'
↳items.item.quantity	string	true	Quantity of the item
↳items.item.price	string	true	Price of item, decimals separated by a "." (dot)
↳items.item.currency	string	true	Currency of the item - has to identical to the transaction currency
↳items.item.extraData	object	false	object containing key-value pairs (string-to-string)
↳items.item.extraData.totalAmount	string	true	The total amount of the Item (item.price * item.quantity)
↳items.item.extraData.type	string	false	Type 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.taxRate	string	false	Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals. I.e 1900 = 19%.
↳items.item.extraData.totalTaxAmount	string	false	Total 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.productUrl	string	false	A Url String that points to your Product
↳items.item.extraData.merchantData	string	false	Information about the Product
↳items.item.extraData.imageUrl	string	false	A 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.

Name	Type	Required	Description
items	object	false	object containing Items
↳items.item.name	string	true	Name of Discount
↳items.item.extraData.type	string	true	Type '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.

Name	Type	Required	Description
items	object	false	object containing Items
↳items.item.extraData.totalDiscountAmount	string	true	Amount of Item Discount (amount has to be positive), decimals separated by a "." (dot)