Hack 74 Provide an Order Summary with IPN

Present order-specific information on the return page after the customer makes payment .

The return URL and the IPN processing script are two pages on your site that can receive posts containing details of a purchase. Used separately, these two pages can enable you to create a more robust eCommerce system by providing order-specific customization.

Using the return page, for instance, you can display the order number [Hack #52] to the customer for later use. Using the IPN system, on the other hand, you can send a customized email to the customer [Hack #71] , giving her that same order number for tracking purposes. When these two features are used together, they can be even more powerful in terms of their ability to present your customer with valuable information.

This hack uses the return page to show the buyer whether the order has been processed successfully by the IPN system. By itself, this feature might not be worth much, but the functionality is called on for more advanced functions, such as delivering digital goods [Hack #72] .

When a customer reviews the payment information at PayPal and clicks the Pay button, PayPal sends a POST to your IPN page with the purchase information. The customer is directed to a PayPal page that shows them the payment confirmation message. There, the buyer sees a Continue button that, when pressed, returns the user back to the return page at your site. Order-specific information is also sent to this page.

In almost all cases, the IPN page will already have been hit and have processed the information, so you have the transaction information in your local system. With that information, you can customize the return page to give your customer order-specific information.

Exactly when your IPN page is hit by the PayPal systemand, therefore, the exact time the customer's order information is made available to your systemis not defined by PayPal. While it usually occurs quite quickly (the I in IPN stands for Instant ), the possibility exists for IPN postings to be queued up at PayPal and delayed for minutes or longer. For best results, build your software to be tolerant of this possibility.

In this example, you simply display a message that notifies the customer of whether the order has been completed in your system. While this hack only displays a message, you can include other things as well. You might also want to display any error information, such as a price-checking error [Hack #73] .

This hack relies on an IPN page that inserts payment details into your database [Hack #82] which checks the database table to determine whether the order has been processed.

7.14.1 The Code

The return page receives purchase details from PayPal through a form POST (if enabled; see "Using a Return URL" in [Hack #66] for more information). Included in the purchase details is the order transaction ID, passed as txn_id . Compare this unique variable to your database to see if the order has been inserted into the table, which indicates whether it has been processed by your system.

See the "Database Coding and Platform Choices" section of the Preface for the additional information needed to put this SQL statement to work with this and the other hacks in this book.

First, you need to pass the value as presented by PayPal into a local variable using the following code:

 <% 'Create local transaction id variable and populate Dim txn_id Txn_id = Request.Form("txn_id") %> 'Query the database table and find the record (if it is there yet). connStore = "DRIVER={Microsoft Access Driver (*.mdb)};                 DBQ="C:/InetPub/wwwroot/database/dbPayPal.mdb") set rsOrder = Server.CreateObject("ADODB.Recordset") rsOrder.ActiveConnection = connStore rsOrder.Source = "SELECT payment_status FROM tblOrders                  WHERE txn_id = '" & txn_id & "'" rsOrder.Open( ) %> <% If Not rsOrder.EOF Or Not rsOrder.BOF Then 'order exists %> Your order has been processed successfully. The payment status for                  this order is: <%=rsOrder("payment_status")%> <% End If %> <!-- Tell the customer if the order information has not yet been processed --> <% If rsOrder.EOF Or rsOrder.BOF Then 'order does not exist %> Your order is still being processed. <% End If %> 

As this hack illustrates, the return page and the IPN page are more powerful when used in conjunction with one another.

Ideally, you don't want to use your return page to process any of the payment information. You want to use the return page only to read the values from PayPal or read the information created by your IPN page. The return page is not completely reliable, because customers might close their browsers when they see the payment confirmation screen at PayPal, rather than follow the Continue link.