Never Miss a PayPal Order Again

[Rutabaga]

A Solution for Dropped Orders Placed on a Third-Party Website

This article introduces a new method used by the shopping cart to capture orders placed on third-party websites. This new method, called Capture Off-Site Transactions (COST), eliminates missing or malformed orders in your store records caused by incomplete data provided to the shopping cart by a third-party website. This article provides an overview of the new system and a tutorial on how to use it in your store.

Because "It Works More Often Than Not" Just Don't Work For Me
If it's one thing that I've learned working in the tech support department for a shopping cart software provider, it's that if a customer places an order, and it doesn't get saved in the store's order records, it's going to lead to a frustrated call to my department. And that's fair. After all, The fundamental purpose of an online store is to record orders from customers. Fortunately, 99.9% of the time, missing orders don't happen. The customer shops, checks out, securely enters their credit card and receives a receipt — all on the store's website. The customer's order is saved in the store records as soon as it is placed. Presto. Works like a charm. However, some payment methods (or "payment gateways") require the customer to leave your website and complete the order on their website. In this scenario, the order is completed off of your website. Because of this, we refer to these payment gateways as "off-site payment gateways". While they provide a level of convenience for the customer, off-site payment gateways introduce a potential problem: their website must report the order data back to your store in order for the order to be saved in your shopping cart records. If the order data reported back from the off-site gateway is delayed, incomplete or missing, then the shopping cart's order record will be incomplete or even missing! This is because the shopping cart must save the entire order in memory, awaiting a signal from the off-site gateway after the order has been completed on their site, or send a copy of the entire order (including complete details about products, customers, coupons, promotions, prices, taxes and shipping methods & fees) to the offsite-payment gateway and then await the gateway to send the order data back after the order has been completed on their website, at which time the order is saved in the store's order records. Figure 1 at right describes how the communication between the shopping cart and an off-site payment gateway works. It seems that merchants using the off-site payment gateway PayPal have started seeing an increase in dropped or incomplete orders saved in their store's records. One client recently reported that over 50 PayPal orders a week weren't being properly reported back into their store records. Modular Merchant's developers decided it was time for a "total redesign" of the way that the shopping cart communicates with PayPal and other off-site payment gateways — to remove the potential point of failure caused by the dependence on the order data returned from the off-site gateway. PayPal is the first off-site gateway to receive this treatment. Modular Merchant version 3.4.11 introduces a new system of recording PayPal orders. The new system allows the shopping cart to capture a copy of the order record before the customer leaves your store's website to complete the order on PayPal's site.	Figure 1: Communication between the shopping cart and an off-site payment gateway.

A New Approach: Capture Off-Site Transaction (COST)
Figure 2: The new method of communication between the shopping cart and an off-site payment gateway.	Here's how the new system, codenamed Capture Off-Site Transaction (COST), works: Instead of submitting the order data directly to PayPal, the store first saves a copy of the transaction in the store's records. A "pending" version of the order is temporarily recorded in the shopping cart records. This "pending" version of the order is listed as "unauthorized" (payment has not been approved) and "unpaid" (the order's funds have not yet been collected). After the "pending" version of the order has been saved in the store's records, a reference number for the order is generated. This reference number is all that the shopping cart submits to PayPal — replacing the need to either submit an entire copy of the order or retain the entire order in the server's memory. Then the customer logs in to PayPal's website as usual to complete the transaction. All the store depends on receiving back from the off-site gateway is is the order's reference number. When the store receives this reference number back from PayPal's website, the store's order record is simply updated as being "authorized" and "paid". The order is then no longer "pending" and the order will be ready to ship and the customer will have access to any downloads they have purchased. Figure 2 at left describes the new method of communication between the shopping cart and an off-site payment gateway. Benefits of the new system: 1. In the worst-case scenario, in which incomplete data is returned from the off-site payment gateway, all that's going to happen is that the order record in the store won't be taken out of "pending" status. In which case, a store administrator will need to manually mark the order as "authorized" and "paid". Comparatively, a much better than incomplete order data, or an entire missing order! 2. The "pending" status prevents problem customers from being able to download digital products until after the order has been approved. This entire process is invisible to the customer. 3. All of the communication received back from PayPal is recorded on the Order Details page in the shopping cart's administration area. A new table titled PayPal Responses dates and displays not only any alerts or warnings generated by the shopping cart during its communication with PayPal, but also every response returned from PayPal's server for the transaction. 4. Advanced fraud screening features become available with this new system. For example, a tactic thieves use with PayPal is to alter the value of the transaction submitted to PayPal. (For example, a $123.45 order may be reduced to $1.00.) The new system compares the order value returned from PayPal to confirm that it matches the value previously recorded in the store records. If the values don't match, then the order is not taken out of "pending" status, and a notification is recorded in the PayPal Responses.

Using the COST System to Communicate with PayPal...

We've made sure that using the new system to communicate with off-site payment gateways is easy! For example, the previous method required using a separate HTML form in your store's HTML templates just for PayPal. This could also cause problems with missing order data if desired information (such as the customer's name and address) wasn't captured within the form containing the "Pay with PayPal" button. Well, no more! With the new system, the "Pay with PayPal" button can be added to the same HTML form that contains all the other customer address fields, credit card fields, etc. Example: Adding a COST "Pay with PayPal" button to a store templates... To add a "Pay with PayPal" button to your store's checkout area that will use the COST system to capture a copy of the order before the customer leaves for PayPal's website, simply add the following QuickCode Tag™ to the desired location in the page's template: {PAYPAL-CAPTURE-ORDER-BUTTON}. That's it. This QuickCode Tag will create the "Pay with PayPal" button encoded with the behavior to capture a "pending" version of the order before continuing on to PayPal's website. If you're using the {PAYPAL-CAPTURE-ORDER-BUTTON} QuickCode Tag to create your "Pay with PayPal" button, then any instances of a separate PayPal form, are no longer needed. That means that separate PayPal forms or related QuickCode Tags, such as {COMPOSITE-PAYPAL-BUTTON} can be removed from your store templates. The {PAYPAL-CAPTURE-ORDER-BUTTON} QuickCode Tag replaces any of these other methods. Question: Will Modular Merchant provide any examples of how to use the {PAYPAL-CAPTURE-ORDER-BUTTON} QuickCode Tag? Within a month of the release of version 3.4.11, the suite of pre-made Design Packages provided by Modular Merchant will be updated to use the new "PayPal Capture Order" system. These Design Packages are available within your store's administration area at: [Navigation Menu > Design > Get Design Packages]. Once the updated Design Packages are released, they can be installed in your store with the click of a button! Keep an eye on the Get Design Packages page in your store's administration area for the availability of these updated Design Packages. Question: Where in my HTML code do to I place the {PAYPAL-CAPTURE-ORDER-BUTTON} QuickCode Tag? Place the {PAYPAL-CAPTURE-ORDER-BUTTON} QuickCode in the same HTML form that contains the billing address, credit card and other payment fields. The {PAYPAL-CAPTURE-ORDER-BUTTON} QuickCode Tag should not be placed in a separate form. Question: Am I required to replace my current PayPal forms with the new {PAYPAL-CAPTURE-ORDER-BUTTON}? No. The COST method is optional. The shopping cart software will remain compatible with other methods of adding PayPal as a payment option in the storefront. For example, both the {COMPOSITE-PAYPAL-BUTTON} QuickCode Tag and custom paypal order forms will continue to function normally.

The Connecting to PayPal Screen

Due to the manner in which the COST system securely records the pending version of the order, it is necessary to change the way that the shopping cart connects to the PayPal website. Previously, the "Pay with PayPal" button would take the customer directly to PayPal's website, bypassing absolutely any interaction with the shopping cart. The COST method first saves the pending version of the order record an then connects the customer to PayPal's website. While this connection is established, a Connecting to PayPal screen will be displayed. The length of time this screen is displayed will vary from milliseconds to a few seconds. Figure 3: A sample Connecting to PayPal page. As with all the other storefront pages, a template is available to customize the display of this Connecting to PayPal page. The update to all Design Packages mentioned above will include the addition of a new template titled "paypal_connect". (The template file name is "paypal_connect.template.php".) Since this template is a new addition, it is possible that the Design Package you're using in your store doesn't yet include it. In that case, it is very easy to add. Simply open any template, in the Template Editor located in the store's administration area at [Navigation Menu > Design > HTML Templates] and then enter "paypal_connect" in the field titled "Name the new HTML template" click the "Save as a NEW HTML template" button. The "paypal_connect" template will then be created and will be ready to customize. Specific HTML, JavaScript and PHP code is required in order to establish the connection to PayPal. Because of this, it is highly recommended that any custom "paypal_connect" template includes a version of the following code: "PayPal Connect page" code sample. Question: Why is this "connecting to PayPal" page necessary? The "connecting to PayPal" page is necessary because PayPal requires the shopping cart to connect to their website via an HTML form post. Common connection methods used with other payment gateways — both on-site and off-site payment gateways — appear to be rejected by PayPal's website.

"Just place my order and leave fate out of it."

The COST system takes the gamble out of shopping cart transactions completed on third-party websites by removing the dependency on the data they return to the cart. The integrity of and speed in which the data is returned is no longer a potential point of failure in saving the order records in the shopping cart's order records. And fewer dropped orders means fewer frustrated phone calls to tech support, which both we and our clients can appreciate.

_________________
Rutabaga
Keeper of the Development Schedule
Modular Merchant Shopping Cart Software.