Introduction

Order Management is part of both plugins: Klarna Payments and Klarna Checkout. The Order Management module bundles components needed by both plugins: The handling of Klarna orders within the Shopware backend.

Usage and operation

Klarna tab in the order

In the Klarna tab in the order details you will find an overview of the Klarna order as well as various actions.

Capture amount manually

You can capture an amount by clicking on the "Capture amount" button. A new window will be displayed where you can specify the amount, the positions and a comment.

The selection of items is optional, you can also enter an amount manually. In this case, however, Klarna does not receive the information about which items have already been captured. Therefore, we always recommend to make the entry via the item selection.

The comment is also optional and serves to clarify why an amount was captured. For example, "Item XY was not captured because it was out of stock."

Once you have selected the desired items and the desired amount, you can capture the amount by clicking "Capture Amount".

You will now be asked if you want to perform the capture.

Confirm the action by clicking on the "Proceed" button. In case of error or success, a corresponding message will be displayed.

Refund amount manually

You can refund an amount by clicking on the "Refund amount" button. You will now see a new window where you can specify the amount, items and a comment.

The selection of items is optional, you can also enter an amount manually. However, in this case Klarna will not receive the information which items have been refunded. Therefore, we always recommend to make the refund via the item selection.

The comment is also optional and serves to clarify why an amount was refunded. For example, "Item XY was refunded because it was out of stock."

Once you have selected the items you want and the amount you want, you can refund the amount by clicking "Refund Amount".

You will now be asked if you would like to refund.

Confirm the action by clicking on the "Proceed" button. In case of error or success, a corresponding message will be displayed.

Manually extend authorization

You can extend the authorization of a payment by clicking on the "Extend Authorization" link.

You will now be asked if you really want to extend the authorization.

Confirm the action by clicking on the "Proceed" button. In case of error or success, a corresponding message will be displayed.

Release remaining amount manually

You can release (unauthorize) the remaining amount by clicking on the "Release" link.

You will now be asked if you really want to release the remaining amount.

Confirm the action by clicking on the "Release" button. In case of error or success, a corresponding message will be displayed.

Resend invoice manually

You can resend an invoice per captured amount. To get an overview of all recorded amounts, click on the Details link.

You will now see an overview of all the amounts captured and a "Resend invoice" button for each. If you want to resend the invoice for a captured amount, click the "Resend invoice" button under the captured amount.

You will now be asked if you really want to resend the invoice.

Confirm the action by clicking on the "Proceed" button. In case of error or success, a corresponding message will be displayed.

Order history

The order history lists all actions that were performed for the order.

The following messages may appear:

Example of a dialog with further information about an action.

Cancel order manually

An order can be canceled only if no amount has been entered yet.

To cancel an order click the "cancel order" button.

You will now be asked if you really want to cancel the order.

Confirm the action by clicking on the "Proceed" button. In case of error or success, a corresponding message will be displayed.

Once an order is cancelled, no further action can be performed on that order.

Automatic changes

Defined changes to an order will automatically trigger actions at Klarna.

Payment status

The payment status is automatically set by Klarna for certain actions.

Address changes

When changing the address of an order in the backend, the new data is first transferred to Klarna. Only if Klarna accepts the new address, it will be updated in Shopware. This ensures that the new address has been accepted by the Klarna risk check.

Changes to the order

When changes are made to an order (e.g. positions), the new data is first transferred to Klarna. Only if Klarna accepts the new order, it will be updated in Shopware. This ensures that the new data has been accepted by the Klarna risk check.

Changes that increase the Authorized Amount are generally rejected.

Shipment number

When changing the shipment number, it will be transferred to Klarna. For multiple shipment numbers, please refer to the respective plugin configuration for shipment number separator.

Change payment type

Changing the payment type from one Klarna payment type to another can only be done if no amount has been entered yet. In this case the order will be automatically cancelled by Klarna.

Delete order

An order can be deleted only if no amount has been captured yet. In this case the order will be automatically cancelled by Klarna.

Extending the plugin

Order Management components are designed to be used not only by both Klarna plugins but also by your individual plugin. For easier control we have provided facades.

Partly the components need the Klarna-Order-Id. This is stored as the transaction ID of an order in Shopware.

Facades

Retrieve order

To retrieve an order, you need the BestitKlarnaOrderManagement\Components\Facade\Order facade. Through it, you can call the get method, which retrieves an order from Klarna.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->get('klarna-order-id');
    }
}

Capture amount

To capture an amount, you need the BestitKlarnaOrderManagement\Components\Facade\Capture facade. Through it, you can call the create method, which captures an amount.

You can also give the method the items as JSON, a comment and shipping information.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Capture as CaptureFacade;

class Example
{
    /** @var CaptureFacade */
    protected $captureFacade;

    public function __construct(CaptureFacade $captureFacade)
    {
        $this->captureFacade = $captureFacade;
    }

    public function example()
    {
        $betragInCents = 500;
        
        $klarnaResponse = $this->captureFacade->create('klarna-order-id', $betragInCents);
    }
}

Refund amount

To refund an amount, you need the BestitKlarnaOrderManagement\Components\Facade\Refund facade. Through it, you can call the create method, which will refund an amount.

You can give the method the items as JSON)and a comment.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Refund as RefundFacade;

class Example
{
    /** @var RefundFacade */
    protected $refundFacade;

    public function __construct(RefundFacade $refundFacade)
    {
        $this->refundFacade = $refundFacade;
    }

    public function example()
    {
        $betragInCents = 500;

        $klarnaResponse = $this->refundFacade->create('klarna-order-id', $betragInCents);
    }
}

Update order

To update an order, you need the BestitKlarnaOrderManagement\Components\Facade\Order facade. Through it, you can call the updateOrder method, which updates an order.

This method needs the Klarna order id, the new total amount of the order and an Array of BestitKlarnaOrderManagement\Components\Api\Model\LineItem with all items.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Api\Model\LineItem;
use BestitKlarnaOrderManagement\Components\Api\Model\ProductIdentifiers;
use BestitKlarnaOrderManagement\Components\Constants;
use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $lineItem = new LineItem();
        $lineItem->type = Constants::KLARNA_LINE_ITEM_TYPE_PHYSICAL;
        $lineItem->totalTaxAmount = 0;
        $lineItem->totalAmount = 0;
        $lineItem->quantity = 1;
        $lineItem->name = 'Free article';
        $lineItem->productIdentifiers = new ProductIdentifiers(); // ProductIdentifiers are blank intentionally
        $lineItem->taxRate = 0;
        $lineItem->totalDiscountAmount = 0;
        $lineItem->unitPrice = 0;
        $lineItem->quantityUnit = 'Pieces';
        $lineItem->reference = 'SW1000';

        $klarnaResponse = $this->orderFacade->updateOrder('klarna-order-id', 0, [$lineItem]);
    }
}

Extend authorization

To extend an authorization, you need the BestitKlarnaOrderManagement\Components\Facade\Order facade. Through it, you can call the extendAuthTime method which extends an authorization.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->extendAuthTime('klarna-order-id');
    }
}

Release remaining amount

To release the remaining amount, you need the BestitKlarnaOrderManagement\Components\Facade\Order facade. Through it, you can call the releaseRemainingAmount method which will release the remaining amount.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->releaseRemainingAmount('klarna-order-id');
    }
}

Resend invoice

To resend an invoice, you need the BestitKlarnaOrdferManagement\Components\Facade\Capture facade. Through it, you can call the resend method, which resends the invoice.

Since an invoice is created per captured amount, it is also possible to resend an invoice only for a specific captured amount. This requires the capture id which is supplied with the order-call.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Capture as CaptureFacade;

class Example
{
    /** @var CaptureFacade */
    protected $captureFacade;

    public function __construct(CaptureFacade $captureFacade)
    {
        $this->captureFacade = $captureFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->captureFacade->resend('klarna-order-id', 'capture-id');
    }
}

Cancel order

To cancel an order, you need the BestitKlarnaOrderManagement\Components\Facade\Order facade. Through it, you can call the cancel method which cancels the order.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->cancel('klarna-order-id');
    }
}

Cents calculation

By default, Shopware uses decimal numbers as prices (e.g. "3.14"), while Klarna works with cents and thus with whole numbers (e.g. "314"). Therefore, the Shopware prices must be converted to cents before they can be transferred to Klarna.

PHP Calculation

With the standard PHP calculation no extensions are necessary. However, rounding errors may occur.

BcMath calculation

Alternatively, the PHP extension bcmath can be installed on the server. Fewer rounding errors occur here due to internal processing.

Custom calculation

To add a custom calculation, the Decorator Pattern can be used to overwrite or extend the PHP calculation.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Calculator\CalculatorInterface;

class Example implements CalculatorInterface
{
    /** @var CalculatorInterface */
    protected $decoratedCalculator;

    public function __construct(CalculatorInterface $decoratedCalculator)
    {
        $this->decoratedCalculator = $decoratedCalculator;
    }

    public function isSupported()
    {
        return $this->decoratedCalculator->isSupported();
    }

    public function toCents($amount)
    {
        return $amount * 100;
    }

    public function toMajorUnit($amount)
    {
        return $this->decoratedCalculator->toMajorUnit($amount);
    }
}

In the service.xml the new service must then be marked as a decorator:

<service
        class="App\Example\Example"
        id="app.example.example"
        decorates="bestit_klarna_order_management.components.calculator.php_calculator">
    <argument type="service" id="app.example.example.inner"/>
</service>

Position mode

Shopware stores a mode for each position, a kind of internal id, for the differentiation of the position type (e.g. article, discount or voucher). Klarna does not know these internal ids, and so they have to be converted to understandable types for Klarna.

For this we have created a Converter class for each mode, which convert the Shopware mode to a Klarna type. All Converter must implement the BestitKlarnaOrderManagement\Components\Converter\ModeInterface.

Modify converter

In the example, the Converter of mode "2" (Shopware discount voucher) is modified so that it always returns the type gift_card.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Constants;
use BestitKlarnaOrderManagement\Components\Converter\ModeInterface;
use BestitKlarnaOrderManagement\Components\Exception\NoSupportedModeException;

class Example implements ModeInterface
{
    /** @var ModeInterface */
    protected $decoratedConverter;

    public function __construct(ModeInterface $decoratedConverter)
    {
        $this->decoratedConverter = $decoratedConverter;
    }

    public function isSupported($mode)
    {
        return $this->decoratedConverter->isSupported($mode);
    }

    public function convert($mode, $price = null)
    {
        if (!$this->isSupported($mode)) {
            throw new NoSupportedModeException();
        }

        return Constants::KLARNA_LINE_ITEM_TYPE_GIFT_CARD;
    }
}

In the service.xml the new service must then be marked as a decorator:

<service
        class="App\Example\Example"
        id="app.example.example"
        decorates="bestit_klarna_order_management.components.converter.voucher">
    <argument type="service" id="app.example.example.inner"/>
</service>

Other

Automatic Klarna actions

By changing the order status, automatic actions can be performed by the plugin. See also the plugin configuration for this.

Automatic capture

When the order status changes to the configured order status, a full capture is performed automatically.

Automatic refund

When the order status changes to the configured order status, a full refund will be executed automatically.