Overview of PayPal (IPN) Instant Payment Notification Module

• Fully integrated with the Zen Cart™ checkout process, Payment and Order Totals classes.
• PayPal's (IPN) Instant Payment Notification automatically updates the store's database, regardless of whether the customer returns to the site or not.
• All PayPal IPN Information available directly on Admin Orders Page
• Full support for Zen Cart™'s built in coupons, gift certificates, downloadable products and shipping options.
• Supports PayPal Instant Payments, e-checks, credit card payments, and multiple currencies.
• Order-status changes with type of payment and/or refund/payment denial/cancellation.
  

Prerequisites for Use

• Completed, working installation of Zen Cart™ v1.3.x
• Premier or Merchant Business Account from PayPal.
  
  Some account configurations may need to be made in your PayPal
  account (at www.paypal.com) for various options that are available.
  See Frequently Asked Questions below for more information.
  

PayPal IPN Module Installation

Installing the Module

• Open your Zen Cart™ Admin page.
• Point your cursor at Modules on the menu bar.
• Choose Payment from the dropdown menu.
• Click the icon on the PayPal IPN row.
• Click the Install button.

Congratulations! You have installed the PayPal IPN module.

Upgrading the Module (or activating changes made in a new version)

This is only relevant if you've just installed an upgrade to Zen Cart™, from an earlier version:

• Open your Zen Cart™ Admin page.
• Point your cursor at Modules on the menu bar.
• Choose Payment from the dropdown menu.
• Click the icon on the PayPal IPN row.
• Click on the edit button .
• Write down all the settings that were previously configured.
• Click on OK
• Click the Remove button. This will uninstall configuration settings from the old version
• Click the Install button to activate the new version.
• Re-enter your configuration settings which you recorded earlier.

Congratulations! You have installed the updated PayPal IPN module.

PayPal IPN Module Configuration

Configuring the Module

• Enable PayPal Module - Do you want to accept PayPal payments?
  • True
    Choose True if not on by default
  • False
    Choosing False here will disable the module, meaning customers won't see it as an option during checkout

• Business ID - Primary email address for your PayPal account
  It's important to use the primary email address for your PayPal account.
  NOTE: This must match EXACTLY the primary email address on your paypal account settings. It IS case-sensitive, so please check your paypal preferences at paypal.com and be sure to enter the EXACT same primary email address here.



• Transaction Currency - Choose the currency/currencies you want to accept
  
  • Selected Currency (means customer-selected currency...the mode the customer is shopping in while placing the order on your site)
    Choose this option if you wish to accept payments in multiple currencies.
  
  
  • Only USD
    Choose this option if you wish to accept payments only in US Dollars.
    
    
  • Only CAD
    Choose this option if you wish to accept payments only in Canadian Dollars.
  
  
  • Only EUR
    Choose this option if you wish to accept payments only in Euros.
  
  
  • Only GBP
    Choose this option if you wish to accept payments only in British Pounds.
  
  
  • Only JPY
    Choose this option if you wish to accept payments only in Japanese Yen.
  
  
  • Only AUD
    Choose this option if you wish to accept payments only in Australian Dollars.
  
  
• Payment Zone - If a zone is selected, only enable this payment method for that zone. Customers in other zones will not see PayPal as a payment option during checkout.


• Set Pending Notification Status - Set the status of orders made with this payment module that are not yet completed to this value ('Pending' recommended)


• Set Order Status - Set the status of orders made with this payment module that have completed payment to this value ('Processing' recommended)
  (This is the status that is set when paypal sends notification via IPN to your store that the order has been paid for successfully on the paypal site.)


• Set Refund Order Status - Set the status of orders made with this payment module that have been refunded (in whole or in part) to this value ('Pending' recommended)


• Sort order of display - Sort order of display ... ie: what order the payment modules are displayed in during checkout. Lowest value is displayed first.


• Continue Button Text - When the customer is on the paypal site to make payment, there is a "continue" button that brings the customer back to your site once the payment process is completed. What you enter here is the text you want that button to display. Leave blank to just use "Continue" (default = blank).


• Page Style - On the paypal.com site, you can customize the appearance of the paypal page which your customers see while paying for their purchase. When you customize that page, you can give it a name. The default name is "paypal", and "paypal" is the page-name used if you don't specify another name on the paypal site.
  If you have created a customized page-style (aka template) on the paypal.com site, you can enter that page-style name here so it is used during customer-checkout.
  You can use "paypal" to use the default style supplied by paypal.
  You can use "primary" if you wish to use the style you have created and designated as primary on the paypal.com site.
  In most cases, setting/leaving this as "paypal" is perfectly acceptable.


• Mode for PayPal web services - Choose the URL for PayPal live or test services
• www.paypal.com/cgi-bin/webscr
        choose this URL for Live Services
• (might have to use www.paypal.com/us/cgi-bin/webscr)


• Debug Mode - You can log all the paypal IPN activity that happens between the paypal server and your store. This is very TECHNICAL output, and will not be of much benefit unless troubleshooting a paypal problem with a support technician. If you choose to "email" the data, it will go to the Store Owner's email address. Be sure to check your junkmail folder if messages are not showing up. If you choose to log the results, they will go to the /includes/modules/paypal/logs folder, which you will need to make read/write.
  

Frequently Asked Questions

Do I need to enable IPN in my PayPal Acccount Profile? What URL should I specify for the IPN feature to be used?

Yes, you must enable it.
1. Log into your PayPal account and go to Profile
2. Click on "Instant Payment Notification Preferences"
3. Click on Edit
The URL should point to: http://www.mydomain.com/ipn_main_handler.php
or if you have the Zen Cart™ program in a subdirectory:
http://www.mydomain.com/subdirectory/ipn_main_handler.php


Do I need to turn on the Auto-Return Feature in PayPal?

Yes. Enabling the Auto-Return feature in your PayPal account profile will return your customers to your site automatically 5-10 seconds after they've completed payment and finish their transaction in your Zen Cart™ store .

1. Log into your PayPal account and go to Profile
2. Click on "Website Payments Preferences"
3. Change Auto-Return to "On"
4. Provide a return URL:
For nonSSL sites:
http://www.mysite.com/MY_SHOP/index.php?main_page=checkout_process
or
For sites with their own SSL Certificates:
https://www.mysite.com/MY_SHOP/index.php?main_page=checkout_process
or
https://mysite.secureserver.net/MY_SHOP/index.php?main_page=checkout_process

Should I enable "PayPal Account Optional"?
This is your choice.

Sessions
Note: The sessions work automatically. Do not change your sessions setting in the Zen Cart Admin.