This & That Store Tools An example of:

Create Your Own IPN Back-End Solution Check it out for FREE!

Help

Overview

Your IPN Solution provides a means for PayPal's Instant Payment Notification service to automate transaction recording and product delivery for single item purchases and shopping cart purchases.  Digital and physical goods can be handled using your IPN Solution.

In addition to a script that handles transactions posted through PayPal, this system includes tools for managing and building your online store.  The tools include the Product Manager for adding products to your online store, the Transaction Manager for viewing the details of purchases, the Button Creator for creating Buy Now and Shopping Cart buttons, and an IPN Tester gives you the ability to completely test Your IPN Soluton for each product you add or change.  A password system is included that allows you to keep your IPN Tools safe even if your web host does not allow password protected directories.

This help file is organized in the same order as the hyperlinks you will find at the top of every tool page.  Additional system information is included at the bottom of this page.  You can jump to your desired target by following the links below:

Product Manager Help

Transaction Manager Help

Button Creator Help

IPN Tester Help

Password Help

System Information

Product Management

The product management page allows a specific product record to be chosen for review or modification.

A new product may be added by pressing the "New" button or changing "Item Name" and pressing "Update".  Pressing "New" will open a blank form to be filled in.

Once a product has been fully defined, press the "Update" button to either change an existing product record or add a new product.

To delete a product from the database press the "Delete" button.  A dialog box will appear for confirmation.  (Note that a product can be made unavailable rather than deleted.)

The fields that appear for each record and their definitions are:

Field	Definition
Item Name	The name of the product as specified in your "Buy Now" button.
Check Item Price	If checked, the payment amount will be checked against the item price.  The check performed is that the PayPal payment is greater than or equal to the item price for single item purchases or the sum of the item prices for shopping cart purchases.  This assures the payment meets your per item price and may include tax, shipping, and handling charges.
Item Price	Per unit item price.
Item Available	Used by this IPN Back-End Solution to determine if a product is available or unavailable (use this rather than deleting the product from the database, if desired).
Enable Download	If checked, the item purchased will automatically be downloaded to the customer's browser after the Successful Payment web page has loaded.  (Requires Item Path to be set.)
Item Path	The full file system path (not the URL) of this product (if it is electronic).
Save As Name	An alternate name for the file.  This name may be used if the product is being emailed to the customer.  (When the attached product is saved from the email, this name is used.)
Attachment Type	This is chosen from a drop-down list.  Typically, the file name extension determines the attachment type. (This is used when attaching a file to an email.)
Enable Email	If checked, the item purchased will automatically be attached to an email sent to the primary PayPal email address of the customer.
Email Content Type	This is used when attaching content to an email.  If email is enabled, this setting is used in conjunction with "Email Content" below.  (Content is typically either text/plain or text/html.)
Email Content	This is the content used in the email sent to the customer if email is enabled.  Either type the content directly in this field or paste html code.
Enable Auto Response	If checked, an auto response will be sent to the customer's primary PayPal email address
Response Content Type	This is used when attaching content to an auto response email.  If auto response is enabled, this setting is used in conjunction with "Response Content" below.  (Content is typically either text/plain or text/html.)
Response Content	This is the content used in the auto response emailed to the customer if auto response is enabled.  Either type the content directly in this field or paste html code.
Enable Follow-up Process	If checked, the IPN back-end solution will start another process before terminating.  Specify the command below.
Follow-up Process Command	If enabled, this command will be started before the IPN back-end solution terminates.  All variables posted by PayPal will be passed to this process.  Any command that can be executed from the command prompt can be entered here.  (Ex. "perl IPNfollower.pl")
Item Comment	Comment specific to a particular product.  This comment can be included on the successful payment page.

Transaction Management

The transaction management page displays the transaction details for one transaction at a time.

All transactions can be cycled through by pressing the "Previous" and "Next" buttons.  At the beginning of the records pressing previous goes to the last record.  At the end of the records pressing next goes to the first record.

The variable retention settings may be changed by following the "change your variable retention settings here" link near the top of the page.  By controlling the transaction variable retention settings, you control how much information you have on hand to make informed business decisions.

Button Creator

Choose the Item Name of the product you wish to create a button for.  Once you have chosen the product, the Item Number and Item Price are automatically filled in for you.  While you can change the price and item number on the Button Creator page, the changes are not applied to the product database.  If you change the price you must do so in the product database or the purchase may be denied based on price.

Next choose which type of button you wish to create.  You may create a Buy Now or Shopping Cart button.  If you choose to create a Shopping Cart button an additional field will appear.  This field should only be filled in if you plan to charge a handling fee on a per cart basis.  If you choose later to switch to a Buy Now button, the additional field will disappear.

Fill in all of the appropriate fields before pressing the "Generate Code" button near the bottom of the Button Creator page.  Once the code is generated press the "Select All" page the copy and paste it into you html code.

Note that leaving a field blank will usually result in that field not being represented in your generated code.  PayPal assumes default values for fields left out.

Note also that it is possible for each product to include up to two option fields.  The option fields may be represented by either a drop-down list box or a text field.  The default is "Use text field."  If you choose "Use drop-down box" an additional field will appear to the right.  You can add option values to a list box for inclusion in your html code along with your Buy Now or Shopping Cart button.  Simply enter the option value in the text field to the left of the "Add" button and press the "Add" button.  Your value will appear in the drop-down box to the right of the "Add" button.  If you want to remove an item from the drop-down box, select it and press the "Remove" button.

To make sure the URLs you may have entered into the Customer Experience Specification section are correct, you can go to the end of the page and press the appropriate button.  Once you have pressed the button the URL will be displayed in the bottom frame.  (Note that once you have followed a URL that isn't correct pressing another test button will not work because of JavaScript security features.  To try again, click somewhere in the bottom frame and press your browser's back button until you are at the beginning again.)

IPN Tester

Suggested Testing Sequence

After adding a new product, it is in your best interest to check the full sequence of processing a purchase.  Your IPN Tester is available to test your system.  The only steps necessary to perform the test is to choose the product(s) to be purchased and submit the test purchase.  This test is performed only within the confines of your own web server--only your URL is allowed to make the test.  Therefore there is no chance of compromising the security of your system with the testing system.

To completely test every aspect, follow this checklist:

• Single Item Purchase with correct information
  • Choose the product to be tested from the "item_name" drop-down list
  • Press the "Test Your IPN" button at the bottom of the Tester page
  • Thoroughly review the successful payment page for complete field name replacement
  • Thoroughly review your transactions database for correct information
• Single Item Purchase with incorrect price
  • Choose the product to be tested from the "item_name" drop-down list
  • Change to mc_gross field to something less than the item price
  • Press the "Test Your IPN" button at the bottom of the Tester page
  • Thoroughly review the displayed page for your desired statement
  • Thoroughly review your transactions database for correct information
• Shopping Cart Purchase with correct information
  • Choose several products from the "item_name" drop-down list
  • Press the "Test Your IPN" button at the bottom of the Tester page
  • Thoroughly review the successful payment page for complete field name replacement and shopping cart product iteration
  • Thoroughly review your transactions database for correct information (should be a single record entry with the fields item_name1, item_number1, quantity1, item_name2, item_number2, quantity2, etc. appended to the end of the record)
• Shopping Cart Purchase with incorrect price
  • Choose several products from the "item_name" drop-down list
  • Change to mc_gross field to something less than the aggregate price
  • Press the "Test Your IPN" button at the bottom of the Tester page
  • Thoroughly review the displayed page for your desired statement
  • Thoroughly review your transactions database for correct information

Password

There are several options for password protection of your IPN tools.  If you choose, you can completely disable password protection.   However, you should only do so if your IPN tools (both the html files and the scripts) are in password protected directories.  If you choose not to disable the built-in password protection, there are three options that determine how strict password protection is applied.  You may choose "strict," "lax," or "one time."  Strict protection requires that the password be entered for every action taken on any of the IPN tool pages.  Lax protection requires that the password be entered once for a single session (a browser session cookie is set).  One time protection requires the entry of the password only once.  Use this option only if you believe your computer is completely secure and only you have access to it.

When you change your password, enter the new password and your current password in the appropriate spaces.  After pressing the "Submit Changes" button, a new page will prompt you to re-enter the new password.  If the new passwords match, the password will be changed.

Note that any change to the password options require that you enter the current password before pressing "Submit Changes."

System Information

Your IPN Solution Dependencies

There are several files included with your IPN Solution that must remain in their starting locations and with their initial permissions.  The files and their function are listed below.

File	Description
/usr/local/www/cgi-bin/products.bsv	The product database.  It is used to verify transactions and to customize the successful payment page buyers see last.
/usr/local/www/cgi-bin/transactions.bsv	The transaction database.  It is used to verify transactions and, once the transaction is complete, to store transaction details (see IPNVariableRetention.htm).
/usr/local/www/cgi-bin/IPNProdMan.pl	This script is used to manage the product database.
/usr/local/www/cgi-bin/IPNTransMan.pl	This script is used to manage the transaction database.  It includes the ability to change which variables from each transaction are retained.
/usr/local/www/cgi-bin/IPNButtons.pl	This script is used to create Buy Now and Shopping Cart buttons.
/usr/local/www/cgi-bin/IPNTester.pl	This script is used to test your IPN solution after entering a new product.
/usr/local/www/cgi-bin/IPNPassword.pl	This script is used to set the options for and change you password.
/usr/local/www/cgi-bin/IPNSol.pl	This script is the workhorse of your IPN Solution.  It handles all interaction with PayPal and your site, including serving up the successful payment page to your customer.
/usr/local/www/cgi-bin/attachtypes	This file includes most known MIME types.  It is used in conjunction with IPNProdMan.pl to specify the email attachment type.
/usr/local/www/cgi-bin/success.htm	This is the successful payment page used for single item purchases.  This page is parsed for field references by IPNSol.pl before being sent to the customer's browser.
/usr/local/www/cgi-bin/success_cart.htm	This is the successful payment page used for shopping cart purchases.  This page is parsed for field references by IPNSol.pl before being sent to the customer's browser.
/usr/local/www/cgi-bin/error.htm	This page is used when the transaction attempt has errors.
/usr/local/www/IPNTools/index.html	This is the home page of your IPN Solution's tools.
/usr/local/www/IPNTools/IPNLaunchTools.htm	This page provides access to all the tools that come with your IPN solution.  This page is automatically loaded from index.html.
/usr/local/www/IPNTools/IPNFieldReferences.htm	This page lists the field references that may be included in your successful payment page (see success.htm).  (The references are replaced when IPNSol.pl parses the page before sending it to the customer.)
/usr/local/www/IPNTools/IPNCheckUp.htm	This page is used to access www.obrador.com to check for any updates to your IPN solution.  This page is automatically loaded from index.html.
/usr/local/www/IPNTools/ReceiveZip.jar	This is the Digital Goods Transfer of Custody Java archive.
/usr/local/www/cgi-bin/IPNtoc.pl	This script is used in conjunction with ReceiveZip.jar for Digital Goods Transfer of Custody.
/usr/local/www/IPNTools/IPNHelp.htm	This page.  It provides information and direction to help you get the most out of your IPN Solution.

The full file system path (not the URL) of an html file that will be displayed upon successful payment.  Images or other linked items within the html file should have their full URL specified.  The html file will be parsed and occurrences of field references will be replaced with their appropriate values.  See field references for a complete list.  (Field references are denoted by %%% before and after the field name.)

Includes checking to circumvent PayPal's greatest weakness (especially through IPN): price alteration.