How Do I Set Up The PayPal™ Payment Module?

PayPal - Zen Cart(tm) Wiki

Detailed setup instructions are contained in the Zen Cart™ distribution zip file in /docs/3.readme_paypal_ipn.html.

Contents

• 1 How Do I Set Up The PayPal™ Payment Module?
  • 1.1 PayPal™ Setup Instructions in a Nutshell
  • 1.2 Using PayPal on Multiple Sites
  • 1.3 Things to check if it's not working
  • 1.4 How Does IPN work?
• 2 Testing PayPal™ Transactions
  • 2.1 Testing using a PayPal™ account
  • 2.2 Testing without a PayPal™ account

PayPal™ Setup Instructions in a Nutshell

This applies to North American PayPal™ users (and maybe others too).

ON THE PAYPAL™ WEBSITE

1. Log in.
2. Click on Profile.
3. Click on Email.
4. Write down your primary email address, noting any UppErcAse LettERS (if any). You need to use this exact email address in your Zen Cart™ settings in the next section below.
5. Click on Back to Profile Summary.
6. Click on Instant Payment Notification Preferences.
7. Click on Edit.
8. Turn it on (check the box).
9. Set the URL to: http://www.myz_domain.com/MY_SHOP/ipn_main_handler.php. (The complete correct URL can be obtained from your Admin area inside the PayPal payment module's information settings.)
10. Click Save.
11. Click on Website Payment Preferences.
12. Auto Return for Website Payments - set to on.
    • Provide the Return URL (obtain correct URL from your Zen Cart admin ... it will take the form of something like the following examples): http://www.myz_domain.com/MY_SHOP/index.php?main_page=checkout_process (for nonSSL sites) or
    • https://www.myz_domain.com/MY_SHOP/index.php?main_page=checkout_process (for sites with their own SSL Certificates) or
    • https://myz_domain.secureserver.net/MY_SHOP/index.php?main_page=checkout_process (for shared SSL)
13. Other settings in this area can be set based on your preferences. Consult PayPal™ for their meanings.
    • Payment Data Transfer ... If you're using PDT, make sure you have the same token in Zen Cart as you have in PayPal.
    • Encrypted Website Payments ... set this to OFF. Zen Cart does not currently support this option.
    • PayPal™ Account Optional ... if you want to allow customers to pay by credit card and not have to create a PayPal™ account, set this to ON
14. Click Save.
15. If your website's language is not a Western/European language, go to Language Encoding and set your language.
16. Turn off ALL tax and shipping settings in your PayPal™ account. These will cause your transaction amounts to not match Zen Cart™ amounts, and thus your orders will not be released.
17. Oh ... and ... if you've never had your PayPal™ account "verified", you should follow their steps to do so.

IN ZEN CART™

1. Admin > Modules > Payment > Paypal.
2. If this is the first time configuring for PayPal™ on this site, then you need to click on Install.
3. Otherwise, click on Edit.
4. Enter the primary email address of your PayPal™ account.
5. Configure any other options as desired.
6. Note the URL's suggested in the top of the PayPal™ module's instructions - they should match what you have set in your PayPal™ profile in the steps above for the PayPal™ site.
   

Another tutorial you might check out is at Camelot Hosting - PayPal™ Setup Tutorial.

Using PayPal on Multiple Sites

You can use a single PayPal™ account to collect payments from multiple Zen Cart™ sites simply by following the "In Zen Cart™" instructions above, for each site. Zen Cart™ will send override information to PayPal™ to let them know which store to send its notifications to.

If you use your PayPal™ account on non-Zen Cart™ sites or on eBay™, be sure that you have all "taxes" and "shipping" options disabled in your PayPal™ profile; otherwise these charges will be added to your Zen Cart™ orders and cause them to not match, and therefore they won't be released or added to your orders list.

Things to check if it's not working

These are the common configuration errors:

1. If it "was" working, but stopped, make sure PayPal's services are running properly. PayPal Live Server Status
2. Make sure your site is *not* in down-for-maintenance mode.
3. Make sure your site does *not* have password-protection via .htaccess in order to get to the "store" area.
4. Check that the email address you enter for PayPal™ in Zen Cart™ admin matches CaSE-SenSItiVE exactly with your PRIMARY email address setting in your PayPal™ account profile on PayPal's™ site.
5. Is your PayPal™ account "verified" yet?
6. Is your PayPal™ account a "Business" account? (Business is preferred. Premier can be used in some cases. Personal cannot.)
7. Check with your host that port 80 and 443 are open for bidirectional communication.
8. Use your browser and go to the Login page of your store. If the page is SSL, do you get any certificate errors in your browser? Test from a couple different computers that you don't normally use. An invalid SSL certificate or one that has errors of any sort, could prevent PayPal from successfully posting the notices to your site.
9. Try accessing http://your_site.com/ipn_main_handler.php with your browser. If you see PHP errors, those will need to be resolved. If you get a white screen, then the first phase of PayPal™ contacting your site isn't encountering errors. This doesn't mean there aren't any, it just means the initial most obvious steps are working.
10. There are two communication testing tools available in the support forum. If you are asking for troubleshooting help, please supply the URL to each of these tools after you have installed them on your site, so we can assess the responses they reveal.
11. Turn on debug logging in your PayPal™ module, and post a link to the zipped log files so they can be analyzed. You'll need to check to be sure that your /includes/modules/payment/paypal/logs folder is marked read/write (chmod 777). Then use your FTP program to access/view those logs and zip-and-upload them for analysis.
12. Check there is no IP block or firewall to prevent PayPal's™ servers from talking to your server (your host should check this, and you should check any blocking you may have done via your control panel. Also check .htaccess for any deny from statements and be sure none of them are addresses related to PayPal™.
    • PayPal IP Address List (these should be in your host's firewall whitelist)
    • notify.paypal.com (as of February 2008; check the link above for specifics):
      • 216.113.188.202
      • 216.113.188.203
      • 216.113.188.204
      • 66.211.170.66
    • For sandbox testing, also open: ipn.sandbox.paypal.com -> 66.135.197.164
    • NOTE: There are others worth checking on PayPal's Go Live Checklist page
13. You may find it helps to Uninstall ("remove") and Re-Install the payment module in Zen Cart™ admin.
14. When you use two PayPal™ accounts to make a simulation, make sure you're using the right account.
15. Check your PayPal™ profile settings on paypal.com
    • You need your Instant Payment Notification preferences ON
    • Instant Payment Notification URL must be set to the URL of your site's ipn_main_handler.php (ie: http://www.your_site.com/ipn_main_handler.php or http://www.your_site.com/directory/ipn_main_handler.php )
    • In Website Payment Preferences, your Return URL should be set to your site's checkout_process page. (ie: http://www.your_site.com/directory/index.php?main_page=checkout_process).
    • It is advisable to have Auto Return set to On.
16. Turn off ALL tax and shipping fees in your PayPal™ profile. They will cause the purchase price to mismatch when returning to Zen Cart™.
17. Using your hosting control panel, find the "Error Log" option, and check your server's errorlog entries to see if any attempts to access your site's ipn_main_handler.php file are being denied for any reason.
18. If you have a SEFU or SEO contribution installed, try removing it and testing again. Some are not configured to allow PayPal processing.
19. Prior to v1.3.8, the PayPal™ IPN handler (ipn_main_handler.php) uses its own version of application_top. If you make changes to your application_top.php, be sure to make these same changes (if applicable) in includes/modules/payment/paypal/ipn_application_top.php.
20. If you're using Payflow Pro (or Website Payments Pro UK), check your PayPal Manager area for any IP address restrictions. If you've got it restricted to only accept payment requests from certain IP addresses, make sure your webserver's IP address is in the list. Or clear the list out completely. A call to PayPal tech support can verify whether they have any additional IP addresses recorded that you can't see.
21. You can check whether PayPal has tried to send you IPN notifications that have failed, and re-send them if needed. In your PayPal account, in the My Account tab, go to the History menu and choose the IPN History option. Tick the relevant boxes and press "Resend selected". If there are many "failed", it's best to start with just checking ONE and attempting Resend. Then check your store to see if it comes through (give it 10-30 minutes). If it doesn't show up in your store, check the IPN debug logs on your server and see what errors have been recorded there.

How Does IPN work?

"IPN" = "Instant Payment Notification" ... part of PayPal's™ "Website Payments Standard" service.

1. Customer places an order on your site
2. For payment, they are taken to a link on PayPal's™ site, where they provide their information and pay for their order.
3. They click a link when finished (or wait 5 seconds) and return to your site.

Meanwhile, between steps 2 and 3 above, PayPal's™ server does this:

1. Paypal's™ server sends a request to your website...which is waiting and listening for connections from PayPal™ to the /ipn_main_handler.php page.
2. Your server sits waiting and listening on ports 80 and 443.
3. When your server receives a request, it attempts to validate and be sure that the PayPal™ data provided matches the order details for which it is intended.
4. If validation passes, the customer's order is released, and it lets the PayPal™ server know that you received their confirmation. This handshaking happens bidirectionally on ports 80 or 443, depending on how it was originated.
5. NOTE: PayPal's™ server will attempt the IPN notification (hourly) for up to four days if it's not successful on the first try. In this case your customer's order will not show up in the Admin until the IPN notification is successful.

Testing PayPal™ Transactions

To test that PayPal™ is properly configured, you should test two methods:

1. Test by paying for something using a PayPal™ account (not the same account as your store).
2. Test by paying for something with a credit card WITHOUT creating or using a PayPal™ account for payment.

All of these tests are to be performed in "production" or "live" mode. Do NOT use a Sandbox for testing. (If you don't know what this means, just proceed with testing.)

Testing using a PayPal™ account

1. You need a second PayPal™ account to do this. PayPal™ allows you to have two accounts per person: one personal and one business. For this test, you will pay for your purchase using funds on account in your personal PayPal™ account. You will be paying money to your store account (and refunding it).
2. Create or select a product which has a low price, such as $0.01 or maybe $1.00.
3. Purchase that product.
4. During checkout, choose the lowest-price shipping option.
5. During checkout, choose PayPal™.
6. After the Checkout Confirmation screen, you'll be taken to the PayPal™ website to make payment.
7. Enter your PERSONAL PayPal™ account username and password.
8. Confirm the transaction.
9. You will be returned to your store after completion.
10. Verify that you received two or three emails: one from PayPal™, one from the store to you as a customer, and one from the store to your Admin address. If you did not receive the emails from the store within five minutes, then go to the Troubleshooting section of this document, above.
11. Log in to your BUSINESS PayPal™ account and refund your test transaction.

Testing without a PayPal™ account

To test payment by credit card without using a PayPal™ account, use these steps:

(Before proceeding, find your credit cards, and select one that's not already associated with any PayPal™ account !!)

1. Create or select a product in your store which has a low price, such as $0.01 or maybe $1.00.
2. Purchase that product.
3. During checkout, choose the lowest-price shipping option.
4. During checkout, choose PayPal™.
5. After the Checkout Confirmation screen, you'll be taken to the PayPal™ website to make payment.
6. Underneath the login box for PayPal™ username/password, there is a link to Purchase without a PayPal™ account. Click that link.
7. Fill in and/or confirm your personal information.
8. Fill in your payment details including credit card number. (You should NOT use a credit card number that's already associated with any PayPal™ account !!)
9. Confirm the transaction.
10. You will be returned to your store after completion.
11. Verify that you received two or three emails: one from PayPal™, one from the store to you as a customer, and one from the store to your Admin address. If you did not receive the emails from the store within five minutes, then go to the Troubleshooting section of this document, above.
12. Log in to your BUSINESS PayPal™ account and refund your test transaction.

What's the difference between PayPal Standard, Express, and Pro?

Zen Cart(tm) Tutorials and FAQs - What's the difference between PayPal Standard,...

PayPal Express Checkout gives the customer two options: They can jump over to the PayPal site to login to their account BEFORE completing checkout on your store (which allows them to select their address information there and never have to re-type their address details on YOUR site, thus the "express" part of the transaction) and then choosing shipping choices and discounts/coupons etc before completing the order ....... OR they can go to the PayPal site to login to their account AFTER making shipping/payment/coupon selections on your site (and creating an account on your store and typing their address info on your store), much like they do with Standard.
With Express Checkout, the customer can pay without having a PayPal account (as long as you have "PayPal Account Optional" enabled inside your PayPal merchant account settings: Profile->Hosted Payment Settings->Website Payments Preferences->PayPal Account Optional = ON), except for merchants/customers in China.
One important benefit is that Express Checkout does not rely entirely on the IPN communications to your store in order to release the order. Instead, it stores the order immediately when payment is completed. It doesn't have to rely on the PayPal server to talk to your server in order to store the order. Granted, you will still want PayPal's server to be able to send IPN updates to you for any orders, in case you do refunds or adjustments to the order... so that those updates are reflected in your store's order history.
Express Checkout has all the same features as Website Payments Standard, but is more reliable because it completes the transaction directly while the customer is actively engaged on your site. It supports all the currencies, payment methods, etc, just the same, but more efficiently.

PayPal sees Express Checkout as a payment option that's offered in addition to other payment choices such as a credit card gateway, and that adding Express is a way to allow PayPal members a very quick and easy way to pay using their PayPal account. Many merchants do use Express Checkout as their sole payment processing option, even without a credit card gateway.

Many merchants also add Website Payments Pro:

Website Payments Pro appears to the customer only as a couple fields to enter their credit card number directly on your website. They have no idea that in the background you're processing their card via PayPal. They have to make an account on your site, and supply the address details, but once they confirm the order, the payment is collected immediately and the order saved. It doesn't rely on IPN to release the order. However, it does store any transaction updates done on the PayPal end such as refunds etc as long as IPNs can be received by your server. Website Payments Pro is currently only offered in the USA, UK, and Canada. A monthly service charge applies, and there is an account application process and credit check to complete before the feature can be activated on your account. PayPal Express Checkout must be enabled in order for Website Payments Pro to be offered on your site.

PayPal sees Website Payments Pro as a payment gateway for handling credit cards. That's exactly what it is. Coupled with Express Checkout, it gives your customers the maximum amount of choice about how to pay: either by credit card directly on your site, or by using their PayPal account to submit payment.

PayPal Website Payments Standard (formerly referred to as "PayPal IPN" in older versions of Zen Cart) takes the customer to PayPal's site AFTER the ENTIRE checkout in order to make payment. The customer can pay without having a PayPal account (depending on what country YOU are in ... PayPal limits that feature for some countries). After the payment is completed, your store is notified of the completed payment, after which time the order is stored in your database. If the customer pays without making a PayPal account and closes their browser when presented with the invitation to make one, your store sits in limbo and never gets the order (due to a bug in PayPal's logic, which they've not fixed yet). If they DO have OR make a PayPal account, you get the notification and the order is stored in your database.
**IF there is any problem in PayPal's ability to communicate to your server, you will never see the order in your store (or receive the confirmation email from your store), because it relies entirely on PayPal's server being able to talk to your server in order to store the order.

PayPal sees Website Payments Standard as a solution for merchants wanting to collect payments on their site easily, especially if they have no other payment method available.
Zen Cart recommends using Express Checkout instead of Website Payments Standard.


More information about the various PayPal services can be found on the PayPal website.


Another much-less-commonly-asked-about PayPal service is:

Payflow Pro is essentially *only* a merchant account. Transactions conducted via Payflow Pro (for US Merchants) do not appear in your PayPal account ... instead, they are forwarded directly to your merchant bank account. Basically, Payflow Pro is just like any other traditional payment gateway (akin to Authorize.net etc). In North America you can connect the Payflow Pro service to your own merchant bank account. In the UK, the Payflow Pro service is actually bundled as a hybrid service with Website Payments Pro, connecting all the transactions to your UK PayPal account, and all monies are deposited to your PayPal account, instead of directly to your bank account.
Zen Cart does not have built-in support for the US Payflow Pro service. However, there is a free addon which can be used for this purpose if required.

Please see PayPal's website for more Payflow and PayPal information.