税金の計算にカスタムの手数料を導入する

販売商品に追加の課税対象手数料を追加します。

税金を計算する場合に商品に追加の手数料を追加し、それらの手数料の税金を計算しなければならないことがあります。

カスタム手数料を追加

Stripe Tax モジュールは、注文、請求書、クレジットメモを作成した時点でリクエストを作成し、それを Stripe Tax calculation API に送信します。モジュールは、見積もり、インボイス、クレジットメモのアイテムを処理して、アイテムの詳細または注文全体を計算リクエストに追加します。

税金の計算が必要なカスタム手数料を追加する場合は、税金計算リクエストが追加できるように、Stripe Tax モジュールに詳細を指定する必要があります。

この組み込みでは、カスタム手数料の開発者がオブザーバーを介してカスタム手数料の合計額を提供し、それが Tax Calculation API リクエストに追加され、Stripe に送信されて計算されます。

Stripe Tax モジュールの仕組み

Stripe Tax モジュールは、手数料が発生する場所に基づきその他の手数料を追加します。

アイテムレベル (税金は見積もり、インボイス、クレジットメモの各アイテムに適用されます)

見積もり、注文、請求書、クレジットメモのレベル (税金はカゴ全体およびそれ以降に設定されます)

サードパーティーの開発者は以下の 3 つの詳細を送信する必要があります。

カスタム手数料の合計金額 (アイテムのカスタム税率が 3 で、アイテムの数量が 2 の場合、送信される値は 6)
カスタム手数料の税種別
カスタム手数料のコード

これら 3 つのコンポーネントは、次の構造の配列で転送されます。

$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
];

実行するアクション (見積もりの計算、インボイスの作成、クレジットメモの作成) およびカスタム手数料の適用場所 (アイテム、見積もり、インボイス、クレジットメモのレベル) に基づいて、この配列構造を送信する必要があります。

オブジェクトは、この情報を Tax モジュールに送信し、その情報の追加先のオブジェクトを指定します。オブザーバーは、注文プロセスの段階とカスタム手数料を適用すべき場所に応じて、以下の 6 つのイベントのいずれかをリッスンする必要があります。

stripe_tax_additional_fee_item が注文のアイテムに適用されます
stripe_tax_additional_fee_quote が見積もりに適用されます
stripe_tax_additional_fee_invoice_item がインボイスアイテムに適用されます

stripe_tax_additional_fee_invoice がインボイス全体に適用されます
クレジットメモアイテムには、stripe_tax_additional_fee_creditmemo_item が適用されます
stripe_tax_additional_fee_creditmemo はクレジットメモ全体に適用されます

各イベントには、additional_fees_container という Magento データオブジェクトが含まれ、Stripe Tax モジュールによる計算が必要な内容の詳細を追加できます。税金計算の詳細を追加するには、詳細配列をパラメーターとして指定し、->addAdditionalFee() メソッドを呼び出します。

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

これらの追加手数料が親または子アイテム (バンドルにする動的な商品など) に追加される可能性がある場合、バンドルにする商品とその中の商品の両方のイベントを送信します。

最上位の商品とサブ商品の数量を別々に指定できるバンドル商品またはその他のタイプの商品を使用する場合は、親アイテムと子アイテムの両方の数量を考慮して、追加手数料の金額を送信します。親アイテムと子アイテムの数量。

Stripe がインボイスに対する税金を計算した後、お客様は税金と基準税額の配列を受け取ります。必要に応じて、この情報を使用して、データベースにカスタムフィールドを設定することができます。この配列には、キーとしての手数料コードと、それに設定された計算値が格納されます。これには、アイテムまたはインボイスで呼び出される getAdditionalFeesTax() メソッドを使用してアクセスできます。

見積もりレベルでアイテムに税を適用する例

イベントファイル (app/code/Vendor/YourModule/etc/events.xml) 内に、以下のイベントを追加します。

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

additional_fees_container 以外で、イベントに指定されるデータは以下のとおりです。

item: 税金の計算対象となるアイテム。
quote: アイテムが属する見積もり

オブザーバーファイル (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuoteItem.php) 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

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

見積もりレベルで税を適用する例

イベントファイル (app/code/Vendor/YourModule/etc/events.xml) 内に、以下のイベントを追加します。

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

additional_fees_container 以外で、イベントに指定されるデータは以下のとおりです。

quote: 税金の計算に使用される見積もり
total: この時点までで収集された合計額

オブザーバーファイル (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuote.php) 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

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

インボイスレベルでアイテムに税金を適用する場合の例

イベントファイル (app/code/Vendor/YourModule/etc/events.xml) 内に、以下のイベントを追加します。

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

additional_fees_container 以外で、イベントに指定されるデータは以下のとおりです。

item: 税金の計算対象となるアイテム。このアイテムの注文アイテムなどの他の詳細は、オブサーバーで 1 回限り取得できます。

invoice: アイテムが属する見積もり。アイテムの注文などの情報をインボイスから取得できます。

オブザーバーファイル app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoiceItem.php 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

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

インボイスレベルで税を適用する場合の例

イベントファイル (app/code/Vendor/YourModule/etc/events.xml) 内に、以下のイベントを追加します。

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

additional_fees_container 以外で、イベントに指定されるデータは以下のとおりです。

invoice: カスタム手数料が適用されるインボイス
order: インボイスが属する注文

オブザーバーファイル app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoice.php 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

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

クレジットメモへの変更

クレジットメモを作成すると、Stripe Tax モジュールに渡す必要がある配列の構造が変わります。tax_class_id は配列から削除され、amount_tax という新しいフィールドが取得されます。これには、カスタム手数料を返金する税額を含める必要があります。

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

注

詳細配列の code コンポーネントは、請求書ステップで指定されたコードコンポーネントと同じである必要があります。これにより、Stripe は返金額を差し引く対象のコンポーネントを認識できます。

元の金額。

クレジットメモレベルでアイテムに税金を適用する場合の例

イベントファイル (app/code/Vendor/YourModule/etc/events.xml) 内に、以下のイベントを追加します。

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

additional_fees_container 以外で、イベントに指定されるデータは以下のとおりです。

item: 税金の計算対象となるアイテム。このアイテムの注文アイテムなどの他の詳細は、オブサーバーで 1 回限り取得できます。
creditmemo: アイテムが属する見積もり

invoice: アイテムが属する見積もり
order: アイテムが属する見積もり

オブザーバーファイル (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemoItem.php) 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

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

クレジットメモレベルで税金を適用する例

イベントファイル (app/code/Vendor/YourModule/etc/events.xml) 内に、以下のイベントを追加します。

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

additional_fees_container 以外で、イベントに指定されるデータは以下のとおりです。

creditmemo: アイテムが属する見積もり
invoice: アイテムが属する見積もり
order: アイテムが属する見積もり

オブザーバーファイル (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemo.php) 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

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