Integrieren Sie eine nutzerdefinierte Gebühr in die Steuerberechnung

Fügen Sie den verkauften Produkten zusätzliche steuerpflichtige Gebühren hinzu.

Möglicherweise müssen Sie bei der Berechnung der Steuer zusätzliche Gebühren zu den Produkten hinzufügen und die Steuer für diese Gebühren berechnen.

Nutzerdefinierte Gebühr hinzufügen

Das Stripe Tax-Modul erstellt Anfragen zum Zeitpunkt der Erstellung von Bestellungen, Rechnungen und Gutschriften und sendet sie an die Stripe Tax Calculation API. Das Modul durchläuft die Positionen des Angebots, der Rechnung oder der Gutschrift, um die Details der Positionen oder der gesamten Bestellung zur Berechnungsanforderung hinzuzufügen.

Wenn Sie eine nutzerdefinierte Gebühr hinzufügen, die eine Steuerberechnung erfordert, müssen Sie die Details im Stripe Tax-Modul angeben, damit sie bei der Anfrage zur Steuerberechnung hinzugefügt werden kann.

Bei dieser Integration stellt der/die Entwickler/in der nutzerdefinierten Gebühr den Gesamtwert der nutzerdefinierten Gebühr über eine Überwachung bereit. Diese wird zur Tax Calculation API-Anfrage hinzugefügt und zur Berechnung an Stripe gesendet.

So funktioniert das Stripe Tax-Modul

Das Stripe Tax-Modul fügt die zusätzlichen Gebühren hinzu, je nachdem, wo die Gebühren anfallen:

Auf Positionsebene (die Steuer wird auf jede Position des Angebots, der Rechnung und der Gutschrift angewendet)

Auf Angebots-, Bestell-, Rechnungs- oder Gutschriftebene (die Steuer wird für den gesamten Warenkorb und darüber hinaus festgelegt)

Der Drittentwickler muss die folgenden drei Details übermitteln:

Der Gesamtpreis der nutzerdefinierten Gebühr (wenn ein Artikel eine nutzerdefinierte Steuer von 3 hat und die Menge des Artikels 2 beträgt, beträgt der gesendete Wert 6)
Die Steuerklasse für die nutzerdefinierte Gebühr
Der Code der nutzerdefinierten Gebühr

Diese drei Komponenten werden in einem Array mit folgender Struktur weitergeleitet:

$details = [
    'amount' => $amountValue, // generic value—provide your own when developing
    'tax_class_id' => $classId, // generic value—provide your own when developing
    'code' => 'custom_fee' // generic value—provide your own when developing
];

Sie müssen diese Array-Struktur basierend auf der ausgeführten Aktion (Angebotsberechnung, Rechnungserstellung oder Gutschriftserstellung) und dem Ort, an dem die nutzerdefinierte Gebühr anfällt (Artikel-, Angebots-, Rechnungs- oder Gutschriftsstufe), senden.

Nach der Überprüfung werden die Informationen an das Steuermodul gesendet und ein Objekt bereitgestellt, dem die Informationen hinzugefügt werden. Bei der Überprüfung muss je nach Phase des Bestellvorgangs und dem Ort, an dem die nutzerdefinierte Gebühr erhoben werden muss, eines der folgenden sechs Ereignisse berücksichtigt werden:

stripe_tax_additional_fee_item gilt für die Artikel einer Bestellung
stripe_tax_additional_fee_quote gilt für das Angebot
stripe_tax_additional_fee_invoice_item gilt für Rechnungspositionen

stripe_tax_additional_fee_invoice gilt für die gesamte Rechnung
stripe_tax_additional_fee_creditmemo_item gilt für Gutschriftspositionen
stripe_tax_additional_fee_creditmemo gilt für die gesamte Gutschrift

Jedes der Ereignisse enthält ein Magento-Datenobjekt mit dem Namen additional_fees_container, in dem Sie die Details dessen hinzufügen können, was vom Stripe Tax-Modul berechnet werden muss. Um die Details der Steuerberechnung hinzuzufügen, rufen Sie die Methode ->addAdditionalFee() mit dem Details-Array als Parameter auf:

$additionalFees = $observer->getAdditionalFeesContainer();

// other operations to get the values to send forward

$details = [
    'amount' => $amountValue, // generic value—provide your own when developing
    'tax_class_id' => $classId, // generic value—provide your own when developing
    'code' => 'custom_fee' // generic value—provide your own when developing
];

$additionalFees->addAdditionalFee($details);
}

In Fällen, in denen diese zusätzlichen Gebühren entweder für einen übergeordneten oder untergeordneten Artikel (zum Beispiel ein gebündeltes dynamisches Produkt) hinzugefügt werden können, senden wir Ereignisse sowohl für das gebündelte Produkt als auch für die darin enthaltenen Produkte.

Wenn Sie gebündelte Produkte oder andere Arten von Produkten verwenden, bei denen Sie die Menge des übergeordneten Produkts und des Unterprodukts separat angeben können, senden Sie den Betrag der zusätzlichen Gebühr und berücksichtigen Sie die Menge der übergeordneten und untergeordneten Artikel. Menge der übergeordneten und untergeordneten Artikel.

Nachdem Stripe die Steuer für die Rechnungen berechnet hat, erhalten Sie eine Reihe von Steuer- und Basissteuerbeträgen. Sie können diese Informationen verwenden, um bei Bedarf nutzerdefinierte Felder in der Datenbank festzulegen. Das Array enthält den Gebührencode als Schlüssel und die dafür eingestellten berechneten Werte. Sie können über die getAdditionalFeesTax()-Methode darauf zugreifen, die im Artikel oder auf der Rechnung aufgerufen wird.

Beispiel für die Anwendung der Steuer auf den Artikel auf Angebotsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (app/code/Vendor/YourModule/etc/events.xml) das folgende Ereignis hinzu:

<event name="stripe_tax_additional_fee_item">
    <observer name="your_custom_observer_name" instance="Vendor\YourModule\Observer\AddAdditionalFeeForQuoteItem" />
</event>

Die Daten, die zusätzlich zum additional_fees_container für das Ereignis bereitgestellt werden, sind:

item: Der Artikel, für den die Steuer berechnet wird
quote: Das Angebot, zu dem der Artikel gehört

Fügen Sie in Ihrer Überwachungsdatei (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuoteItem.php) den Code zum Erstellen der Details für die Berechnung wie im folgenden Beispiel hinzu:

<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForQuoteItem implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $item = $observer->getItem();
        $quote = $observer->getQuote();

        // Calculations where you determine that the item has an additional tax and the tax needs to be calculated
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $itemDetails = [
                'amount' => $amount, // generic value determined from previous calculations—provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations—provide your own when developing
                'code' => 'custom_fee' // generic value—provide your own when developing
            ];

        $additionalFees->addAdditionalFee($itemDetails);
    }
}

Beispiel für die Anwendung der Steuer auf Angebotsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (app/code/Vendor/YourModule/etc/events.xml) das folgende Ereignis hinzu:

<event name="stripe_tax_additional_fee_quote">
    <observer name="stripe_tax_additional_fee_quote" instance="Vendor\YourModule\Observer\AddAdditionalFeeForQuote" />
</event>

Die Daten, die zusätzlich zum additional_fees_container für das Ereignis bereitgestellt werden, sind:

quote: Das Angebot, für das die Steuer berechnet wird
total: Die gesammelten Summen bis zu diesem Punkt

Fügen Sie innerhalb Ihrer Überwachungsdatei app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuote.php den Code zum Erstellen der Details für die Berechnung wie im folgenden Beispiel hinzu:

<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForQuote implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $quote = $observer->getQuote();
        $total = $observer->getTotal();

        // Calculations where you determine that the quote has an additional tax and the tax needs to be calculated
        // After the calculations are done and you have the values, add them to the details array and send the array forward

        $details = [
                'amount' => $amount, // generic value determined from previous calculations—provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations—provide your own when developing
                'code' => 'custom_fee' // generic value—provide your own when developing
            ];

        $additionalFees->addAdditionalFee($details);
    }
}

Beispiel für die Anwendung der Steuer auf den Artikel auf Rechnungsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (app/code/Vendor/YourModule/etc/events.xml) das folgende Ereignis hinzu:

<event name="stripe_tax_additional_fee_invoice_item">
    <observer name="your_custom_observer_name" instance="Vendor\YourModule\Observer\AddAdditionalFeeForInvoiceItem" />
</event>

Die Daten, die zusätzlich zum additional_fees_container für das Ereignis bereitgestellt werden, sind:

item: Die Position, für die die Steuer berechnet wird. Sie können andere Details wie die Auftragsposition für diese Position einmalig in der Überwachung abrufen.

invoice: Das Angebot, zu dem der Artikel gehört. Sie können Informationen wie die Bestellung des Artikels aus der Rechnung abrufen.

Fügen Sie innerhalb Ihrer Überwachungsdatei app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoiceItem.php den Code zum Erstellen der Details für die Berechnung wie im folgenden Beispiel hinzu:

<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForInvoiceItem implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $item = $observer->getItem();
        $invoice = $observer->getInvoice();

        // Calculations where you determine that the item has an additional tax and the tax needs to be calculated
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $itemDetails = [
                'amount' => $amount, // generic value determined from previous calculations, provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations, provide your own when developing
                'code' => 'custom_fee' // generic value, provide your own when developing
            ];

        $additionalFees->addAdditionalFee($itemDetails);
    }
}

Beispiel für die Anwendung von Steuern auf Rechnungsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (app/code/Vendor/YourModule/etc/events.xml) das folgende Ereignis hinzu:

<event name="stripe_tax_additional_fee_invoice">
    <observer name="stripe_tax_additional_fee_quote" instance="Vendor\YourModule\Observer\AddAdditionalFeeForInvoice" />
</event>

Bei den Daten, die dem Ereignis zur Verfügung gestellt werden, handelt es sich abgesehen von additional_fees_container um:

invoice: Die Rechnung, auf der die nutzerdefinierte Gebühr erhoben wird
order: Der Auftrag, zu dem die Rechnung gehört

Fügen Sie innerhalb Ihrer Überwachungsdatei app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoice.php den Code zum Erstellen der Details für die Berechnung. Hier ein Beispiel:

<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForInvoice implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $invoice = $observer->getInvoice();
        $order = $observer->getOrder();

        // Calculations where you determine that the invoice has an additional tax and the tax needs to be calculated
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $details = [
                'amount' => $amount, // generic value determined from previous calculations, please provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations—provide your own when developing
                'code' => 'custom_fee' // generic value—provide your own when developing
            ];

        $additionalFees->addAdditionalFee($details);
    }
}

Änderungen an Gutschriften

Beim Erstellen von Gutschriften ändert sich die Struktur des Arrays, das an das Stripe Tax-Modul zurückgegeben werden muss. Die tax_class_id wird aus dem Array entfernt und Sie erhalten ein neues Feld namens amount_tax, das den Steuerbetrag enthalten muss, den Sie für die nutzerdefinierte Gebühr zurückerstatten möchten.

$details = [
    'amount' => $amount,
    'amount_tax' => $taxAmount,
    'code' => 'custom_fee'
];

Notiz

Die code-Komponente des Detail-Arrays muss dieselbe Codekomponente sein, die im Rechnungsschritt angegeben wurde. Dadurch wird sichergestellt, dass Stripe weiß, von welcher Komponente die erstatteten Beträge abgezogen werden sollen.

Beträge von.

Beispiel für die Anwendung der Steuer auf die Position auf Gutschriftebene

Fügen Sie innerhalb Ihrer Ereignisdatei (app/code/Vendor/YourModule/etc/events.xml) das folgende Ereignis hinzu:

<event name="stripe_tax_additional_fee_creditmemo_item">
    <observer name="your_custom_observer_name" instance="Vendor\YourModule\Observer\AddAdditionalFeeForCreditmemoItem" />
</event>

Die Daten, die zusätzlich zum additional_fees_container für das Ereignis bereitgestellt werden, sind:

item: Die Position, für die die Steuer berechnet wird. Sie können andere Details wie die Auftragsposition für diese Position einmalig in der Überwachung abrufen.
creditmemo: Das Angebot, zu dem der Artikel gehört

invoice: Das Angebot, zu dem der Artikel gehört
order: Das Angebot, zu dem der Artikel gehört

Fügen Sie in Ihrer Überwachungsdatei (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemoItem.php) den Code zum Erstellen der Details für die Berechnung wie im folgenden Beispiel hinzu:

<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForCreditmemoItem implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $item = $observer->getItem();
        $creditmemo = $observer->getCreditmemo();
        $invoice = $observer->getInvoice();
        $order = $observer->getOrder();

        // Calculations where you determine that the item has an additional tax and the tax needs to be refunded
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $itemDetails = [
                'amount' => $amount, // generic value determined from previous calculations, please provide your own when developing
                'tax_amount' => $taxAmount, // generic value determined from previous calculations, please provide your own when developing
                'code' => 'custom_fee' // generic value, please provide your own when developing
            ];

        $additionalFees->addAdditionalFee($itemDetails);
    }
}

Beispiel für die Anwendung von Steuern auf Gutschriftebene

Fügen Sie innerhalb Ihrer Ereignisdatei (app/code/Vendor/YourModule/etc/events.xml) das folgende Ereignis hinzu:

<event name="stripe_tax_additional_fee_creditmemo">
    <observer name="stripe_tax_additional_fee_quote" instance="Vendor\YourModule\Observer\AddAdditionalFeeForCreditmemo" />
</event>

Die Daten, die zusätzlich zum additional_fees_container für das Ereignis bereitgestellt werden, sind:

creditmemo: Das Angebot, zu dem der Artikel gehört
invoice: Das Angebot, zu dem der Artikel gehört
order: Das Angebot, zu dem der Artikel gehört

Fügen Sie in Ihrer Überwachungsdatei (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemo.php) den Code zum Erstellen der Details für die Berechnung wie im folgenden Beispiel hinzu:

<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForInvoice implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $creditmemo = $observer->getCreditmemo();
        $invoice = $observer->getInvoice();
        $order = $observer->getOrder();

        // Calculations where you determine that the invoice has an additional tax and the tax needs to be refunded
        // After the calculations are complete and you have the values, add them to the details array and sent the array forward

        $details = [
                'amount' => $amount, // generic value determined from previous calculations, please provide your own when developing
                'tax_amount' => $taxClassId, // generic value determined from previous calculations, please provide your own when developing
                'code' => 'custom_fee' // generic value, please provide your own when developing
            ];

        $additionalFees->addAdditionalFee($details);
    }
}