PaymentModule - Multiple Orders for a Cart

Sometime PrestaShop will split a Cart in multiple Order with same Reference after a Payment.

This is made in PaymentModule::validateOrder()

Because this splitting is made by PrestaShop after the Payment, Customer has only paid Shipping Costs for one Order.

So PrestaShop will display a warning on Order view page to notify merchant the total order amount is not equal to total cart amount.

PrestaShop will send to PaymentModule only Order id and Order reference of the last created Order.

Every PaymentModule will only update OrderState of the last created Order, on module validation trigger by API (like bank validation return).

Every child Order should be manually update by merchant because he needs to choose if additional shipping cost should be paid by Customer or if he take it in charge.

⚠️ Possible cases :

1. A product of Cart exceeds the price/weight range of carriers
2. A product of Cart is restricted to one Carrier (case described bellow)
3. Warehouse management in 1.6, removed in 1.7
4. Multi-shipping functionnality in 1.5 removed in 1.6
5. Others cases I don't know

➡️ Need more informations to find every possible cases will cause Order splitting and how to handle that for Module developer.

How to test

Case : A product of Cart is restricted to one Carrier

1. Install a fresh PrestaShop instance
2. Install PrestaShop Checkout module or another Payment module require validation from an API
3. Go to BO > Sell > Catalog > Products
4. Edit Product 1 aka Hummingbird printed t-shirt
5. In Shipping tab > Available carriers > check case of PrestaShop (Pick up in-store)
6. Save product
7. Edit Product 2 aka Hummingbird printed sweater
8. In Shipping tab > Available carriers > check case of My carrier (Delivery next day!)
9. Save product
10. Go to Shop
11. Go to product page of Product 1 aka Hummingbird printed t-shirt
12. Add to cart
13. Go to product page of Product 2 aka Hummingbird printed sweater
14. Add to cart
15. Go to Cart page
16. Go to Proceed to checkout
17. Choose to paid with PrestaShop Checkout
18. Paid
19. See Your order hasn't been validated yet, only created. There can be an issue with your payment or it can be captured later, please contact our customer service to have more details about it.
20. Go to BO > Sell > Orders
21. See 2 Orders created with same reference, only one is with status Payment accepted
22. View this Orders and see Warning €[TOTAL ORDER] paid instead of €[TOTAL CART]. This warning also concerns order [Order reference]

Start with classes/PaymentModule.php, especially PaymentModule::validateOrder() and the cited order ID, reference, and last-created-order locations. Reproduce the carrier-restriction case using the listed checkout and back-office steps, then investigate the other described splitting cases. Done means documenting the causes and the handling implications for payment-module developers.