Add "Checkout complete page is viewed" event

The attached patch need to be applyed inside Drupal Commerce module (inside commerce folder), but if you don`t like hacking source code or don`t know how to apply a patch there is a small custom module as a temporary solution. install it as usual.

Surely it don`t need anymore if the patch will be successfully commited by a maintainer. I`ve created the module as a temporary solution.

The initial problem I encountered was with login user in as one of the actions "Create a new account for an anonymous order" default rule. When you pay on PayPal WPS and then return back on your site it appears user not logged in but looking in the log messages i`ve found that actually session for the user is open! Why?

The reason is that all the actions are executed at the moment when user presses "Pay now" on the PayPal site, then user redirected (by PayPal code?) to intermediate page and that page may be two kinds depending of your PayPal account settings: static or automatic redirection. If it is static - user need click on the "Return to ExampleSite" to return and in that case action for logging user in already dead. If you set up automatic redirection you also have one more page where you asked "If you not redirected after 10 seconds click this link". And if you wait for redirection - action of logging in user does not work, but if you click the link - it does!

Obviously this behaviour is not what we need and that`s why i decided to make one more event.

Thank you, rszrama, for your reply.

Yes, we at any time can "hook" into something as I did in my custom module above, we can even "hack" but the main idea of the CMS is to change code through web-forms interface by clicking those wonderfull buttons and links, is not it?

The question is: when "Completing the checkout process" event fires?

As I understand it happens when our drupal code receives IPN from a payment provider or something like "Success!" message. Different providers send this notification at a different step of the payment process. Some of them do it at the moment when a user actually redirected back to our drupal site and some (as PayPal WPS does) when user clicks "Pay now" button and money transaction is over and done.

In my opinion we can`t rely on others systems code and need to abstract from it as much as we can.

Sorry, a combination of "When an order is first paid in full" and "Completing the checkout process" with a condition on the order balance does not work, at least not always. But anyway, thanks for putting me on the right way because I did not undestand so far what "When an order is first paid in full" event serves for. As a matter of fact it serves exactly for what it says - for checking if the order paid in full or not. Surprisingly, is not it? :-)

I think we MUST to apply this rule on our drupal commerce site because there may be cases when a user redirected to a payment provider has not enough money on his/her account or choose to pay as a bank transfer instead of credit card or paying from a PayPal account, for example. In that case PayPal need to wait until money actually would be transfered and it flags such a transaction as "The payment is pending while it is being reviewed by PayPal for risk" which means an order is NOT paid in full and the "When an order is first paid in full" did not fire as a result. However "Completing the checkout process" event fires in any case even if only 1 (one) dollar is paid for the order say, with a cost of 1000 dollars. Don`t be misleading by a word "Completing..." in this rule as it related only with a checkout process and not a payment!

In the attached exported example rule where I don`t use "Order balance comparison" condition as it is already checked before firing "When an order is first paid in full" rule. (commerce/modules/payment/commerce_payment.module:line 455). I change the order status in this rule for "Processing" (Pending:Processing) to mark (or to flag) paid in full order.

I guess some people do not realize what those order state and statuses mean (like it was me) and I try to explain it in my own words:

• State:Checkout Complete (Status:Checkout) - It is immediatly before firing "Completing the checkout process" rule.
• State:Pending (Status:Pending) - It is after "Completing the checkout process" rule firing and before "When an order is first paid in full" rule. Order is registered on our drupal site, but not cleared out (paid in full).
• State:Pending (Status:Processing) - If you apply the rule I`ve suggested order with this status is paid in full and safe for packing and delivering to a customer. (I wonder why this rule is not a default one...)
• State:Completed (Status:Completed) - I think it is obvious, you change for this status after putting order items on their way to a customer or after receiving delivery confirmation number, depending on your firm policy. But be carefull to no mess up this status with the PayPal "The payment has completed" status because it is their inner status which is equavalent of our State:Pending (Status:Processing).

I think this rule need to be a default rule.

As a conclusion for this issue I`d like to share with others what I know about the ways of accessing "Checkout Complete" page and doing something there:

1. Use form_alter() hook putting this code into template.php of your theme
   

   function your_theme_name_form_alter(&$form, &$form_state, $form_id) {
   if ($form['#id'] == 'commerce-checkout-form-complete') {
     // Doo something here but only remember this is the place for changing a way
     // of displaying data, not for changing data itself.
     }
   }
   

2. Go to admin/commerce/config/checkout/form/pane/checkout_completion_message, change text format for PHP code and do anything what you want using available tokens, variables, functions... but you need really understand what you are doing. Not recommended.
3. Use custom module for adding "Checkout complete page is viewed" event and do all the things you can do with the power of Rules. I do NOT recommend to apply the patch above because the maintainer of Drupal Commerce has decided not to commit it into the module`s stable release.
4. If you know more ways - share their with us here...

May be I was misunderstood but I need to repeat that both "Completing the checkout process" and "When an order is first paid in full" events (EVENTS, not rules in which they are used) called perfectly as their names show us the exact point of time they are firing. Moreover, the default rules (RULES, which are using "Completing the checkout process" event) are extremly vital if you don`t like those mind-blowing error messages on your site.

As for the mustToBeRule I think it is also need to be a default one because it let us know if the order paid in full or not. Just that, no more. And there is no any collision with the default rule "Update the order status on checkout completion" because it is really a misnomer as this rule updates order state (STATE!) not only status as the mustToBeRule does and the default rule is triggered by the "Completing the checkout process" event which fires BEFORE "When an order is first paid in full" event and both these events are fired when a user is still on the PayPal site (or any other) and that is the right behaviour because we never can guarantee if the user will return on our site or not.

So, if the order is just claimed for paying ("Pay now" or similar button is pressed) and no matter what a scheme for paying was chosen (on-point-in-full payment, eCheck, capturing money for later, waiting for bank transfer or even some unknown tricky malicious scheme) payment provider initiates payment transaction and sends us IPN with their inner payment status and order balance. Then our drupal code assigns "Pending" state/status for the order regardless of whether it was paid in full or not and for a payment (PAYMENT, not order) "Success" or "Pending" status (not related with the order and PayPal payment state/status) based on the order balance comparison. Note that there may be many payments for one order and only one of these payments has a "Success" status. Somebody may ask why we can`t use this feature for triggering a rule using the "Completing the checkout process" event with order balance comparison condition and change the order state/status? The answer is in the name of the event - it fires only once on the completing of checkout and even if it fires when the condition is met it may cause collision with the default "Update the order status on checkout completion" rule. That`s why we need safely apply mustToBeRule triggered by the "When an order is first paid in full" event which happens only AFTER "Completing the checkout process" event not interfering with it.

To summarize: The "When an order is first paid in full" event happens not during a checkout process which is ended for the moment but in the PAYMENT process (may be a set of transactions) which is continuining until the order will be paid in full. Note that this event also happens only once and any attempts to add money for the paid in full order will be ignored as it said in the name of the event (When...is first...). There is no way back in the checkout process if a checkout was completed and also in the payment process if an order is paid in full.

About "beset result for this issue is documentation...", yes, but I don`t know exactly what place of the drupal(commerce?) it will be appropriate to put in and would be grateful if you give me right direction.

For those using PayPal WPP method (on-site payment by a credit card) I need to make some update for the post above.

If a payment is making on-site in that case "When an order is first paid in full" event happens BEFORE "Completing the checkout process" event and that is right because we are still on the Checkout:Review page, are we? ...and doing payment on Checkout:Payment state/status. Above all we have a chance to go on a previous page by clicking "Back" button.

That`s why we need first of all to check if a payment transaction was successfull and only then complete checkout process. There may be a case user made a mistake typing in his/her card data and if to complete checkout on that stage there is no way to do one more attempt or to go back. With an off-site payment it is the other way round as it is a payment provider duty to check if the current user able to pay for the order. For our drupal code it is sufficient to know that "Pay now" or similar button, for which a user has access, was pressed. After that we complete checkout and register completed (Pending) order.

If you are using PayPal WPP method and want to mark paid in full orders changing their status for "Processing" you need to apply one more WPPmustToBeRule which is triggered by a "Checkout complete page is viewed" event. To have the event on your site you need to install this custom module.

Note that this rule only works if an order was paid in full. If you choose "Authorization only" option in your PayPal WPP payment method this rule will not fire. Why? Because the order balance == order total and order is not paid in full. Choose "Authorization and capture" to have this rule work. If you are using some another on-site payment method provider than PayPal WPP, please edit "Selected payment method comparison" condition in the WPPmustToBeRule.

Sorry, if somebody get into trouble follow my post above but I myself didn`t know that. The more I go - the more I know :-))