> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://ixopay.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ixopay.ferndocs.com/_mcp/server. # 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 ```html ``` > **Note** > > It is important to set the `data-main="payment-widget-js"` attribute on the script tag. 2. Provide Container for the Klarna Widget. ```html

``` 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](https://documentation.ixopay.com/api/transaction/debit) 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](https://documentation.ixopay.com/api/transaction/debit) | | ↳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](https://documentation.ixopay.com/api/transaction/debit) - 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 ```html ``` 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. ```html ``` 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](https://documentation.ixopay.com/api/transaction/debit), [Preauthorize](https://documentation.ixopay.com/api/transaction/preauthorize), [Capture](https://documentation.ixopay.com/api/transaction/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](https://documentation.ixopay.com/api/transaction/debit) 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](https://documentation.ixopay.com/api/transaction/debit) | | ↳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](https://documentation.ixopay.com/api/transaction/debit) - 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](https://documentation.ixopay.com/api/transaction/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](https://documentation.ixopay.com/api/transaction/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](https://documentation.ixopay.com/api/transaction/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](https://developers.klarna.com/documentation/klarna-checkout/use-cases/discounts/). 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](https://documentation.ixopay.com/api/transaction/debit) | | ↳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](https://documentation.ixopay.com/api/transaction/debit) | | ↳items.item.extraData.totalDiscountAmount | string | **true** | Amount of Item Discount (amount has to be positive), decimals separated by a "." (dot) |