https://github.com/aligent/orocommerce-fees-bundle
OroCommerce Bundle to charge Fees during Checkout
https://github.com/aligent/orocommerce-fees-bundle
Last synced: 4 months ago
JSON representation
OroCommerce Bundle to charge Fees during Checkout
- Host: GitHub
- URL: https://github.com/aligent/orocommerce-fees-bundle
- Owner: aligent
- License: gpl-3.0
- Created: 2022-04-08T07:04:28.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-12-05T02:38:33.000Z (7 months ago)
- Last Synced: 2026-01-29T21:27:05.560Z (5 months ago)
- Language: PHP
- Size: 183 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Aligent OroCommerce Fees Bundle
==============================
This Bundle adds the ability to dynamically inject 'fees' as new Line Items into the Checkout process.
For example, if a 'Handling Fee' is to be charged for orders under $100.
This Bundle takes advantage of OroCommerce's 'Freeform LineItem' feature,
where a LineItem can be added to the Checkout without being linked to a Product.
It also supports Fees added as Subtotals against the entire Order.
Requirements
-------------------
- OroCommerce 5.0
Important Notes/Caveats
-------------------
* This bundle currently only adds a Payment Processing Fee, any other Fees must be implemented manually
using the provided Abstract classes/interfaces.
* The Line Item which is added to the cart is _not_ a real product.
We utilize the 'FreeForm Line Item' feature in Oro Checkouts.
This allows the price and description to be set by the fee itself,
and avoids any possible inventory/visibility issues.
* The process for placing a new Order (**ShoppingList => Checkout => Order**)
is slightly different to the process for Re-Ordering an
existing Order (**Order => Checkout => Order**).
As a result, our `CreateCheckoutListener` is required to
manually persist/flush the Checkout so that the new line item is saved.
Installation and Usage
-------------------
**NOTE: Adjust instructions as needed for your local environment**
### Installation
Install via Composer
```shell
composer require aligent/orocommerce-fees-bundle
```
Once installed, run platform update to perform the installation:
```shell
php bin/console oro:platform:update --env=prod
```
### Configuration
1. Login to the Oro Admin
2. Visit **System Configuration => Commerce => Aligent => Fees** (or the Website-specific equivalent)
3. Set the **Default Product Tax Code**
Note: This Tax Code will apply to the Fee itself.
Oro does not apply taxes to FreeForm Line Items, this configuration is used by
our `ContextHandler\FreeFormAwareTaxOrderLineItemHandler` to apply the correct tax.
Database Modifications
-------------------
* Adds a new `processing_fee` column to the `oro_order` database table (and extends the Oro `Order` entity)
All configuration is stored in System Configuration (`oro_config_value`).
### Payment Processing Fees
This feature allows OroCommerce to charge an additional percentage for payments made via specific methods.
The percentage can be configured on a per-Method basis, eg:
* 1.5% fee for VISA/MasterCard Credit Card Payments
* 2.0% fee for AMEX Credit Card Payments
After installation, visit the System Configuration (or Website Configuration to configure on a per-Website scope).
Each Payment Method will be visible here. Set the Percentage to a value above `0` to charge a processing fee for that method:
If the Customer chooses that method during the Checkout, a processing fee will be calculated and add to the Subtotals:
**NOTE: Processing Fees are not currently support by PayPal Express as they are not included in the Subtotal, which causes a payment validation error.**
Additionally, the [PayPal User Agreement](https://www.paypal.com/us/webapps/mpp/ua/useragreement-full) does not allow charging Payment Processing Fees (See [#13](https://github.com/aligent/orocommerce-fees-bundle/issues/13))
### Adding and Registering new Custom Fees
1. Create a new Bundle (or use an existing one as needed)
1. Create a new class for the fee (eg `MyBundle\Fee\HandlingFeeProvider`).
This new class should extend `Aligent\FeesBundle\Fee\AbstractLineItemFee`.
1. Define a new service for the new fee, and add it to the fee registry:
```yaml
services:
Acme\MyBundle\Fee\HandlingFeeProvider:
parent: '@Aligent\FeesBundle\Fee\Provider\AbstractLineItemFeeProvider'
tags:
- { name: aligent_fees.fee_provider, priority: 0 }
```
1. Create a new Fee Provider Class and implement the applicable methods:
```php
translator->trans(self::LABEL);
}
/**
* Return SKU of Fee
* @return null|string
*/
public function getSKU(): ?string
{
return self::SKU;
}
/**
* @param Checkout $checkout
* @return float|null
*/
public function getAmount(Checkout $checkout): ?float
{
return self::AMOUNT;
}
/**
* Is the fee Supported by this Entity?
* @param mixed $entity
* @return bool
*/
public function isSupported($entity): bool
{
return ($entity instanceof Checkout);
}
}
```
Noteworthy Features
-------------------
*Where to look first if something goes wrong*
* Method `EventListener\CreateCheckoutListener::onStartCheckoutConditionCheck()` injects Fees into the current Checkout as new LineItems.
* Method `Fee\AbstractFee::getCheckoutLineItem()` builds and generates the Fee Freeform LineItem, including Price/Currency/SKU/Unit/etc.
Core Overrides & Extensions
-------------------
* Class `ContextHandler\FreeFormAwareTaxOrderLineItemHandler` decorates the core Oro `\Oro\Bundle\TaxBundle\OrderTax\ContextHandler\OrderLineItemHandler` class so that it can support Tax calculations for Freeform Line Items.
Roadmap / Remaining Tasks
-------------------
- [x] OroCommerce 5.0 Support
- [x] Implement Unit Tests
- [x] Complete adding support for Fees added as Subtotals
- [x] Add Native Support for Payment Processing Fees
- [x] ~~Add support for PayPal Express Processing Fees~~ (See [#13](https://github.com/aligent/orocommerce-fees-bundle/issues/13))
- [ ] Re-implement support for line item messaging
- [ ] Convert Product Tax Code Configuration into Select field
- [ ] More fine-grained control over Processing Fees (e.g. exclude certain Customer Groups from being charged fee)
- [ ] (TBC) Add support for Expression Language