PAYPAL

GLOSSARY

• PayPal is the payment processing service owned by eBay
• paypal is the CGI program developed by PhysTech.com to enable sale of products from a web site with payment processing by PayPal
• item_name is the item_name/service assigned to the product when enabling it in Merchant Services of PayPal
• item_number is the Item ID assigned to the product when enabling it in Merchant Services of PayPal
• cgi-bin is the CGI directory of a web server where paypal program should be installed
• nobody is the name of the account web server runs under

INSTRUCTIONS

1. Create PayPal account. It can be personal or business account.
2. Login to PayPal account and click on My Account tab. Then click on Profile tab. Down the page click on Web Payment Preferences. Have the following options turned On or Off
   • Auto Return for Website Payments: On
     Return URL: type in the full URL to the paypal executable installed under cgi-bin directory of the web server. Read step 4 below.
     Example of Return URL: http://www.mywebsite.com/cgi-bin/p
   • Payment Data Transfer: On
     Copy the displayed Identity Token string into s.htm file to be created in step 10 below
   • Encrypted Website Payments
     Block Non-encrypted: On
   • PayPal Account Optional: On
   • Contact Telephone Number: Off
   • Express Checkout Settings
     Support giropay and bank transfer payments: No
   Click on Merchant Services and then on Buy Now Button. On the next page choose the following values:
   • Item name/service: product_x ← type in the item name. It is the same item_name parameter to be used later in steps 3-10
   • Item ID/number: NNN ← assign the number to the product item. It is the same item_number parameter to be used later in steps 3-10
   • Price: ← type in the price of product_x
   • Pick the Buy Button image you like
   • Button encryption: Yes
   Scroll down the page and click on Add More Options button. On the next page choose
   • Successfull payment URL: ← type in full URL to paypal executable on your web server, e.g. http://www.mywebsite.com/cgi-bin/p
   • Payment Data Transfer: On
   • Cancel Payment URL: ← type in full URL to paypal executable on your web server, e.g. http://www.mywebsite.com/cgi-bin/p
   • Quantity and shipping preferences: No
     No shipping needed
   • Customer notes and special instructions: No
   • Type in email address to receive payments
   Click on Create Button Now. On the next page select and copy HTML form code provided in the window and save it. That piece of HTML code will be used in 3.htm file in step 10. You may want to add target=_top string to form action tag if you are using frames or iframes.
3. Create product_x home page. This page is an example of product home page. The product_x home page should have URL link to product_x purchase page, with 2 mandatory parameters: item_number and item_name as in example:
   <A HREF="http://www.mywebsite.com/cgi-bin/p?item_number=NNN&item_name=product_x">Buy product_x</A>
   The http://www.mywebsite.com/cgi-bin/p part in the URL link should be the same one used for Return URL parameter in step 2 above when creating Buy Now Button
4. Install paypal executable into cgi-bin directory of the web server under some name, e.g. p, so that the full URL to that executable is the same as was typed in the step 2 when creating Buy Now Button, for example http://www.mywebsite.com/cgi-bin/p
5. Type the http://www.mywebsite.com/cgi-bin/p URL into the browser and verify the executable works. It should produce "paypal: no license found" string in the browser window.
6. Create subdirectory paypal under cgi-bin directory of the web server. Make nobody the owner of cgi-bin/paypal subdirectory.
7. Generate paypal.key license file and copy it to cgi-bin/paypal subdirectory. Set the permissions on the paypal.key file so that the nobody account is able to read paypal.key file.
8. Create subdirectory item_number under cgi-bin/paypal directory of the web server. Here item_number should actually be the numeric Item ID, for example cgi-bin/paypal/119 if item_number=119. Create symbolic link cgi-bin/paypal/item_name→cgi-bin/paypal/item_number, for example cgi-bin/paypal/product_x→cgi-bin/paypal/119
9. Create subdirectory cgi-bin/paypal/item_number/trans, for example cgi-bin/paypal/119/trans if item_number=119. The cgi-bin/paypal/item_number/trans subdirectory will store paypal confirmation pages for all purchases.
10. Create the following files under cgi-bin/paypal/item_number subdirectory. Click on the links to see the examples of the files.
    • 2.htm ← this file usually contains product disclaimers and HTML forms for customer input. This file is parsed and displayed by paypal when 2 parameters:
      item_number=NNN&item_name=product_x
      are passed to http://www.mywebsite.com/cgi-bin/p in URL string
    • 3.htm ← this file is processed when 3 parameters are passed to http://www.mywebsite.com/cgi-bin/p. Normally the call to http://www.mywebsite.com/cgi-bin/p with 3 parameters is made from the HTML form in 2.htm file. Paste the HTML code for Buy Now Button obtained in step 2 into 3.htm file if 3.htm file will have the last input form before passing control to PayPal.
    • [... n.htm ...] more n.htm files as necessary
    • s.htm ← this file has just 1 line with Identity Token obtained in step 2 above. The identify token is used by paypal program when communicating with PayPal to verify transaction.
    • item_number.exe ← this is a program which paypal will try to execute when browser is redirected from PayPal back to http://www.mywebsite.com/cgi-bin/p after successfull payment. The nobody account must have execute permissions on item_number.exe file. Example of item_number.exe file name: 119.exe. The input to item_number.exe program is provided by paypal via environment variables. paypal program makes all parameters passed in URL string available to item_number.exe program in a form of environment variables, as e.g.
      item_number=119
      item_name=product_x
      hostid=23ddss22
      dayofweek=Monday
      item_number.exe program should print name1=value1&name2=value2&... pairs in HTTP format on standard output. The name=value pairs printed by item_number.exe are used by paypal to parse and display t.htm file. The example of item_number.exe is an executable program which prints license_key=xxcvxxx for product_x based on the input provided by the buyer on various forms in 2.htm and 3.htm files. The license_key value will then be used by paypal to parse and display t.htm file.
    • t.htm ← this is the payment confirmation page. This file is parsed and displayed by paypal when browser is redirected from PayPal back to http://www.mywebsite.com/cgi-bin/p after successfull payment and after item_name.exe program is executed.
    • e.htm ← this is the error page. This file is parsed and displayed by paypal if an error is encountered with processing user inputs
    • trans ← this a directory where paypal program will store parsed t.htm files for every purchase made. The file names will be the same as transaction IDs provided by PayPal. The nobody account must have read/write permissions on this directory. If a buyer saves the link to the final confirmation page after successfull payment, and later tries to visit that page again the paypal will read and display the confirmation page from under trans subdirectory as it was displayed after the purchase.
    Note:
    • When processing 2.htm, 3.htm, t.htm, e.htm, etc files any strings of the form ${variable} will be substituted by paypal program with the corresponding HTML form value
    • files 2.htm, 3.htm, ... n.htm are parsed and displayed by paypal program based on the number of parameters passed in URL string, i.e. a call to
      http://www.mywebsite.com/cgi-bin/p?item_number=119&item_name=product_x
      makes paypal parse and display file 2.htm, and a call to
      http://www.mywebsite.com/cgi-bin/p?item_number=119&item_name=product_x&hostid=sdjjffss
      makes paypal parse and display file 3.htm, etc. One can have up to 128 parameters passed to paypal and up to 128 input files.
    • to avoid issues with permissions on the files and directories, change the owner of cgi-bin/paypal directory and all the files and subdirectories under cgi-bin/paypal to nobody account: chown -R nobody cgi-bin/paypal

paypal executables available for download:

Linux	paypal_linux.tgz	Test the paypal executable on command line. It should print some HTML output. If it coredumps or errors out on incompatible library, send email to support, describing the problem.
MS Windows cygwin	paypal_cygwin.tgz	The executable requires cygwin1.dll library to be present in the PATH.

Please email questions or comments to phystech@hotmail.com