PayPal Website Payments Standard - 2005 User Manual

Website Payments Standard Checkout Integration Guide
For Professional Use Only
Currently only available in English.
A usage Professional Uniquement
Disponible en Anglais uniquement pour l'instant.
Last Updated: November 2005
PayPal Website Payments Standard Checkout Integration Guide
Inc. Designated trademarks and brands are the property of their respective owners.
Notice of Non-Liability
PayPal, Inc. and the authors assume no liability for errors or omissions, or for damages, resulting from the use of this Manual or the information contained in this Manual.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Chapter 1 How Website Payments Standard Works . . . . . . . . . .15
Example of the Basic Page Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
How You Get Your Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Transaction History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Downloadable History Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Instant Payment Notification (IPN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
How To Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Other Standard Products and Features . . . . . . . . . . . . . . . . . . . . . . . . . 23
Website Payments Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Authorization & Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Related Online Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Complementary Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 2 Using Your Merchant Account Profile and Tools . . . . . .27
The Account Profile Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Account Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Financial Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Selling Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Correspondence Between Profile Settings and HTML Variables . . . . . . . . . . . . 28
Branding PayPal’s Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Working with Custom Payment Pages. . . . . . . . . . . . . . . . . . . . . . . . . . 31
Adding or Editing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Making a Page Style Primary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Overriding Page Style Settings On Individual Transactions . . . . . . . . . . . . . . . 33
Streamlining Purchases with Website Payment Preferences . . . . . . . . . . . . . . . . 34
Account Optional or Website Payments Express . . . . . . . . . . . . . . . . . . . . 35
Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Automatic Calculation of Shipping and Handling Cost and Tax . . . . . . . . . . . . . 45
Blocking Certain Kinds of Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
November 20053
Contents
Adding Your Credit Card Statement Name . . . . . . . . . . . . . . . . . . . . . . . . . 49
Getting Customer Contact Telephone Numbers . . . . . . . . . . . . . . . . . . . . . . . 49
Language Encoding Your Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Multi-User Access to Your PayPal Account . . . . . . . . . . . . . . . . . . . . . . . . . 55
PayPal-Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Accepting or Denying Cross-Currency Payments . . . . . . . . . . . . . . . . . . . . 57
Managing Currency Balances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Chapter 3 Single-Item Payment: Buy Now and Donations . . . . . . . 61
Using Buy Now or Donations Button Factory . . . . . . . . . . . . . . . . . . . . . . . . 61
Adding More Details to the Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Copy and Paste the HTML Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Sample Buy Now Button HTML and Hyperlink . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 4 Multiple-Item Payment: Shopping Cart . . . . . . . . . . . 67
How the PayPal-Hosted Shopping Cart Works . . . . . . . . . . . . . . . . . . . . . . . 67
What The Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Button Factory for PayPal-Hosted Shopping Cart . . . . . . . . . . . . . . . . . . . . . . 72
Adding More Details to the Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Copy and Paste the Shopping Cart HTML. . . . . . . . . . . . . . . . . . . . . . . . 74
Sample HTML for PayPal-Hosted Shopping Cart . . . . . . . . . . . . . . . . . . . . . . 75
How A Third-Party Shopping Cart Works . . . . . . . . . . . . . . . . . . . . . . . . . . 76
What The Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
What You See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Adding PayPal to Your Third-party Shopping Cart . . . . . . . . . . . . . . . . . . . . . . 82
Required Third-Party Shopping Cart Variables . . . . . . . . . . . . . . . . . . . . . 82
Passing Individual Item Details to PayPal . . . . . . . . . . . . . . . . . . . . . . . . 82
Setting the Tax for the Entire Cart. . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Passing the Aggregate Shopping Cart Amount to PayPal . . . . . . . . . . . . . . . . 83
Chapter 5 Encrypted Website Payments . . . . . . . . . . . . . . . . 85
Creating Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Creating Your Private Key Using OpenSSL . . . . . . . . . . . . . . . . . . . . . . . 86
Creating Your Public Certificate Using OpenSSL . . . . . . . . . . . . . . . . . . . . 86
Uploading Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4 November 2005
Contents
Downloading PayPal's Public Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Removing Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Blocking Unencrypted Website Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Chapter 6 Testing in the PayPal Sandbox . . . . . . . . . . . . . . . 89
Chapter 7 Website Payments Standard HTML FORM Basics . . . . . . 91
FORM Attributes: ACTION and METHOD . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Hidden Input Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Specifying the Website Payments Standard Product: cmd . . . . . . . . . . . . . . . . . 92
Variations on Basic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Prompting for Quantity in Buy Now or Donations: undefined_quantity . . . . . . . . . 92
Recordkeeping with Passthrough Variables . . . . . . . . . . . . . . . . . . . . . . . 92
Setting the Character Set: charset. . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Setting Return URL on Individual Transactions . . . . . . . . . . . . . . . . . . . . . 93
Desired Currency on Individual Transactions . . . . . . . . . . . . . . . . . . . . . . 93
URL-Encoding Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Prepopulating FORMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Sample HTML for FORM Prepopulation . . . . . . . . . . . . . . . . . . . . . . . . . 94
Overriding PayPal-Stored Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Sample HTML for Overriding PayPal-Stored Shipping Addresses . . . . . . . . . . . 95
Instant Payment Notification: notify_url . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Appendix A Website Payments Standard HTML Variables . . . . . . . .99
Appendix B Country Codes . . . . . . . . . . . . . . . . . . . . . . 109
ISO 3166 Standard Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
November 20055
Contents
6 November 2005
List of Tables
Table 1.1 How To Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 1.2 Hyperlinks for Fees, Security, User Agreement, Policies, Online Help, and
Customer Service 24
Table 1.3 PayPal Technical Documentation . . . . . . . . . . . . . . . . . . . . . 25
Table 2.1 Order of Page Style Customization Variables . . . . . . . . . . . . . . . 33
Table 2.2 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction
Amounts 56
Table 4.1 Required Third-Party Shopping Cart Variables . . . . . . . . . . . . . . 82
Table 5.1 How Encrypted Website Payments Work . . . . . . . . . . . . . . . . . 85
Table 7.1 Allowed Values for cmd Variable . . . . . . . . . . . . . . . . . . . . . . 92
Table 7.2 Character Sets and Encodings Supported by PayPal . . . . . . . . . . . 93
Table A.1 Allowed Values for cmd Variable . . . . . . . . . . . . . . . . . . . . . . 99
Table A.2 HTML Variables: IPN Control notify_url. . . . . . . . . . . . . . . . . . . 99
Table A.3 HTML Variables: Item Information . . . . . . . . . . . . . . . . . . . . . 99
Table A.4 HTML Variables: Display Information. . . . . . . . . . . . . . . . . . . .100
Table A.5 HTML Variables: Transaction Information . . . . . . . . . . . . . . . . .103
Table A.6 HTML Variables Specific to Shopping Carts . . . . . . . . . . . . . . . .104
Table A.7 HTML Variables: Individual Items in Third-Party Shopping Carts . . . . .104
Table A.8 HTML Variables: Prepopulating PayPal FORMs or Address Overriding . .105
Table A.9 HTML Variables: Prepopulating Business Account Sign-up . . . . . . . .106
Table B.1 ISO 3166 Two-Character Country Codes. . . . . . . . . . . . . . . . . .109
Website Payments Standard Checkout Integration Guide November 2005 7
List of Tables
8 November 2005Website Payments Standard Checkout Integration Guide
List of Figures
Figure 1.1 Basic Website Payments Standard Page Sequence . . . . . . 15
Figure 1.2 Beginning of Basic Page Sequence on Your Website . . . . . . 16
Figure 1.3 Customer Logs In to or Signs Up for PayPal . . . . . . . . . 17
Figure 1.4 Customer Reviews Payment . . . . . . . . . . . . . . . . . 18
Figure 1.5 Payment Confirmation or “You Made a Payment” Page on PayPal 19
Figure 1.6 Customer Returns to Your Website . . . . . . . . . . . . . 20
Figure 1.7 Account History: Recent Activity . . . . . . . . . . . . . . . 21
Figure 2.1 Account Profile Summary Page . . . . . . . . . . . . . . . 27
Figure 2.2 Uncustomized Payment Page in Standard PayPal Page Style . . 29
Figure 2.3 Complete Custom Page Style . . . . . . . . . . . . . . . . 30
Figure 2.4 Edit Custom Page Style Page . . . . . . . . . . . . . . . . 31
Figure 2.5 Website Payment Preferences on the Profile Summary Page . . 34
Figure 2.6 Page Sequence with PayPal Account Optional . . . . . . . . . 35
Figure 2.7 Momentary “You Made a Payment Page” with Auto Return On . 44
Figure 2.8 Payment Receiving Preferences . . . . . . . . . . . . . . . 47
Figure 2.9 Adding a Credit Card Statement Name . . . . . . . . . . . . 49
Figure 2.10 Prompt for Customer Contact Telephone Number . . . . . . . 50
Figure 2.11 Profile Selling Preferences for Language Encoding . . . . . . 51
Figure 2.12 Language Encoding Settings: Basic Choices . . . . . . . . . 52
Figure 2.13 Website Language Preference . . . . . . . . . . . . . . . . 53
Figure 2.14 More Language Encoding Options . . . . . . . . . . . . . . 54
Figure 2.15 Multi-User Access Link in Account Profile Summary . . . . . . 55
Figure 2.16 Multi-User Access: Adding a User . . . . . . . . . . . . . . 56
Figure 2.17 Accepting or Denying a Cross-Currency Payment . . . . . . . 57
Figure 4.1 PayPal-Hosted Shopping Cart Example: Add to Cart . . . . . 68
Figure 4.2 PayPal-Hosted Shopping Cart Example: Logging In to PayPal during
Checkout 69
Figure 4.3 PayPal-Hosted Shopping Cart Example: Confirmation Page . . 70
Figure 4.4 PayPal-Hosted Shopping Cart Example: Thank You Page After
Payment 71
Figure 4.5 PayPal-Hosted Shopping Cart Example: Email Transaction Receipt .
71
Figure 4.6 Third-party Shopping Cart Example: Add to Cart . . . . . . . 76
November 2005 9
List of Figures
Figure 4.7 Third-Party Shopping Cart Example: Proceed to Checkout . . . 77
Figure 4.8 Third-Party Shopping Cart Example: Logging In to PayPal during
Figure 4.9 Third-Party Shopping Cart Example: Confirmation Page . . . . 79
Figure 4.10 Shopping Cart Example: Thank You Page After Payment . . . 80
Figure 4.11 Example: Email Transaction Receipt . . . . . . . . . . . . . 80
Figure 4.12 Example: Seller’s Email Receipt . . . . . . . . . . . . . . . 81
Figure 5.1 Upload Public Certificate for EWP . . . . . . . . . . . . . . 87
Figure 5.2 Download PayPal’s Public Certificate for EWP . . . . . . . . . 88
Figure 7.1 How IPN Works: Three General Steps . . . . . . . . . . . . 96
Checkout 78
10 November 2005
List of Examples
Example 2.1 Flat Amount Shipping Calculation . . . . . . . . . . . . . . . . . . . . . 46
Example 2.2 Percentage Shipping Calculation . . . . . . . . . . . . . . . . . . . . . . 46
Example 3.1 HTML for Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . 65
Example 4.1 HTML for PayPal-Hosted Shopping Cart “Add to Cart” Button . . . . . . . 75
Example 4.1 HTML for Passing Individual Item Detail to PayPal. . . . . . . . . . . . . 83
Example 4.2 HTML for Aggregate Cart Detail to PayPal . . . . . . . . . . . . . . . . . 84
Example 7.1 HTML for FORM Prepopulation. . . . . . . . . . . . . . . . . . . . . . . 94
Example 7.2 HTML for Overriding PayPal-Stored Address. . . . . . . . . . . . . . . . 95
Website Payments Standard Checkout Integration Guide November 2005 11
List of Examples
12 November 2005 Website Payments Standard Checkout Integration Guide

Preface

This Document
This document, the PayPal Website Payments Standard Checkout Integration Guide, is a complete revision of the version issued in September 2005.
Intended Audience
This document is for merchants whose websites obtain payments using PayPal features.
Notational Conventions
This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below:
Typeface How Used
serif italics A document title.
A term being discussed or defined. For example: A file is a readable or writable stream of characters.
Boolean values (not keywords). For example: The function returns true if it encounters an error.
monospaced Pathnames or file names that appear in body text frames.
Code-related names that appear in body text frames. Such names are used for functions, callbacks, arguments, data structures, and fields.
For example: AbstractResponseType is the SOAP response type definition on which all PayPal API response methods are based.
Components of internet protocol requests and responses, such as HTTPS and FORM variables.
For example: The PayPal system uses a method=POST request to return IPN status variables related to subscriptions, such as txn_type.
Serif bold User interface names such as window names or menu selections.
For example: On the Profile page, click Email to confirm your email address.
San-serif oblique
Placeholders used in the context of a format or programming standard or formal descriptions of PayPal system syntax. Placeholders indicate values or names that the reader should provide.
Example: For example, amount is the variable for a single-item shopping cart, but
amount_
is the item amount for the third item in a multiple-item shopping cart.
X is the name of the variable for a multi-item shopping cart. amount_3
Website Payments Standard Checkout Integration Guide November 2005 13
Preface
To convey additional information, this document may also apply color and underlining to words or phrases that use the typefaces described above. Such use is described below:
Text attribute How Used
xxxxxx
xxxxxx
Documentation Problems
Hypertext link to a page in the current document or to another document in the set.
Hypertext link to a URL or that initiates a web action, such as sending mail.
If you discover any errors in or have any problems with this documentation, please mail us by following the instructions below. Describe the error or problem in as much detail as possible and give us the document title, the date of the document (located at the foot of every page), and the page number or page range.
To contact Customer Service about documentation problems:
1. Go to
https://www.paypal.com/.
2. Click Help in the upper left corner of the page.
3. Click Contact Us in the lower left corner of the page.
4. In the Help by Email section, click Contact PayPal Customer Service.
5. Complete the form.
To contact Developer Technical Support about documentation problems:
1. Go to
https://developer.paypal.com/.
2. Log in to your account by entering your email address and password in the Member Log In box.
3. Click Help Center at the bottom of the box on the right side of the page.
4. Click Email PayPal Technical Support.
5. Complete the form.
14 November 2005 Website Payments Standard Checkout Integration Guide
1

How Website Payments Standard Works

The PayPal Website Payments Standard Checkout Integration Guide describes how you use Website Payments Standard. Website Payments Standard consists of HTML FORMs on your website that direct your customer’s web browser to the PayPal website at
http://www.paypal.com in order to pay you and then return the customer to your website.
Figure 1.1, “Basic Website Payments Standard Page Sequence,” shows the basic sequence of
web browser pages when a customer pays you with PayPal Website Payments Standard.
FIGURE 1.1 Basic Website Payments Standard Page Sequence
All features of Website Payments Standard are variations on this basic page sequence. You use HTML FORM variables and the settings in your PayPal account Profile to affect the behavior of the basic sequence.
Website Payments Standard Checkout Integration Guide November 2005 15
How Website Payments Standard Works
1

Example of the Basic Page Sequence

Example of the Basic Page Sequence
Here’s an example of the basic page sequence of Website Payments Standard. Like all examples of pages in this guide, this example is based on the PayPal sample integration, which demonstrates how PayPal has been integrated with the fictitious online store called “DesignerFotos.”
BEGIN. The customer chooses to pay with PayPal on your website.
FIGURE 1.2 Beginning of Basic Page Sequence on Your Website
This example illustrates PayPal Buy Now, which is discussed in Chapter 3, “Single-Item
Payment: Buy Now and Donations.”
16 November 2005 Website Payments Standard Checkout Integration Guide
How Website Payments Standard Works
Example of the Basic Page Sequence
The customer logs in to PayPal.
FIGURE 1.3 Customer Logs In to or Signs Up for PayPal
1
If the customer were new to PayPal, the customer could choose to sign up for a PayPal account.
Website Payments Standard Checkout Integration Guide November 2005 17
How Website Payments Standard Works
1
Example of the Basic Page Sequence
On PayPal, the customer reviews the details of the payment and makes the payment.
FIGURE 1.4 Customer Reviews Payment
At this point, the customer can choose among funding sources (credit cards, debit cards, or bank accounts recorded in the PayPal accounts) with which to pay you and can also choose among shipping addresses stored on PayPal. This example does not show the pages containing these options.
18 November 2005 Website Payments Standard Checkout Integration Guide
How Website Payments Standard Works
Example of the Basic Page Sequence
The customer sees a payment confirmation page on PayPal and clicks Return to
Merchant.
FIGURE 1.5 Payment Confirmation or “You Made a Payment” Page on PayPal
1
Website Payments Standard Checkout Integration Guide November 2005 19
How Website Payments Standard Works
1
Example of the Basic Page Sequence
END. The customer is returned to your website.
FIGURE 1.6 Customer Returns to Your Website
20 November 2005 Website Payments Standard Checkout Integration Guide

How You Get Your Money

After a customer makes a payment, your PayPal account lists the payment in your Account History, as shown below.
FIGURE 1.7 Account History: Recent Activity
How Website Payments Standard Works
How You Get Your Money
1

Notifications You Receive

You can be notified of payments in four ways: email, History Log, Downloadable History Log, and Instant Payment Notification (IPN).

Email

You receive email notification in the following cases:
z Successful payment
z Pending payment
z Canceled payment
If you do not want to receive email notification:
1. Click the Profile subtab of the My Account tab.
2. Click the Notifications link in the Account Information column.
Website Payments Standard Checkout Integration Guide November 2005 21
How Website Payments Standard Works
1
Notifications You Receive
3. Under the Payment Notifications heading, clear the I receive PayPal Website Payments and Instant Purchase checkbox.
4. Click Save.

Transaction History

Your transaction history (also called your “History) displays information about your payments. The status of each payment is one of the following statuses:
z Completed: The transaction was successful and the money was credited to your account
z Cleared: The payment cleared the sender’s account and was credited to your account
z Uncleared: The payment has not cleared the sender’s account yet

Downloadable History Log

You can download copies of your transaction history to your computer. You can specify a date range for the transactions and the format of the downloadable file. The file contains a record of your transactions.
To learn more about Downloadable History Logs, see the Order Management Integration Guide.

Instant Payment Notification (IPN)

Instant Payment Notification is a mechanism by which you to receive transaction data. IPN posts individual transaction information to a URL on your website that you have programmed to process this incoming data. To use IPN, you must activate it, because it is disabled by default.
If IPN is activated, you receive a notification in the following cases:
z When a payment is first sent, indicating that the status of the payment is Completed or
Pending
z When a payment clears, fails, or is denied, if the status was pending
To learn more about IPN, see “Instant Payment Notification: notify_url” on page 96 and the Order Management Integration Guide.
22 November 2005 Website Payments Standard Checkout Integration Guide
How Website Payments Standard Works

How To Use This Guide

How To Use This Guide
Website Payments Standard has two primary components: Buy Now or Donations buttons and Shopping Cart. Both are constructed with the same basic set of HTML FORM variables. You can affect their behavior and appearance with settings in your account Profile and with additional FORM variables.
The following table summarizes the contents of this guide.
TABLE 1.1 How To Use This Guide
Feature Description See Also...
1
Buy Now or
Paying for single items from your website.
Donations
Shopping Cart Paying for multiple items from your website. It
comes in two forms: a shopping cart hosted on PayPal’s website and as HTML FORM variables for use in third-party shopping carts.
Custom Payment Pages Account Profile settings that brand PayPal’s pages
with your own colors and images.
“Account Optional” or Website Payments Express
Auto Return Account Profile settings that eliminate PayPal’s
Automatic Calculation of Shipping, Handling, and Tax
Customer Contact Telephone
Account Profile setting that allows a customer to pay you with credit or debit cards without having a PayPal account.
payment receipt page (step 4 in
Website Payments Standard Page Sequence
Account Profile settings that calculate shipping and handling costs and sales tax for you.
Account Profile setting that sends you the customer’s contact telephone number.
Figure 1.1, “Basic
).
Chapter 3, “Single-Item Payment: Buy Now and Donations
Chapter 4, “Multiple-Item Payment: Shopping Cart
“Branding PayPal’s Payment Pages” on page 29
“Account Optional or Website Payments Express” on page 35
“Auto Return” on page 43
“Automatic Calculation of Shipping and Handling Cost and Tax” on page 45
“Getting Customer Contact Telephone Numbers” on page 49
Multi-User Access Account Profile setting that allows up to seven
email addresses to share your Business account.
Encrypted Website Payments
Encrypt payment information before it is sent to PayPal to protect customer data.
“Multi-User Access to Your PayPal Account” on page 55
Chapter 5, “Encrypted Website Payments

Other Standard Products and Features

Website Payments Standard also includes other products and features not detailed in this guide:
Website Payments Standard Checkout Integration Guide November 2005 23
How Website Payments Standard Works
1

Related Online Information

z Instant Payment Notification (IPN) and Payment Data Transfer (PDT) are HTML FORM-
based mechanisms to send information about payments to programs on your website. IPN and PDT are described in the
z Subscriptions and Recurring Payments, which are described in the Subscriptions and
Recurring Payments Guide

Website Payments Pro

Website Payments Pro consists of PayPal Express Checkout and the Direct Payment Application Programming Interfaces (APIs). Rather than being based solely on HTML FORM variables (as is Website Payments Standard), these products rely on the PayPal Web Services API. For more information, see the

Authorization & Capture

Authorization & Capture supplements both Website Payments Standard and Website Payments Pro with PayPal’s enhancements to conventional credit card authorization and payment capture. It has both PayPal website tools and a Web Services Application Programming Interface (API). For more information, see the
Integration Guide.
Order Management Integration Guide.
Website Payments Pro Integration Guide.
Authorization & Capture
Related Online Information
Consult the following URLs for information about PayPal’s fees, online security, user agreement and related policies, online help, and customer service.
TABLE 1.2 Hyperlinks for Fees, Security, User Agreement, Policies, Online Help, and Customer
Service
Information URL
Fees https://www.paypal.com/fees
Online Security https://www.paypal.com/security
User Agreement and Policies
Online Help https://www.paypal.com/help
Customer Service https://www.paypal.com/wf
https://www.paypal.com/cgi-bin/webscr?cmd=p/gen/ua/ua-outside
24 November 2005 Website Payments Standard Checkout Integration Guide
How Website Payments Standard Works

Complementary Documentation

Complementary Documentation
All PayPal technical documentation is listed here. The description of each guide indicates its subject matter and documentation necessary for effective use of the guide.
TABLE 1.3 PayPal Technical Documentation
Guide Title Description Prerequisites
1
Website Payments Standard Integration Guide
Express Checkout Integration Guide
Website Payments Pro Integration Guide
Authorization & Capture Integration Guide
Details basic PayPal payment process for shopping cart and single-item purchase. Account Profile settings for variations on basic payment process. Customization of PayPal's payment pages. HTML
FORM variables for control of payment process.
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_Integrati onGuide.pdf
Details use of Express Checkout API. PayPal placement on merchants' websites and related business rules.
https://www.paypal.com/en_US/pdf/PP_ExpressCheckout_IntegrationGuide.p df
Details use of Express Checkout and Direct Payment APIs. PayPal placement on merchants' websites and related business logic.
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsPro_IntegrationGui de.pdf
Details use of PayPal website and API for authorization and capture; relates Authorization & Capture to Express Checkout and Direct Payment.
https://www.paypal.com/en_US/pdf/PP_AuthCapture_IntegrationGuide.pdf
None
Website Payments Standard Integration Guide
Website Payments Standard Integration Guide
z Website
Payments Standard Integration Guide
z Website
Payments Pro Integration Guide
z API Reference
Order Management Integration Guide
Details Instant Payment Notification (IPN) and Payment Data Transfer (PDT) for automated receipt of payment information after payment completion. Details IPN
FORM variables and their meanings. Also includes information about
HTML Downloadable History Logs.
Website Payments Standard Integration Guide
https://www.paypal.com/en_US/pdf/PP_OrderManagement_IntegrationGuide .pdf
Website Payments Standard Checkout Integration Guide November 2005 25
How Website Payments Standard Works
1
Complementary Documentation
TABLE 1.3 PayPal Technical Documentation
Guide Title Description Prerequisites
Java SDK Guide .NET SDK Guide Classic ASP Guide PHP SDK Guide
Details the use of the PayPal Software Development Kits for Java, Microsoft .NET, Microsoft Classic ASP, and PHP to simplify use of the PayPal Web Services API.
https://www.paypal.com/en_US/pdf/PP_SDK_Java_Guide.pdf https://www.paypal.com/en_US/pdf/PP_SDK_NET_Guide.pdf https://www.paypal.com/en_US/pdf/PP_SDK_ClassicASP_Guide.pdf https://www.paypal.com/en_US/pdf/PP_SDK_PHP_Guide.pdf
Sandbox User Guide Describes the PayPal Sandbox testing environment for testing website payments and
Web Services APIs. Details how to get PayPal API digital certificates.
https://www.paypal.com/en_US/pdf/PP_Sandbox_UserGuide.pdf
Web Services API Reference
Field-by-field description of all PayPal Web Services APIs, their SOAP structures, and error messages. Location of PayPal WSDL and XSD files.
https://www.paypal.com/en_US/pdf/PP_APIReference.pdf
z Website
Payments Standard Integration Guide
z Website
Payments Pro Integration Guide
z Authorization &
Capture Integration Guide
z Sandbox User
Guide
z API Reference
All other PayPal guides for an understanding of how products work
None
Subscriptions and Recurring Payments Guide
Virtual Terminal User Guide
Describes HTML services.
FORM variables for using PayPal for subscriptions to goods and
https://www.paypal.com/en_US/pdf/subscriptions.pdf
Details how to use the virtual terminal to accept credit card payments.
https://www.paypal.com/en_US/pdf/VT_user_guide.pdf
Website Payments Standard Integration Guide
None
26 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account
2
Profile and Tools
This chapter details how you can use your account Profile settings and other tools on the PayPal website to affect how payments are processed.

The Account Profile Summary

Use your PayPal account Profile to manage information about your PayPal account. To see your Profile, log in to your PayPal account, and click the Profile subtab of the My Account tab. The Profile has three sections: Account Information, Financial Information, and Selling Preferences.
FIGURE 2.1 Account Profile Summary Page
Website Payments Standard Checkout Integration Guide November 2005 27
Using Your Merchant Account Profile and Tools
2
The Account Profile Summary

Account Information

Use the Account Information column for basic account maintenance, including updating your password, adding and confirming email addresses, managing your business information, and (for Premier accounts) configuring multi-user access to your PayPal account.

Financial Information

Use the Financial Information column to organize and maintain the financial instruments associated with your PayPal account: manage your credit cards and bank accounts, activate and manage your PayPal Debit Card, maintain multiple currency balances, and view your monthly account statements.

Selling Preferences

Use the Selling Preferences column to organize the way you sell with your PayPal account, including:
z Branding PayPal’s payment pages
z Streamlining purchases with Website Payment Preferences:
– Account Optional –Auto Return – Automatic calculation of shipping, handling, and sales tax
z Payment receiving preferences for blocking certain kinds of payments
z Getting customers’ contact telephone numbers
z Language encoding your data
The majority of this chapter focuses on using Selling Preferences.

Correspondence Between Profile Settings and HTML Variables

Many Profile settings have equivalent HTML FORM variables that can control the behavior of individual transactions. After you enable a setting in your Profile, you can include FORM variables with a transaction to take advantage of that Profile setting. See the following sections for more information:
z “Overriding Page Style Settings On Individual Transactions” on page 33
z “Overriding Tax Setting on Individual Transactions” on page 46
z “Overriding Shipping Calculation on Individual Transactions” on page 46
z “Setting the Character Set: charset” on page 93
z “Setting Return URL on Individual Transactions” on page 93
z “Desired Currency on Individual Transactions” on page 93
28 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools

Branding PayPal’s Payment Pages

With our Custom Payment Pages feature, you can tailor PayPal’s payment pages to the style of your website. Custom Payment Pages work with all PayPal Website Payment buttons and with the PayPal Account Optional feature.
You can add up to three custom page styles.
The pictures in this section demonstrate the types of customization you can add to your PayPal Website Payment buttons. Figure 2.2, “Uncustomized Payment Page in Standard PayPal Page
Style,” shows a payment page with no customization.
FIGURE 2.2 Uncustomized Payment Page in Standard PayPal Page Style
Branding PayPal’s Payment Pages
2
Website Payments Standard Checkout Integration Guide November 2005 29
Using Your Merchant Account Profile and Tools
2
Branding PayPal’s Payment Pages
Figure 2.3, “Complete Custom Page Style,” shows all the customization you can make.
FIGURE 2.3 Complete Custom Page Style
Page header image Page header border color Page header background color
Page background color
30 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools

Working with Custom Payment Pages

1. Log in to your PayPal account at https://www.paypal.com.
2. Click the Profile subtab.
3. In the Selling Preferences column, click Custom Payment Pages.
The customization page shown in Figure 2.4, “Edit Custom Page Style Page,” is displayed.
FIGURE 2.4 Edit Custom Page Style Page
Branding PayPal’s Payment Pages
2
From this page, you can add, edit, preview, and remove page styles, and make any defined page style the primary page style.
Website Payments Standard Checkout Integration Guide November 2005 31
Using Your Merchant Account Profile and Tools
2
Branding PayPal’s Payment Pages

Adding or Editing a Page Style

The settings described here can also be specified with HTML FORM input variables set for individual transactions. For more information, see Table A.4, “HTML Variables: Display
Information” on page 100.
To add a page style:
1. Begin at the Custom Payment Page Styles page.
2. Click Add or Edit.
3. Enter your page style preferences:
z Page Style Name (required)
Enter a name up to 30 characters long. The name can contain letters, numbers, and underscores but no other symbols or spaces. The Page Style Name is used to refer to the page style in your PayPal account and in the HTML FORM Website Payment buttons.
z Header Image URL (optional)
Enter the URL for an image that should appear at the top left of the payment page. Maximum size of the image is 750 pixels wide by 90 pixels high; larger images are reduced to this size. The image must be in a valid graphics format such as gif, jpg, or png.
page_style variable for your
IMPORTANT:PayPal recommends that you enter an image URL only if the image is stored
on a secure (https) server. Otherwise, your customer’s web browser displays a message that the payment page contains insecure items.
z Header Background Color (optional)
Enter the background color for the header using HTML hex code. The color code must be six digits long and should not contain the # symbol. If the Header Image URL is present, the header is a 750 pixel wide by 90 pixel high space at the top of the payment page. If the Header Image URL is not present, the header height is only 45 pixels high.
z Header Border Color (optional)
Enter the border color for the header using HTML hex code. The color code must be six digits long and should not contain the # symbol. The header border is a two-pixel perimeter around the header space.
z Background Color (optional)
Enter the background color for the payment page using HTML hex code. The color code must be six digits long and should not contain the # symbol.
4. Click Preview to preview your page style, or click Save to save it.
Disallowed Colors. Because PayPal’s error message system highlights errors in red, PayPal
does not allow certain background colors that make these error messages unreadable.
A background color is allowed if you are able to preview the payment page with your chosen background color. If you receive an error message about the background color, the color is not allowed.
32 November 2005 Website Payments Standard Checkout Integration Guide
About Font Colors. PayPal dynamically changes font colors from black to white, depending
on the background color. To confirm that these font changes comply with your font color selections, you should test your color settings on PayPal.

Making a Page Style Primary

When you make a page style primary, it is applied to all payment pages unless you specify otherwise on individual transactions.
NOTE: If you do not designate a page style as Primary, the default is the PayPal page style.
To make a page style primary:
1. Begin at the Custom Payment Page Styles page shown in Figure 2.4, “Edit Custom Page
Style Page” on page 31.
2. Click the radio button next to the page style you wish to make your primary style.
3. Click Make Primary.
4. Click Make Primary to confirm your choice.
Using Your Merchant Account Profile and Tools
Branding PayPal’s Payment Pages
2

Overriding Page Style Settings On Individual Transactions

Your primary page style is applied to all payment pages unless you specify otherwise. You can override this behavior by specifying custom page style variables on individual transactions.
To change the page style for a button you already created, replace the value of the page_style variable with the page style name you want to use. The next time the button is clicked, the subsequent payment pages appear in the new style.
When you specify custom payment page variables on individual transactions, the page variables override page styles set in your Profile or the page_style variable. Customization variables take precedence in the following order:
TABLE 2.1 Order of Page Style Customization Variables
Custom Option Description
1 Custom Payment Pages
Variables on Individual Transactions
2 Primary Page Style on
Individual Transactions
3 Primary Page Style in
Profile
See
Table A.4, “HTML Variables: Display Information” on
page 100
With the on individual transactions that overrides any page styles set in your Profile.
You can create and set the primary style in your Profile.
.
page_style variable, you can specify a page style
4 Default PayPal Page
Style in Profile
Website Payments Standard Checkout Integration Guide November 2005 33
The default page style used when an alternative is not selected and designated as primary.
Using Your Merchant Account Profile and Tools
2

Streamlining Purchases with Website Payment Preferences

Streamlining Purchases with Website Payment Preferences
You can speed up your customers’ purchases with three Profile settings:
z Account Optional
z Auto Return
z Automatic calculation of shipping and handling cost and taxes
These settings are part of the Website Payment Preferences of your account Profile Selling Preferences.
FIGURE 2.5 Website Payment Preferences on the Profile Summary Page
34 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Streamlining Purchases with Website Payment Preferences

Account Optional or Website Payments Express

Account Optional (also known as Website Payments Express) is a Profile setting that allows customers new to PayPal to pay you by credit card without signing up for a PayPal account, thus shortening their time and effort.
Customers who have PayPal accounts go through the same Website Payments page sequence shown in Figure 1.1, “Basic Website Payments Standard Page Sequence” on page 15. Customers who are new to PayPal go through a page sequence that does not require PayPal signup, with the option to sign up after completing the payment.
FIGURE 2.6 Page Sequence with PayPal Account Optional
2
Website Payments Standard Checkout Integration Guide November 2005 35
Using Your Merchant Account Profile and Tools
2
Streamlining Purchases with Website Payment Preferences
Turning PayPal Account Optional On or Off
1. Log in to your PayPal account at https://www.paypal.com.
2. Click the Profile subtab.
3. Click the Website Payment Preferences link in the Selling Preferences column. See
Figure 2.5, “Website Payment Preferences on the Profile Summary Page” on page 34.
4. Scroll down to the PayPal Account Optional section of the page.
5. Select On to turn PayPal Account optional on, or Off to turn it off and use the basic
Website Payments flow.
6. Click Save to save your preference.
What Your Customer Sees With Account Optional On
Step 1: Bob goes to the DesignerFotos website and clicks Buy Now.
36 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Streamlining Purchases with Website Payment Preferences
Step 2: Bob is taken to a Payment Details page. He is prompted to log in to his PayPal account. He is not a PayPal member, so he clicks Secure Checkout.
2
Website Payments Standard Checkout Integration Guide November 2005 37
Using Your Merchant Account Profile and Tools
2
Streamlining Purchases with Website Payment Preferences
Step 3: Bob is prompted to enter the shipping information for the purchase, and to indicate if his shipping address is the same as the billing address on his credit card.
Accepting the default selection of Yes, Bob clicks Continue Checkout and is taken to the page shown in Step 4.
NOTE: If Payment Receiving Preferences are set to accept payments from customers only with
confirmed addresses, the customer skips this shipping information page and goes directly to billing information in Step 4.
38 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Streamlining Purchases with Website Payment Preferences
Step 4: Bob is prompted to enter billing information for the credit card for the purchase.
2
Website Payments Standard Checkout Integration Guide November 2005 39
Using Your Merchant Account Profile and Tools
2
Streamlining Purchases with Website Payment Preferences
Step 5: Bob is taken to a review page. He clicks Pay to complete his purchase.
40 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Streamlining Purchases with Website Payment Preferences
Step 6: Bob is taken to a payment completion page where he sees the Receipt ID for this transaction and DesignerFoto’s customer service contact information.
2
If Bob clicks Save My Info, he is taken to a page where he can enter the rest of the information needed to create a PayPal account (see Step 7). The information Bob entered to complete the transaction is carried forward.
If he clicks Return to Merchant, he is redirected to back to the merchant’s website.
Website Payments Standard Checkout Integration Guide November 2005 41
Using Your Merchant Account Profile and Tools
2
Streamlining Purchases with Website Payment Preferences
Step 7: If Bob clicked Save My Info, he is taken to a page where he can complete signing up for a PayPal account. Once he has filled in the fields, he clicks Save Information to create the account.
Step 8: Bob sees a page that confirms the creation of his account.
42 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Streamlining Purchases with Website Payment Preferences
Step 9: Bob receives an email receipt that confirms his payment and includes a copy of the payment details for this transaction.
2

Auto Return

With Auto Return for Website Payments, you can avoid making your customers click an extra button before returning to your website after completing a payment. Auto Return applies to all Website Payments, including Buy Now, Donations, Shopping Cart, and Subscriptions.
What Your Customer Sees with Auto Return On
With Auto Return on, instead of having to click a button on the You Made a Payment page (which is annotated as a circled 3 in Figure 1.1 and shown in Figure 1.5), the customer sees a payment confirmation page for a few seconds before the browser is returned to your website, as shown in Figure 2.7, “Momentary “You Made a Payment Page” with Auto Return On.”
Website Payments Standard Checkout Integration Guide November 2005 43
Using Your Merchant Account Profile and Tools
2
Streamlining Purchases with Website Payment Preferences
FIGURE 2.7 Momentary “You Made a Payment Page” with Auto Return On
Turning On Auto Return
To turn Auto Return on:
1. Log in to your PayPal account at
2. Click the Profile subtab.
3. Under the Selling Preferences column, click Website Payment Preferences. See
Figure 2.5, “Website Payment Preferences on the Profile Summary Page” on page 34.
4. Under Auto Return for Website Payments, click the On radio button to enable Auto Return.
https://www.paypal.com.
5. In the Return URL field, enter the URL to which you want your buyers redirected after payment completion.
44 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Streamlining Purchases with Website Payment Preferences
NOTE: If the Return URL you supply is not valid, PayPal displays the standard You Made a
Payment page when payment is complete.
6. Click Save.
Setting Return URL on Individual Transactions
With Auto Return turned on in your Profile, you can set the value of the return URL on each individual transaction, overriding the value you have stored on PayPal. For example, you might want to return the customer’s browser to a URL on your site that is specific to that customer, perhaps with a session-id or other transaction-related data included in the URL.
To set the return URL for a transaction, include the return variable in the HTML FORM:
<INPUT TYPE=”hidden” NAME=”return” value=”URLspecificToThisTransaction”>
Subscriptions Password Management and Auto Return
If you use or plan to use Subscriptions Password Management, you must make sure that Auto Return is turned off in order to display the PayPal-generated username and password to the buyer.
NOTE: You can use Auto Return with Subscriptions, which is a separate feature from
Subscription Password Management. For more information about Subscriptions, see the Subscriptions and Recurring Payments Guide, which is available on the PayPal website.
2

Automatic Calculation of Shipping and Handling Cost and Tax

You can set up your PayPal account to automatically calculate and charge shipping and sales tax (also called value added tax or VAT).
You can set up your PayPal account to automatically calculate and charge shipping.
To view or modify your sales tax and shipping charges:
1. Log in to your PayPal account at
1. Log in to your PayPal account at
2. Click the Profile subtab of the My Account tab.
3. In the Selling Preferences column, click Sales Tax or Shipping Calculation.
Sales or Value Added Tax Collection
You can charge your customers tax by choosing a country or state from the Country and U.S. State drop-down menus, and entering your tax rate for that state. All customers who reside in
the country or state you select are automatically charged the tax rate you choose. You can specify a different tax rate for each U.S. state and any of the listed countries.
IMPORTANT:If you are entering the rate for a U.S. state, ensure that the Country drop-
down menu is set to United States.
https://www.paypal.com.
https://www.paypal.com/cn.
Website Payments Standard Checkout Integration Guide November 2005 45
Using Your Merchant Account Profile and Tools
2
Streamlining Purchases with Website Payment Preferences
With the radio buttons, you can apply tax either to the item itself or to an item and any shipping and handling costs.
Click Save to save your changes.
Overriding Tax Setting on Individual Transactions
Regardless of a customer’s location, you can set a flat tax amount on an individual transaction or items in the transaction. For more information, see “Setting the Tax for the Entire Cart” on
page 83.
Shipping Calculation
Determine if you want to charge shipping as a flat amount or a percentage of the total purchase amount.
Flat Amount. A flat amount is based on the subtotal of a purchase. Choose the Flat Amount
radio button (indicated by $), and enter a flat amount for each currency amount increment. Click Save to save your changes.
EXAMPLE 2.1 Flat Amount Shipping Calculation
Assume your flat amount settings are as follows:
$0.00 through $49.99 = $3.00
$50.00+ = $6.00
If the subtotal is $36.50, your customer is charged $3.00 for shipping, and the total purchase $39.50.
If the subtotal is $66.50, your customer is charged $6.00 for shipping, and the total purchase $72.50.
Percentage. A percentage is based on the subtotal of a purchase. Choose the Percentage
radio button (indicated by %), and enter a percentage for each currency amount increment. Click Save to save your changes.
EXAMPLE 2.2 Percentage Shipping Calculation
Assume your percentage settings are as follows:
$0.00 through $49.99 = 5%
$50.00+ = 4%
If the subtotal is $36.50, your customer is charged 5% x $36.50 = $1.83 for shipping, and the total purchase $38.33.
If the subtotal is $66.50, your customer is charged 4% x $66.50 = $2.66 for shipping, and the total purchase $69.16.
Overriding Shipping Calculation on Individual Transactions
You might want to set a special shipping rate for an item; for example, if the item is especially heavy and costs more to ship or if it is a service which does not require shipping charges. To
46 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
charge a different shipping amount for an item, include the shipping cost in the shipping and handling_cart variables in the HTML FORM for the button.
You must set your Profile to allow individual transactions to override the Profile shipping calculation settings:
1. Go to the Shipping Calculations page in your Profile.
2. Click the checkbox labeled Click here to allow transaction-based shipping values to override the profile shipping settings listed above (if profile settings are enabled).
3. Click Save.

Blocking Certain Kinds of Payment

Payment Receiving Preferences let you block the types of payments you receive.
FIGURE 2.8 Payment Receiving Preferences
Blocking Certain Kinds of Payment
2
Blocking Payments From U.S. Users Without a Confirmed Address
You can better manage your risk by blocking payments where the buyer chooses not to share his Confirmed Address with you. PayPal provides Confirmed Addresses to help you make informed decisions when shipping goods. To be eligible for PayPal's Seller Protection Policy (SPP), and to help reduce your risk of dealing with fraudulent buyers, ship to a buyer’s Confirmed Address.
There are three choices for this preference:
z Yes: All payments from U.S. buyers without a Confirmed Address are blocked. All U.S.
buyers must provide a Confirmed Address in order to pay you.
z No: All payments are accepted. To maximize your sales, select No.
z Ask Me: You can choose whether to accept or deny payment without a Confirmed Address
on a case-by-case basis. This option allows you the flexibility to decide whether you want
Website Payments Standard Checkout Integration Guide November 2005 47
Using Your Merchant Account Profile and Tools
2
Blocking Certain Kinds of Payment
to take on the risk of not having the buyer’s Confirmed Address for each transaction. If you accept the payment, it becomes a completed transaction. If you deny a particular payment, the sender of the payment is notified that the payment has been denied and is credited with the payment amount. PayPal does not charge fees for denied payments.
Blocking Payments in a Currency You Do Not Hold
When you receive a payment in a currency you do not hold, PayPal prompts you to open a balance for that currency, convert it to your primary balance, or deny the payment. Payments in currencies for which you hold a balance are applied to the appropriate balance. You see a summary of each currency balance in your Account Overview page. For more information about managing your currency balances, see “PayPal-Supported Currencies” on page 56.”
There are three choices for this preference:
z Yes: Accept the payment regardless of the currency in which the payment is made.
z No, accept them and convert them to U.S. Dollars: Accept the payment but
automatically converts to U.S. Dollars.
z Ask Me: Transaction-by-transaction, you can choose to accept or deny a payment in a
currency you do not currently hold. If you accept the payment, it becomes a completed transaction. If you deny a particular payment, the sender of the payment is notified that the payment has been denied and is credited with the payment amount. PayPal does not charge fees for denied payments.
Blocking Payments From Users With Non-U.S. PayPal Accounts
Because many international addresses cannot be confirmed, you may choose to block payments from users with non-U.S. PayPal accounts in order to qualify for the Seller Protection Policy.
Blocking Payments From the Pay Anyone Subtab
You can choose whether or not to receive payments initiated via the Pay Anyone subtab of the Send Money tab on the PayPal website. Selecting this option might help you manage your
account, because the payments you receive will be associated with a specific item or transaction that you defined.
If you block these payments, you accept only payments initiated from Buy Now buttons, Donations, Shopping Cart, Subscriptions and Recurring Payments, Winning Buyer Notification, Mass Payments, Money Requests, Smart Logos, or eBay Checkout Payments.
Blocking Payments Funded By Credit Cards When Sender Has a Bank Account
You can force customers to pay you with a bank account or PayPal funds if they are able to do so. However, if they cannot pay you using a bank account or PayPal funds, they still have the option to pay with a credit card.
This preference can also help to reduce your risk of chargebacks. Verified users are users who have confirmed their bank accounts with PayPal or have been otherwise verified by PayPal. Because most Verified members have the option of paying with their bank accounts (via eCheck or Instant Transfer), this preference does not prevent users from sending you money. When they pay with PayPal’s Instant Transfer, you receive the payment instantly, just as when
48 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools

Adding Your Credit Card Statement Name

they pay with a credit card. Users who have not confirmed their bank accounts with PayPal can still send you money funded by credit cards.
Blocking Payments Funded By eChecks
You can block eCheck payments. Because eCheck payments take three to four business days to clear, you might want to block them for your Instant Purchase and Buy Now buttons.
If you choose to block these payments, users who attempt to pay via eCheck are prompted to add a credit card to their account before completing the transaction.
If you choose not to block these payments, you can receive eCheck payments through PayPal Website Payments or Auction Logos. eCheck payments are listed as Pending and are not credited to your PayPal account for three to four business days.
Adding Your Credit Card Statement Name
On the Payment Receiving Preferences page, you can specify the name that appears on your customers’ credit card statements.
2
FIGURE 2.9 Adding a Credit Card Statement Name
When a buyer pays you by credit card, your credit card statement name appears with the word PAYPAL* next to the charge on the statement (for example, PAYPAL*MYCCNAME). The Credit Card Statement Name can be up to 11 characters long, including spaces, but must not contain special characters (such as &, #, or _). The name is converted to all capital letters and might be truncated by some credit card processors.
The Credit Card Statement Name should accurately reflect your business or legal name.

Getting Customer Contact Telephone Numbers

“Customer Contact Information Telephone” is an option that gives you a contact telephone number for your customer. When you activate this option, customers are prompted to include a contact telephone number with their payment information.
Website Payments Standard Checkout Integration Guide November 2005 49
Using Your Merchant Account Profile and Tools
2

Language Encoding Your Data

IMPORTANT:In accordance with PayPal’s User Agreement, you may use this Contact
Telephone Number only to communicate with the buyer about the related purchase. You may not use this number for unsolicited commercial messages.
You can make the contact telephone number optional or required, or you can turn it off. “Off” is the recommended default option because customers value their privacy and prefer to minimize unsolicited communications.
When you require the buyer’s contact telephone number, your buyer sees the prompt during purchase.
FIGURE 2.10 Prompt for Customer Contact Telephone Number
Activating Customer Contact Telephone
Follow these steps to activate the Customer Contact Information Telephone option:
1. Log in to your PayPal account at
1. Log in to your PayPal account at
2. Click the My Account tab.
3. Click the Profile link.
4. Click the Website Payment Preferences link.
5. Select the option you prefer: On (Optional Field), On (Required Field), or Off (Recommended).
6. Complete the rest of the selections on the page.
7. Click Save.
Language Encoding Your Data
Websites that use PayPal in different parts of the world work with different languages. Human languages are represented in computing by the terms “character set” and “character encoding”.
https://www.paypal.com.
https://www.paypal.com/cn.
A character set is a computer representation of all the individual possible letterforms or word symbols of a language. For instance, ASCII (or American Standard Code for Information Interchange) is a common character set that has been used for decades to represent the
50 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Language Encoding Your Data
letterforms, numbers, punctuation, and symbols of American English. Another example of a character set is Big 5, which is one of the most widely implemented Chinese character sets. Character encoding, on the other hand, refers to how a particular character set is represented internally in data processing; that is, how the individual characters are actually stored and operated on. There many different kinds of character encodings. For example, an encoding might allow 7, 8, or 16 computer bits for a single character.
PayPal refers to these two terms together as language encoding.
Changing Your Language Encoding
With your Language Encoding preferences, you can precisely control the encoding of the data that PayPal should expect from your website’s use of any PayPal Website Payment button, and the encoding of the data that your website expects to receive back from PayPal
When you sign up for a new business account with PayPal, the PayPal system determines your character set and its encoding based on your country of origin, as specified by you during signup. For example, if your postal address indicates France, by default your Selling Preferences language encoding is set to a Western language character set.
Navigating Your Profile: Language Encoding
2
To set the default language encoding for your PayPal Business account, log in to your account and click the Profile tab. In the Selling Preferences column, click Language Encoding.
FIGURE 2.11 Profile Selling Preferences for Language Encoding
Website Payments Standard Checkout Integration Guide November 2005 51
Using Your Merchant Account Profile and Tools
2
Language Encoding Your Data
Changing Your Website Language
The Language Encoding page displays the setting for your website’s language, as shown in the following illustration. With the Your website’s language drop-down menu, you change the setting.
FIGURE 2.12 Language Encoding Settings: Basic Choices
To change the language of data PayPal should expect from your website, click the Your website’s language drop-down menu and select a different language, as shown in Figure 2.13,
“Website Language Preference.”
52 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
FIGURE 2.13 Website Language Preference
Language Encoding Your Data
2
Click Save to save your selection or Cancel to leave the setting unchanged.
More Encoding Options
If you want to specify the exact standard name of your website’s character encoding, click More Options on the Language Encoding page to open the More Encoding Options page shown in Figure 2.14, “More Language Encoding Options.”
The More Encoding Options page allows you to specify the character encoding PayPal should expect from your website and the encoding of data PayPal sends to your website.
Website Payments Standard Checkout Integration Guide November 2005 53
Using Your Merchant Account Profile and Tools
2
Language Encoding Your Data
FIGURE 2.14 More Language Encoding Options
The encoding selection in the Encoding drop-down menu is based on the country of origin you specified at signup.
To change the encoding selection, click the Encoding drop-down menu and select one of the available encodings. For a complete list of supported encodings, see “Table 7.2, “Character
Sets and Encodings Supported by PayPal” on page 93.
For data that PayPal sends to you, you have the option to specify the same or a different encoding. To use the same encoding as your website, click the Yes radio button. To use a different encoding, click the No, use radio button and select the desired encoding from the associated drop-down menu.
Setting Language Encoding On Individual Transactions
You can set the language encoding on each individual transaction with the charset variable. See “Setting the Character Set: charset” on page 93.
54 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools

Multi-User Access to Your PayPal Account

Multi-User Access to Your PayPal Account
With Multi-User Access, you can set up multiple logins with different permissions for business functions in your PayPal account, so employees have access only to the parts of your account they need to do their work. For example, you can give your customer service representatives their own login with limited permissions, so that they have the ability only to view balances and make refunds but not the ability to edit profiles, send money, or withdraw funds.
You can add up to seven separate logins to your account. You might want to establish a separate username and password for each employee, and grant each user the minimum access necessary. If an employee forgets or loses a password, you can log in and reset it.
NOTE: Remember to revoke the privileges of any employee that leaves your company.
To set up Multi-User Access:
1. Log in to your PayPal Business account.
2. Go to your Profile
2
3. Click Multi-User Access.
FIGURE 2.15 Multi-User Access Link in Account Profile Summary
4. Specify your Administrative Contact email address, which is the email address that receives notifications about your account activity.
NOTE: You must confirm this email address before you can proceed.
5. For each login, specify a User ID, password, and which account privileges the user has permission to use.
Website Payments Standard Checkout Integration Guide November 2005 55
Using Your Merchant Account Profile and Tools
2

PayPal-Supported Currencies

FIGURE 2.16 Multi-User Access: Adding a User
PayPal-Supported Currencies
The following currencies are supported by PayPal.
TABLE 2.2 PayPal-Supported Currencies, Currency Codes, and Maximum
Transaction Amounts
Maximum Transaction
Code Currency
AUD Australian Dollar 12,500 AUD
CAD Canadian Dollar 12,500 CAD
EUR Euro 8,000 EUR
56 November 2005 Website Payments Standard Checkout Integration Guide
Amount
Using Your Merchant Account Profile and Tools
T
ABLE 2.2 PayPal-Supported Currencies, Currency Codes, and Maximum
Transaction Amounts
Maximum Transaction
Code Currency
GBP Pound Sterling 5,500 GBP
JPY Japanese Yen 1,000,000 JPY
USD U.S. Dollar 10,000 USD
Amount

Accepting or Denying Cross-Currency Payments

You choose which currencies you accept and how you would like to accept them. You can set your Payment Receiving Preferences to handle cross-currency payments. See “Blocking
Certain Kinds of Payment” on page 47.
2
When a customer sends a payment in a currency you hold, the funds appear in your account in the balance of that currency. When a customer sends a payment in a currency you do not hold, you can accept or deny the payment.
FIGURE 2.17 Accepting or Denying a Cross-Currency Payment
Receiving fees are assessed in the currency in which the funds were sent. Payments converted to your primary currency are converted at a competitive exchange rate.
Website Payments Standard Checkout Integration Guide November 2005 57
Using Your Merchant Account Profile and Tools
2

Issuing Refunds

Managing Currency Balances

Use the Currency Balances section of your Profile to manage your currency balances:
z Select your primary currency
z Open or close a currency balance
z Transfer funds between currency balances. Funds transferred from one currency balance to
another are exchanged at a competitive rate.
Issuing Refunds
When you issue a refund, the gross amount of the refund is sent to your customer. The gross amount equals the net amount of the original transaction plus the refunded fee from PayPal.
Gross Amount = Net Amount + Refunded Fee
Refunding Within 60 Days of Payment
You can refund the entire amount of a transaction or portions of it. If you issue a refund within 60 days, the original transaction fee for receiving the payment is credited to your account. For partial refunds, you are credited a percentage of the original transaction fee based on the refunded amount.
To issue a refund within 60 days:
1. Log in to your PayPal account.
2. Click the History subtab.
3. Find the payment transaction you want to refund.
4. Click the Details link for the transaction.
5. Click the Refund Payment link on the Transaction Details page.
6. Enter the refund amount and click Submit.
7. Confirm the refund amount and click Process Refund.
If you refund a pending eCheck payment, no fees are charged because the pending payment is effectively canceled.
Refunding After 60 Days
When you issue a refund after 60 days, your original transaction fee for receiving the payment is not credited to your account.
To issue a refund after 60 days:
1. Log in to your PayPal account.
2. Click the Send Money tab.
58 November 2005 Website Payments Standard Checkout Integration Guide
Using Your Merchant Account Profile and Tools
Issuing Refunds
3. Enter the required information.
4. Click Continue.
5. Review the information on the confirmation page, and click Send Money to complete the
refund.
2
Website Payments Standard Checkout Integration Guide November 2005 59
Using Your Merchant Account Profile and Tools
2
Issuing Refunds
60 November 2005 Website Payments Standard Checkout Integration Guide
3

Single-Item Payment: Buy Now and Donations

Buy Now or Donations buttons are suitable for single-item payments or purchases. A single Buy Now button can sell one or more copies of the same item. However, to sell different items you must create separate Buy Now Buttons for each or use PayPal’s Shopping Cart. You can use to a Donations button to collect a pre-determined amount, or you can allow your donors to choose the amounts of their donations. “Example of the Basic Page Sequence” on page 16 shows how Buy Now or Donations work.
You can create a Buy Now or Donation button in two ways:
1. Use PayPal’s online Buy Now or Donation button factory to create an HTML FORM you copy to your website or to an email message.
2. Using the webpage tools of your own choice, construct your own HTML FORM based on the example in “Sample Buy Now Button HTML and Hyperlink” on page 65 and the descriptions of variables in Appendix A, “Website Payments Standard HTML Variables.”

Using Buy Now or Donations Button Factory

The button factories for Buy Now and Donations work in exactly the same way, except they prompt for slightly different information. These differences are noted in the following steps.
To create HTML with the Buy Now or Donations button factory:
1. Log in to your PayPal account at
2. Click the Merchant Tools tab.
3. Click Buy Now Buttons or Donations.
4. Enter the details of your item. All fields are optional.
Buy Now Button Fields
Item Name/Service: Enter the name of the item or service you wish to sell. If you do not
enter anything in this field, your customers can complete it at time of purchase. PayPal recommends entering an item name to make it easier for you to ship the order.
Item ID/Number: If you have an ID or tracking number for your item, enter it here. This
field is not be displayed to your customers at the time of payment, but they see it in their transaction details on the PayPal website.
Item Price: Enter the price of the item you wish to sell. If you do not enter anything in
this field, your customers can complete it. PayPal recommends entering an Item Price to make it easier for you to collect the correct amount.
https://www.paypal.com.
Website Payments Standard Checkout Integration Guide November 2005 61
Single-Item Payment: Buy Now and Donations
3
Using Buy Now or Donations Button Factory
Donations Button Fields
Donation Name/Service: Enter the reason for payment or the name of your
organization/charity here. If you do not enter anything in this field, your donors can complete this field.
Donation ID/Number: You can use this field to differentiate payments (e.g. to enter a
campaign name). This field is not displayed to your donors at the time of payment, but they see it in their transaction details on the PayPal website.
Donation Amount: If you would like to collect a pre-determined amount, you can enter
it in the Donation Amount field. If you would like your donors to choose their donation amounts, do not enter a price in this field. Users are prompted to enter a donation amount when they make payment.
Common Fields
Currency: Choose the currency in which you would like this payment to be
denominated. This field defaults to the currency of your primary balance.
Buyer’s Country: To display the PayPal login or sign-up page in a certain language,
select a country where that language is spoken from the pull-down menu.
5. Choose a image for your button.
If you are going to receive payments or donations from your website, choose the image for the button you would like your customers to click to make their purchase. To display your own image, enter the URL of the image’s location in the URL field.
NOTE: PayPal recommends that you enter an image URL only if the image is stored on a
secure (https) server. Otherwise, your customer’s web browser displays a message that the payment page contains insecure items.
If you are creating an email link, go to “Adding More Details to the Button” on page 63.
6. Security Settings
PayPal offers the option to encrypt your button’s HTML code. Encryption ensures that an item’s price and other details cannot be altered by a third party, thus increasing the security of your transactions. Select Yes to encrypt your code, or No to leave it editable.
PayPal highly recommends encrypting your button code. However, there are three limitations:
– Encrypted button HTML is not editable. If you want to modify your button code
manually, select No for this option.
– You cannot encrypt your button if it has dynamically-generated code from the Add
More Options page, such as drop-down Options fields (see step 5). If you need Option fields for your products, select No to turn encryption off.
– If you choose to encrypt your button, you cannot create an email link.
62 November 2005 Website Payments Standard Checkout Integration Guide

Adding More Details to the Button

If you do not have additional details to add to your button (such as sales tax, shipping, or your logo), click Create Button Now and go to “Copy and Paste the HTML Code” on page 64. Otherwise, click Add More Options.
If you have additional details for your button, follow these steps:
1. For Buy Now buttons, Add Shipping and Sales Tax
Shipping Cost Calculation: If you have specified shipping rates in your Profile, they
are listed here.
Sales or Value Added Tax Calculation: If you have specified your tax rate in your
Profile, it is listed here. For more information, see “Automatic Calculation of Shipping
and Handling Cost and Tax” on page 45.”
2. For Buy Now buttons, add Option fields to your button
Creating an option field allows your customers to specify information about their purchases. You can use Option fields to specify options like color, size, or gift-wrapping. These options must not change the price of an item but let you collect additional information from your customer without extra email communication. Each Buy Now Button can have up to two option fields, and you can use a drop-down menu or text box to collect the information.
Single-Item Payment: Buy Now and Donations
Using Buy Now or Donations Button Factory
3
Unfortunately, Option fields and button encryption cannot be used if you are creating an email hyperlink. If you would still like to include Buy Now links in email messages, you can try either sending HTML emails, providing a link to the Buy Now Button (with Option fields) on your website, or asking your user to include the optional information in the Note field.
Option Field Type: Choose the type of option field: drop-down menu or text box. If you
choose drop-down menu, you must enter the menu choices. If you choose text box, your customers enter their choice.
Option Name: Enter the name of your option. The Option Name field has T a 60-
character limit.
Drop-Down Menu Choices: If you are using a drop-down menu, you must enter your
menu choices. There is a 30-character limit per choice, with a maximum of 10 choices. Use a carriage return (press ENTER) to separate each choice.
3. Customize your payment pages
Custom Payment Page Style: Give your customers a seamless payment experience by
customizing PayPal’s payment pages to match your website’s style. If you already added Custom Payment Page Styles in your Profile, they are listed here. Choose the page style you would like to appear when your customer clicks your Buy Now button. To learn more about creating page styles, see “Branding PayPal’s Payment Pages” on page 29.”
4. Customize your customer’s experience
Successful Payment URL: Enter the URL for the page you want your customers
redirected to after they have completed their payments. Unless you have enabled Auto Return, your customers see a payment completion page where they click Continue and
Website Payments Standard Checkout Integration Guide November 2005 63
Single-Item Payment: Buy Now and Donations
3
Using Buy Now or Donations Button Factory
return to the Successful Payment URL you have specified. If you do not enter a Successful Payment URL, customers clicking this link are taken to a PayPal webpage.
Cancel Payment URL: Enter the URL where you want to send your customers if they
cancel their payments at any point in the Buy Now payment flow. If you do not enter a Cancel Payment URL, customers who click this link are taken to a PayPal webpage.
5. Miscellaneous Options
Quantity: If you want your customers to purchase more than one item or service, choose
Yes to prompt them to enter the quantity they want. If you choose No, the quantity is set to 1, and your customers can purchase only one item per payment.
Shipping Address: If you want to prompt customers for a shipping address, choose Yes.
If you choose No, your customers are not asked to provide a shipping address.
6. Collect additional information from your customers
Note: Select Yes if you want your customers to be able to include a note to you with their
payment. If you select No, your customers cannot include a note.
Note Title: If you allow your customers to include a note with their payments, you can
specify a title for the note field. By specifying a title, you can prompt your buyers to enter specific information, such as a User ID or special instructions. There is a 40-character limit on your note field title. If you do not enter a title, your customers see Special
Instructions (optional) as the note field title.
7. Choose an email address to receive payment
If you have more than one confirmed email address, you can specify the address where you want to receive your email payment notifications when your customers pay you.

Copy and Paste the HTML Code

When you completed the Buy Now Button Factory form, click Create Button Now.
If your customers pay on your website:
1. Copy the code from the HTML for Websites text box by highlighting all the text and
pressing Ctrl+C, or by highlighting all the text, right-clicking your mouse, and selecting
Copy.
2. Open the webpage where you want to collect payment.
3. Paste the code you just copied into your webpage file wherever you would like the image to
appear, typically next to the description of the item or service, either by pressing Ctrl+V or by right-clicking your mouse and selecting Paste.
If your customers pay by email:
NOTE: If you use Encrypted Website Payments (EWP), you cannot create an email link.
64 November 2005 Website Payments Standard Checkout Integration Guide
Single-Item Payment: Buy Now and Donations

Sample Buy Now Button HTML and Hyperlink

1. Copy the code from the Link for Emails text box by highlighting all of the text and pressing Ctrl+C, or by highlighting all of the text, right-clicking your mouse, and choosing
Copy.
2. Open the email you want to send.
3. Paste the code you just copied into your email either by pressing Ctrl+V or by right- clicking on your mouse and selecting the Paste option.
4. When your customers receive the email, the code appears as a link. Clicking the link takes
them to your PayPal payments page.
HTML Tip: Ensure that the HTML code on your webpage exactly matches the code you copy from PayPal. Some HTML editors might change some characters in the code. In addition, be sure you paste the code into a field that accepts HTML. If you paste the code into a standard text field, the code is treated as displayable text.
Sample Buy Now Button HTML and Hyperlink
3
The HTML for a Buy Now Button looks similar to the following. Several optional fields are shown.
EXAMPLE 3.1 HTML for Buy Now Button
IMPORTANT:You can change the values for any of the variables, with the exception of the
first two lines.
<form target="paypal" action="https://www.paypal.com/cgi-bin/webscr" method="post"> <!-- a Buy Now button is specified by the command _xclick -->
<input type=”hidden” name=”cmd” value=”_xclick”> <input type=”hidden” name=”business” value=”seller@designerfotos.com”> <!-- Allow customer to enter desired quantity --> <input type=”hidden” name=”undefined_quantity” value=”1”> <input type=”hidden” name=”item_name” value=”Baseball Hat”> <input type=”hidden” name=”item_number” value=”123”> <!-- No currency_code variable has been specified, so monetary amount is assumed to be USD --> <input type=”hidden” name=”amount” value=”5.95”> <! Passthrough variables for order tracking or other purpose --> <input type=”hidden” name=”custom” value=”merchant_custom_value”> <input type=”hidden” name=”invoice” value=”merchant_invoice_12345”> <input type=”hidden” name=”charset” value=”utf-8”> <input type=”hidden” name=”no_shipping” value=”1”> <input type=”hidden” name=”image_url” value=”https://www.designerfotos.com/logo.gif”> <input type=”hidden” name=”return” value=”http://www.designerfotos.com/thankyou.htm”> <input type=”hidden” name=”cancel_return” value=”http://www.designerfotos.com/cancel.htm”> <!-- Do not prompt customer to include a note with the purchase -->
Website Payments Standard Checkout Integration Guide November 2005 65
Single-Item Payment: Buy Now and Donations
3
Sample Buy Now Button HTML and Hyperlink
<input type=”hidden” name=”no_note” value=”2”> <table>
<tr>
<td>
<!-- Allow customer to choose product options --> <input type=”hidden” name=”on0” value=”Color?”>Color? <select name=”os0”>
<option value=”Red”>Red <option value=”Green”>Green <option value=”Blue”>Blue</select>
</td>
</tr> </table> <input type=”image” src=”http://images.paypal.com/images/x-click-but01.gif” name=”submit” alt=”Make payments with PayPal - it’s fast, free and secure!”> </form>
The HTML shown above generates the following hyperlink. This example includes several optional fields, and the text is URL-encoded.
https://www.paypal.com/xclick/business=seller@designerfotos.com&undefined_quantity=1& item_name=Baseball+Hat&item_number=123&amount=5.95&no_shipping=1&return=http%3A//www. designerfotos.com/thankyou.htm&cancel_return=http%3A//www.designerfotos.com/cancel.ht m¤cy_code=USD
66 November 2005 Website Payments Standard Checkout Integration Guide
4

Multiple-Item Payment: Shopping Cart

With PayPal’s Shopping Cart, your customers can buy multiple items with a single payment, browse your entire selection, and view a consolidated list of all their items before purchasing.
The shopping cart comes in two basic forms:
1. A shopping cart hosted on the PayPal website,
2. HTML input variables for use in third-party shopping carts.
The key distinction between the PayPal-hosted shopping cart and a third-party shopping cart is in the following HTML variables:
z add or display: these variables indicate the PayPal-hosted shopping cart.
z upload: this variable indicates that a third-party shopping cart is in use.
https://www.paypal.com/.

How the PayPal-Hosted Shopping Cart Works

This example shows how the shopping carted hosted by PayPal can work with the following features:
z Account Optional is turned off. In this example, to pay with PayPal, the customer must
already have a PayPal account. For more information, see “Account Optional or Website
Payments Express” on page 35.”
z Auto Return is turned on. At the end of the transaction, the customer’s browser is
automatically redirected back to your website. For more information, see “Auto Return” on
page 43.”
Website Payments Standard Checkout Integration Guide November 2005 67
Multiple-Item Payment: Shopping Cart
4
How the PayPal-Hosted Shopping Cart Works

What The Customer Sees

Bob, who has a PayPal account, is buying from The Stuff Shop. He selects a baseball hat by clicking Add to Cart.
FIGURE 4.1 PayPal-Hosted Shopping Cart Example: Add to Cart
The Stuff Shop is using a generic Add to Cart button created with the PayPal shopping cart button factory described in “Button Factory for PayPal-Hosted Shopping Cart” on page 72. The HTML code for this button is detailed in “Sample HTML for PayPal-Hosted Shopping
Cart ” on page 75.
68 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart
How the PayPal-Hosted Shopping Cart Works
Bob’s browser is redirected to the PayPal website enters his PayPal username and password, and clicks Log In.
FIGURE 4.2 PayPal-Hosted Shopping Cart Example: Logging In to PayPal during
Checkout
4
Website Payments Standard Checkout Integration Guide November 2005 69
Multiple-Item Payment: Shopping Cart
4
How the PayPal-Hosted Shopping Cart Works
Bob is taken to a confirmation page showing the details of his payment.
FIGURE 4.3 PayPal-Hosted Shopping Cart Example: Confirmation Page
Because The Stuff Shop has not activated Profile-based shipping preferences, no shipping costs are added to the order. For information about automatic shipping calculation, see
“Automatic Calculation of Shipping and Handling Cost and Tax” on page 45.
Bob clicks Pay to complete the payment.
70 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart
How the PayPal-Hosted Shopping Cart Works
Bob’s browser is returned to The Stuff Shop website, which displays a “Thank you” page.
FIGURE 4.4 PayPal-Hosted Shopping Cart Example: Thank You Page After Payment
Bob receives an email receipt for this transaction that confirms the payment and payment details.
FIGURE 4.5 PayPal-Hosted Shopping Cart Example: Email Transaction Receipt
4
Website Payments Standard Checkout Integration Guide November 2005 71
Multiple-Item Payment: Shopping Cart
4

Button Factory for PayPal-Hosted Shopping Cart

Button Factory for PayPal-Hosted Shopping Cart
With the PayPal-hosted shopping cart, customers can make a single payment for multiple items. With our shopping cart button factory, you can create a separate Add to Cart button for each item and put the automatically generated HTML code for that button on your website next to the item.
Use the following steps to create a shopping cart button, or if you are familiar HTML, you can use the variables in Appendix A to code your own buttons.
1. Log in to your PayPal account at
2. Enter the following URL:
https://www.paypal.com/us/cgi-bin/webscr?cmd=_cart-factory
3. Enter the details for the item.
Item Name/Service (required): Enter the name of the item or service you wish to sell – Item ID/Number: If you have an ID or tracking number for your item, enter it here. This
field will be displayed to your customers at the time of payment, and will be shown in
both the buyer’s and seller’s transaction details on the PayPal website – Item Price (required): Enter the price of the item you wish to sell – Currency (required): Choose the currency in which you would like this payment to be
denominated. This field defaults to the currency of your primary balance. – Buyer’s Country: If you want the PayPal login or sign-up page to be displayed in a
certain language, select a country from the pull-down menu where that language is
spoken.
4. Choose an image for your button.
If you are going to be receiving payments from your website, choose the image for the button you would like your customers to click to make their purchase. To display your own image, enter the URL of the image’s location in the URL field.
https://www.paypal.com.
NOTE: All items added to a PayPal shopping cart must be denominated in a single currency,
which is determined by the currency specified for the first item added to the Cart or by the currency_code variable. Once a buyer adds one item to a cart, the buyer is not allowed to add any items listed in other currencies to that cart. To change the currency, customers must purchase the items in the first currency or remove all items from the cart and add the items of the second currency. The best option is to list all of your items in the same currency.

Adding More Details to the Button

If you do not have additional details to add to your button (such as sales tax, shipping, or your logo), click Create Button Now and go to “Copy and Paste the Shopping Cart HTML” on
page 74. Otherwise, click Add More Options.
72 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart
Button Factory for PayPal-Hosted Shopping Cart
1. Calculate shipping and tax.
If you have specified shipping rates or tax calculations in your Profile, they are listed under Shipping Cost Calculation and Sales Tax Calculation. For more information, see
“Automatic Calculation of Shipping and Handling Cost and Tax” on page 45.”
2. Add option fields to your button.
Creating an option field lets your customers specify information about their purchases. Option fields can specify information such as color, size, or gift wrapping. Options must not change the price of an item. A shopping cart button can have up to two option fields, and you can use a drop-down menu or a text box to collect the information.
Option Field Type: Choose the type of option field: drop-down menu or text box. If you
choose drop-down menu, you will enter the different choices. If you choose text box,
your customer will enter his choice. – Option Name: Enter the name of your option. There is a 60-character limit on option
names. – Drop-Down Menu Choices: If you are using a drop-down menu, enter your menu
choices. There is a 30-character limit per choice, with a maximum of 10 choices. Use a
carriage return (press Enter) to separate each choice.
4
3. Select a View Cart button.
Choose the button image you would like your customers to click when they check out and complete their purchases. To display your own image, enter the URL of the image’s location in the URL field.
4. Customize your payment pages.
Custom Payment Page Style: Give your customers a seamless payment experience by
customizing PayPal's payment pages to match the style of your website. If you have
already added Custom Payment Page Styles in your Profile, they will be listed here.
Choose the page style you would like to appear when your customer clicks your
Shopping Cart button. For more information about adding, selecting, or changing custom
page styles, see “Branding PayPal’s Payment Pages” on page 29.”
5. Customize your customer’s experience.
Successful Payment URL: Enter the URL where you would like to send your customers
after they have completed payment. Once customer has completes the payment, he sees
a payment confirmation page. From this page, he will click Continue and return to the
Successful Payment URL you have specified. If you do not enter a Successful Payment
URL, customers who click this link will be taken to a PayPal web page. – Cancel Payment URL: Enter the URL where you would like to send your customers if
they cancel their payment at any point in the PayPal Shopping Cart payment flow. If you
do not enter a Cancel Payment URL, customers who click this link will be taken to a
PayPal web page.
6. Select other options.
Website Payments Standard Checkout Integration Guide November 2005 73
Multiple-Item Payment: Shopping Cart
4
Button Factory for PayPal-Hosted Shopping Cart
Shipping Address: If you would like your customers to be prompted to provide a
shipping address, choose Yes. If you choose No, your customers will not be asked to
provide a shipping address.
7. Collect additional information from your customers.
Note: Select Yes if you would like your customers to be able to include a note to you
with their payments. If you select No, your customers will not be given the opportunity
to include a note. – Note Title: You can choose a title for the note field. By including a title, you can prompt
your buyers to enter specific information (like a User ID) or special instructions. If you
do not enter a title, your customers will see the note field title Optional Instructions.
8. Choose the email address at which you want to receive payment.
If you have more than one confirmed email address attached to your PayPal account, you can specify the address at which you would like to receive your email payment notifications when your customers pay you.

Copy and Paste the Shopping Cart HTML

When you have finished filling out the PayPal Shopping Cart Button Factory form, click Continue.
z Copy the code from the HTML for Websites text box by highlighting all of the text and
pressing Ctrl+C, or by highlighting all of the text, right-clicking your mouse, and choosing Copy.
z Open the web page file into which you’d like to add your Shopping Cart Button.
z Paste the code you just copied into your web page file wherever you would like the button
to appear (typically, next to the description of the item or service) by either pressing
Ctrl+V or by right-clicking on your mouse and selecting Paste.
HTML Tip: Ensure that the HTML code on your web page exactly matches the code you
copy from PayPal. Some HTML editors might change some characters in the code. In addition, be sure that you paste the code into a field that accepts HTML. If you paste the code into a standard text field, the code is treated as displayable text.
Create Add to Cart buttons for all items.
Click Create Another Button to create more Add to Cart buttons the previous steps.
Copy the View Cart button HTML code.
Now that you have placed your Add to Cart buttons on your website, you need to include the “View Cart” buttons so your customers can quickly proceed to checkout when they are ready.
– Copy the code from the Copy ‘View Cart’ button HTML box by highlighting all of the
text and pressing Ctrl+C, or by highlighting all of the text, right-clicking on your mouse,
and choosing Copy. – Open each web page from which you would like your customers to be able to get to their
PayPal Shopping Carts.
74 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart

Sample HTML for PayPal-Hosted Shopping Cart

– Paste the code you just copied into your web page file where you would like your “View
Cart” button to appear, by either pressing Ctrl+V or by right-clicking your mouse and
choosing Paste.
Sample HTML for PayPal-Hosted Shopping Cart
The following HTML is of a generic Add to Cart button created with the PayPal Shopping Cart button factory. Several optional fields are shown.
EXAMPLE 4.1 HTML for PayPal-Hosted Shopping Cart “Add to Cart” Button
IMPORTANT:You can change the values for any of the variables, with the exception of the
first two lines.
<form target="paypal" action="https://www.paypal.com/cgi-bin/webscr" method="post"> <!-- The PayPayl-hosted shopping cart is specified with the command _cart -->
<input type="hidden" name="cmd" value="_cart"> <input type="hidden" name="business" value="seller@designerfotos.com”> <!-- add the item to the PayPal-hosted shopping cart --> <input type=”hidden” name=”add” value=”1”> <input type="hidden" name="item_name" value="Baseball Hat"> <input type="hidden" name="item_number" value="12345"> <!-- No currency_code variable specified, so monetary amount is assumed to be USD --> <input type="hidden" name="amount" value="12.95"> <table>
<tr> <td> <!-- allow customer to selection product option --> <input type="hidden" name="on0" value="Color?">Color? <select name="os0">
<option value="Red">Red <option value="Green">Green
<option value="Blue">Blue </select> </td> </tr>
</table> <input type="image" src="https://www.paypal.com/images/x-click-but22.gif" border="0" name="submit" alt="Make payments with PayPal - it’s fast, free and secure!"> </form>
4
Rather than creating a separate button for every single item you want to sell with the PayPal­hosted shopping cart, you can edit the HTML to create different Add to Cart buttons.
Website Payments Standard Checkout Integration Guide November 2005 75
Multiple-Item Payment: Shopping Cart
4

How A Third-Party Shopping Cart Works

How A Third-Party Shopping Cart Works
This example shows how PayPal can work with a third-party shopping cart and with the following features:
z Account Optional is turned off. In this example, to pay with PayPal, the customer must
already have a PayPal account. For more information, see “Account Optional or Website
Payments Express” on page 35.”
z Auto Return is enabled. At the end of the transaction, the customer’s browser is
automatically redirected back to the merchant website. For more information, see “Auto
Return” on page 43.

What The Customer Sees

Bob, who has a PayPal account, is buying photos from DesignerFotos. He selects several photos by clicking Add to Cart.
FIGURE 4.6 Third-party Shopping Cart Example: Add to Cart
76 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart
How A Third-Party Shopping Cart Works
In this example integration, the contents of the shopping cart are displayed each time an item is added to the cart.
FIGURE 4.7 Third-Party Shopping Cart Example: Proceed to Checkout
4
After selecting all the items he wants, Bob clicks Proceed to Checkout.
Website Payments Standard Checkout Integration Guide November 2005 77
Multiple-Item Payment: Shopping Cart
4
How A Third-Party Shopping Cart Works
Bob’s browser is redirected to the PayPal website, where he enters his PayPal username and password and clicks Continue to login.
FIGURE 4.8 Third-Party Shopping Cart Example: Logging In to PayPal during
Checkout
78 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart
How A Third-Party Shopping Cart Works
Bob is taken to a confirmation page showing the details of his payment.
FIGURE 4.9 Third-Party Shopping Cart Example: Confirmation Page
4
Because DesignerFotos has activated Profile-based shipping preferences, the shipping costs are automatically added to the order. For information about automatic shipping calculation, see “Automatic Calculation of Shipping and Handling Cost and Tax” on page 45.
Bob clicks Pay to complete the payment.
Website Payments Standard Checkout Integration Guide November 2005 79
Multiple-Item Payment: Shopping Cart
4
How A Third-Party Shopping Cart Works
Bob’s browser is returned to the merchant’s website, which displays a “Thank you” page.
FIGURE 4.10 Shopping Cart Example: Thank You Page After Payment
Bob receives an email receipt for this transaction that confirms the payment and includes a copy of the payment details.
FIGURE 4.11 Example: Email Transaction Receipt
80 November 2005 Website Payments Standard Checkout Integration Guide

What You See

DesignerFotos receivers an receives an email notification of Bob’s payment.
FIGURE 4.12 Example: Seller’s Email Receipt
Multiple-Item Payment: Shopping Cart
How A Third-Party Shopping Cart Works
4
DesignerFotos (the user seller@designerfotos.com) can also see the payment in the PayPal account history.
Website Payments Standard Checkout Integration Guide November 2005 81
Multiple-Item Payment: Shopping Cart
4

Adding PayPal to Your Third-party Shopping Cart

Adding PayPal to Your Third-party Shopping Cart
Instead of relying on the PayPal-hosted Shopping Cart, some web developers want to integrate PayPal payment processing with their own third-party shopping cart. The details in this section allow your buyers to pay with PayPal when they are ready to check out after adding all of their items to your third-party shopping cart.

Required Third-Party Shopping Cart Variables

Your FORM requires at least the following hidden variables. For complete list of variables, see
Appendix A, “Website Payments Standard HTML Variables.”
TABLE 4.1 Required Third-Party Shopping Cart Variables
Name Description
amount_1 Price of a single item or the total price of all items in the
shopping cart
business Email address of your PayPal account
item_name_1 Name of the item or a name for the entire shopping cart
upload Indicates the use of third-party shopping cart
There are two ways to integrate your third-party shopping cart with the PayPal payment flow:
1. Pass the details of the individual items.
2. Pass the aggregate amount of the total cart payment, rather than the individual item details.

Passing Individual Item Details to PayPal

If you can configure your third-party shopping cart to pass individual items to PayPal, the information about the items is included in the buyer’s and seller’s history transactions and notifications.
1. Set the cmd variable to
2. Include the upload variable:
<input type="hidden" name="upload" value="1">
3. Define item details for each item in the cart.
_cart.
Specify the required variables and any optional variables listed in Table A.6, “HTML
Variables: Individual Items in Third-Party Shopping Carts” on page 102. Append _
variable name, where
x is the item number, starting with 1 and increasing by one for each item
x to the
added to the cart. The first item in the cart must be defined with variables ending in _1, like item_name_1, amount_1, and quantity_1; the second item with variables like
82 November 2005 Website Payments Standard Checkout Integration Guide
Multiple-Item Payment: Shopping Cart
Adding PayPal to Your Third-party Shopping Cart
item_name_2, amount_2, and quantity_2; the third item with variables like item_name_3, amount_3, and quantity_3; and so on.
IMPORTANT:The _x values must increment by one continuously in order to be recognized.
If you skip from item #1 to item #3 without defining an item #2, the third item will be ignored.
The minimum required HTML for your post to PayPal looks similar to the following.
EXAMPLE 4.1 HTML for Passing Individual Item Detail to PayPal
<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>
<input type=”hidden” name=”cmd” value=”_cart”> <input type=”hidden” name=”upload” value=”1”> <input type=”hidden” name=”business” value=”seller@designerfotos.com”> <input type=”hidden” name=”item_name_1” value=”Item Name 1”> <input type=”hidden” name=”amount_1” value=”1.00”> <input type=”hidden” name=”item_name_2” value=”Item Name 2”> <input type=”hidden” name=”amount_2” value=”2.00”> <input type=”submit”” value=”PayPal”>
</form>
4
Setting Currency in the Cart
All monetary variables (amount_x., shipping_x., shipping2_x, handling_x, tax_x., and tax_cart) are interpreted in the currency designated by the currency_code variable posted with the payment. Because currency_code is not item-specific, there is no need to append _
x to the currency_code variable name. If no currency_code variable is posted,
all monetary values default to U.S. Dollars.
Setting Tax on Individual Items
Use the tax_x variable to specify the tax for a particular item in the cart. For example, the following line specifies that the tax on item 2 in the cart is 15 cents:
<INPUT TYPE=”hidden” name=”tax_2” value=”.15”>

Setting the Tax for the Entire Cart

Use the tax_cart variable to specify a tax amount that applies to the entire purchase, rather than to individual items. The tax_cart variable overrides any per-item tax amount specified with tax_x.

Passing the Aggregate Shopping Cart Amount to PayPal

You can aggregate your entire shopping cart and pass the total amount to PayPal. You must post a single item_name_1 for the entire cart and the total price of the cart’s contents in amount_1 as though it were a purchase of a single item.
Website Payments Standard Checkout Integration Guide November 2005 83
Multiple-Item Payment: Shopping Cart
4
Adding PayPal to Your Third-party Shopping Cart
NOTE: One drawback of this method is that your buyers will not see the individual items in
their carts. In addition, you cannot change our variable names, nor can you add your own variable names.
The following HTML is identical to “HTML for Passing Individual Item Detail to PayPal” on
page 83 except the individual items’ amounts and item names have been aggregated into a
single item and amount.
EXAMPLE 4.2 HTML for Aggregate Cart Detail to PayPal
<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>
<input type=”hidden” name=”cmd” value=”_cart”> <input type=”hidden” name=”upload” value=”1”> <input type=”hidden” name=”business” value=”seller@designerfotos.com”> <input type=”hidden” name=”item_name_1” value=”Aggregated items”> <input type=”hidden” name=”amount_1” value=”3.00”> <input type=”submit”” value=”PayPal”>
</form>
84 November 2005 Website Payments Standard Checkout Integration Guide

Encrypted Website Payments

5
To add security to online payments, you can create Encrypted Website Payment (EWP) button code that relies on standard public key encryption. With public and private keys, you can dynamically encrypt payment information before sending it to PayPal.
Encrypted Website Payments works in the following way.
TABLE 5.1 How Encrypted Website Payments Work
Merchant Customer PayPal
Creates HTML name/value pairs that represent the parameters of the HTML PayPal when a customer clicks a button on his website
Encrypts the button parameters with PayPal’s public key
Signs the encrypted data with his own private key
FORM to post to
Publishes the signed, encrypted website with a “Pay” button
Prerequisites to Using EWP
This section describes how to create your private and public keys for EWP, upload your public key to PayPal, and download a copy of PayPal’s public key:
z Generate a private key
z Generate a public certificate
z Upload your public certificate to the PayPal website at https://www.paypal.com/us/cgi-
bin/webscr?cmd=_profile-website-cert
z Download PayPal's public certificate from https://www.paypal.com/us/cgi-
bin/webscr?cmd=_profile-website-cert
FORM to his
Clicks “Pay” button, which posts the signed, encrypted
FORM data to PayPal’s URL
Checks the authenticity of the data by using the merchant’s uploaded public key
Decrypts the data with PayPal’s private key
Directs the buyer’s browser to the PayPal payment flow specified in the button parameters
Website Payments Standard Checkout Integration Guide November 2005 85
Encrypted Website Payments
5

Creating Your Public Certificate

Public Key Encryption Background
Public key encryption (asymmetric encryption) improves security and convenience by allowing senders and receivers to have separate public and private encryption keys:
z The public key: The public key is the portion of an asymmetric cryptographic key that
receivers give senders who want to send them encrypted information. I
z The private key: The private key is the portion of an asymmetric cryptographic key
receivers keep secret and do not send to anyone. The public certificate: The public certificate consists of the public key and identity information, such as a person's name, which could be signed by a certificate authority (CA). The CA guarantees that the public key belongs to the named entity.
z The encryption process: Sender use both their private key and the receivers’ public key to
encrypt the information. Receiver use their private key and the senders’ public key to decrypt the information that was encrypted. This encryption process is also used with digital signatures to verify the origin of the information.
Creating Your Public Certificate
For EWP, PayPal requires that you upload your public certificate to its website so that the authenticity of the encrypted code can be verified.
PayPal accepts only X.509 public certificates, not public keys. The difference between a key and a certificate is that a certificate includes the public key along with information about the key, such as when the key expires and who the key belongs to. PayPal accepts public certificates in OpenSSL PEM format from any established certificate authority, such as VeriSign.
You can also create your own private key and public certificate using open source software such as OpenSSL (

Creating Your Private Key Using OpenSSL

Using the openssl program, enter the following command to create your private key. The command generates a 1024-bit RSA private key that is stored in the file my-prvkey.pem:
openssl genrsa -out my-prvkey.pem 1024

Creating Your Public Certificate Using OpenSSL

The public certificate must be in PEM format. To create your certificate, enter the following openssl command, which generates a public certificate in the file my-pubcert.pem:
http://www.openssl.org), which is detailed in the following section.
openssl req -new -key my-prvkey.pem -x509 -days 365 -out my-pubcert.pem
86 November 2005 Website Payments Standard Checkout Integration Guide

Uploading Your Public Certificate

To upload your public certificates to the PayPal website:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. In the Seller Preferences column, click Encrypted Payment Settings.
4. Click Add.
5. Click Browse, and select the public certificate you want to upload.
When your public certificate is successfully uploaded, it appears on the next screen under
Your Public Certificates.
FIGURE 5.1 Upload Public Certificate for EWP
Encrypted Website Payments
Uploading Your Public Certificate
5
After you successfully upload your certificate, PayPal assigns a corresponding certificate ID. Store the certificate ID in a safe place; you need it to make Encrypted Website Payments.

Downloading PayPal's Public Certificate

To download PayPal’s public certificate:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. In the Seller Preferences column, click Encrypted Payment Settings.
4. Under the PayPal Public Certificate section, click Download.
Website Payments Standard Checkout Integration Guide November 2005 87
Encrypted Website Payments
5

Removing Your Public Certificate

FIGURE 5.2 Download PayPal’s Public Certificate for EWP
Removing Your Public Certificate
NOTE: If you remove your public certificate, it’s associated certificate ID is no longer valid for
encrypting buttons, and any buttons generated by your website with that certificate ID will not function correctly.
To remove one or more of your public certificates:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. In the Seller Preferences column, click Encrypted Payment Settings.
4. Select one of the listed certificates, and click Remove.
5. On the next screen, click Remove again to remove the selected public certificate.

Blocking Unencrypted Website Payments

To prevent someone from creating a “spoof” version of your Website Payment buttons, you can block unencrypted website payments.
To allow only Encrypted Website Payments:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. Click the Website Payment Preferences link in the right-hand menu.
4. Select On next to Block Non-encrypted Website Payments.
88 November 2005 Website Payments Standard Checkout Integration Guide
6

Testing in the PayPal Sandbox

The PayPal Sandbox can be used to test the following functionality.
IMPORTANT:The Sandbox does not process real money.
z Buy Now and Donations: Test single-item payments. For more information, see
Chapter 3, “Single-Item Payment: Buy Now and Donations.”
z Shopping Carts: Test the purchase of multiple items in a single transaction and making a
single payment. For more information, see Chapter 4, “Multiple-Item Payment: Shopping
Cart.”
z Subscriptions: Create and publish test/prototype webpages and other content to which
only paying members will have access. For more information, see the Subscriptions and
Recurring Payments Guide.
z Refunds: Test Aa providing a refund of money paid by a PayPal user in a transaction.
z Simulated transactions: Test scenarios such as successful and failed eChecks.
To test in the Sandbox, you must first create a Developer Central account. With this account, you can create multiple PayPal accounts, such as seller and buyer accounts, to simulate different scenarios.
For complete details about using Developer Central and the Sandbox, see the Sandbox User
Guide.
Website Payments Standard Checkout Integration Guide November 2005 89
Testing in the PayPal Sandbox
6
90 November 2005 Website Payments Standard Checkout Integration Guide
Website Payments Standard
7
HTML FORM Basics
This chapter describes the basic functionality of Website Payments Standard HTML FORMs in technical terms.
Your customers interface with Website Payments Standard through hidden HTML FORM input variables on your website. These FORMs submit variables and their values to PayPal. You set these variables to produce the desired effect. Depending on the values of the variables, you can invoke PayPal’s shopping cart, Buy Now, or Donations and activate or invoke various PayPal features.
There is a wide variety of HTML creation tools for you to choose from. This guide does not describe all the possibilities. PayPal offers “button factories” that walk you through the process of creating HTML for Buy Now or Donations buttons and Shopping Cart buttons. For more information about these button factories, see Chapter 3 and Chapter 4.

FORM Attributes: ACTION and METHOD

The FORM tag includes two required attributes, ACTION and METHOD, and always looks like this:
<FORM ACTION=”https://www.paypal.com/cgi-bin/webscr” METHOD=POST>
IMPORTANT:Do not change these values.These attributes are required for any PayPal
Shopping Cart, Buy Now, or Donations button.

Hidden Input Variables

HTML input variables in a PayPal Website Payments Standard FORM are always hidden from the customer’s view. They have the following general format:
<INPUT TYPE=”hidden” name=”variableName” value=”allowedValue”>
The variableName is any of the variables described in Appendix A, “Website Payments
Standard HTML Variables,” and the
variables.
allowedValue is any of the values detailed for those
Website Payments Standard Checkout Integration Guide November 2005 91
Website Payments Standard HTML FORM Basics
7

Specifying the Website Payments Standard Product: cmd

Specifying the Website Payments Standard Product: cmd
The cmd variable is always required in a FORM. Its value determines which Website Payments Standard product you are using to obtain payment from the customer:
TABLE 7.1 Allowed Values for cmd Variable
Value of cmd Description
_xclick A Buy Now or Donations button
_cart A shopping cart
The input tag looks like one of the following:
z Buy Now or Donations: <INPUT TYPE=”hidden” name=”cmd” value=”_xclick”>
z Shopping Cart: <INPUT TYPE=”hidden” name=”cmd” value=”_cart”>
IMPORTANT:These INPUT tags are required exactly as shown above. Do not alter them.

Variations on Basic Variables

This section highlights some useful miscellaneous ideas about Website Payments Standard FORM variables.
The HTML variables interact in various ways. Sometimes their effect is cumulative, sometimes they can cancel each other out, sometimes a variable requires that you also set another variable. These interactions are detailed in the descriptions of the variables in
Appendix A, “Website Payments Standard HTML Variables.”

Prompting for Quantity in Buy Now or Donations: undefined_quantity

With Buy Now and Donations, you can require the customer to specify the desired number of copies of the single item by using the undefined_quantity variable:
<INPUT TYPE=”hidden” name=”undefined_quantity” value=”1”>

Recordkeeping with Passthrough Variables

Some variables are exclusively for your own use (such as for tracking orders) and are not recorded or used by PayPal. The values you send to PayPal are returned to you in an Instant Payment Notification (IPN) exactly as you set them. For this reason, they are called passthrough variables.
The following are passthrough variables:
z custom
92 November 2005 Website Payments Standard Checkout Integration Guide
Website Payments Standard HTML FORM Basics
z item_number or item_number_x
z invoice

Setting the Character Set: charset

You can use the charset FORM variable to specify the character set or character encoding of the data you collect in your website forms and send to PayPal. PayPal sends data to you in the same character set or encoding you specify with the charset variable. For example, the following INPUT tag sets the encoding to UTF-8:
<INPUT TYPE=”hidden” name=”charset” value=”utf-8”>
T
ABLE 7.2 Character Sets and Encodings Supported by PayPal
Variations on Basic Variables
7
Big5 (Traditional Chinese in Taiwan)
EUC-JP EUC-KR EUC-TW gb2312 (Simplified Chinese) gbk HZ-GB-2312
(Traditional Chinese in Hong Kong)
ibm-862 (Hebrew with European characters) ISO-2022-CN
ISO-2022-JP ISO-2022-KR ISO-8859-1
(Western European Languages) ISO-8859-2 ISO-8859-3 ISO-8859-4 ISO-8859-5 ISO-8859-6 ISO-8859-7
ISO-8859-8 ISO-8859-9 ISO-8859-13 ISO-8859-15 KOI8-R
(Cyrillic) Shift_JIS UTF-7 UTF-8 UTF-16
UTF-16BE UTF-16LE UTF16_Platform
Endian UTF16_Opposit eEndian UTF-32 UTF-32BE UTF-32LE UTF32_Platform
Endian UTF32_Opposit
eEndian

Setting Return URL on Individual Transactions

With Auto Return turned on in your Profile, you can set the value of the return URL on each individual transaction, overriding the value you have stored on PayPal. For example, you might want to return the customer’s browser to a URL on your site that is specific to that customer, perhaps with a session ID or other transaction-related data included in the URL.
To set the return URL for a transaction, include the return variable in the HTML FORM:
US-ASCII windows-1250 windows-1251 windows-1252 windows-1253 windows-1254 windows-1255 windows-1256 windows-1257
windows-1258 windows-874 (Thai) windows-949
(Korean) x-mac-greek x-mac-turkish x-mac­centraleurroman x-mac-cyrillic ebcdic-cp-us ibm-1047
<INPUT TYPE=”hidden” NAME=”return” value=”URLspecificToThisTransaction”>

Desired Currency on Individual Transactions

Use the currency_code variable on individual transactions to specify the currency of the payment:
<INPUT TYPE=”hidden” NAME=”currency_code value=”PayPalSupportedCurrencyCode”>
Website Payments Standard Checkout Integration Guide November 2005 93
Website Payments Standard HTML FORM Basics
7

Prepopulating FORMs

The value of currency_code must be a code from Table 2.2, “PayPal-Supported Currencies,
Currency Codes, and Maximum Transaction Amounts” on page 56.
NOTE: If currency_code is not included, the default currency is USD.

URL-Encoding Variable Values

Variables such as return, cancel_return, image_url require a URL as their values. You must ensure that these values are URL-encoded before you pass them to PayPal. URL­encoding is the substitution of characters required in URLs with characters that will not be misinterpreted by web servers. For example, a colon character is replaced with the characters %3A.
Prepopulating FORMs
Account Optional (also called Website Payments Express) allows you to accept payments from customers without a PayPal account. However, checking out with PayPal is often faster than forcing the customer to reenter information that is already stored on PayPal. For repeat purchases, it is to your advantage to get your customers to create a PayPal account.
During a payment transaction, you can prepopulate a FORM by including HTML input variables specifically for this purpose. A complete description of these variables is in
Table A.7, “HTML Variables: Prepopulating PayPal FORMs or Address Overriding” on page 103.
IMPORTANT:The value of the cmd variable must be _ext-enter, and you must include
the redirect_cmd variable, the value of which must be _xclick.

Sample HTML for FORM Prepopulation

The following sample HTML shows the optional prepopulation fields with the required variables in payment buttons. The field entries must be dynamically generated by your website and included in the URL to which your customers are sent when they make a PayPal payment.
EXAMPLE 7.1 HTML for FORM Prepopulation
<form action=”https://www.paypal.com/cgi-bin/webscr” method=”POST”>
<input type=”hidden” name=”cmd” value=”_ext-enter”> <input type=”hidden” name=”redirect_cm d” value=”_xclick”> <input type=”hidden” name=”business” value=”seller@designerfotos.com”> <input type=”hidden” name=”item_name” value=”hat”> <input type=”hidden” name=”item_number” value=”123”> <input type=”hidden” name=”amount” value=”15.00”> <input type=”hidden” name=”first_name ” value=”John”> <input type=”hidden” name=”last_name ” value=”Doe”> <input type=”hidden” name=”address1 ” value=”9 Elm Street”>
94 November 2005 Website Payments Standard Checkout Integration Guide
Website Payments Standard HTML FORM Basics

Overriding PayPal-Stored Addresses

<input type=”hidden” name=”address2 ” value=”Apt 5”> <input type=”hidden” name=”city” value=”Berwyn”> <input type=”hidden” name=”state” value=”PA”> <input type=”hidden” name=”zip” value=”19312”> <input type=”hidden” name=”night_phone _a” value=”610”> <input type=”hidden” name=”night_phone _b” value=”555”> <input type=”hidden” name=”night_phone _c” value=”1234”> <input type=”image” SRC=”http://images.paypal.com/images/x-click-but01.gif”
border=”0” name=”submit” alt=”Make payments with PayPal - it’s fast, free and secure!”> </form>
Overriding PayPal-Stored Addresses
For customers who already have PayPal accounts and whom you already prompted for a shipping address before they choose to pay with PayPal, you can use the entered address instead of the address the customer has on file with PayPal. Set the address_override variable to 1, as in the following example:
7
<INPUT TYPE=”hidden” name=”address_override” value=”1”>
You must also include FORM variables that contain the customer’s address information, as detailed in Table A.7, “HTML Variables: Prepopulating PayPal FORMs or Address
Overriding” on page 103.
The customer is shown the passed-in address but cannot edit it. No address is shown Iif the address is not valid, such as missing required fields, including country, or if the address is not included at all.

Sample HTML for Overriding PayPal-Stored Shipping Addresses

The following HTML shows the address_override variable in conjunction with the prepopulation variables for overriding a customer’s PayPal-stored shipping address.
EXAMPLE 7.2 HTML for Overriding PayPal-Stored Address
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick"> <input type="hidden" name="business" value="seller@designerfotos.com"> <input type="hidden" name="item_name" value="Memorex 256MB Memory Stick"> <input type="hidden" name="item_number" value="MEM32507725"> <input type="hidden" name="amount" value="3"> <input type="hidden" name="tax" value="1"> <input type="hidden" name="quantity" value="1"> <input type="hidden" name="no_note" value="1"> <input type="hidden" name="currency_code" value="USD"> <!-­Override the customer’s stored PayPal address
-->
Website Payments Standard Checkout Integration Guide November 2005 95
Website Payments Standard HTML FORM Basics
7

Instant Payment Notification: notify_url

<input type="hidden" name="address_ override" value="1"> <!-- Set the prepopulation variables that override the stored address --> <input type="hidden" name="first_na me" value="John"> <input type="hidden" name="last_nam e" value="Doe"> <input type="hidden" name="address1 " value="345 Lark Ave"> <input type="hidden" name="city" value="San Jose"> <input type="hidden" name="state" value="CA"> <input type="hidden" name="zip" value="95121"> <input type="hidden" name="country" value="US"> <input type="image" src="https://www.paypal.com/en_US/i/btn/x-click­but01.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
</form>
Instant Payment Notification: notify_url
Instant Payment Notification consists of three parts:
1. A customer pays you.
2. PayPal POSTs FORM variables to a URL you specify that runs a program to process the
variables.
3. You validate the notification.
FIGURE 7.1 How IPN Works: Three General Steps
1. A customer payment or a refund triggers IPN. This payment can be via Website Payments Standard FORMs or via the PayPal Web Services APIs for Express Checkout, MassPay, or
96 November 2005 Website Payments Standard Checkout Integration Guide
Website Payments Standard HTML FORM Basics
Instant Payment Notification: notify_url
RefundTransaction. If the payment has a “Pending” status, you receive another IPN when the payment clears, fails, or is denied.
2. PayPal posts HTML FORM variables to a program at a URL you specify. You can specify this URL either in your Profile or with the notify_url variable on each transaction. This post is the heart of IPN. Included in the notification is the customer’s payment information (such as customer name, payment amount). All possible variables in IPN posts are detailed in the Order Management Integration Guide. When your server receives a notification, it must process the incoming data.
3. Your server must then validate the notification to ensure that it is legitimate. For details, see the Order Management Integration Guide.
7
Website Payments Standard Checkout Integration Guide November 2005 97
Website Payments Standard HTML FORM Basics
7
Instant Payment Notification: notify_url
98 November 2005 Website Payments Standard Checkout Integration Guide
Website Payments Standard HTML
A
Variables
This appendix details all variables for Buy Now, Donations, Add to Cart buttons and shopping carts.
TABLE A.1 Allowed Values for cmd Variable
Value of cmd Description
_xclick A Buy Now or Donations button
_cart A shopping cart
_ext-enter For prepopulating PayPal account signup. Requires
redirect_cmd.
T
ABLE A.2 HTML Variables: IPN Control notify_url
Name Description
Required or Optional
Character Length
notify_url The URL to which PayPal posts information about the
transaction. Must be URL-encoded.
ABLE A.3 HTML Variables: Item Information
T
Name Description
amount The price or amount of the purchase, not including shipping,
handling, or tax. If omitted in Buy Now or Donations, customers can enter an amount at time of purchase.
z Optional for Buy Now or Donations z Required for Shopping Cart
item_name Description of item. If omitted in Buy Now or Donations,
customers can enter an item name at time of purchase.
z Optional for Buy Now or Donations z Required for Shopping Cart
item_number Passthrough variable for you to track purchases or donations,
passed back to you at payment completion. If omitted in Buy Now or Donations, no variable is passed back to you.
Optional 255
Required or Optional
See description.
See description.
Optional 127
Character Length
127
Website Payments Standard Checkout Integration Guide November 2005 99
Website Payments Standard HTML Variables
A
T
ABLE A.3 HTML Variables: Item Information
Name Description
quantity Number of items. The amount, shipping and tax are multiplied
by the quantity to derive the total payment amount. If this is a shopping cart transaction, PayPal appends the number of the item (e.g.
quantity1, quantity2).
NOTE: The value for quantity must be a positive integer.
Null, zero, or negative numbers are not allowed.
undefined_ quantity
1: allows buyer to specify the quantity.
NOTE: This variable is allowed only in Buy Now or Donations,
and not allowed in shopping carts.
on0 First option field name. If omitted, no variable is passed back to
you.
on1 Second option field name. If omitted, no variable is passed back
to you.
os0 First set of option values. If this option is selected through a text
box or radio button, each value should be no more than 64 characters. If this value is entered by the customer in a text field, there is a 200-character limit. If omitted, no variable is passed back to you.
NOTE: on0 must also be defined set.
Required or Optional
Character Length
Optional
Optional 1
Optional 64
Optional 64
Optional 64 or 200
See description.
os1 Second set of option values.
NOTE: on1 must also be set.
If this option is selected through a text box or radio button, each value should be no more than 64 characters. If this value is entered by the customer in a text field, there is a 200-character limit. If omitted, no variable is passed back to you.
TABLE A.4 HTML Variables: Display Information
Name Description
add Add an item to the PayPal-hosted shopping cart.
This variable must be set as follows:
add=1
The alternative is the display=1 variable, which allows the user to view the contents of the PayPal-hosted shopping cart.
If both
add and display are specified, display takes
precedence.
Optional 64 or 200
See description.
Required or Optional
Character Length
Required 1
100 November 2005 Website Payments Standard Checkout Integration Guide
Loading...