Download the PHP package aligent/orocommerce-fees-bundle without Composer

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

Once installed, run platform update to perform the installation:

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 does not allow charging Payment Processing Fees (See #13)

Adding and Registering new Custom Fees

1. Create a new Bundle (or use an existing one as needed)
2. Create a new class for the fee (eg MyBundle\Fee\HandlingFeeProvider). This new class should extend Aligent\FeesBundle\Fee\AbstractLineItemFee.

3. Define a new service for the new fee, and add it to the fee registry:

4. Create a new Fee Provider Class and implement the applicable methods:

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)
• [ ] 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