Note: This document was originally written by druru and was improved by Ryan and raddy. Inaccuracies should be reported in the documentation forum.
UC - Ubercart
PP - Paypal
CC - Credit Card
WPS - Web Payments Standard
IPN - Instant Payment Notification
INTRO - How this works behind the scenes
PayPal WPS works as follows:
- Customer fills in name, email, billing and shipping info on the checkout form.
- Customer selects to pay with CC (WPS) on the checkout form.
- Customer clicks "Review Order" and then "Submit Order."
- UC automatically "packages up" the customer's order (either as an itemized list or as a sum total depending on your WPS settings), along with the name, email, and shipping / billing addresses and redirects the customer along with that information to a secure payment form at PP.
- Customer fills in credit card info on the PP site. The form already contains all of the information passed to it by UC so the customer only needs to enter the CC details in the PayPal form.
* The customer may choose to create a PayPal account at checkout time depending on how you configured "Website Payment Preferences" in your PayPal account (see configuration steps below).
- Customer is either approved or denied by PayPal.
- Customer is manually or automatically redirected back to UC site.
- A user account is created automatically and the order tables updated appropriately when Ubercart receives the IPN from PayPal.
CONFIGURATION - How to make it work
PP Account Settings:
- Signup for a PayPal account.
Before you can use WPS you need to sign up for a PP account. We recommend using this link to tell PayPal you registered through Ubercart. They in turn support the continued development of our project.
- Open a business account (optional).
Although this step is optional, it is recommended for you to keep your personal and business PayPal accounts separate. Opening a business account is preferable because it allows you to use a business name on the PayPal checkout pages and in theory allows you to keep your private name separate. Presenting a business name to customers will help build customer confidence.
- Go through the approval process to verify your account. This will require a bank account and correct contact information, possibly more. You can always contact their customer service if you get stumped here.
- Configure PayPal account settings.
Login to your PayPal account and go to the profile page/tab. There are many options here but only a few are required to get WPS working with UC.
Setting up WPS:
- Click on "Website Payment Preferences" under the "Selling Preferences" section.
- Enable "Auto Return".
- Set the "Return URL" to
- Enable "Paypal Account Optional" (optional). This will make it so customers are not forced to create a PayPal account during checkout.
- Save your settings.
Setting up IPN:
- Click on "Instant Payment Notification Preferences" under the "Selling Preferences" section.
- Make sure that "Instant Payment Notification (IPN)" is not
- Make sure that no IPN URL is set. UC provides this automatically.
* Note: When you login to PayPal, you may get taken to a "Getting Started Steps" page. Steps 1 and 2 are required and involve opening your business account and getting verified. However, step 3 is not required. You do not have to create any buttons or links as UC handles redirecting users to PayPal automatically.
Ubercart PayPal Settings
- Enable uc_payment and uc_paypal modules at "admin/build/modules".
- Configure PayPal WPS settings at admin/store/settings/payment/edit/methods:
- Click the "Enable" checkbox for WPS.
- Expand the "PayPal Website Payments Standard settings" fieldset and make the following changes:
- Enter your PayPal account e-mail address in the appropriate field.
- Set the "PayPal server" to "Live" (versus Sandbox) when you're ready to process orders.
- The other fields are self-explanatory and based upon your requirements. Be sure to set them per your needs.
- Configure your Checkout Settings at admin/store/settings/checkout. You probably want to make sure you've enabled the following two options:
- New customers receive an e-mail with their account details.
- Anonymous checkout.
- Enable Automatic order update in WorkFlow-NG module by going to "admin/build/workflow-ng"
- Click "Edit" for the Update order status on full payment
- Tick "Active" checkbox.
- Click "Submit"
module by going to "admin/build/modules"
- Now enable Report feature by going to "admin/store/settings/reports"
- Choose "Payment Received" under "Report Statuses"
That's it! Everything should be working now.
TIP: PayPal automatically checks your billing and shipping addresses to see if they are valid when you submit the order from UC. It must use a national address database to do this. This is a great feature for security reasons. You can test it yourself and see how it works.
However, you need to remember that if you are testing your site and entering bogus address info, PP will not bring you to checkout page but instead spit out an error similar to following:
"Unable to process payment. Please contact the merchant as the shipping address provided by the merchant is invalid, and the merchant has requested that your order must be shipped to that address."
So, test with valid addresses. You CAN enter in bogus name, email and phone number for testing purposes but you MUST enter in a valid postal address or you never get to see how this works in real life!
Testing in the PayPal Sandbox (optional)
In order to test WPS without actually submitting real CC data, you can create a PP Sandbox account. This requires that you go to an entirely separate PayPal site and create a new and separate account from your main PayPal business or WPS account. Here's the site: http://developer.paypal.com
When testing in the sandbox, make sure you've configured WPS in your UC settings form to process payments in the Sandbox.