OXID eShop Dokumentation / Manual

Lizenz: Copyright © 2024 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. 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.

This plugin allows you to add the payment methods provided by Klarna to your OXID eShop.

The payment methods provided by Klarna are listed on the payment method selection page, as is normally the case in the OXID eShop. You can choose between three different options:

For your own safety, we recommend that you create a data backup of both the store files and your Mysql database before you start the installation, so that you can fall back on the previous version in the event of a problem.

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

• Community Edition: Version 7.0.x - 7.5.x
• Professional Edition: Version 7.0.x - 7.5.x
• Enterprise Edition: Version 7.0.x - 7.5.x

Please verify that you have the appropriate package for your OXID eShop version.
Do not install this module version if you are using a different shop version!

The Klarna Checkout and Klarna Payments module for OXID eShop is operational and tested with PHP 8.0 through PHP 8.5.

You can find the current version number of the OXID 7 Klarna Payments Plugin at https://github.com/FATCHIP-GmbH/OXID-Klarna-7/releases

To update the OXID 7 Klarna Payments Plugin, follow these steps:

• Log in to your server via sFTP/FTP and navigate to the shop's root directory
• Open composer.json and change the specified version to the version you want to update to
  
• Log in to the command line (CLI) and navigate to the shop's root directory
• Execute the following command:
  

  composer update

The server on which the Klarna Payments module for OXID eShop will be used must naturally meet the OXID server and system requirements: https://docs.oxid-esales.com/eshop/de/7.1/installation/neu-installation/server-und-systemvoraussetzungen.html

To use the Klarna Payments module for OXID eShop, the shop must have an SSL certificate.

Note: It doesn't matter whether it's an official or self-signed SSL certificate.

Klarna sends requests to your OXID eShop for transaction validation.

For such callback requests from Klarna to your shop to work, your shop must be freely accessible from the internet. This means there should be no password protection, IP restrictions, or firewall protection active in your shop that would prevent Klarna from accessing the necessary validation URLs.

Keep this in mind especially if you want to test in your development or staging environment: HTTPS requests from external Klarna servers to port 443 of your server must be allowed.

The article numbers in the OXID ARTICLES.OXARTNUM field must always be unique in the shop (for Enterprise Edition, only within the respective subshop ID). The Klarna Payments module for OXID eShop sends these article numbers to Klarna for validation during the ordering process. If there are multiple order lines with articles or variants having the same article number in an order, the order cannot be created.

The Klarna Payments module for OXID eShop provides Klarna payment methods for the following countries: SE, NO, FI, DE, AT, CH, NL, UK, BE, IT, ES, FR, DK, IRL

Please ensure that you only activate Klarna payment methods in countries where you have corresponding contracts with Klarna.

There are some special features in the Klarna Payments module for OXID eShop, as well as some Klarna features that have not yet been implemented with the Klarna Payments module for OXID eShop. Please check before using this module whether these features might be relevant for you:

• Pending Flow: The current module assumes that orders are either immediately accepted or immediately rejected by Klarna. However, the Klarna Pending status is not supported. This must be considered when configuring the Merchant ID with Klarna.
• Refunds/Returns: Credits for previously debited payments cannot be sent to Klarna via the OXID Admin Backend. Please use the Klarna Merchant Portal for this. On the „Klarna“ tab of each Klarna order, you'll find a link that takes you directly there.
• Gift Cards: Klarna understands these as monetary vouchers that can be purchased in a retail store, for example. Such functionality is currently not offered by OXID eShop.
• Vouchers: OXID promotion vouchers are transmitted to Klarna as „Discounts“.
• Partial Captures: It is not possible to transmit partial deliveries to Klarna via the OXID Admin Backend. Please use the Klarna Merchant Portal for this. On the „Klarna“ tab of each Klarna order, you'll find a link that takes you directly there.
• B2B Support: Business orders are technically implemented in the module but are only contractually activated by Klarna in exceptional cases for individual countries. Please contact your Klarna Account Manager for more information on whether B2B is available for your sales countries. In the Klarna Checkout area, a company name can be entered, which is saved as a „c/o specification“. The integration of Billie for B2B orders is planned.
• The automatic debiting of orders directly upon order completion has not been implemented in this Klarna Checkout and Klarna Payments module for OXID eShop.
• Localization: If a customer in a German shop with German shop frontend language selects Japan as the delivery country in the Klarna Checkout Global Iframe, the language of the iframe remains German.
• Please check whether you have set telephone number or date of birth as mandatory fields under Admin > Master Settings > Core Settings > Settings > Additional Settings > „Must“ fields for customer registration. If you require any of these fields, make sure you also set these fields as mandatory in the Klarna Checkout configuration. Otherwise, orders may be cancelled due to incomplete data.

To set up the Klarna module in your shop, please execute the following steps in the specified order.

• Log in to the command line (CLI) and navigate to the shop's root directory
• Execute the following command:
  

  composer require fatchip-gmbh/oxid-klarna-7

• Log in to your OXID eShop's admin area
• Activate the plugin Go to „Extensions“ → „Modules“ → „Klarna Payments“ → „Main“ and click „Activate“

Assign the newly created Klarna payment methods under „Shop Settings“ → „Shipping Methods“ to the corresponding shipping methods, just as you would do for other payment methods in OXID eShop.

If you are using the OXID Enterprise Edition, please repeat steps 2 and 3 for each individual subshop.

In the eShop Admin main menu, the new „Klarna“ section appears on the left with several sub-menu entries:

Here you'll find some information about Klarna:

On this page, you make various settings.

For more information, you can also find tooltip help in the shop by clicking on the question mark icon behind each setting.

At the bottom of each page, you'll always find the „Save“ button. Remember to always save your settings so they are applied to the system.

Here you can select which Klarna Payments you want to offer:

Activate the functions on this page only if instructed to do so by your Klarna Integration Manager.

Klarna Extra Merchant Data refers to additional information about your customers that may be automatically transmitted from your shop to Klarna and is required by Klarna for better risk assessment.

Customer Account Info transmits information about the customer account to Klarna: When was the account created, when was it last modified.

Payment History Full transfers information about the number and amounts of a customer's purchases, the date of the first and last purchase, and the payment method used. If you transmit this information to Klarna, please assign once for each payment method in the shop what type of payment method it is and whether and how these orders should be reported as paid to Klarna.

With the help of the Pass-through Field „merchant_data“, you can transfer individual additional information about an order to Klarna if needed. You can later access this data via API whenever retrieving the order data from Klarna. You can transmit a simple string or even a complex JSON structure as a string to Klarna in this field.

If the corresponding switch in the Admin Backend is set, the getPassThroughField() method of the KlarnaPassThrough class is executed. This class returns an empty response by default. To transmit corresponding individual information to Klarna, this class must be overloaded using a custom module.

This is the simplest way to transmit additional information to Klarna. You can find more details in the developer documentation.

Here is an example for a custom extension module:

class your_module_pass_through extends your_module_pass_trough_parent
{
 public function getPassThroughField()
 {
 $mainData = "any custom string";
 return $mainData;
 }
}

You must make your module known in your shop via the Metadata.php.

Another, somewhat more complex way to transmit additional information to Klarna is to extend the Klarna module with a custom module to transmit additional information packages like Travel, Event, Voucher, or Subscription to Klarna.

Here is an example for a custom extension module:

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);
 }
}

You must make your module known in your shop via the Metadata.php.

Customers are not always aware of the various credit and financing options available to them before reaching the checkout. Early available financing options influence the purchase decision. On-Site Messaging is easy and seamless to integrate and provides tailored information ranging from general banners to promoting your partnership with Klarna and the availability of installment payments to personalized credit promotions on product or shopping cart pages.

Select the „On-Site Messaging“ link under the „Klarna“ menu item in your shop admin backend to receive more information and step-by-step instructions for setup and configuration.

If you use one of the themes/template sets supplied standard with OXID eShop, then the placement codes that you can store in the admin area will be inserted directly at the corresponding position in the template. How the different placements look in practice when using standard themes can be seen in the following screenshots:

Credit Promotion Product Detail Page	Below the shopping cart button on the product detail page, the credit promotion is inserted. Based on the product price, a corresponding installment payment is offered.
Credit Promotion Shopping Cart	This promotion is displayed on the shopping cart page – the calculated rate refers to the purchase of the entire shopping cart contents via installment payment.
Top-strip Promotion	This promotion appears at the very top of the shop homepage.
Banner Promotion	Between the „Our Brands“ and „Just Arrived“ sections on the shop homepage, a banner promotion appears:

If you use heavily modified or completely individual templates, you can of course also insert the placement tags that you receive in the Klarna merchant portal directly at the desired location in your templates. For the individual integration, you can use the screenshots shown above as a visual reference.

Please note that on each page where a placement tag is to be used, the JavaScript tag must also be included.

However, if you want to manage the placement tags through the admin area, you would need to adopt the corresponding placeholders that are now anchored in various template blocks at the desired locations.

You can find placeholder for placement tags in the following files:

The JavaScript tag must also be placed on each respective page.

After installing the Klarna Checkout and Klarna Payments module for OXID eShop, a new „Klarna“ tab appears in the „Orders“ section when selecting a corresponding Klarna order.

During the ordering process in the shop, a corresponding Klarna reservation is created for the respective customer and their creditworthiness is checked. To be paid out for orders, you must inform Klarna when you have shipped the goods. You can do this via the OXID Admin area by clicking the „Capture complete order“ button on the Klarna tab. A „capture“ thus activates the claim with Klarna and therefore also leads to the debit, for example, if payment was made by credit card.

Even if you click on „Ship now“ on the „Overview“ or „Main“ tab, the shop automatically sends a „capture“ to Klarna in the background.

Changes made to the order via the OXID Admin Backend (e.g., adding and deleting articles and discounts) are also transmitted to Klarna where possible.

We recommend avoiding extensive adjustments to orders using the OXID Admin Backend, and instead only using the standard process such as „Capture complete order“ or „Cancel order“. For an order previously completed with „Capture“, a complete „Refund“ is also possible via the OXID Admin Backend. All other necessary adjustments to orders and e.g., the processing of partial returns can be conveniently made via the Klarna Portal.

The color „green“ indicates whether the order data in the OXID eShop and in the Klarna Portal match. In case of discrepancies, check the status directly in the Klarna Portal if necessary, as only the data there is decisive.

In the OXID Admin Backend, subsequent editing of addresses is blocked for all orders made via a Klarna payment method, as the risk assessment was only valid for the address provided during the online purchase.

Various merchandise management or logistics solutions can also be connected via the Klarna API to automatically transmit „Capture“ messages when goods are shipped and corresponding „Refund“ messages to Klarna for returns.

Updates of the Klarna Payments module for OXID eShop are published on Github. You can see the current version status of your installed module by clicking on „Start“ in the „Klarna“ section in the OXID Admin area.

Github Repository: https://github.com/FATCHIP-GmbH/OXID-Klarna-7/releases

If needed, you can receive support with the installation, configuration, or daily operation of your module directly from Klarna.

As long as you are still in the integration phase, please contact either your personal Klarna Integration Manager, or if you have not been assigned a technical contact from Klarna, please contact oxid@klarna.com.

If you are already in live operation with Klarna, please contact Klarna Merchant Support for assistance and support at shop@klarna.de.