Einführung

Das Order Management ist Teil von beiden Plugins: Klarna Payments und Klarna Checkout. Das Modul Order Management bündelt Bestandteile die von beiden Plugins benötigt werden: die Handhabung von Klarna Bestellungen innerhalb des Shopware Backends.

Verwendung und Bedienung

Klarna Tab in der Bestellung

Im Klarna Tab in den Bestelldetails finden Sie neben einer Übersicht der Klarna-Bestellungen diverse Aktionen.

Betrag manuell erfassen

Sie können einen Betrag erfassen indem, Sie auf den "Betrag erfassen" Button klicken. Es wird Ihnen nun ein neues Fenster angezeigt, indem Sie den Betrag, die Positionen und einen Kommentar festlegen können.

Die Auswahl der Positionen ist optional, Sie können auch einen Betrag manuell eingeben. In diesem Fall erhält Klarna allerdings nicht die Information, welche Positionen bereits erfasst wurden. Daher empfehlen wir stets, die Erfassung über die Positionsauswahl durchzuführen.

Der Kommentar ist ebenfalls optional und dient Ihnen zur Verdeutlichung, wieso ein Betrag erfasst wurde. Zum Beispiel: "Position XY wurde nicht erfasst, weil diese nicht mehr auf Lager war."

Sobald Sie die gewünschten Positionen und den gewünschten`Betrag ausgewählt haben, können Sie den Betrag erfassen, indem Sie auf "Betrag erfassen" klicken.

Sie werden nun abgefragt, ob Sie die Erfassung durchführen möchten.

Bestätigen Sie die Aktion, indem Sie auf den "Vorgehen" Button klicken. Im Fehler- und Erfolgsfall wird Ihnen eine entsprechende Meldung angezeigt.

Betrag manuell rückerstatten

Sie können einen Betrag rückerstatten, indem Sie auf den "Betrag rückerstatten" Button klicken. Es wird Ihnen nun ein neues Fenster angezeigt, indem Sie den Betrag, die Positionen und einen Kommentar festlegen können.

Die Auswahl der Positionen ist optional, Sie können auch einen Betrag manuell eingeben. In diesem Fall erhält Klarna allerdings nicht die Information, welche Positionen erstattet wurden. Daher empfehlen wir stets, die Rückerstattung über die Positionsauswahl durchzuführen.

Der Kommentar ist ebenfalls optional und dient Ihnen zur Verdeutlichung, wieso ein Betrag erstattet wurde. Zum Beispiel: "Position XY wurde erstattet, weil diese nicht mehr auf Lager war."

Sobald Sie die gewünschten Positionen und den gewünschten Betrag ausgewählt haben, können Sie den Betrag erstatten, indem Sie auf "Betrag rückerstatten" klicken.

Sie werden nun abgefragt, ob Sie die Erstattung durchführen möchten.

Bestätigen Sie die Aktion, indem Sie auf den "Vorgehen" Button klicken. Im Fehler- und Erfolgsfall wird Ihnen eine entsprechende Meldung angezeigt.

Autorisierung manuell verlängern

Sie können die Autorisierung einer Zahlung verlängern, indem Sie auf den "Authorisierung verlängern" Link klicken.

Sie werden nun abgefragt, ob Sie die Autorisierung wirklich verlängern möchten.

Bestätigen Sie die Aktion, indem Sie auf den "Vorgehen" Button klicken. Im Fehler- und Erfolgsfall wird Ihnen eine entsprechende Meldung angezeigt.

Verbleibenden Betrag manuell freigeben

Sie können den verbleibenden Betrag freigeben (Autorisierung aufheben), in dem Sie auf den "Freigeben" Link klicken.

Sie werden nun abgefragt, ob Sie den verbleibenen Betrag wirklich freigeben möchten.

Bestätigen Sie die Aktion, indem Sie auf den "Freigeben" Button klicken. Im Fehler- und Erfolgsfall wird Ihnen eine entsprechende Meldung angezeigt.

Rechnung manuell erneut senden

Sie können eine Rechnung je erfassten Betrag erneut senden. Um eine Übersicht aller erfassten Beträge zu erhalten, klicken Sie auf den Details Link.

Sie sehen nun eine Übersicht aller erfassten Beträge und je erfassten Betrag einen Button "Rechnung erneut senden". Wenn Sie für einen erfassten Betrag die Rechnung erneut senden möchten, klicken Sie den "Rechnung erneut senden" Button unter dem erfassten Betrag.

Sie werden nun abgefragt, ob Sie die Rechnung wirklich erneut senden möchten.

Bestätigen Sie die Aktion, indem Sie auf den "Proceed" Button klicken. Im Fehler- und Erfolgsfall wird Ihnen eine entsprechende Meldung angezeigt.

Bestellhistorie

Die Bestellhistorie listet alle Aktionen auf, welche für die Bestellung durchgeführt wurden.

Folgende Meldungen können auftreten:

Beispiel eines Dialogs mit weiteren Informationen zu einer Aktion.

Bestellung manuell stornieren

Eine Bestellung kann nur storniert werden, wenn noch kein Betrag erfasst wurde.

Um eine Bestellung zu stornieren, klicken Sie den "Bestellung stornieren" Button.

Sie werden nun abgefragt, ob Sie die Bestellung wirklich stornieren möchten.

Bestätigen Sie die Aktion, indem Sie auf den "Vorgehen" Button klicken. Im Fehler- und Erfolgsfall wird Ihnen eine entsprechende Meldung angezeigt.

Sobald eine Bestellung storniert ist, können keine weiteren Aktionen mit dieser Bestellung durchgeführt werden.

Automatische Änderungen

Durch definierte Änderungen an einer Bestellung werden automatisch Aktionen bei Klarna ausgelöst.

Zahlungsstatus

Der Zahlungsstatus wird bei bestimmten Aktionen automatisch von Klarna gesetzt.

Änderungen an den Adressen

Bei Adressänderungen einer Bestellung im Backend werden die neuen Daten zuerst an Klarna übertragen. Nur wenn Klarna die neue Adresse akzeptiert, wird diese in Shopware aktualisiert. So wird sichergestellt, dass die neue Adresse durch den Klarna Risikocheck akzeptiert wurde.

Änderungen an der Bestellung

Bei Änderungen an einer Bestellung (bspw. Positionen) werden die neuen Daten zuerst an Klarna übertragen. Nur wenn Klarna die neue Bestellung akzeptiert, wird diese in Shopware aktualisiert. So wird sichergestellt, dass die neuen Daten durch den Klarna Risikocheck akzeptiert wurden.

Änderungen, die den autorisierten Betrag erhöhen, werden generell abgelehnt.

Sendungsnummer

Bei der Änderung der Sendungsnummer wird diese an Klarna übertragen. Für mehrere Sendungsnummern beachten Sie bitte die jeweilige Plugin-Konfiguration zum Trennzeichen von Sendungsnummern.

Zahlungsart ändern

Das Ändern der Zahlungsart von einer Klarna Zahlungsart zu einer anderen Zahlungsart kann nur ausgeführt werden, wenn noch kein Betrag erfasst wurde. In diesem Fall wird die Bestellung bei Klarna automatisch storniert.

Bestellung löschen

Eine Bestellung kann nur gelöscht werden, wenn noch kein Betrag erfasst wurde. In dem Fall wird die Bestellung bei Klarna automatisch storniert.

Plugin erweitern

Die Komponenten des Order Management sind so entwickelt, dass diese nicht nur von beiden Klarna Plugins, sondern auch von Ihrem individuellen Plugin verwendet werden können. Für die leichtere Ansteuerung haben wir sogenannte "Facaden" bereitgestellt.

Teilweise benötigen die Komponenten die Klarna-Order-Id. Diese wird als Transaktions-Id einer Bestellung in Shopware gespeichert.

Facaden

Bestellung abrufen

Um eine Bestellung abzurufen, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die get Methode aufrufen, welche eine Bestellung von Klarna abruft.

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

Betrag erfassen

Um einen Betrag zu erfassen, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Capture Facade. Über diese können Sie die create Methode aufrufen, welche einen Betrag erfasst.

Sie können der Methode auch die Positionen als JSON, einen Kommentar und Versandinformationen mitgeben.

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

Betrag rückerstatten

Um einen Betrag zu erstatten, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Refund Facade. Über diese können Sie die create Methode aufrufen, welche einen Betrag erstattet.

Sie können der Methode die Positionen als JSON)und einen Kommentar mitgeben.

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

Bestellung aktualisieren

Um eine Bestellung zu aktualisieren, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die updateOrder Methode aufrufen, welche eine Bestellung aktualisiert.

Diese Methode benötigt die Klarna-Order-Id, den neuen Gesamtbetrag der Bestellung und ein Array von BestitKlarnaOrderManagement\Components\Api\Model\LineItem mit allen Positionen.

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

Autorisierung verlängern

Um eine Autorisierung zu verlängern, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die extendAuthTime Methode aufrufen, welche eine Autorisierung verlängert.

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

Verbleibenden Betrag freigeben

Um den verbleibenden Betrag freizugeben, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die releaseRemainingAmount Methode aufrufen, welche den verbleibenden Betrag freigibt.

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

Rechnung erneut senden

Um eine Rechnung erneut zu senden, benötigen Sie die BestitKlarnaOrdferManagement\Components\Facade\Capture Facade. Über diese können Sie die resend Methode aufrufen, welche die Rechnung erneut sendet.

Da eine Rechnung per erfassten Betrag erstellt wird, kann auch nur für einen bestimmten erfassten Betrag eine Rechnung erneut versendet werden. Hierzu wird die Capture Id benötigt, welche bei dem Bestellabruf mitgeliefert wird.

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

Bestellung stornieren

Um eine Bestellung zu stornieren, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die cancel Methode aufrufen, welche die Bestellung storniert.

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

Cent Kalkulation

Standardmäßig verwendet Shopware Dezimalzahlen als Preise (bspw "3,14"), während Klarna mit Cents und somit mit ganzen Zahlen (bspw. "314") arbeitet. Daher müssen die Shopware Preise entsprechend in Cents umgewandlet werden, bevor diese an Klarna übertragen werden können.

PHP Kalkulation

Mit der Standard PHP Kalkulation sind keine Erweiterungen notwendig. Allerdings können hierbei Rundungsfehler auftreten.

BcMath Kalkulation

Alternativ kann die PHP Erweiterung bcmath auf dem Server installiert werden. Aufgrund der internen Verarbeitung treten hierbei weniger Rundungsfehler auf.

Eigene Kalkulation

Mit dem Decorator Pattern kann die PHP Kalkulation überschrieben bzw. erweitert werden, um eine eigene Kalkulation zu ergänzen.

<?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 der service.xml muss dann der neue Service als Dekorator markiert werden:

<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>

Positionsmodus

Shopware speichert einen Modus für jede Position, eine Art interne Id, für die Differenzierung des Positions-Typ (bspw. Artikel, Rabatt oder Gutschein). Klarna kennt diese internen Identifikationen nicht und müssen somit für Klarna in verständliche Typen konvertiert werden.

Dazu haben wir für jeden Modus eine Converter Klasse erstellt, welche den Shopware Modus zu einem Klarna Typ konvertieren. Alle Converter müssen das BestitKlarnaOrderManagement\Components\Converter\ModeInterface implementieren.

Converter modifizieren

In dem Beispiel wird der Converter des Modus "2" (Shopware Rabattgutschein) modifiziert, sodass dieser immer den Typ gift_card zurück gibt.

<?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 der service.xml muss dann der neue Service als Decorator markiert werden:

<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>

Sonstiges

Automatische Klarna Aktionen

Durch Änderungen des Bestellstatus können automatische Aktionen durch das Plugin durchgeführt werden. Sehen Sie hierfür auch die Plugin-Konfiguration.

Automatische Erfassung

Wenn sich der Bestellstatus auf den konfigurierten Bestellstatus ändert, wird eine volle Erfassung automatisch ausgeführt.

Automatische Rückerstattung

Wenn sich der Bestellstatus auf den konfigurierten Bestellstatus ändert, wird eine volle Rückerstattung automatisch ausgeführt.