Website Payments Standard Integration Guide Last updated: September 2008
PayPal Website Payments Standard Integration Guide Document Number: 100000.en_US-200809 © 2008 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Documentation Feedback . . . . . .
Contents Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . . 61 Sample HTML Code for Buy Now Buttons . . . . . . . . . . . . . . . . . . . . . . . . . 61 Sample HTML Code for a Basic Buy Now Button . . . . . . . . . . . . . . . . . . . . 61 Sample HTML Code for Buy Now Buttons With Product Options . . . . . . . . . . . . 62 Sample HTML Code for a Buy Now Button that Prompts for Quantities. . . . . . . . . 66 Sample URL Code for a Buy Now Email Payment Link . . . . . . . . .
Contents Chapter 3 Recurring Payments – Subscribe Buttons . . . . . . . . 107 Getting Started With Subscribe Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . .108 Using the Button Creation Tool for a Basic Subscribe Button . . . . . . . . . . . . . .108 Creating Basic Subscribe Buttons With JavaScript Disabled . . . . . . . . . . . . . .109 Creating Subscribe Buttons Before You Create Your PayPal Account . . . . . . . . . 112 The Checkout Experience With Subscribe Buttons . . . . . . . . . .
Contents Sample HTML Code for an Unsubscribe Button. . . . . . . . . . . . . . . . . . . . .171 Sample HTML Code for a Subscribe Button With Password Management . . . . . . .172 Sample HTML Code for a Subscribe Button That Reattempts Payments . . . . . . . .172 Sample URL Code for Subscribe Email Payment Links . . . . . . . . . . . . . . . . . . .173 Chapter 4 The PayPal Shopping Cart – Add to Cart and View Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Sample HTML Code for View Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . .238 Sample HTML Code for a View Cart Button . . . . . . . . . . . . . . . . . . . . . . .239 Sample HTML Code for a View Cart Button That Opens the Shopping Cart in the Merchant Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239 Sample HTML Code for View Cart Buttons that Continue Shopping on the Current Merchant Webpage . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Chapter 7 Using Your PayPal Account Profile . . . . . . . . . . . . 265 The Account Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265 Account Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265 Financial Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265 Selling Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Automatic Calculation of Shipping Charges (non-U.S. Merchants Only) . . . . . . . . . .304 Examples of Cost Methods and Shipping Calculations . . . . . . . . . . . . . . . . .305 Overriding Shipping Calculation on Individual Transactions . . . . . . . . . . . . . . .306 Blocking Certain Kinds of Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307 Accessing Your Payment Receiving Preferences to Block Payments . . . . . . . . . .307 Blocking Payments From U.S.
Contents Recommendations for Best Use of Authorization & Capture . . . . . . . . . . . . . . . .332 Capturing Funds on Basic Authorizations . . . . . . . . . . . . . . . . . . . . . . . .332 Buyer Approval for Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . .332 Voiding Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332 Chapter 9 Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . 333 Refunding Within 60 Days of Payment. . . . . . . . . . . .
Contents Appendix B Address Handling (U.S. Merchants Only) . . . . . . . . . 363 Address Handling With PayPal Account Optional Turned On . . . . . . . . . . . . . . . .364 Endpoint A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364 Endpoints B, C, and D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365 Endpoint E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365 Endpoints F and H . . . . . . . . . . . . . . . . . . . .
Contents 12 September 2008 Website Payments Standard Integration Guide
P Preface About This Guide The Website Payments Standard Integration Guide describes how to integrate your website with PayPal by using HTML buttons and forms. Website Payments Standard lets you accept payments for: z z z z Single-item purchases with Buy Now buttons – Sell from websites that offer single or mutually exclusive products. Contribution payments with Donate buttons – Raise financial support for any cause.
P Preface About This Guide TABLE P.1 Summary of the Contents of This Guide Feature Description See Automatic Calculation of Sales Tax Specify tax rates that PayPal uses to calculate taxes automatically. “Automatic Calculation of Sales Tax” on page 285 Automatic Calculation of Shipping Charges Specify shipping rates that PayPal uses to calculate shipping charges automatically. “Automatic Calculation of Shipping Charges (U.S.
Preface Intended Audience P Intended Audience This guide is for: z Merchants and developers who want to understand: – The checkout experiences that people go through when they make payments with Website Payments Standard payment buttons – How account profile settings affect the way that Website Payments Standard works z Developers who want to learn how to implement Website Payments Standard Revision History The following table lists the revisions made to the Website Payments Standard Integration Guide
P Preface Where to Go for More Information TABLE P.2 Revision History for This Guide Date Published Description August 2006 New PayPal Shopping Cart variable, shopping_url The value _ext-enter of the cmd variable for FORM prepoulation is now no longer necessary. Clarification of values for the rm variable – 0, 1, or 2; not the strings "GET" or "POST".
1 Single-Item Payments – Buy Now Buttons Use Buy Now buttons to accept single-item purchase payments. A Buy Now button can sell one or more units of a single item. Make additional Buy Now buttons for additional items that you want to sell. You can create Buy Now buttons that you add to your website by using a tool on the PayPal website, or you can write the HTML code for Buy Now buttons manually.
1 Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons Getting Started With Buy Now Buttons The easiest way to add a Buy Now button to your website is by using the button creation tool on the PayPal website. As soon as you add the button, you can begin accepting payments on your website.
Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons 1 7. Scroll to the bottom of the page, and click the Create Button button. The You are viewing your button code page opens. 8. Click the Select Code button on the Websites tab to select all of the generated HTML code. 9. Copy the text that you selected to the clipboard, by: – pressing Ctrl+C. – or – – right-clicking your mouse, and selecting Copy. 10.In your web editing tool, open the webpage where you want the button to be seen.
1 Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons For more information, see “Enabling JavaScript in Your Browser” on page 21. Creating a Basic Buy Now Button With JavaScript Disabled To create a basic Buy Now button for your website with JavaScript disabled: 1. Log in to your PayPal Premier or Business account at https://www.paypal.com. The My Account Overview page opens. 2. Click the Edit Profile link. The Profile Summary page opens. 3.
Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons 1 IMPO RTANT: Be sure that your tool is ready for you to paste HTML code, such as by switching to an HTML view from a design view of your webpage. 10.Paste the text that you copied from the clipboard onto your webpage where you want the button to appear, by: – pressing Ctrl+V. – or – – right-clicking your mouse, and selecting Paste.
1 Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons 5. Scroll down to the Scripting section, and then select the Enable radio button as the option for active scripting. 6. Click the OK button to dismiss the Security Settings dialog box. A Warning message box asks if you are sure you want to change the security settings. 7. Click the Yes button to dismiss the message box. 8. Click the OK button to dismiss the Internet Options dialog box. Enabling JavaScript in FireFox.
Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons z “Limitations of Buy Now Buttons Created Without a PayPal Account” on page 23 z “Unclaimed Payments From Buttons Created Without a PayPal Account” on page 23 z “Creating a Basic Buy Now Button Without a PayPal Account” on page 24 1 Limitations of Buy Now Buttons Created Without a PayPal Account Consider the following limitations of payment buttons that you create and add to your website before you sign up for your PayPal a
1 Single-Item Payments – Buy Now Buttons Getting Started With Buy Now Buttons FIGURE 1.1 Unclaimed Payments From Buttons Created Without a PayPal Account Creating a Basic Buy Now Button Without a PayPal Account To create a basic Buy Now button without a PayPal account: 1. Visit the PayPal website at https://www.paypal.com. 2. Click the Business tab. 3. Under the Need to accept credit cards? heading, click the On your website link. The Choose a payment solution page opens. 4.
Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons 1 10.Click the close icon in the upper right corner of the message box to proceed. The You’ve created your button page opens. 11. Click the Select Code button on the Websites tab to select all of the generated HTML code. 12.Copy the text that you selected to the clipboard, by: – pressing Ctrl+C. – or – – right-clicking your mouse, and selecting Copy. 13.
1 Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons FIGURE 1.
Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons 1 FIGURE 1.3 Buyers Begin on Your Website When They Are Ready To Buy Your Item In this example, Steve begins on Herschel’s Hot Sauce website and decides to try a bottle. He clicks the Buy Now button for a single 12 oz. bottle to check out.
1 Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons FIGURE 1.4 Buyers Enter Their Billinng information or Log In to PayPal For Buy Now buttons, the PayPal billing information/log-in page shows transaction details near the top, such as item name and transaction subtotal. If buyers are satisfied with the details, they do one of the following to select a payment method: z z 28 To pay with a credit card – Buyers enter their billing information.
Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons 1 In this case, Steve is satisfied with the total transaction amount of $5.95 USD. He doesn’t have a PayPal account. Instead, he enters his billing and contact information, and then he clicks the Review Order and Continue button.
1 Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons 3 – Buyers View and Print Their PayPal Payment Confirmations PayPal displays a payment confirmation page after buyers pay to let them know that they have completed their transactions and authorized their payments successfully. FIGURE 1.6 Buyers View Their Payment Confirmations From the payment confirmation page, buyers can: 30 z View the PayPal Receipt ID – the transaction ID – to reconcile their payments.
Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons 1 FIGURE 1.7 Buyers Print Their PayPal Payment Receipts In this case, Steve prints the PayPal payment receipt for his records. End – Buyers Receive Payment Authorization Notices by Email PayPal sends buyers a payment authorization notice by email to confirm the transaction that they made with the merchant.
1 Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons FIGURE 1.8 Buyers Receive Payment Authorization Notices by Email In this case, PayPal sends Steve an email message notifying him of his transaction with Herschel’s Hot Sauce and his authorization for payment of $5.95 USD.
Single-Item Payments – Buy Now Buttons The Checkout Experience With Buy Now Buttons z Calculating Tax and Shipping Amounts z Co-Branding the Checkout Pages with Your Logo and Colors z Prepopulating the Checkout Pages With Billing and Shipping Addresses z Returning People to Your Website After They Check Out 1 Calculating Tax and Shipping Amounts The basic checkout experience handles tax and shipping, if you provide the information.
1 Single-Item Payments – Buy Now Buttons Managing Buy Now Transactions IMPO RTANT: PayPal recommends that you turn Payment Data Transfer on when you turn Auto Return on. With Auto Return on, PayPal redirects people to your website from an alternative PayPal payment confirmation page that does not display a View Printable Receipt link, so people cannot print PayPal payment receipts. Payment Data Transfer provides the transaction information that you need to let people print receipts from your website.
Single-Item Payments – Buy Now Buttons Managing Buy Now Transactions 1 Using Recent Activity to Track Buy Now Transactions PayPal displays Buy Now transactions in your recent activity, soon after buyers complete their transactions by clicking Buy Now buttons on your website. FIGURE 1.9 Using Recent Activity to Track Buy Now Transactions To view your recent history: 1. Log in to you PayPal account. 2. Navigate to My Account > Overview. The My Account Overview opens. 3.
1 Single-Item Payments – Buy Now Buttons Advanced Features of Buy Now Buttons Using Instant Payment Notification to Track Buy Now Transactions PayPal lets your web server receive messages about Buy Now transactions and payment activity on your account. If you activate Instant Payment Notification, PayPal sends messages when: z Payments are first made, with a status of completed or pending. z Payments clear, fail, or are denied, if the initial status was pending.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 Prompting for Item Quantities With Buy Now Buttons By default, PayPal allows buyers to purchase single quantities of your product items with Buy Now buttons. You can have PayPal prompt buyers for item quantities, instead.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website In addition to HTML code, PayPal generates URL code for email payment links. Use email payment links to add Buy Now functionality to your email messages. If your web editing tool or your service provider does not allow you to paste HTML code onto your webpages, you may be able to paste the URL code for email payment links onto your webpages instead.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 One section at a time is open for you to work with. To work with another section, click its step bar to expand it. You can switch between the sections as often as you like, until you click the Create Button button at the bottom of the page. Then, PayPal generates the code for your button and displays it on the You are viewing your button code page.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website If you track inventory, PayPal helps you avoid oversold situations. PayPal sends you an alert by email when your inventory on hand falls to or below the alert level you specify. You have the option to let oversold transactions go through or to warn buyers and prevent them from buying more than your quantity on hand.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 – Click the My Saved Buttons link, and then click the Create new button link in the upper right of the page, if you previously saved payment buttons in your PayPal account. To create a new button that is similar to a button that you saved, find the saved button in the list. Then, click the Action dropdown menu at the right and click the Create similar button link.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website – Add dropdown menu with price/option – Select this checkbox to add a dropdown menu of product options, with a separate price for each option. Enter a name for the dropdown menu, such as “Color”. For each menu option, enter a name, such as “Red”, “Blue”, or “Green”, and the price you want buyers to pay. Select the currency for your prices from the dropdown menu.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 9. Add shipping charges and tax rates to your item (optional). You can add shipping charges and tax rates for your item here. They override the tax and shipping rates that PayPal calculates automatically based on rates that you specify in your account profile. – Shipping – Enter a specific amount to charge for shipping this item. The currency for the amount is the same as the currency for the item.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 11. Do one of the following: – Click the Create Button button if you specified all the features for your button. Follow the instructions for “Copying and Pasting the Buy Now Code” on page 50. – Click the Step 2 bar if you want PayPal to track inventory levels for your item or if you do not want to save your button in your PayPal account.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 Button” on page 40. If you set up product options with prices, the radio button is selected automatically. For each option listed, enter a unique item ID, the quantity that you currently have in stock, and an alert level. PayPal sends you an alert by email when your inventory on hand for any option falls to or below its alert level.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website of out of stock items. When PayPal detects an oversold situation, PayPal lets buyers know that the item is out of stock. If there are some items in stock, but not enough to fulfill a buyer’s request, PayPal proposes the amount currently available. Buyers can adjust their request to match the quantity on hand. Otherwise, they cannot check out.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 3. Do one of the following: – Click the Create Button button if you specified all the features for your button. Follow the instructions for “Copying and Pasting the Buy Now Code” on page 50. – Click the Step 3 bar if you want to specify advanced features for your button, such as prompting buyers for item quantities.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website – Yes – Select this radio button to prompt buyers for item quantities. PayPal prompts buyers for quantities after they click your Buy Now button. Use this feature cautiously, because buyers could specify quantities greater than you could fulfill.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 for the text box in which buyers enter there special instructions; the default value is “Add special instructions to merchant”. “Yes” is the default choice for this feature. – No – Select this radio button if you do not want a text box for special instructions. 3.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 6. Add advanced variables to the HTML code of your payment button (optional). If you are familiar with the HTML programming and the advanced HTML variables supported by Website Payments Standard payment buttons, you can enter them here. Select the checkbox, and then enter the variables in the text box below it.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 Copying and Pasting the HTML Code for the Buy Now Button. The Website tab on the You are viewing your button code page contains the generated HTML code for your Buy Now payment button. If in “Step 2 – Tracking Inventory With Your Buy Now Button” on page 44 you specified that you do not want to save your button in your Paypal account, PayPal protects the generated HTML button code with encryption.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1. Click the Select Code button on the Email tab to select all of the generated URL code. 2. Copy the text that you selected to the clipboard, by: – pressing Ctrl+C. – or – – right-clicking your mouse, and selecting Copy. 3. Open the email template or message that you want to send. 4. Paste the text that you copied from the clipboard into your email, by: – pressing Ctrl+V.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 2. Click the Edit Profile link. The Profile Summary page opens. 3. Under the Selling Preferences heading, click the Create New Button link. The Create PayPal payment button page opens. 4. Under the Create button without JavaScript enabled heading, click the Buy Now link. The Buy Now buttons page opens. 5. Enter the details of your item.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website To display your own image that is hosted on your website: – Click the Use your own button image link. An additional radio button and text box appear. – In the Button Image URL text box, enter the URL of your button image. If your image is hosted securely, change the entry to begin with https//. Use your own button image if the buttons hosted by PayPal do not fit the look of your website. 7.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 – Encrypted HTML code cannot be used for email payment links. Select the No radio button if you want to create an email payment link instead of or in addition to your button. If you select the No radio button for any reason, use an alternative strategy described in Chapter 6, “Securing Your Website Payments Standard Buttons” to secure the payments you receive from the payment button or the email payment link.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website and follow the instructions for “Page 2 – Specifying Advanced Features of Your Buy Now Button” on page 56. – or – If you entered all the basic and advanced features for your button, go to “Copying and Pasting the Buy Now Code With JavaScript Disabled” on page 59.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 3. Customize your buyer’s experience. Use these settings to give buyers a payment experience that is easy to navigate. – Successful Payment URL – (optional) Do one of the following: Enter the URL of a page on your website that you want buyers redirected to after they complete their payments. The URL that you enter is used by this payment button only.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 4. Select your quantity and shipping preferences. Use these settings to control how many units of the item you want to let buyers purchase and how you collect their shipping addresses. – Select the Yes radio button to let buyers purchase more than one unit of the item or service when they click the Buy Now button that you are creating.
Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website 1 5. Collect customer notes and special instructions from buyers. Use these settings to prompt buyers to enter notes or special handling instructions. – Select the Yes radio button if you want buyers to enter notes to you when they make their payments. If you leave the No radio button selected, buyers cannot include notes.
1 Single-Item Payments – Buy Now Buttons Creating Advanced Buy Now Buttons on the PayPal Website Copying and Pasting the HTML Code for the Buy Now Button With JavaScript Disabled. To copy and paste the HTML code for the Buy Now payment button: 1. Click the HTML code for Websites text box to select all of the generated HTML code. 2. Copy the text that you selected to the clipboard, by: – pressing Ctrl+C. – or – – right-clicking your mouse, and selecting Copy. 3.
Single-Item Payments – Buy Now Buttons Sample HTML Code for Buy Now Buttons 1 bottom of the Add a Buy Now button to your website page and click the Create Another Button button. Then follow the instructions for “Page 1 – Specifying the Basic Features of the Buy Now Button” on page 52, beginning with Step 5. The pages of the button creation tool retain the options that you previously specified.
1 Single-Item Payments – Buy Now Buttons Sample HTML Code for Buy Now Buttons name="item_name" value="Hot Sauce-12 oz. Bottle"> name="amount" value="5.95"> name="currency_code" value="USD"> PAGE 63
Single-Item Payments – Buy Now Buttons Sample HTML Code for Buy Now Buttons 1 Type of sauce
PAGE 64
1 Single-Item Payments – Buy Now Buttons Sample HTML Code for Buy Now Buttons PAGE 168
3 Recurring Payments – Subscribe Buttons Sample HTML Code for Subscribe Buttons name="currency_code" value="USD"> name="a1" value="129.95"> name="p1" value="1"> name="t1" value="M"> PAGE 169
Recurring Payments – Subscribe Buttons Sample HTML Code for Subscribe Buttons name="item_name" value="Hot Sauce-12 oz. Bottle"> name="amount" value="5.95"> name="currency_code" value="USD"> 
PAGE 171
Recurring Payments – Subscribe Buttons Sample HTML Code for Subscribe Buttons name="currency_code" value="USD"> name="a3" value="69.95"> name="p3" value="6"> name="t3" value="M"> ...
