This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Happy About™ Website Payments with PayPal Answers to Over 40 of the Most Commonly Asked Questions By Stephen Ivaskevicius and Patrick O’Neal with a foreword by Patrick Breitenbach WHITE PAPER - Subset of the book available at http://happyabout.info/paypal.php
21265 Stevens Creek Blvd. Suite 205 Cupertino, CA 95014
Trademarks All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Happy About™ cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark. PayPal is a registered trademark of PayPal Inc. eBay is a registered trademark of eBay Inc.
Warning and Disclaimer Every effort has been made to make this book as complete and as accurate as possible, but no warranty of fitness is implied. The information provided is on an “as is” basis. The authors and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book. The views expressed in this book are those of Happy About™, and do not necessarily reflect those of PayPal Inc. or eBay Inc.
NOTE: This is the TOC for the Book which can purchased at Amazon, your local book retailer or from Happy About™ at http://happyabout.info/paypal.php
Happy About Website Payments with PayPal Whitepaper
Page v
f o r e w o r d
Foreword by Patrick Breitenbach It's no secret that PayPal is one of the most successful services to hatch during the dot com era. From its humble beginnings in a small office building in downtown Palo Alto, California, (previous tenant: Google) through the growing pains of adolescence to young adulthood under the wing of online auction giant eBay, PayPal has achieved what few other Silicon Valley startups have: global recognition, hyper growth, financial success and most of all, a vibrant community of active users. I've had the distinct privilege to witness most of PayPal's lifespan from its public introduction in late 1999, through a public offering during the IPO doldrums, to a buyout by eBay to its current phase of maturation. The ride has been amazing. But it is that community of loyal users that has proven so fascinating and so crucial to both PayPal and eBay's success. Both companies managed to understand at an early stage that success was rooted in the community. Lots of companies are extremely customer centric but PayPal and eBay are practically directed by their users. Who could have predicted auto sales on eBay? Certainly not eBay. But when cars started getting sold, frequently "sight unseen", eBay Motors was born. When PayPal became "the way to pay on eBay", eBay scrapped its advantaged competitor Billpoint and purchased PayPal. When it came to Web developers, PayPal's community was even more pronounced. Over 300,000 developers registered for the PayPal Developers Network in the first 2 years. Instant Payment Notification (aka "IPN") scripts sprouted up like weeds all over the Internet. Over 200 developers attended the first PayPal developers conference in 2002 in San Francisco, California. And significantly, PayLoadz developer Shannon Sofield, created PayPalDev.org as a place for the PayPal developer community to share tips, answer questions and offer integration services. While a handful of PayPal employees participated on "the boards", the most value clearly came from the community. The genesis of this book came when long time PayPal employees and PayPalDev.org participants Stephen Ivaskevicius ("PayPalStephen") and Patrick O'Neal ("PayPal_PatrickO") wanted to pull together a compendium of the most-asked questions. Scouring the forums and sifting through hundreds of threads and thousands of posts, Stephen and Patrick culled the topics down to 43 and that is the book you are holding in your hand. Patrick and Stephen are eminently qualified in the task having been in PayPal Developer Technical
Happy About Website Payments with PayPal Whitepaper
Page 1
Support for several years each. Both have represented PayPal several times at the annual eBay Live confabs. And they, more than anyone at PayPal are on the developer front line, handling phone calls, turning around emails and monitoring the online forums. And so without further adieu, I am happy to present to you "Happy About Website Payments with PayPal". Please enjoy it and I have no doubt that you will express your feelings about the material at the Web forums! Patrick Breitenbach, Manager, PayPal Merchant Services
Page 2
foreword
c h a p t e r
1
Introduction
We are very "Happy About Website Payments with PayPal", so much that we want to help merchants and developers in using PayPal. In this book, we will provide real examples of common issues and questions merchants and developers have asked on the PayPalDev.org Message Board (http://paypaldev.org). PayPalStephen and PayPal_PatrickO work for PayPal Developer Technical Support. Most of the solutions they provide can be found on the PayPal Developer Network (http://paypal.com/pdn) or on PayPalTech.com (http://paypaltech.com). We have provided five chapters with commonly asked and some unique questions about using and integrating PayPal into Websites. We will cover shopping carts, subscriptions, shipping and tax, payment data transfer (PDT) and instant payment notification (IPN). These five chapters will help you set up the right front end needed to send information to PayPal to process your transaction and the back end needed to provide the product or service to your customer and update your records. The front end chapters are Shopping Cart, Subscription and Shipping & Tax. The back-end chapters are PDT and IPN. The Appendix (Tidbits) contains the stuff we could not fit into the existing chapters. Some excerpts from the forum may have been altered to fit the formatting of this book. A description of each topic will be provided, since some customers solve their issues or ask additional questions via the PayPal web forum or phone.
Happy About Website Payments with PayPal Whitepaper
Page 3
c h a p t e r
2
Shopping Cart
PayPal offers an easy-to-use HTML shopping cart with eight pass-through variables. PayPal’s cart can use the shipping, tax, color scheme, redirects and some required fields such as phone number or payment blocking. https://paypal.com/cgi-bin/webscr?cmd=p/xcl/rec/sc-intro-outside When these solutions do not fit your needs, you can usually find an answer on the message boards. The answers may be a turn key, customized, or open source solution. This chapter covers some of the basic solutions posted to the message boards that describe how to pass additional information (or calculate products and cost before passing the customer) to PayPal to process the payment.
Happy About Website Payments with PayPal Whitepaper
Page 5
The Basics Below is the basic code you would need to use PayPal's shopping cart.
The examples in this chapter explain how to use the basic code in common situations that allow a merchant or developer to obtain the look and feel they want when adding a PayPal button on their website. • • • • • • • •
Example Example Example Example Example Example Example
1: Shopping Cart Solution Advice: What is the Best Cart to Use? 7: Dynamic Pricing Shopping Cart Button 3: HTML Editors: Examining a View Cart Button Issue 4: HTML Help: Fixing Alignment Issues in a Table 5: Checkout Window Manipulation 6: I have my own Shopping Cart, How do I use it with PayPal? 7: Dynamic Pricing Shopping Cart Button
NOTE: The White Paper only shows a couple examples. The Book, which shows all the examples, can be purchased at Amazon, your local book retailer, or from Happy About™ at http://happyabout.info/paypal.php in either pdf or trade book versions.
Page 6
Chapter 2: Shopping Cart
Example 1:
Shopping Cart Solution Advice: What is the Best Cart to Use?
PayPalDev.org Poster
Subject: What is the Best Shopping Cart Solution for me to use with PayPal? I have searched on this but could not find an answer. Which would be the best way to script a simple shopping cart. All I need is to allow the visitor to add items to the shopping cart and be able to retrieve those items at checkout time. I do not want to use cookies since not all browsers support them and some visitors would not be able to order at all. I was thinking of using the IP of the visitor and storing it in a MySQL database, but I was told the IP could differ from page to page for the same visitor. So how do most shopping carts work? How can I keep track of a visitor's session.
PayPalStephen
You can use the PayPal Shopping Cart, it will allow you to place an HTML form for each product, when the form is submitted, it adds that product to a shopping cart. The customer can then continue shopping or check out. http://paypal.com/cgi-bin/webscr?cmd=p/xcl/rec/sc-intro-outside You can use a third party shopping cart that can be found in the PayPal Developer Network Third Party Solutions Section. http://paypal.com/cgi-bin/webscr?cmd=p/pdn/3p-solutions-code-outside http://paypal.com/cgi-bin/webscr?cmd=p/pdn/3p-solutions-stores-outside If you build your own shopping cart or have an existing shopping cart, you can pass the contents to PayPal using the Buy Now or Shopping Cart Upload code. https://paypal.com/cgi-bin/webscr?cmd=p/pdn/howto_checkout-outside
Happy About Website Payments with PayPal Whitepaper
Page 7
To update your database you can use the PayPal Instant Payment Notification (IPN) feature. http://paypal.com/cgi-bin/webscr?cmd=p/xcl/rec/ipn-intro-outside To let your customer see their order after it has been completed, you can use the PayPal Payment Data Transfer (PDT) feature. http://paypal.com/cgi-bin/webscr?cmd=p/xcl/rec/pdt-intro-outside To redirect customers that cancel before completing the order, you can use the 'cancel_return' variable.
PayPal uses cookies, JavaScript and 128 bit encryption on their secure website. So, you can use all of these on your web site to pass information to PayPal and process the payment. There are many tools you can use to set up a shopping cart with PayPal. To get an ideal of what you need, you can go to: http://paypaltech.com/Stephen/ppip/
Page 8
Chapter 2: Shopping Cart
Example 7:
PayPalDev.org Poster
Dynamic Pricing Shopping Cart Button
Subject: Adding drop-down Selections to Add to Cart Buttons I am trying to set up a paypal shopping cart on my site and am keen on setting up a drop down list for payments for various photos (depending on size) instead of one form per size. I saw the code in http://members.aol.com/paypalhelper/simp1.html but that requires insertion of code into the "head" portion of HTML. Unfortunately, my photosite only allows me control inside the "body" tag and I can’t insert code in other places. Any help?
PayPal_PatrickO
You can create a standard HTML drop down by hand editing the code like below.
To do this, the user must manipulate the amount variable, since it dictates price. Normally the amount is set via a hidden input type but these can be changed to whatever you like to give your users the look and feel that you desire. In this example, to add a drop down selection for price, the poster must find the line
and change it to <select name="amount">
This will provide the prospective buyer with a drop down menu on the front end that they can use to select the size they want. The size selection will drive the price charged. The user will see a drop down with choices of: size 1 and size 2. If they choose size 1, the price is 1.00, if they choose size 2, the price is 10.00. For advanced solutions that can dynamically change more than one variable, you can go to: http://paypaltech.com/Stephen/orderform/ http://paypaltech.com/Stephen/das/
Page 10
Chapter 2: Shopping Cart
c h a p t e r
3
Subscriptions
PayPal Subscription feature offers recurring billing with one free trial and one additional trial. The PayPal system treats subscriptions as payments for future services offered. This is important to note for merchants and developers looking for a post service recurring billing. PayPal allows you to alter the terms of the subscription, as well as to integrate the Subscription feature to work with a Perl Password Management IPN script. This chapter covers ways to use the PayPal Subscription feature outside the traditional set up to give you more flexibility collecting recurring payments.
Happy About Website Payments with PayPal Whitepaper
Page 11
The Basics Below is the basic code you would need to use PayPal's subscription.
The examples in this chapter explain how to use the basic code in common situations that a merchant or developer may have to obtain the look and feel they want when adding a PayPal button on their website. • • • • • • • •
Example 1: Modifying Subscriptions Example 2: Billing for Past Month: Using Invoicing as a Workaround Example 3: Minimum Term Subscription: You need a Contract Example 4: Dynamic Subscription Pricing Example 5: Managing Subscriptions Example 6: Subscription IPN's: When are they Triggered? Example 7: PayPal Password Management Basics Conclusion of Subscriptions
NOTE: The White Paper only shows a couple examples. The Book, which shows all the examples, can be purchased at Amazon, your local book retailer, or from Happy About™ at http://happyabout.info/paypal.php in either pdf or trade book versions.
Page 12
Chapter 3: Subscriptions
c h a p t e r
4
Shipping & Tax
PayPal offers shipping and tax settings (https://paypal.com/cgi-bin/webscr?cmd=p/ship/center-outside), but it has some limitations that could prevent a merchant or developer from being able to use it. Some common questions we find on the message boards have to do with collecting shipping cost based on weight, size, or location before sending the payment to PayPal. Other common questions are setting up multiple taxes for city, county, state, country, postal code or providence. In this chapter, you will find these questions and some of the solutions that we offer.
Happy About Website Payments with PayPal Whitepaper
Page 13
The Basics Below is the basic code you would need to use PayPal's shipping and tax in a button. If the profile based shipping or tax features do not fulfill your needs when using PayPal's buttons, you can use transaction based HTML code to achieve the results you need. The first variable of 'shipping' will apply to the first quantity of the item you create a button for: The second variable of 'shipping2' will apply to additional quantities of the same item you create a button for: Handling can be used to cover the "cost of doing business", this is not a "surcharge", this is simply the amount needed by a merchant to properly handle the product or service they are providing to a customer. Tax, is just that, the tax you want to apply to an item. This variable is only used for the shopping cart, it adds an additional cost to the entire cart order, this is used with the cart upload featured offered by PayPal, but could be used in the traditional shopping cart as well. This variable will override any tax variable in the code and only use the value you set. This is generally used with the cart upload feature, but can be used with the traditional cart as well. This variable has three possible values: zero (0) - give the customer the option to pass their shipping address to the merchant. one (1) - does not allow the customer to enter shipping information and does not pass any shipping information to the merchant. This is generally used for a digital good or
Page 14
Chapter 4: Shipping & Tax
service. two (2) - requires the customer to provide a shipping address and provides that to the merchant. Generally used for products that are shipped. This variable is used with the above variable when it has a value of (2). This also requires the Pre Population Variables. This will then pass the address the customer types in on your website and passes it PayPal, this can not be altered by the customer at that point and is provided to the merchant. This variable is used for 'unique' items and should not be used with the traditional shopping cart. The value has to be unique for every transaction. Once used, the PayPal system will prevent a product with the same value from being purchased again. This is generally used for "One of a kind" items or Artwork, autographs, digital goods key and so on. The examples in this chapter explain how to use the basic code in common situations that a merchant or developer may have in order to obtain the look and feel they want when adding a PayPal button on their website. • • • • • • • •
Example 1: Can you Ship to the US only? Example 2: The no_shipping variable and Other Code-level Shipping Variables Example 3: Overriding Tax Example 4: How to Charge for Standard vs. Express Shipping Example 5: How to do Tax and Shipping for Subscriptions Example 6: PayPal Fees and Shipping Charges Example 7: Dynamic Shipping based on Location Conclusion of Shipping & Tax
NOTE: The White Paper only shows a couple examples. The Book, which shows all the examples, can be purchased at Amazon, your local book retailer, or from Happy About™ at http://happyabout.info/paypal.php in either pdf or trade book versions.
Happy About Website Payments with PayPal Whitepaper
Page 15
c h a p t e r
5
Payment Data Transfer (PDT)
Payment Data Transfer (PDT) is a back end user initiated feature offered by PayPal. This feature is used to populate transaction information to a “Success” or “Thank You” page after the customer has completed a payment to you. PDT requires the use of scripts offered by PayPal in several languages. It uses a Token that you get from your PayPal profile and decrypts information passed to your page when the customer completes a transaction. PDT is used with the Auto Return feature. This will use a timed delay to automatically redirect your customer to your page. PDT can be used to allow your customer to print the invoice, email the customer the transaction information, allow access to your site, and provide a download of a product. Since PDT requires the customer to complete the process and go to your page, it is recommended that critical information is sent using IPN.
Happy About Website Payments with PayPal Whitepaper
Page 17
• • • • • • • • •
Example 1: Why You May Want to Use PDT Example 2: Using PDT with Auto Return Example 3: Using PDT to Limit Access to Displayed Information Example 4: Using PDT with Inventory Control Example 5: Limitations of PDT Example 6:PDT and eBay Example 7:PDT Sample Code Example 8: How you Generate a PDT Token Conclusion of PDT
NOTE: The White Paper only shows a couple examples. The Book, which shows all the examples, can be purchased at Amazon, your local book retailer, or from Happy About™ at http://happyabout.info/paypal.php in either pdf or trade book versions.
Page 18
Chapter 5: Payment Data Transfer (PDT)
c h a p t e r
6
Instant Payment Notification (IPN)
Instant Payment Notification (IPN) is PayPal's interface for handling real-time purchase confirmation and server-to-server communications. IPN delivers immediate notification and confirmation of PayPal payments you receive and provides status and additional data on pending, cancelled, or failed transactions. IPNs are delivered in the form of an HTTP POST of name/value pairs. They are sent from PayPal after you receive a payment. IPNs are sent to an IPN processing script that would run on your (the merchant's) web site. The purpose of this script would be to receive the IPN and perform the validation process and once complete, perform tasks that you deem necessary. Tasks could include the following: • • • • •
Customizing your Website's response to customer purchases in real-time Tracking customers/orders by writing records to a database on your web site Delivering access keys for software downloads and other digital goods Automation of fulfillment operations Tracking affiliate sales and commissions
Happy About Website Payments with PayPal Whitepaper
Page 19
The upcoming examples highlight some of the more common IPN related questions and provide summaries of the answers that were posted. • • • • • • • • • • •
Example 1: Getting Started with IPN: The Basics Example 2: How to Use IPN on Multiple Sites Example 3: Troubleshooting HTTP 500 Errors Example 4: The ‘rm’ Variable Example 5: Practicing IPN: Updating a Database and Sending an Email to a Customer after Payment. Example 6: IPN Script Planning Example 7: Just Starting Out with IPN Example 8: Deciphering payment_status=Pending, pending_reason=unilateral Example 9: Shopping Cart IPNs Explained Example 10: IPN and Subscriptions Conclusion for IPN
NOTE: The White Paper only shows a couple examples. The Book, which shows all the examples, can be purchased at Amazon, your local book retailer, or from Happy About™ at http://happyabout.info/paypal.php in either pdf or trade book versions.
Page 20
Chapter 6: Instant Payment Notification (IPN)
c h a p t e r
7
Conclusion
We have explored what you need on the front end of your website to use PayPal effectively and to pass your customers information to PayPal to process payment. This information was covered in the sections on Shopping Cart, Subscriptions and Shipping and Tax. In addition, PayPal provides the tools you can use on your back end to provide a unique and pleasant user experience. These are the PDT and IPN features which were covered in their respective sections. You should now have a better understanding of how PayPal's front-end and back-end processes work along with greater insight into some common issues developers’ face. There were a number of cases where the tools and products PayPal provides did not satisfy the developer’s request. In those situations, there were many workarounds explored that can deliver the result you want. We would recommend using PayPal Developer Network (PDN) (http://paypal.com/pdn) when you are setting up or adding enhancements to your website using PayPal. All of the information provided in this book can be accessed in one section or another from PDN. We would also recommend signing up for the PDN newsletter to keep up on any system or feature changes and updates. The no cost newsletter will also provide tips and introductions to new products and features PayPal launches.
Happy About Website Payments with PayPal Whitepaper
Page 21
a u t h o r s
About the Authors Stephen Ivaskevicius (PayPalStephen) is currently in Developer Technical Support. This includes support of PayPal’s API’s, Developer Central, Developer Network, PayPalTech.com and all features used in Merchant Tools. He is an ordained minister, motorcyclist and Parrothead. He graduated from Wayne State College in Wayne, NE in 1996 with a B.S. in Criminal Justice and Psychology. He worked in Corrections and Juvenile Services from 1996 until January 2001 when he started at PayPal (X.com). Stephen also maintains OasisBay.com, designing and developing websites at night and on weekends.
Patrick O’Neal (AKA PayPal_PatrickO) is a member of PayPal’s Developer Technical Support Team tasked with supporting PayPal Web Services and Developer Central. Before joining the Developer Technical Support team, Patrick was Senior Agent in PayPal Technical Support and worked primarily with supporting PayPal’s Merchant Features (e.g., web site payment buttons, IPN, and PDT). Patrick holds an Associate’s degree in Computer Network Systems and a Bachelor of Science degree in Computer Science with an emphasis on Web Programming. In his free time, Patrick enjoys learning new programming languages, spending time with his 3 children and gaming on the Xbox.
Happy About Website Payments with PayPal Whitepaper
Page 23
authors
A Message From Happy About™ Thank you for reading this Happy About whitepaper. The book is available online at http://HappyAbout.info/paypal.php or at other online and physical book stores in pdf and paperback versions. • Please contact us for quantity discounts at [email protected] • If you want to be informed by e-mail of upcoming Happy About™ books, please e-mail [email protected] • If you want to contribute to upcoming Happy About™ books, please go to http://happyabout.info/contribute/ Happy About helps companies establish thought leadership, increase leads and facilitate customer adoption. We write and publish books for corporations with a positive spin on educational and controversial topics utilizing case studies, testimonials and war stories from those that have "Been There and Done That!". Please contact us by e-mail [email protected] or phone (001-408-257-3000) if you are: • A corporation that would like to explore having us create a book for you • An author that would like to submit a book Other Happy About books available include: • Happy About Outsourcing http://happyabout.info/outsourcing.php • Happy About Knowing What to Expect in 2005 http://happyabout.info/economy.php
NOTE: The White Paper only shows a couple examples. The Book, which shows all the examples, can be purchased at Amazon, your local book retailer, or from Happy About™ at http://happyabout.info/paypal.php in either pdf or trade book versions.
Page 24
Happy About Website Payments with PayPal
“I never thought I would see the day when a book would rival the Internet as a source of customized, up-to-date information on a technical topic. The day has come.” Greg Brown, Vice President of Operations and Technology, The Tech Museum of Innovation “Stephen and Patrick have done a wonderful job with Happy About Website Payments with PayPal, sharing their wisdom about the most common problems people run into. This book is a must for anyone who wants to ensure they get every penny they are due.” Jared M. Spool, Usability Expert, UIE.com “This is a great book for PayPal merchants and developers. Easy-toread and full of tips and techniques that can be applied immediately. As a PayPal merchant that doesn’t generate much revenue with PayPal today, I learned a lot from this book. I expect to be able to dramatically increase the revenue I produce.” Mitchell Levy, PayPal Merchant and CEO, Happy About “Smart companies take great effort to nurture and sustain a vital developer community. This book pays tribute to the PayPal developer community by capturing the essentials required for a new developer (or merchant) to participate productively in the community and allows them to leverage the wisdom of those who have come before.” Rajiv Dholakia, V.P. Strategy & Solutions, PGP Corporation “This book is an invaluable asset! It provides clear, concise answers to the most common issues that a PayPal developer/merchant faces. Stephen and Patrick are the two most knowledgeable PayPal developers out there; they are the biggest contributors in the community and have closer relationships with the developers than any other advocates of the PayPal system.” Shannon Sofield, Lead Developer, PayLoadz.com and PayPalDev.org
