PayPal Instant Payment Notification - Features & Installation Instructions












Welcome to Zen Cart™ ...

The Zen Cart™ software is made available to you for use, additions, changes, modifications, etc. without charge, under the GNU General Public License.


While we do not charge for this software, donations are greatly appreciated each time you download a new version, to help cover the expenses of maintenance, upgrades, updates, the free support forum and the continued development of this software for your online e-commerce store.


Donations can be made at:
The Zen Cart™ Team Page


We appreciate your support.
The Zen Cart™ Team



Zen Cart™ is derived from: Copyright 2003 osCommerce
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
and is redistributable under the GNU General Public License







This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.






PayPal (IPN) Instant Payment Notification
Features & Installation Instructions


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.

MORE INFORMATION
https://www.paypal.com/en_US/pdf/PP_OrderManagement_IntegrationGuide.pdf








Zen Cart™ Copyright 2006