Fatchip GmbH Wiki

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
{{public:faq:klarna-de:0_klarna_logo.png?nolink&400|}}\\
====== Klarna Checkout and Klarna Payments Modul ======
OXID eShop Documentation / Manual

| modul version | 5.5.4 – Stand 24.07.2023 |
| modul name | Klarna Checkout and Klarna Payments Module for the OXID eShop |
| modul category | Bezahlmethoden / Payments \\ This module adds additional payment methods to the OXID eShop. |
| Module vendor | Klarna AB [[https://www.klarna.com/de/verkaeufer/plattformen-und-partner/oxid/|www.klarna.com]] Mail: [[oxid@klarna.com|oxid@klarna.com]] |
| Development of module | Fatchip GmbH [[https://www.fatchip.de|www.fatchip.de]] Mail: [[support@fatchip.de|support@fatchip.de]] |
| Klarna integrations-support | If no technical contact has been assigned to you by Klarna, please contact: ...\\ If you already process Klarna transactions: [[shop@klarna.de|shop@klarna.de]]\\ Or if you are integrating Klarna right now:[[oxid@klarna.com|oxid@klarna.com]] | 

Lizenz: Copyright © 2021 Klarna AB \\ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
[[http://www.apache.org/licenses/LICENSE-2.0|http://www.apache.org/licenses/LICENSE-2.0]]. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

===== Module description =====
This plugin allows you to extend your OXID eShop by the payment methods provided by Klarna. You have the choice between two different operating modes, namely "Klarna Checkout" and "Klarna Payments":

=== Klarna Checkout ===
The "Klarna Checkout" integrates the payment methods "Klarna purchase on account", "Klarna installment purchase", “Sofort“, direct debit and credit card payments via Visa or MasterCard in a revolutionary simple checkout solution. Your customers just have to enter data that they always have in mind. This simplifies shopping enormously and can literally explode your conversion rate - especially on smartphones and tablets.
After installing this module and then activating the Klarna Checkout, your customers will have the opportunity to switch directly from the product detail page or from the mini basket to the Klarna checkout. Here, customers can then simply complete the purchase by entering the e-mail address and postal code.

=== Klarna Payments ===
Or you can integrate the "Klarna Payments" instead. In this mode of operation, the payment methods provided by Klarna are listed as usual in the OXID eShop on the payment method selection page. You have the choice between three different options:
| **Pay later** | The option to pay later makes buying quicker and easier for customers: no need to fill out lengthy personal details or card number online. |
| **Financing** | Your customers can spread the cost of their purchases at a low interest rate, giving them flexibility and increased purchasing power. Our unique credit application requires minimal information and takes just seconds to complete. |
| **Pay Now** | Customers who want to pay in full at checkout can do it quickly and securely with Klarnas Pay now-option - using credit/debit card or Direct bank transfer: Klarna Direkt, Sofort, SEPA Direct Debit. |
|**Pay with Klarna** | Pay Now, Pay later and Financing will be combined into one payment method in the future: Pay with Klarna. Only activate this payment method if the switch has already been made in your merchant account. Activating this payment method in OXID will result in all other Klarna Payments payment methods being hidden in the checkout. |
** Please note:** Different contracts with Klarna may be required for the use of the Klarna Checkout and Klarna Payments.

===== Prerequisites for the installation =====
==== Security notice ====
For your own safety, we recommend that you create a backup of both the store files and your Mysql database before starting the installation, so that you can access the previous status in the event of a problem.

Tip: It is best to first perform the desired installation, including any required template adjustments, in a stage system / test system before making any changes in your productive system.

==== Supported OXID eShop versions ====
  * Community Edition: Version 6.0.x - 6.5.x
  * Professional Edition: Version 6.0.x  - 6.5.x
  * Enterprise Edition: Version 6.0.x - 6.5.x
**Please check if you have the right package for your OXID eShop version.** \\ 
**Do not install this module version if you use another version of the shop!** \\ 

=== Is your OXID eShop unsupported? ===
For the older OXID eShop versions 4.7 to 5.3 you can use the Klarna Payments and Klarna Checkout OXID module version 4.4.1. Please not that further development of this version ended in 2019.
For OXID eShop versions 4.5 to 4.6.X you can use the Klarna OXID module version 3.5.1. 

Please note that the further development of the Klarna OXID module for these older OXID eShop versions has already been discontinued since 2016. We therefore recommend that you first bring your OXID eShop up to date and then use the latest Klarna Checkout and Klarna Payments Module for the OXID eShop version instead.

=== Supported PHP versions ===
The Klarna Checkout and Klarna Payments Module for the OXID eShop runs with PHP 7.1 up to PHP 8.1.

=== Update of an already installed Klarna OXID module ===
Starting from OXID eShop Version 6.0.3 the latest available Klarna OXID module will be shipped together with the OXID eShop Core, so no installation is required. If however you want to update only the Klarna OXID module to the latest version without updating the rest of the OXID eShop, please continue reading:

Please make sure to backup your shop files and database before updating. \\ 
If you have OXID eShop version 6.1.3 for instance, this was shipped with Klarna OXID module version 4.2.2. To upgrade the module to latest 5.5.4 version, please follow these steps:
Edit the following files in your shop folder: \\
<code> vendor/oxid-esales/oxideshop-metapackage-ce/composer.json\\
vendor/composer/installed.json</code>
find all rows which contain „Klarna“ and replace the version number 4.2.2 with 5.5.4. \\
Next, edit the composer.json in your shop root-directory. \\
Within the „require“ section please add: \\
<code>"fatchip-gmbh/oxid-klarna-6": "v5.5.4"</code>
Then please delete the file composer.lock from your shop root-directory. \\
Then please remove the following folder completely with its contents: \\
<code>source/modules/tc/tcklarna\\
vendor/topconcepts/oxid-klarna-6</code>
Then execute the following commands: \\
<code>composer clearcache\\
composer update</code>

**Module update from module version 4.X**\\
This module can be simply installed over an existing module of the 4.X version.

**General update hints**
Please go through all the configuration settings in the admin backend after a module update. Pay particular attention to possible country or language-specific settings. Since additional payment methods have been added, please also check the OXID shop settings under the menu item "Payment methods" and assign them to user groups, countries, shipping methods etc., if necessary. Please ensure that existing old Klarna payment methods from a previously installed Klarna OXID module must be deactivated or deleted. \\
If you use individual shop templates, please check screenshot by screenshot from this manual, in order to incorporate appropriate changes in your individual templates.

----

===== OXID eShop system requirements =====
The server on which the Klarna Checkout and Klarna Payments Module for the OXID eShop is to be used must of course comply with the OXID server and system requirements:
https://docs.oxid-esales.com/eshop/en/6.2/installation/new-installation/server-and-system-requirements.html

===== SSL-Encryption =====
In order to use the Klarna Checkout and Klarna Payments Module for the OXID eShop in the operating mode "Klarna Checkout", the shop must have an SSL certificate. Without SSL certificate the "Klarna Checkout" can not be activated in the shop!

In the "Klarna Checkout" mode, Klarna sends various requests to the OXID eShop to validate transactions. This communication must be encrypted. In the config.inc.php of your shop, a valid https URL must therefore be stored under $this->sSSLShopURL - or in multi-client mode, all clients who are to implement Klarna Checkout must have a corresponding https URL in the mall settings SSL URL to be entered. This also applies in test mode if you want to test the installation.

**Note:** It does not matter if it is an official or a self-signed SSL certificate. \\
**Recommendation:** In general, even in Klarna Payments mode, online shops should nowadays use an SSL certificate, even if it is not absolutely necessary in this mode, as leading browsers will otherwise display warnings when filling out form fields, which might prevent customers from buying.

==== Availability of the shop from the internet ====
As mentioned in the "SSL-Encryption" section above, Klarna sends requests to your OXID eShop to validate transactions.

To make such callback calls from Klarna to your shop, your shop must be accessible from outside via the internet. This means that neither password protection nor an IP lock or firewall protection must be active in your shop, which prevent Klarna from reaching the corresponding validation URLs.

In particular, if you want to test in your development or stage environment: Please keep in mind that HTTPS calls from the external Klarna servers must reach your servers on port 443!

==== Uniqueness of article numbers ====
The article numbers in the OXARTICLES.OXARTNUM field must always be clearly assigned in the shop (in the Enterprise Edition only for the respective subshop ID). The Klarna Checkout and Klarna Payments Module for the OXID eShop sends these part numbers to Klarna for validation during the ordering process. If there are several order lines with articles or variants with the same article number in an order, the order can not be created.

==== Supported countries / markets ====
The present Klarna Checkout and Klarna Payments Module for the OXID eShop provides the Klarna Checkout and Klarna Payments for the following countries: SE, NO, FI, DE, AT, IE, CH, NL, UK, BE, IT, ES, FR + KCO global (see https://developers.klarna.com/documentation/klarna-checkout/kco-global/implementation-guidelines – KCO global is available in most other countries in the world, which means that customers from these countries can at least pay by credit card in the Klarna Checkout Iframe.)

To see which products are supported by country, please see the Klarna Developers page:
https://developers.klarna.com/en/gb/kco-v3/checkout

Please make sure to activate Klarna Payment options only for those countries, for which you have signed corresponding contracts with Klarna.

==== Peculiarities of the OXID module implementation ====
Compared to the full functionality of Klarna, which is described in the Klarna Developer Portal ( https://developers.klarna.com/ ), there are some peculiarities in the present Klarna Checkout and Klarna Payments Module for the OXID eShop. Also, there are some Klarna features which have not been implemented in this module yet. Before using this module, please check whether these peculiarities are relevant for you:
  * Pending Flow: The present module assumes that orders from Klarna are either accepted immediately or rejected immediately. The Klarna Pending Status is not supported. This must be taken into account when configuring Klarna's Merchant ID.
  * Refunds / Returns: Credit of a previously debited payment can not be sent to Klarna via the OXID Admin backend. Please use the Klarna Merchant Portal instead. In the OXID admin backend order administration you will find a direct link to the Merchant Portal on the tab "Klarna" for each Klarna order.
  * Gift Cards: In Klarna terminology “gift cards” are money vouchers, which one could purchase in a local store. Such feature is currently not offered by the OXID eShop.
  * Vouchers: OXID Promotion Vouchers will be sent to Klarna as "Discounts".
  * Partial Captures: It is not possible to send partial deliveries to Klarna via the OXID Admin Backend. Please use the Klarna Merchant Portal instead. In the OXID admin backend order administration you will find a direct link to the Merchant Portal on the tab "Klarna" for each Klarna order.
  * Compatibility with the Amazon Pay module of Best IT: The compatibility with the Klarna Checkout and Klarna Payments Module for the OXID eShop is only guaranteed when using PHP 7.0 or higher.
  * Products with differing VAT rate: If you are using an OXID eShop version prior to 6.0 on a PHP 7 environment (which is not officially supported by OXID eSales), then there is a bug in the handling of products with reduced VAT rate. The reduced VAT rate is ignored at the moment when such product is put into the cart, and the standard VAT rate will be applied instead.
  * B2B-Support: Orders from companies are technically implemented but contractually activated by Klarna only in exceptional cases. Please ask your Klarna Account Manager for further information if B2B will be available for your selling countries. In the Klarna Checkout mode, a company name can be entered, which will be saved as a "c/o address".
  * The reserveOCR function from previous Klarna Checkout and Klarna Payments Module for the OXID eShops has been removed. Usually, this is no longer needed since the Klarna order ID remains constant from the time of ordering to order management.
  * The automatic capturing of orders directly at order completion has not been implemented in this Klarna Checkout and Klarna Payments Module for the OXID eShop.
  * Localization: If a customer in a German shop with shop front-end language set to “German” picks a country like Japan from the list in the Klarna checkout Global Iframe, the language of the Klarna iframe will still remain “German”.  
  * If the selected currency does not match the typical national currency or if a company name has been specified, a warning will be displayed instead of the Klarna payment option.
  * Please check if you have set phone number or the date of birth as mandatory fields in Admin > Master Settings > Core Settings > Settings > Other settings > Mandatory fields in User Registration Form. If you require either of these fields to be filled, you'll also have to make them mandatory in the Klarna Checkout configuration, otherwise orders will fail because of missing data.

----

===== Step-by-step module installation =====
To install the Klarna Checkout and Klarna Payments Module for the OXID eShop in your shop please perform the following steps in the given order. Steps 1. and 2. have to be skipped, if the Klarna Checkout and Klarna Payments Module for the OXID eShop already has been preinstalled in your shop.
 
=== 1. The module is pre-installed ===
Since OXID eShop version 6.0.3 the Klarna Checkout and Klarna Payments module is shipped with the OXID eShop as a core component.
If a manual installation should be necessary however, you'll have to use composer:
** (edit composer.json file) **

In your project folder containting the composer.json execute the following command: <code>composer require fatchip-gmbh/oxid-klarna-6:v5.5.4</code>
or add the following line to the central composer.json file of your project within the section „require“: <code>"fatchip-gmbh/oxid-klarna-6": "v5.5.4"</code>
and then execute the following command: <code>composer update</code>
There might be dependencies with OXID metapackage when installing deviating module versions which should be taken care of manually. \\
Please continue on step 2. 

=== 2. Purge /tmp folder ===
Please delete all files from the /tmp folder of your shop.

=== 3. Please log in ===
Please log in to the OXID admin backend.

=== 4. Activate the module ===
Please perform the following steps:
  - Go to „Extensions“ -> „Modules“ -> „Klarna“ -> „Overview“ and click the button „Activate“
  - Please log off from the OXID admin backend (logout)
  - Please once more delete all files from the /tmp folder of your shop
  - Re-Login to the OXID admin backend

=== 5. Database updates ===
Go to the newly created menu item "Klarna" and select "Start". The database is checked, required fields and tables are added if necessary. A message will be displayed on the screen upon success. \\
**Note:** If the module has already been installed before, click on "Start" to output the version number of the currently installed Klarna module. You will also receive contact information about Klarna here.

=== 6. Module Configuration ===
Then click on the sub-item "Klarna" -> "General" and select the desired operating mode. Some more basic settings have to be made on this page too. Then continue on the Klarna admin section "Configuration" to make appropriate settings for the selected operating mode.
Detailed explanations of the module configuration can be found in the chapter "Configuration" of this manual.

=== 7. Assign user-groups ===
The module installation adds some new payment methods in the admin section "Shop settings" -> "Payment methods":

**For the operating mode: Klarna Checkout**
  * Klarna Checkout

Please make sure, you don't assign any users or user-groups to the payment method “Klarna Checkout”. Klarna Checkout has to be available even to guest-users, without registration or login, that's why users must not be in any way restricted.

**For the operating mode: Klarna Payments**
  * Klarna Pay Later
  * Klarna Financing
  * Klarna Pay Now*
  * Pay with Klarna

Assign suitable user groups to the newly created Klarna payment methods, which you would like to use, just as you would for other payment methods in the OXID eShop. This does not apply to the Klarna Checkout (see above).

** *) Split of Pay Now sub-payment options**
If you applied for the split of the “Pay Now” payment methods at Klarna, please only use the following payment methods instead of “Klarna Pay Now”:
  * Klarna Direct Debit
  * Klarna Online Bank Transfer
  * Klarna Card

Depending on the split or combined display setting on Klarna side, the Pay Now sub-payment options will either be displayed as a combined collection of options with the name “Klarna Pay Now”, where customer may choose one of the three sub-payment options direct debit, credit card or online bank transfer, or – in the split mode – as the sub-payments direct debit and online bank transfer will be shown as separate options on the same level next to Klarna Pay Later and Klarna Financing.

=== 8. Assign shipping sets ===
Please assign the freshly added Klarna payment methods to shipping settings in the section „Shop Settings“ -> „Shipping Methods“, just in the same way as you would configure it for any other shipping method in OXID eShop.

=== 9. Sub-shops ===
If you are using OXID Enterprise Edition, please repeat the steps 3) to 8) for every single sub-shop.

=== 10. Purge /tmp files ===
Please once more delete all files from the /tmp folder of your shop.

=== 11. Inspect your shop-templates ===
We recommend to compare and tick off all pages listed in the chapter “Template modifications” within this manual with your shop-templates, to ensure that both all contents and all legally required modifications for usage of the Klarna Module for OXID have been implemented in a fully visible and functional way in your web-shop.
**Hint:** This is especially important, if you are using a different template in your web-shop as the “Flow” or “Wave” standard themes which are generally shipped by OXID, or if you are using an individual or modified template or if you have removed or changed any OXID blocks from one of the default templates on your own.

=== 12. Perform a test transaction ===
Please test the new Klarna payment methods in your shop first, before activating it for all shop customers.
Prior to the Go-Live of the Klarna payment methods please contact Klarna integrations team, who will perform an approval cycle together with you.

=== 13. Done ===
Congratulations! Your web-shop has now been configured to offer Klarna payment methods including the Klarna Checkout. You are ready to start!

----

===== Configuration =====
In this chapter you will find annotations about the required and other possible settings for installation and configuration of the Klarna Checkout and Klarna Payments Module for the OXID eShop using the OXID eShop Admin backend area. To access these settings please log in to the admin backend of your OXID eShop as usual.

=== Overview ===
In the eShop admin main menu the new link “Klarna” will appear on the left side with several sub-menu entries: \\
{{:public:faq:klarna-en:konfig-ueberblick.png?nolink&200|}} 

=== Start ===
During the module installation (see above) you will initially have to click on the link “Start”, to automatically update the database and module settings. Afterwards some information about Klarna will be displayed: \\
{{:public:faq:klarna-en:konfig-start.png?nolink&800|}}\\
Additionally you will find Klarna contact details and the download link to access the latest manual matching module version 5.5.1. \\
The download-link is: [[https://www.cgrd.de/customer/klarna/docs/klarna-module-for-oxid-de-5.5.1.pdf|https://www.cgrd.de/customer/klarna/docs/klarna-module-for-oxid-de-5.5.1.pdf]]  

==== General ====
First, on the menu item "General" you must make an important decision: Do you want to use the Klarna Checkout and Klarna Payments Module for the OXID eShop in your shop in the operating mode "Klarna Checkout" or in the operating mode "Klarna Payments"?

Your Klarna Integration Team will be pleased to advise you if you have questions about these operating modes.

On this page, you make a few more settings, which are valid regardless of the selected operating mode. However, depending on the selected type of operation, the contents of the menu item "Configuration" will change fundamentally.

To set up the Klarna Checkout and Klarna Payments Module for the OXID eShop in your shop, numerous settings must be made. These are explained on the following pages.

{{:public:faq:klarna-en:allgemein-info.png?nolink&60|}} You can also find additional information in the tooltip help in the shop by clicking on the question mark symbol behind the respective setting.

At the bottom of each page you will always find the "Save" button. Remember to always save your settings so that they are applied to the system.

==== Configuration-Settings on the page „General“ ====
| Choose Klarna module mode | Select  the operating mode for the Klarna Checkout and Klarna Payments Module for the OXID eShop: either "Klarna Checkout" or "Klarna Payments". Depending on this important selection, the configuration settings of the other menu items differ. |
| Mode | Choose between Playground (test mode) and Live (productive mode). Only switch to productive operation after successfully performing integration tests and after consulting with your Klarna Integration Manager. |
| Merchant ID | Please enter your Klarna Merchant ID here. You received it in the welcome email from Klarna. This merchant ID and password apply globally to all countries. Only if you have received different Merchant IDs for different countries, you can add country-specific access data for each country below. |
| Password | Enter your password matching the Merchant ID used. You have received this password in the welcome email from Klarna. |
^ Add country specific credentials ^ optional, if you have received separate access data from Klarna for individual countries: ^ 
^ Country | From the selection on the left, select the country for which you have received country-specific access data from Klarna. |
^ Merchant ID | Please enter the corresponding Merchant ID for this country here. | 
^ Password  | Please enter here the corresponding password for this country. | 
^ Enable logging  | Enables the logging function to record all API communication with Klarna into the mysql table tcklarna_logs. This can be useful for analysis or troubleshooting. In productive mode, the function should be switched off, as otherwise table rows might increase quickly and sensitive data will be saved. | 
^ Send additional product data to Klarna? ^^
^ Product URLs | Submit the URLs of the product detail pages of the products that are in your customer's shopping cart to Klarna so that Klarna can later link to your articles from the Klarna portal. |
^ Image URLs  | Send the URLs of the product images of the products that are in your customer's shopping cart to Klarna so that Klarna can display them in the Klarna portal. | 
^ Enable anonymization  | Enable anonymization to hide the product names of products in your customer's shopping cart from Klarna. This is e.g. recommended for online pharmacies, but should only be activated after consultation with Klarna. |
^ In Language  | With this selection you can define a suitable anonymized product title for each language. |
^ Anonymized product title  ^ Please enter the string which should be transmitted to Klarna instead of the real product title. Moreover, the article numbers are anonymized, too, so that based on this data no conclusion on the purchased items is possible. ^
^ Allowed customer types  | Here you can define whether the shop should accept only B2C transactions (default setting), only B2B transactions or both B2C and B2B transactions and which of these is the preferred customer type. In some shipping countries this will render different forms inside the Klarna Checkout iframe, optimized for either companies or persons. Please note that B2B functionality will only be enabled for your account upon request. Make sure to contact your Klarna Account Manager if you plan to offer B2B sales, so it can be activated for you. | 

==== Configuration for Klarna Checkout ====
The content of this menu item differs depending on which selection of the operating mode you have made on the menu item "General". This chapter describes the settings in the "Klarna Checkout" mode.
| Default Shop Country | Please choose from the list for which country the Klarna Checkout should be loaded by default, as long as the customer has not yet specified his country. | 
| Allow separate shipping address | If delivery to a different delivery address should be enabled, activate this button. | 
| Phone number mandatory  | If you want to require the specification of a telephone number, activate this switch. Normally for Klarna the telephone number is not mandatory. Please make sure that you activate this, if your OXID eShop is configured to require a phone number (see Admin > Master Settings > Core Settings > Settings > Other settings > Mandatory fields in User Registration Form) | 
| Date of birth mandatory | If you want to require the specification of a date of birth, activate this button. Usually for Klarna the date of birth is not mandatory. However, the information is necessary to allow the purchase on account or installment. Please make sure that you activate this, if your OXID eShop is configured to require a date of birth (see Admin > Master Settings > Core Settings > Settings > Other settings > Mandatory fields in User Registration Form) | 
| Enable autofocus on Klarna Checkout iframe  | With this switch, you can set focus on the Klarna Iframe automatically when loading the page with the Klarna Checkout. | 
^ Add custom checkbox to Klarna Checkout iframe ^^ 
^ Do not show a Checkbox | There is a possibility that you can activate an additional checkbox within the Klarna Checkout Iframes to offer the customer, to open a customer account or to sign up for your newsletter, or both. If a checkbox was activated and user already has an account or signed up for the newsletter the text will be adjusted or hidden accordingly. |
^ Create Customer Account | ::: |
^ Subscribe to Newsletter | ::: |
^ Create Customer Account AND subscribe to Newsletter | ::: |
^ Order validation  | ::: |
^ No validation  | Hereby you can activate an additional check of the shopping cart, which validates the availability of the desired products again when sending the Klarna checkout order, in order to avoid errors through over sales. The mode 'Require successful validation' is recommended. |
^ Perform validation, but ignore validation timeouts  | ::: |
^ Require successful validation | ::: |
| Enable Pre-filling  | Activate pre-filling of the Klarna Checkout Iframe with the data of the customer logged in to the OXID eShop |
| Enable Pre-filling notification | If pre-filling of the Klarna Checkout Iframe is active, some countries require a corresponding privacy notice. This note is activated by this switch. |
^ Language-specific settings: ^ Enter corresponding URLs and texts for each shop language. To do this, select the respective language in the "In Language" drop-down. ^
^ Set terms and conditions URI | Enter the URL to your terms and conditions here. This page will be linked from inside the Klarna Checkout Iframe. A valid URL starting with https:// must be specified. |
^ URL Cancellation rights | Please specify the URL to your webpage containing the cancellation rights text. The URL must start with https:// . |  
^ Shipping details  | These shipping instructions will be shown to the customer on the thank you page after completing the order. | 

----

===== Configuration for Klarna Payments =====
The content of this menu item differs depending on which selection of the operating mode you have made on the menu item "General". This chapter describes the settings in the "Klarna Payments" mode.

In Klarna Payments mode, you simply select on this page which Klarna Payments you would like to offer:

{{:public:faq:klarna-en:konfig-klarna-payments_new.png?nolink&800|}}

You can find further settings for Klarna Payments on the Design Settings page.

==== Design Settings ====
The content of this menu item differs depending on which selection of the operating mode you have made on the menu item "General". 

==== Footer ====
Select here, which Klarna element should be displayed in the footer of your shop.
In the operating mode "Klarna Checkout" you have the choice between the "Payment Method Display", which indicates, which Klarna payment methods are available in your shop, and a simple Klarna logo. Only one of these options can be switched on at the same time - or none at all.
Depending on your store design, you can choose a suitable color variation from "Payment Method Display" or logo. The "Payment Method Display" is also available in one long and one short version.
In the operating mode "Klarna Payments" only the Klarna logo is available for integration.

==== Product details page ====
The setting "Display 'Buy Now' Button?" is only available in the operating mode "Klarna Checkout".
The button inserts a 'buy now' button on the article detail pages of your shop in the standard themes Flow or Wave.
If a customer presses this button in the shop frontend, the current article is added to the shopping cart, and the customer is immediately forwarded to the Klarna checkout page.

=== Klarna Checkout Design Options ===
With these settings you can customize the Look'n'Feel of the Klarna Checkout Iframe according to your shop layout. Just leave the fields empty to use the Klarna standard color scheme.
| Button | Background color of the pay-button within the Klarna Checkout iframe. |
| Button Text | Color of the text of the pay-button inside the Klarna Checkout iframe. |
| Checkbox | Background color of the checkboxes within the Klarna Checkout iframe. |
| Checkbox Checkmark | Color of the checkbox checkmark within checkboxes inside the Klarna Checkout iframe. |
| Header | Color of headlines / titles within the Klarna Checkout iframe. |
| Link | Color of links within the Klarna Checkout iframe.  |
| Border Radius  | With this setting, you can specify the degree of rounding of the Klarna Checkout Iframe. |
**Hint:** Clicking in one of the color fields opens a comfortable color picker, so that the hexadecimal color code is automatically entered into the field. The radius setting has an immediate effect on the input field itself, so that you have a direct idea of what the selected radius looks like in the front end.

Here's how the input of color values in the above fields affects the shop frontend:

{{:public:faq:klarna-en:design-1.png?nolink&600|}}
{{:public:faq:klarna-en:design-2.png?nolink&600|}}

=== Klarna Payment Design Options ===
With these settings you can customize the Look'n'Feel of the Klarna Payment options according to your shop layout. Just leave the fields empty to use the Klarna standard color scheme.
| Border | Color of the frame, which appears in the shop frontend in the case of various available sub-options after selecting the Klarna payment method. |
| Border selected  | Color of the frame, which appears in the shop frontend in the case of various available sub-options after selecting the Klarna payment method. This color value is used to highlight the currently active sub-option. |
| Button | This setting has no effect at the time of publishing this module. |
| Button Text  | This setting has no effect at the time of publishing this module. |
| Checkbox | Background color of the radio-buttons, which appear in the shop frontend in the case of various available sub-options after selecting the Klarna payment method |
| Checkbox Checkmark | This setting has no effect at the time of publishing this module. |
| Details  | Color of bullets in the presentation of payment details on the payment methods selection page. |
| Header | This setting has no effect at the time of publishing this module. |
| Link | Color of the links within the detail description of the payment methods on the payment methods selection page. |
| Text | Text color of the detailed description of the payment methods on the payment methods selection page. |
| Secondary Text | Alternative text color of the detailed description of the payment methods on the payment methods selection page. |
| Border Radius  | With this setting, you can specify the degree of rounding of the frame, which appears in the shop frontend after selecting the Klarna payment method in case of different available sub-options. |
**Hint:** Clicking in one of the color fields opens a comfortable color picker, so that the hexadecimal color code is automatically entered into the field. The radius setting has an immediate effect on the input field itself, so that you have a direct idea of what the selected radius looks like in the front end.

Here's how the input of color values in the above fields affects the shop frontend:

{{:public:faq:klarna-en:design-3.png?nolink&800|}}

==== External Payment Methods / External Checkouts ====
If you run your online shop in the operating mode "Klarna Checkout", you can integrate further external payment methods and external checkouts in addition to the conventional Klarna payment methods into the Klarna Checkout Iframe.

==== External Payment Methods ====
The Klarna Checkout and Klarna Payments Module for the OXID eShop already contains the implementation for the use of the following external payment methods, which are available in the standard functional scope of the OXID eShop:
  * COD (cash on delivery)
  * cash in advance
This means that if you Activate "COD (cash on delivery)" as an external payment method, then your customers can use the Klarna Checkout in the shop frontend and choose "COD (cash on delivery)" as payment method directly within the Klarna Checkout Iframe.
The advantage is that even in the case of such COD order as a guest, the address data are automatically filled in, if:
a) customer has paid using Klarna before and the same browser of the customer was recognized again by a cookie, \- OR -
b) customer has paid using Klarna before and the customer is recognized by Klarna after entering his e-mail address and postal code.
Other external payment methods can be added by custom module. See chapter "Modules for external payment methods and checkouts".

{{:public:faq:klarna-en:extern-zahlmethoden.png?nolink&400|}} 

==== External Checkouts ====
In contrast to the external payment methods, external checkouts are already displayed even before the customer has entered data into the Klarna Checkout iframe. Corresponding buttons are displayed at the bottom of the iframe with the note "Checkout with ...":
External checkouts are e.g. Amazon Pay and PayPal.
These can be supplemented by module. See chapter "Modules for external payment methods and checkouts".

{{:public:faq:klarna-en:extern-checkout.png?nolink&600|}}

==== Modules for External Payment Methods and Checkouts ====
The following modules can be used together with the Klarna Checkout and Klarna Payments Module for the OXID eShop:
  * Amazon Pay & Login 4 OXID provided by best it GmbH & Co. KG
  * PayPal Modul provided by OXID eSales AG
Both modules provide functionalities that enable Amazon Pay or PayPal to be activated as "external payment method" and / or "external checkout" in your online shop.

=== Add custom External Payment Methods or Checkouts ===
There is also the option for developers to add other payment methods with additional external payment methods or external checkouts. Please note that these have to be consistent with the contracts between you and Klarna.
The integrations for cash in advance, COD (cash on delivery), Amazon Pay and PayPal contained in the package scope of the present Klarna Checkout and Klarna Payments Module for the OXID eShop can be used as a template.
Extend the Controllers / KlarnaOrderController.php and add appropriate actions for your new payment methods in the methods klarnaExternalCheckout () or klarnaExternalPayment ().
Moreover, you have to add the name of your new payment method by extending the core / KlarnaConsts.php in the method getKlarnaExternalPaymentNames (). Only names approved by Klarna may be used.
If you are interested, contact your Klarna Integration Manager.

=== Settings for External Payment Methods and External Checkouts ===
On the Klarna page "External Payment Methods" in OXID admin backend, you will find all the OXID payment methods that you have set up and activated in the Shop Settings -> Payment Methods section.
For each payment method you can now make the following settings:
| Payment method  | Assign this external payment method to one of the predefined payment methods. More payment methods can be added to this list by developers, see chapter “Add custom External Payment Methods or Checkouts” |
| External Payment Method | With this switch, you activate this payment method as an external payment method for the Klarna Checkout. If active, the customer can select this payment method from the list of payment methods in the Klarna Checkout iframe. | 
| External Checkout | With this switch, you activate this payment method as an external checkout. If active, this payment method will be displayed at the very bottom of the Klarna Checkout iframe before entering customer data. | 
^ Language-specific settings  ^ Define image URIs for each shop language. To do this, select the respective language from the "In Language" drop-down. ^ 
^ Image URI external payment method  | Enter here the URL to an image which should be displayed next to the payment method in the Klarna Checkout Iframe. You ideally use a picture from a secure URL that starts with https: //.  Image dimensions: 69x24 Pixel |
^ Image URI external checkout | Enter here the URL to an image that should be displayed as a button for this payment method in the Klarna Checkout Iframe below. You ideally use a picture from a secure URL that starts with https: //.  Image dimensions: 276x48 Pixel | 
This is where the images for External Payment Methods and External Checkouts are displayed inside the Klarna Checkout Iframe:

{{:public:faq:klarna-en:extern-zahlmethode-bilder.png?nolink&nolink&600|}} {{:public:faq:klarna-en:extern-zahlmethode-bilder2.png?nolink&600|}}

==== Klarna Extra Merchant Data (Attachments) ====
Activate the functions on this page only if instructed by your Klarna Integration Manager.

Klarna Extra Merchant Data is defined as additional information about your customers, which may be automatically transferred from your shop to Klarna and required by Klarna for a better risk assessment.
With "Customer Account Info" information about the customer account is transmitted to Klarna: When was the account created, when was it last updated.

The "Payment History Full" transmits data about the number and sums of a customer's purchases, the date of the first and last purchase and the method of payment used. If you want to transfer this information to Klarna, you'll have to assign each payment method defined in your OXID eShop to the corresponding payment method type accepted by Klarna and if and how these orders should be reported as paid to Klarna.

=== Metadata ===
With the help of the pass-through field "merchant_data" you can transfer individual additional information about an order to Klarna. You can access this data later via API every time the order data from Klarna is retrieved. You can use this field e.g. to transmit a simple string or a complex JSON structure (also represented as a string) to Klarna.

If the appropriate switch is set in the admin backend, the getPassThroughField () method of the KlarnaPassThrough class is executed. By default, this class returns an empty response. In order to transfer individual information to Klarna, this class must be overloaded with the help of a custom module.

This is the easiest way to submit additional information to Klarna. For details, see the developer documentation.

Here is an example of an individual extension module:
<code>class your_module_pass_through extends your_module_pass_trough_parent
{
 public function getPassThroughField()
  {
  $mainData = „any custom string“;
  return $mainData; 
 }
}</code>
You'll also have to register your module using the Metadata.php in your shop.

=== More Attachments ===
Another, somewhat more complex way to submit additional information to Klarna is to extend the Klarna module with an individual module to submit additional information packages such as travel, event, voucher or subscription to Klarna.

Here is an example of an individual extension module:
<code>class your_module_klarna_emd extends your_module_klarna_emd_parent
{
 public function getAttachments($oxUser)
  {
  $mainData = parent::getAttachments($oxUser);
  $myEMDData = array('your_custom_info' => 
 array('example_field' => 'example data')
 );
  return array_merge($mainData, $myEMDData); 
 }
}</code>

You'll also have to register your module using the Metadata.php in your shop.

==== Configuration of Payment Methods in OXID Shop Settings ====
In the OXID shop admin settings on the page “Shop Settings” -> "Payment Methods" you will also find the Klarna payment methods, which you can assign individually to different countries and user groups. So that the Klarna payment methods can be used in the shop, you must assign them as usual in the OXID eShop, also according to the desired shipping methods

Please only assign those countries to Klarna payment methods, for which you have signed a contract with Klarna.

**Important:** \\
You are not allowed to use the field "Price increase / discount" for Klarna payment methods.

**Do not assign user groups to Klarna Checkout when allowing guest orders**\\
As the Klarna Checkout is also displayed to guest users before registration or login takes place, the payment method "Klarna Checkout" must not be restricted to any user groups. \\
The following also applies to the Shipping Methods and Shipping Cost Rules: There has to be at least one Shipping Method and one Shipping Cost Rule which are not restricted to any user groups.

==== Multilingualism ====
If you offer other languages in your shop more than German and English, then you have to copy the supplied language files (such as "de/klarna_lang.php") into the other language folders and adapt and translate them accordingly. The Klarna Checkout and Klarna Payments Module for the OXID eShop is generally only delivered with the language support for German and English. By translating the provided *lang* files, delivered within the present package, you can supplement any languages.

Remember that in the shop admin area, the payment methods themselves must be translated too. To do this, go to the admin backend page “Shop Settings” -> “Payment Methods” and then press the "In language ... Copy" button for all Klarna payment methods.

The recommended terms and descriptions for payment methods in other languages can be found here: [[https://brand.klarna.com/#/merchant-partners|https://brand.klarna.com/#/merchant-partners]]

==== Klarna On-Site Messaging ====
Customers are not always aware of the various credit and financing options available to them before they reach the checkout. Financing options available at an early stage influence the purchase decision. On-site messaging is simple and easy to integrate and offers tailor-made information that ranges from general banners to promoting your partnership with Klarna and the availability of instalment payments to personalized credit campaigns on product or shopping cart pages.

Select the "On-Site Messaging" link under the "Klarna" menu item in your shop admin backend for more information and step-by-step instructions for setting up and configuring.

==== If you are using standard Themes ====
If you use one of the themes / template sets supplied by OXID eShop as standard, then the placement codes that you can store in the admin area are inserted directly at the appropriate position within the template.
The following screenshots show what the different placements look like in practice when using standard themes.
| **Credit Promotion product details page:** | The credit promotion is inserted below the shopping cart button on the item details page. A corresponding instalment payment is offered based on the product price. | {{:public:faq:klarna-en:theme-standart-credit-promo-proddetail.png?nolink&800|}} |
| **Credit Promotion Basket Page:** | This promotion is displayed on the shopping cart page - the calculated instalment rate refers to the purchase of the entire shopping cart content. |{{:public:faq:klarna-en:theme-standart-credit-promo-warenkorb.png?nolink&800|}} |
| **Top-strip Promotion:** | This promotion appears at the top of the shop homepage. |{{:public:faq:klarna-en:theme-standart-credit-promo-starttop.png?nolink&800|}} |
| **Banner Promotion:** | A banner promotion appears between the "Our brands" and "Just arrived" sections on the shop homepage: | {{:public:faq:klarna-en:theme-standart-credit-promo-banner.png?nolink&800|}} |

===  If you are using custom themes ===
If you use highly modified or completely individual templates, you can of course insert the placement tags that you receive in the Klarna merchant portal directly into the desired position in your templates. Visually, you can use the screenshots shown above to orientate yourself to individual integration.
Please note that the JavaScript tag must always be included on the respective page on which a placement tag is to be used.
However, if you want to maintain the placement tags via the admin area, you would have to accept the corresponding placeholders, which are now anchored in different template blocks, at the desired locations.
You can find placeholders for placement tags in the following files:
| Credit Promotion product details page: | views/blocks/productmain_details_productmain_tobasket.tpl |
| Credit promotion basket page:  | views/blocks/basket_checkout_basket_next_step_top.tpl |
| Top-strip promotion:  | views/blocks/header_main.tpl |
| Banner Promotion: | views/blocks/start_widget_manufacturer.tpl |
Even here the JavaScript tag must be placed on the respective page.

----

===== Shipping Sets =====
Under the menu item „Shipping Sets“ in the Klarna area of the admin backend you'll find the assignment of shipping sets to the predefined Klarna shipping methods for Klarna Checkout.

This configuration enables you to tell Klarna that for instance your shipping set created in OXID eShop for „Pick up“ corresponds with the Klarna shipping method „PickUpStore“. This matching of OXID shipping sets to Klarna shipping methods can be assigned here once for all sets.

The assignment is optional. You can leave the selection empty if you like. A detailed assignment however simplifies risk checks and customer service for Klarna.

If you want to offer DHL Packstation deliveries an assignment as described below is required though:

==== DHL Packstation ====
The shipping set assignment is used to configure which of your shipping sets are DHL shipping sets allowing deliveries to DHL Packstations. If you won't offer this, please choose „Postal“. To offer Packstation delivery choose „Postal + DHLPackstation“. 

----

===== Ordermanagement =====
==== Manage Klarna orders from the OXID admin backend ====
After installing the Klarna Checkout and Klarna Payments Module for the OXID eShop, a new tab "Klarna" appears in the "Administer Orders" section after selecting a corresponding Klarna order.

{{:public:faq:klarna-en:ordermanagment.png?nolink&800|}}

=== Capture an order ===
During the ordering process in the shop, a corresponding Klarna reservation is created for the respective customer and the creditworthiness is checked. In order to be paid for orders, you must inform Klarna when you have shipped the goods. 

You can do this via the OXID Admin section by clicking on the "Capture complete order" button on the Klarna tab. A "capture" thus activates the claim at Klarna and thus leads, for example, to the debit, if paid by credit card.

Even if you click on the tab "Overview" or "Main" on "Send now", the shop automatically sends a "Capture" to Klarna in the background.

=== Ordermanagement from OXID Admin Backend ===
Changes to the order made via the OXID Admin backend (e.g., adding and deleting items and discounts) will also be transferred to Klarna, if possible.

Regardless of the Klarna Checkout and Klarna Payments Module for the OXID eShop, unfortunately there are some known problems in OXID eShop when processing orders via the OXID Admin Backend:

Bundled products will be deleted from their orders after using forms in order_main or order_article https://bugs.oxid-esales.com/view.php?id=5610

Discount removed from orderitem when adding another discount in oxid admin backend https://bugs.oxid-esales.com/view.php?id=6807

We therefore recommend that you refrain from making extensive adjustments to orders using OXID Admin Backend. Only perform the standard processes such as "Capture complete order" or "Cancel order". Since module version 5.4.0 even the full refund of a previously fully captured order can be triggered from the OXID admin backend. All other necessary adjustments to orders and also e.g. partly returns can be carried out conveniently via the Klarna portal.

In the color "green" you will see whether the data of the order in the OXID eShop and in the Klarna Portal match. In case of deviations, you may check the status directly in the Klarna Portal, because only the data there is decisive.

=== Update address ===
In the OXID Admin backend the update of addresses is blocked for all orders that were made via a Klarna payment method, because the risk check was only valid for the address entered by the customer during the online purchase.

=== Klarna API and connecting ERP systems ===
The Klarna API can also be used to connect various order  management or logistics solutions, so "Capture" messages would be transferred to Klarna upon shipment and "Refund" messages upon returns.

----

===== Template Modifications =====
The installation of the Klarna Checkout and Klarna Payments Module for the OXID eShop has numerous effects on the frontend of the online shop.

If you use the OXID Flow or Wave Theme, then the Klarna customizations are automatically inserted via the OXID template blocks.

However, if you use an individual or customized theme in which the OXID template blocks have been changed or deleted, we recommend that you use the following screenshots from the OXID Flow Theme to check whether all Klarna functions have been correctly integrated in your online shop.

The following adjustments apply to both operating modes "Klarna Checkout" AND "Klarna Payments":

==== Footer ====
On the bottom right in the footer, the Klarna logo can be displayed if desired - or in Klarna checkout mode, depending on the setting in the "Design Settings" section, alternatively the Payment Method Display in different colors and sizes:

{{:public:faq:klarna-en:template-footer.png?nolink&800|}}

==== Products details page ====
This modification only affects the operating mode "Klarna Checkout":
Depending on the setting in the "Design Settings", the "Buy Now" button will also be displayed here:

{{:public:faq:klarna-en:template-detail.png?nolink&800|}}

==== Add to cart popup ====
This modification only affects the operating mode "Klarna Checkout":
When an item is added to the shopping cart, a corresponding pop-up window can be shown. In this popup, the Klarna Checkout and Klarna Payments Module for the OXID eShop adds an additional "Checkout" button that leads directly to the Klarna checkout page.

{{:public:faq:klarna-en:template-warenkorb-overlay.png?nolink&800|}}

==== Account Registration and Login ====
This modification only affects the operating mode "Klarna Checkout":
On all pages where a login to the OXID eShop customer account is possible, or the entry of customer data is possible, an additional privacy notice must be inserted for shops that are active in Germany or Austria. This is required because when entering the e-mail address and password on the next page, the Klarna Checkout Iframe is automatically filled with the customer data stored in the online shop. The customer must be informed in advance that his data will be transmitted from the online shop to Klarna.

In the admin backend of the OXID eShop, you activate the items "Pre-filling" and "Pre-filling note" on the page "Configuration".

Example: Open account

{{:public:faq:klarna-en:template-warenkorb-regsitrieren.png?nolink&800|}}

Example: My account

{{:public:faq:klarna-en:template-mein-konto.png?nolink&800|}}

==== Klarna Checkout Page ====
This modification only affects the operating mode "Klarna Checkout":

This page is added by the Klarna Checkout and Klarna Payments Module for the OXID eShop. You will need to apply this page accordingly if you use a custom template set. There are lots of interactive features on this page. Adjustments should therefore only be made by experienced developers, if necessary.

{{:public:faq:klarna-en:checkout.png?nolink&800|}}

====  Payment Selection Page ====
This modification only affects the operating mode "Klarna Payments":
In addition to the conventional OXID eShop payment methods such as "cash on delivery" and "payment in advance", the available Klarna payment methods are automatically displayed here. There are lots of interactive features on this page. Adjustments should therefore only be made by experienced developers, if necessary.

{{:public:faq:klarna-en:checkout-auswahl-zahlart.png?nolink&800|}}

The integration of the Klarna Checkout and Klarna Payments Module for the OXID eShop was minimally invasive at this point, so that even further payment provider third-party modules can easily implement extensions at this point. The payment methods Amazon Pay, PayPal and PAYONE included in the standard OXID package have been checked for compatibility.

==== Order Overview Page ====
This modification only affects the operating mode "Klarna Payments":
In the field "Payment method" the logo of the selected payment method is displayed:

{{:public:faq:klarna-en:checkout-pruefen.png?nolink&800|}}

==== Order Confirmation Mail ====
Even in the order confirmation mail the logo of the chosen Klarna payment method is inserted:

{{:public:faq:klarna-en:checkout-mail-bestaetigung.png?nolink&400|}}

===== Validation and confirmation at Klarna Checkout =====
After submitting the Klarna Checkout order, Klarna will send a notification to the online shop. First, a call is made to the so-called validation URL (Klarna field merchant_urls.validation, by default in this module: index.php?cl=KlarnaValidate). This validation once more checks the stocks and availabilities.
This validation call can be deactivated in the shop admin backend on the page Klarna -> Configuration with the option “Order validation”. This may accelerate the waiting time at the time of purchase, however, stocks and price changes are then no longer checked.

After successful completion of the Klarna checkout transaction, the customer is then forwarded to the confirmation URL (Klarna field merchant_urls.confirmation, by default in this module: index.php?cl=order&fnc=execute). The shop then creates the order in the OXORDER table and then redirects to the thank-you page of the shop.

If this forwarding to the confirmation URL fails for any reason, the order will not be created in the OXID eShop.

Then another call from Klarna to the push URL in the shop (Klarna field merchant_urls.push, by default in this module: index.php?cl=KlarnaAcknowledge) is made. The result of calling this controller is that the OXID eShop checks once again whether the order has been created and saved properly in the OXID eShop. If successful, the shop sends another confirmation to Klarna. Otherwise the shop will send a cancellation for this order to Klarna.

**Important** In order for these calls to arrive at the shop and be processed, the shop must be accessible on the one hand via the internet without password protection and on the other hand, both the validation URL and the push URL have to begin with <nowiki>"https: //"</nowiki>. Please pay attention to the chapters "SSL encryption" and "Availability of the shop from the internet" in this manual.

----
 
===== Updates of this module ======
Updates of the Klarna Checkout and Klarna Payments module for OXID eShop are published on Github. You can see the current version status of your installed module by clicking "Start" in the "Klarna" section of the OXID Admin area.

Github repository: https://github.com/FATCHIP-GmbH/OXID-Klarna-6/releases
----

===== Support for this module =====
If necessary, you get support for installation, configuration, or in the daily operation of your module directly from Klarna.

While you are integrating Klarna please contact your personal Klarna integration manager, or if no technical contact has been assigned to you by Klarna, please contact [[oxid@klarna.com|oxid@klarna.com]]..
If you are already processing Klarna transactions, please contact Klarna Merchant Support at [[shop@klarna.de|shop@klarna.de]].
Fatchip GmbH Wiki

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Seiten-Werkzeuge
