This Patch modifies the checkout process of HTML-Form based payment methods (e.g. PayPal) in order to generate and send confirmation email to the client only AFTER the payment is confirmed by the payment gateway.
With VirtueMart's included PayPal integration a quick and price efficient solution is available for any business starting with e-commerce. With virtually no startup fees it is now possible for any businesses around the world to offer a secure and trustworthy interface for credit card payments. The administrative steps are simple and thanks to VirtueMart the implementation takes only a few steps.
Transaction confirmation confusion
Many shop owners have been confronted with confused clients because of VirtueMart's checkout process while using HTML-Form based payment methods. As of today, a client going through the checkout process receives a transaction confirmation before he even opened his wallet. This generates much confusion and hesitation to the clients being responsible for many hours of additional support for the web site owner.
The early confirmation of the transaction has further implications: sending notification to the shop owner, clearing the clients cart and reducing the stocks amount available for the shop. All this for clients that might never pay a cent to the shop....
This Patch changes the checkout process for HTML-Form based payment methods in order to wait on the confirmation from the payment gateway (IPN) before saving the transaction to the database and sending the confirmation emails. The patch was combined with the PayPal payment gateway as proof of concept but can be applied to any HTML-Form based payment method. Even though all efforts were taken to minimize the impact on the VirtueMart platform, you will need to replace the VirtueMart core files listed below to apply this functionality. So please be careful while applying the patch and save a copy of the originals before. This patch is distributed "as is". NO WARRANTY OF ANY KIND IS EXPRESSED OR IMPLIED. YOU USE IT AT YOUR OWN RISK.
How it works
This Patch will change the checkout process in following ways:
- A temporary transaction is saved to a new VirtueMart database table when the client reaches the last step of the checkout process. This data contains the full session variables of the client as well as the GET parameters. These variables are later used to process the transaction on confirmation by the payment gateway.
- When the client clicks on the “Confirm Order” button an AJAX called is made to save the clients comments to the temporary transaction table before posting the form to PayPal and thus redirecting the client to the PayPal interface.
- The checkout confirmation process is triggered on reception of the payment confirmation by the payment gateway (IPN). The process is triggered using VirtueMart’s ps_checkout class. In order for this class to work properly, the $_SESSION and $_REQUEST variables of the client must be restored from the database before the ps_checkout->add() function is called (The confirmation script is called by the payment gateway which does not have the clients session information). Once the variables restored the ps_checkout->add() function triggers the entire checkout process (incl. stock, email and transaction creation) as usual.
- When the client returns to your site (by either using the back button, completing the transaction or hitting the PayPal cancel button) the transaction status is checked. If the confirmation from the payment gateway has been received the client is redirected to the thank you page and his cart emptied. If the confirmation hasn’t been received, the client is informed that the payment is still pending. His cart is still full. He can either hit the refresh button if he believes the payment confirmation should arrive anytime or he can repeat his checkout as desired.
Core Files modified
- /administrator/components/com_virtuemart/html/checkout.index.php Line 146-176 => If the constant GENERATE_TRANSACTION_ON_CONFIRMATION is enabled the php code in the Payment Extra Info field is evaluated at the end of the final confirmation html form.
- /administrator/components/com_virtuemart/classes/ps_checkout.php Line 909-914 => If the order number is in the session use it instead of generating a new one. This is necessary to use the same order number as sent to the payment gateway when creating the actual transaction.
- /administrator/components/com_virtuemart/notify_gen_transaction.php => clone of notify.php with the changes needed for triggering the transaction. It is also called by a AJAX function in order to save customers comments before redirection to PayPal
- /administrator/components/com_virtuemart/classes/payment/ps_paypal_conf.php => The payment module class file
- /administrator/components/com_virtuemart/classes/payment/ps_paypal_conf.cfg.php => The payment module configuration file
- /administrator/components/com_virtuemart/html/checkout.result_confirmation.php =>New result page (client is redirected to this page after paypal) to verify if transaction is confirmed and react in accordance.
- /images/stories/spin.gif => Spinning Image to display to user while waiting
Payment Extra Info Code
The code to be pasted into the Payment Extra Info Field of the payment module configuration is included in the downloadable zip file and is called payement_extra_info.php.
In order to store the temporary transactions (transactions not confirmed by the payment gateway) an additional table is needed. The script to create the table for you is included in the downloadable zip file and is called create_temporary_order_table.sql.
In order to install the "patched" PayPal payment gateway follow these steps:
- Download the VirtueMart PayPal Patch zip file.
- Unzip the zip file to the root folder of your Joomla installation (WARNING: DON’T FORGET TO BACKUP YOUR FILES FIRST, THE VIRTUEMART CORE FILES LISTED EARLIER WILL BE OVERWRITTEN)
- Make sure your server has write access to /administrator/components/com_virtuemart/classes/payment/ps_paypal_conf.cfg.php
- Create the database Table using the create_temporary_order_table.sql script included in the downloaded zip file.
- Create a new payment module
NOTE: For detailed information on creating a new PayPal module please refer to this VirtueMart forum thread.
1. In the VirtueMart administration Interface select "Store" => "Add Payment Method". An empty payment method form opens. Now fill in the details of your payment method like this:
Make sure the “Payment class name” is set to “ps_paypal_conf” and that the “Payment method type“ is set to “HTML-Form based”.
2. Go to the Configuration Panel, which can be reached by clicking on the Tab "Configuration" and set the following values:
- PayPal payment Email => Your business email, which is your login at PayPal (or PayPal sandbox).
- Order Status for confirmed Payments, Order Status for Pending Payments, Order Status for failed Payments =>With these settings you can define, which Order Status should be set when a payment was successful / is pending / has failed.
- Generate Transaction on Confirmation => "yes". This enables the changes made by the patch thus changing the checkout process to accept a transaction and send out the confirmation email only AFTER the payment gateway validates the payment. Once enabled the code inside the Payment Extra Info field will be included into the last checkout page.
- Payment Extra Info =>Open the file payement_extra_info.php included in the downloaded zip and copy-paste the complete php code into this field.
- Save the new module.
The module is now ready to be used.To clean up the installation delete the following 3 files in your Joomla root directory:
For testing purpose you can use PayPal's sandbox by simply modifying a single line of the code inserted in "Payment Extra Info" in the configuration tab of the module:
On line 12 change
$url = "https://www.paypal.com/cgi-bin/webscr";
$url = "https://www.sandbox.paypal.com/cgi-bin/webscr";
and save the changes.