PayPal Merchant - 2005 User Manual

Merchant User Manual and Integration Guide

Last Updated: May, 2005

Merchant User Manual and Integration Guide

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.

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.

4 May, 2005 Merchant User Manual and Integration Guide

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . .19

PayPal-Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2 PayPal Payments Overview . . . . . . . . . . . . . . . . .21

PayPal Account Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Buy Now and Donations Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Custom Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Calculating Shipping, Handling, and Tax . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Contact Telephone Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Back-end Integration Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Instant Payment Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Payment Receiving Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Multi-User Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Subscriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Payment Flow Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Getting Started . . . . . . . . . . . . . . . . . . . . . . .27

Managing Your PayPal Merchant Account. . . . . . . . . . . . . . . . . . . . . . . . . . 29

Account Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Payment Receiving Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 4 PayPal Account Optional . . . . . . . . . . . . . . . . . .35

Turning PayPal Account Optional On or Off . . . . . . . . . . . . . . . . . . . . . . . . . 35

Merchant User Manual and Integration Guide May, 2005 5

Contents

Your Customer’s Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 5 Creating Buy Now and Donation Buttons . . . . . . . . . . 43

How Buy Now and Donations Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

What You See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Buy Now and Donations Button Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Creating a Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Creating a Donations Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

How You Get Your Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Downloadable Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Instant Payment Notification (IPN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 6 Creating Shopping Cart Buttons . . . . . . . . . . . . . . 59

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

What You See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

PayPal Shopping Cart Button Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Creating Your Shopping Cart Button . . . . . . . . . . . . . . . . . . . . . . . . . . 65

How You Get Your Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Downloadable Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Instant Payment Notification (IPN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Chapter 7 Adding PayPal to Your Third-party Shopping Cart . . . . . 71

Passing the Aggregate Shopping Cart Amount to PayPal . . . . . . . . . . . . . . . . . . 71

Passing Individual Items to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 8 Custom Payment Pages . . . . . . . . . . . . . . . . . . .73

6 May, 2005 Merchant User Manual and Integration Guide

Contents

Examples of Custom Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Adding a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Editing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Previewing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Making a Page Style Primary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Removing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Overriding Page Style Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Background Colors and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 9 Calculating Shipping, Handling, and Tax . . . . . . . . . .83

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Sales or Value Added Tax Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Overriding Tax Setting Per Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 83

Shipping Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Flat Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Percentage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Overriding Your Shipping Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Chapter 10 Creating Customer Contact Telephone . . . . . . . . . . .87

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

What You See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Chapter 11 Auto Return . . . . . . . . . . . . . . . . . . . . . . . . .89

How Auto Return Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Setting Up Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Subscription Password Management and Auto Return . . . . . . . . . . . . . . . . . . . 94

Chapter 12 Backend Integration - Payment Notifications . . . . . . . .95

Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Instant Payment Notification (IPN) and Payment Data Transfer (PDT) . . . . . . . . . 96

Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Merchant User Manual and Integration Guide May, 2005 7

Contents

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Enabling Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Setting Up Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Instant Payment Notification (IPN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

How IPNs Are Sent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Setting Up IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Notification Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Using IPN with Multiple Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . .107

Dispute Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Processing Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Chapter 13 Using Multiple Currencies . . . . . . . . . . . . . . . . . 111

Receiving Money. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Accepting Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Managing Currency Balances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Chapter 14 Language Encoding for Your Data . . . . . . . . . . . . 115

Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Changing Your Language Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Your Default Language Encoding at PayPal Sign-up . . . . . . . . . . . . . . . . . .115

Navigating Your Profile: Language Encoding . . . . . . . . . . . . . . . . . . . . . .116

Changing Your Website Language . . . . . . . . . . . . . . . . . . . . . . . . . . .117

More Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

Setting Language in Website Payments: charset . . . . . . . . . . . . . . . . . . . . . .120

Chapter 15 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Website Payments, PDT, and IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

Your PayPal Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

Testing Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Third-Party IPN Testing Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Chapter 16 Processing eChecks . . . . . . . . . . . . . . . . . . . . 125

Blocking eChecks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Refunding eChecks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Chapter 17 Security . . . . . . . . . . . . . . . . . . . . . . . . . . 127

8 May, 2005 Merchant User Manual and Integration Guide

Contents

Notification Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127

Button Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127

Multi-User Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

Using Secure Socket Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

SSL Certificate Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Appendix A HTML Samples. . . . . . . . . . . . . . . . . . . . . . . 131

PayPal Buy Now and Donation Buttons HTML and Variables . . . . . . . . . . . . . . . .131

Integrating Buy Now Buttons with your Shopping Cart . . . . . . . . . . . . . . . . .131

Sample Buy Now Button HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

Sample Buy Now Hyperlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

Buy Now and Donations HTML and Hyperlink Variables . . . . . . . . . . . . . . . .132

PayPal Shopping Cart HTML and Variables . . . . . . . . . . . . . . . . . . . . . . . . .137

PayPal Shopping Cart HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Standard Add to Cart HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Shopping Cart Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Adding PayPal Checkout To Your Third-Party Shopping Cart. . . . . . . . . . . . . .138

Passing Individual Items to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Prepopulating Your Customer’s PayPal Sign-Up . . . . . . . . . . . . . . . . . . . . . .141

Prepopulation for Website Payments Buttons . . . . . . . . . . . . . . . . . . . . . .141

Prepopulation for Account Signup . . . . . . . . . . . . . . . . . . . . . . . . . . . .142

Sample HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Appendix B IPN and PDT Variables . . . . . . . . . . . . . . . . . . 145

About These Tables of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

test_ipn Variable in Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

IPN Variables in All Posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Buyer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Basic Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Advanced and Custom Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148

Shopping Cart Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148

Currency and Currency Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Auctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154

Subscriptions Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Merchant User Manual and Integration Guide May, 2005 9

Contents

Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162

Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . 163

ISO 3166 Standard Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163

10 May, 2005 Merchant User Manual and Integration Guide

List of Tables

Table 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum Transation

Amounts 20

Table 1.2 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Table 8.1 Order of Customization Variables . . . . . . . . . . . . . . . . . . . . . 80

Table 14.1 Character Sets and Encodings Supported by PayPal . . . . . . . . . . .120

Table A.1 HTML and Hyperlink Variables for Buy Now and Donations Buttons. . . .133

Table A.2 Shopping Cart Variables . . . . . . . . . . . . . . . . . . . . . . . . . .138

Table A.3 Third-Party Shopping Cart Variables . . . . . . . . . . . . . . . . . . . .138

Table A.4 Variables for Individual Items in Third-Party Shopping Carts. . . . . . . .139

Table A.5 Prepopulation Variables for Website Payments . . . . . . . . . . . . . .141

Table A.6 Prepopulation Variables for Account Signup . . . . . . . . . . . . . . . .142

Table 17.1 IPN and PDT Variables: Buyer Information . . . . . . . . . . . . . . . .146

Table B.1 IPN and PDT Variables: Basic Information . . . . . . . . . . . . . . . . .147

Table B.2 IPN and PDT Variables: Advanced and Custom Information. . . . . . . .148

Table B.3 IPN and PDT Variables: Shopping Cart Information . . . . . . . . . . . .148

Table B.4 IPN and PDT Variables: Currency and Currency Exchange Information . .152

Table B.5 IPN and PDT Variables: Auctions . . . . . . . . . . . . . . . . . . . . .153

Table B.6 IPN and PDT Variables: Mass Pay . . . . . . . . . . . . . . . . . . . . .154

Table B.7 Subscriptions Variables . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Table B.8 IPN Variables with Each Subscription Event . . . . . . . . . . . . . . . .158

Table B.9 Dispute Notification Variables . . . . . . . . . . . . . . . . . . . . . . .160

Table B.10 PDT-Specific Variables . . . . . . . . . . . . . . . . . . . . . . . . . . .162

Table C.1 ISO 3166 Two-Character Country Codes. . . . . . . . . . . . . . . . . .163

Merchant User Manual and Integration Guide May, 2005 11

List of Tables

12 May, 2005 Merchant User Manual and Integration Guide

List of Figures

Figure 2.1 PayPal Payment Flows . . . . . . . . . . . . . . . . . . . 26

Figure 3.1 Business Account Sign-up . . . . . . . . . . . . . . . . . . 27

Figure 3.2 Confirming Your Email Address . . . . . . . . . . . . . . . 28

Figure 3.3 Adding a Bank Account . . . . . . . . . . . . . . . . . . . 28

Figure 3.4 Merchant Profile Page . . . . . . . . . . . . . . . . . . . . 30

Figure 3.5 Payment Receiving Preferences . . . . . . . . . . . . . . . 31

Figure 8.1 Payment Page in Standard PayPal Page Style . . . . . . . . . 73

Figure 8.2 Payment Page with Custom Style: Header Image and Header

Border 74

Figure 8.3 Payment Page with Custom Style: Header Image, Image Border,

and Background Color 75

Figure 8.4 Editing Page Style Settings . . . . . . . . . . . . . . . . . 77

Figure 8.5 Example of Unallowed Background Color . . . . . . . . . . . 81

Figure 8.6 Example of Allowable Background Color . . . . . . . . . . . 82

Figure 14.1 Profile Seller Preferences for Language Encoding . . . . . . . 116

Figure 14.2 Language Encoding Settings: Basic Choices . . . . . . . . . 117

Figure 14.3 Website Language Preference . . . . . . . . . . . . . . . . 118

Figure 14.4 More Language Encoding Options . . . . . . . . . . . . . . 119

Merchant User Manual and Integration Guide May, 2005 13

List of Figures

14 May, 2005 Merchant User Manual and Integration Guide

Preface

This Document

This document, the Merchant User Manual and Integration Guide, which describes how to use and integrate PayPal features for merchants, replaces the PayPal Merchant User Manual and Integration Guide, issued in February, 2005.

Intended Audience

This document is written for merchants whose websites use PayPal features to obtain payments from PayPal members.

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.

Merchant User Manual and Integration Guide May, 2005 15

Preface

Typeface How Used

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

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

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 e-mail us by following the instructions below. Describe the error or problem as completely 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 of the page.

4. Chose Help by Email.

5. Complete the form.

To contact Developer Technical Support about documentation problems:

1. Log in to your account at

https://developer.paypal.com/ by entering your email address and

password in the Member Log In box

2. Click Help Center at the bottom of the box on the right side of the page.

3. Click Email PayPal Technical Support.

4. Complete the form.

16 May, 2005 Merchant User Manual and Integration Guide

Preface

Merchant User Manual and Integration Guide May, 2005 17

Preface

18 May, 2005 Merchant User Manual and Integration Guide

Introduction

The Merchant User Manual and Integration Guide provides information about the majority of PayPal's features, and instructions for using these features to meet your online payment needs.

Use the Merchant User Manual and Integration Guide to:

z Quickly and easily set up eCommerce functionality with PayPal. For example, learn how to

integrate PayPal into your website in minutes with the PayPal Shopping Cart or Buy Now buttons.

z Learn more advanced techniques and tools to get the most out of the PayPal products. For

example, set up Instant Payment Notification to integrate PayPal payments with your business's back-end operations.

z Understand what your buyers see when they pay with PayPal. For example, review what it

means for a new buyer to optionally create a PayPal account using the PayPal Account Optional feature.

z View various product flows to better visualize your end product.

z Review recommended solutions and best practices.

The Merchant User Manual and Integration Guide includes information about, and instructions for using, the following features:

z Buy Now Buttons

z Donations Buttons

z Shopping Cart Buttons

z PayPal Account Optional

z Custom Payment Pages

z Instant Payment Notification

z Payment Data Transfer

z Multi-User Access

z Shipping, Handling, and Tax

z Auto Return

Merchant User Manual and Integration Guide May, 2005 19

Introduction

PayPal-Supported Currencies

The following currencies are supported by PayPal.

TABLE 1.1 PayPal-Supported Currencies, Currency Codes, and Maximum

Transation Amounts

Code Currency

AUD Australian Dollar 12,500 AUD

CAD Canadian Dollar 12,500 CAD

EUR Euro 8,000 EUR

GBP Pound Sterling 5,500 GBP

JPY Japanese Yen 1,000,000 JPY

USD U.S. Dollar 10,000 USD

Maximum Transaction Amount

Additional Information

The following table lists URLs you can consult for more information about PayPal.

NOTE: In most cases, you must log in to PayPal to see this additional information.

ABLE 1.2 Additional Information

Information URL

Fees https://www.paypal.com/fees

Onlines Security https://www.paypal.com/security

User Agreement and Policies

Online Help https://www.paypal.com/fees/help

Customer Service https://www.paypal.com/wf

https://www.paypal.com/cgibin/webscr?cmd=p/gen/ua/ua-outside

20 May, 2005 Merchant User Manual and Integration Guide

PayPal Payments Overview

This section provides a brief overview of each of the products described in this manual.

PayPal Account Optional

With PayPal Account Optional turned on, your customers who are new to PayPal will be able to make credit card payments without signing up for a PayPal account. This setting is available from your Profile, and is available to Premier and Business accounts.

PayPal Account Optional is turned on by default for all U.S. Premier and Business accounts. This means that your customers who already have PayPal accounts will go through the same Website Payments experience to which they’re accustomed.

Your new customers, or existing customers who are new to PayPal, will go through a checkout that doesn’t require PayPal signup; however, they will have that option available after completing the payment. Whether customers sign up for a PayPal account or not, you can set your Buy Now, Donations, and Shopping Cart Buttons to return them to your website, and you will still receive the same notification emails as in the current checkout flow.

For more information about PayPal Account Optional, see Chapter 4, “PayPal Account

Optional.”

Buy Now and Donations Buttons

PayPal makes it easy to accept donations and payments for single items through your own website. The Buy Now and Donations Buttons feature can be implemented in minutes, giving you easy access to business from PayPal’s millions of members, and any other buyer on the Web.

Because using Buy Now and Donations Buttons to send and receive payments is secure, both you and your customers remain protected. PayPal automatically encrypts your confidential information using the Secure Sockets Layer (SSL) protocol with an encryption key length of 128 bits (the highest level commercially available). Your customers will not need to share their private financial information (e.g. credit card or bank account numbers) during the transaction, so they can complete payment while retaining security. However, using button encryption does impose some limitations, and therefore PayPal does offer both encrypted and unencrypted button options.

The flexibility of our Buy Now Buttons feature will keep your website working for you. You can accept payments from current PayPal members as well as people who have just signed up for our service, and you won’t lose your customers after they have made a purchase—the payment process lets you return buyers to your website, not lose them to ours.

Merchant User Manual and Integration Guide May, 2005 21

PayPal Payments Overview

Shopping Cart

Benefits of Buy Now and Donations Buttons include:

z Easy to implement — no CGI scripting necessary.

z No up-front costs — you’ll have the same low fee schedule used as when you receive other

PayPal payments.

z Sell with ease — PayPal maintains detailed transaction records on the PayPal website.

z Improve buyer experience — with customizable buttons and secure payments, happy

customers become repeat customers.

For more information about Buy Now and Donations Buttons, see Chapter 5, “Creating Buy

Now and Donation Buttons.”

Shopping Cart

When you use PayPal’s free Shopping Cart, your customers can purchase multiple items with a single payment, browse your entire selection, and view a consolidated list of all their items before purchasing. The PayPal Shopping Cart is a low-cost way for you to accept credit card and bank account payments, and can be fully integrated with your website in a few easy steps.

The PayPal Shopping Cart also offers customizable buttons and secure payments to help you improve your buyer experience, so happy customers become repeat customers.

For more information about PayPal's Shopping Cart, see Chapter 6, “Creating Shopping Cart

Buttons.”

Custom Payment Pages

With our Custom Payment Pages feature, you can tailor PayPal's payment pages to the style of your website for a truly seamless payment experience. Make PayPal's payment flow yours with custom page colors and your own images. Custom Payment Pages can be used with all PayPal Website Payment buttons, including Buy Now, Donations, Shopping Cart, and Subscriptions.

For more information about Custom Payment Page, see Chapter 8, “Custom Payment Pages.”

Calculating Shipping, Handling, and Tax

You can set up your PayPal account to automatically calculate and charge shipping and sales (or value added) tax, as well as specify a different tax rate for each of the 50 U.S. states and any of the countries listed. In addition, you can charge shipping costs as a fixed rate based on the amount of the total purchase, or as a percentage of the purchase price. You also have the option to assign shipping amounts to individual products.

22 May, 2005 Merchant User Manual and Integration Guide

For more information about shipping and tax, see Chapter 9, “Calculating Shipping, Handling,

and Tax.”

Contact Telephone Number

The Customer Contact Information Telephone field provides merchants with a contact telephone number for their buyer. In accordance with our User Agreement, merchants may only use this Contact Telephone Number to communicate with buyers about the related purchase. This number may not be used for unsolicited commercial messages.

Auto Return

Auto Return for Website Payments allows merchants to eliminate the Payment Receipt page in the Website Payments flow and automatically return or redirect buyers to their website upon payment completion.

PayPal Payments Overview

Contact Telephone Number

For more information about Auto Return, see Chapter 11, “Auto Return.”

Back-end Integration Methods

There are two back-end integration methods, Instant Payment Notification and Payment Data Transfer.

Instant Payment Notification

PayPal's Instant Payment Notification (IPN) allows you to integrate PayPal payments with your website's back-end operations. IPN provides immediate notification and confirmation of PayPal's payments you receive, allowing you to:

z Customize your website's response to customer purchases in real-time.

z Track customers through the notification's pass through variables.

z Automate your fulfillment operations.

z Store transaction information in your own database.

Once you activate IPN, you will receive an IPN when a payment is first received that will display the status of the payment (Completed or Pending). If the payment status was Pending, you will receive another IPN when the payment clears, fails, or is denied.

IPN can be seamlessly integrated with each of the PayPal Website Payments solutions (Buy Now Buttons, PayPal Shopping Cart, Subscriptions and Recurring Payments, and Donations), as well as with regular PayPal Send Money and Mass Pay payments, and lets you focus on selling, not on manually tracking your orders.

Merchant User Manual and Integration Guide May, 2005 23

PayPal Payments Overview

Payment Receiving Preferences

For more information about IPN, “Instant Payment Notification (IPN) ” on page 103.

Payment Data Transfer

Payment Data Transfer (PDT) provides merchants with the ability to display transaction details to buyers who are redirected back to their site upon payment completion.

For more information about PDT, see “Payment Data Transfer” on page 96.

Payment Receiving Preferences

Once you have set up your PayPal account, you’re ready to start receiving payments. Your Payment Receiving Preferences let you manage the types of payments you receive.

For more information about Payment Receiving Preferences, see “Payment Receiving

Preferences” on page 31.

Refunds

You can automatically send a refund to your buyer for 60 days after receiving payment by using the refund link.

For more information about sending refunds, see “Processing Refunds” on page 108.

Multi-User Access

PayPal’s Multi-User Access feature allows you to set up multiple logins and access levels, so your employees only have access to the parts of your Paypal account that they need to complete their jobs, letting you run your business smoothly and securely.

For more information about Multi-User Access, see “Multi-User Access” on page 128.

Reports

PayPal’s Reporting Tools provide you with the information you need to effectively measure and manage your business. With PayPal’s Reporting Tools, you can:

z Analyze your revenue sources to better understand your customers’ buying behavior.

z Automate time-consuming bookkeeping tasks.

z Accurately settle and reconcile transactions.

24 May, 2005 Merchant User Manual and Integration Guide

For more information about PayPal's Reporting Tools, see https://www.paypal.com/us/cgi-

bin/webscr?cmd=p/xcl/rec/reports-intro-outside.

Subscriptions

PayPal Subscriptions and Recurring Payments is a service that will let you accept recurring payments for your service.

When you set up Subscriptions, you can offer your subscribers a trial period, special introductory rates, and a regular rate. Your subscribers will be billed automatically according to the terms you dictate, removing the hassle of keeping track of which payments you have and have not received.

For more information about PayPal Subscriptions and Recurring Payments, see the PayPal Subscriptions manual, which is available on the PayPal website.

PayPal Payments Overview

Subscriptions

Merchant User Manual and Integration Guide May, 2005 25

PayPal Payments Overview

Payment Flow Overview

The following diagram represents an overview of the PayPal payment flows.

FIGURE 2.1 PayPal Payment Flows

26 May, 2005 Merchant User Manual and Integration Guide

Getting Started

You can start accepting payments with PayPal in 5 easy steps:

Step 1 - Sign Up: Go to hand corner of the page. Click the Business link to sign up for a Business account, as shown in the following diagram. Make sure to write down the email address you use and the password you choose; in the future, you will use them to login to your PayPal account.

FIGURE 3.1 Business Account Sign-up

https://www.paypal.com/ and click the Sign Up link in the upper right-

Step 2 - Confirm Email Address: After completing the two-page signup, PayPal will send

you an email to confirm your email address. Open your email and click the link in the email we sent you. You will be taken to a PayPal page and asked to enter your password, as shown in the following diagram. Once you have successfully entered your password, your email address will be confirmed.

IMPORTANT:PayPal representatives will never ask you for your password, and will never

ask you to enter your password or financial information in an email or send such information in an email. If you believe someone has learned your password, please change it immediately and contact PayPal customer service as soon as possible.

Merchant User Manual and Integration Guide May, 2005 27

Getting Started

FIGURE 3.2 Confirming Your Email Address

Step 3 - Add Bank Account: In order for PayPal to add funds to your bank account, you must add it. Before you add your bank account, you will need a check or deposit slip for that bank account. Log in to your PayPal account and click the Profile subtab of the My Account tab. Click the Bank Accounts link in the Financial Information column. On the Bank Accounts page, click Add to reach the page shown in the following diagram. Once you have added your bank account, it will become your Primary bank account. If you decide to add additional bank accounts to your PayPal account, you can change any of them to be your primary account.

FIGURE 3.3 Adding a Bank Account

In order for PayPal to confirm that you are the owner of the bank account, PayPal will send two small deposits, each of less than $1.00, to your bank account. Check your bank statement in 3-4 business days, or check online, for the amounts of the two deposits. After getting the deposit amounts, log in to your PayPal account and click the Confirm Bank Account link in the Activate Account box on your Account Overview. Enter the amounts of each of the deposits on the page and your bank account will be confirmed and you will become Verified.

Step 4 - Add Credit Card (optional): Log in to your PayPal account and click the Profile subtab of the My Account tab, as shown in the following diagram. Click the Credit Cards link in the Financial Information column. On the Credit Cards page, click the Add button. The credit card you added will become your primary credit card, meaning it is the default

28 May, 2005 Merchant User Manual and Integration Guide

Getting Started

Managing Your PayPal Merchant Account

credit card used on your PayPal account. If you decide to add additional credit cards to your PayPal account, you can select any of them as your primary card.

In addition, the credit card billing address you entered when you added your credit card is now a Confirmed Address. Many sellers require that buyers use their Confirmed Address as their shipping address when they pay with PayPal. You can use Confirmed Addresses as a positive indicator of a buyer’s identity. When you ship to a Confirmed Address, you can qualify for protection under PayPal’s Seller Protection Policy. For more information about PayPal's Seller Protection Policy, see the PayPal User Agreement, which is available on the PayPal website.

Step 5 - Start Receiving Payments: Now that you’ve set up everything in your PayPal account, you’re ready to start receiving payments.

Managing Your PayPal Merchant Account

Account Profile

The PayPal account Profile consolidates all of the different settings and preferences for your account. You can use your Profile to manage all of the information in your PayPal account. To go to your Profile, log in to your PayPal account and click the Profile subtab of the

Account tab, as shown in the following diagram.

Your Profile is organized in three sections for managing your account information, as shown in the following diagram.

Merchant User Manual and Integration Guide May, 2005 29

Getting Started

Managing Your PayPal Merchant Account

FIGURE 3.4 Merchant Profile Page

Account Information

Use the Account Information column to perform basic account maintenance, including updating your password, adding and confirming email addresses, and managing your business information.

Financial Information

Use the Financial Information column to organize and maintain all of the financial instruments associated with your PayPal account, including adding credit cards and bank accounts, activating and managing your PayPal Debit Card, maintaining your Multiple Currency Balances, and viewing your Monthly Account Statements.

Selling Preferences

Use the Selling Preferences column to organize the way you sell with your PayPal account, including editing your Payment Receiving Preferences, tax, and shipping.

30 May, 2005 Merchant User Manual and Integration Guide

Payment Receiving Preferences

Once you have set up your PayPal account, you’re ready to start receiving payments. Your Payment Receiving Preferences let you manage the types of payments you receive, including:

z Block payments from U.S. users that do not have a confirmed address.

z Block payments sent to you in a currency you do not hold.

z Block payments from users with non-U.S. PayPal accounts.

z Block payments from users who initiate payments from the Pay Anyone subtab.

z Block payments funded by credit cards when the sender has a bank account.

z Block payments funded by eCheck for PayPal Website Payments and Smart Logo

payments.

To edit your Payment Receiving Preferences:

z Log in to your PayPal account.

z Click the Profile subtab of the My Account tab.

z Click the Payment Receiving Preferences link in the Selling Preferences column. The

Payment Receiving Preferences page opens, as shown in the following diagram.

Getting Started

Managing Your PayPal Merchant Account

FIGURE 3.5 Payment Receiving Preferences

Blocking Payments From U.S. Users Without a Confirmed Address

This preference allows you to better manage your risk by screening out payments where the buyer chooses not to share his Confirmed Address with you. PayPal provides Confirmed

Merchant User Manual and Integration Guide May, 2005 31

Getting Started

Managing Your PayPal Merchant Account

Addresses to help you make informed decisions when shipping goods. To be eligible for PayPal's Seller Protection Policy, 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 will be blocked. All

U.S. buyers will be required to provide a Confirmed Address in order to pay you.

z No: All payments will be accepted. To maximize your sales, select No.

z Ask Me: You may 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 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 will be notified that the payment has been denied and will be credited with the payment amount. PayPal does not charge fees for denied payments.

Blocking Payments in a Currency You Do Not Hold

You can use your PayPal account to accept payments in U.S. Dollars, Canadian Dollars, Euros, Pounds Sterling, and Yen.

When you receive a payment in a currency you do not hold, PayPal will prompt 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 will automatically be applied to the correct balance, and you will see a summary of each currency balance in your Account Overview page.

There are three choices for this preference:

z Yes: Accepts the payment regardless of the currency in which the payment is made.

z No, accept them and convert them to U.S. Dollars: Accepts the payment but

automatically converts to U.S. Dollars.

z Ask Me: You may choose to accept or deny a payment that is received in a currency you

do not currently hold on a transaction-by-transaction basis. If you accept the payment, it becomes a completed transaction. If you deny a particular payment, the sender of the payment will be notified that the payment has been denied and will be credited with the payment amount. PayPal does not charge fees for denied payments.

Blocking Payments From Users With Non-U.S. PayPal Accounts

Since 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 (SPP).

Blocking Payments Initiated From the Pay Anyone Subtab

This preference allows you to choose whether or not to receive payments initiated via the Pay Anyone subtab of the Send Money tab on the PayPal website.

If you choose to block these payments, you will accept only payments initiated via PayPal’s Buy Now Buttons, Donations, PayPal Shopping Cart, Subscriptions and Recurring Payments, Winning Buyer Notification, Mass Payments, Money Requests, Post-Sale Manager Invoices,

32 May, 2005 Merchant User Manual and Integration Guide

Getting Started

Managing Your PayPal Merchant Account

Smart Logos, or eBay Checkout Payments. Selecting this option may help you manage your account, because all of the PayPal payments you receive will be attached to a specific item or transaction that you previously defined.

If you choose not to block these payments, you will accept all payments, including those initiated via the Pay Anyone subtab of the Send Money tab.

Blocking Payments Funded By Credit Cards When Sender Has a Bank Account

This preference allows you to 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 will 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), choosing this preference will not prevent any users from being able to send you money. When they pay you with PayPal’s Instant Transfer, you receive the payment instantly, just as when they pay with a credit card. Users who have not confirmed their bank accounts with PayPal can still send you money funded from credit cards.

Blocking Payments Funded By eChecks

This preference allows you to block eCheck payments. Because eCheck payments take 3-4 business days to clear, you may not want to accept them for your Instant Purchase and Buy Now buttons.

If you choose to block these payments, you will not receive eCheck payments through PayPal Website Payments and Auction Logos. Users who attempt to pay via eCheck will be prompted to add a credit card to their account before completing the transaction.

If you choose not to block these payments, you will receive eCheck payments through PayPal Website Payments or Auction Logos. eCheck payments will be listed as ‘Pending’ and will not be credited to your PayPal Account for 3-4 business days.

Adding the Credit Card Statement Name

This preference allows you to specify the name that will appear on your customers’ credit card statements. When a buyer pays you by credit card, your Credit Card Statement Name will appear with the word PAYPAL* next to the charge on the statement (e.g. PAYPAL*MYCCNAME). The Credit Card Statement Name can be up to 11 English and/or German characters in length, including spaces, and cannot contain special characters (e.g. &, #, _, etc). This name will be converted to ALL CAPS, and may be truncated by some credit card processors.

The Credit Card Statement Name should accurately reflect your business or legal name.

Merchant User Manual and Integration Guide May, 2005 33

Getting Started

Managing Your PayPal Merchant Account

34 May, 2005 Merchant User Manual and Integration Guide

PayPal Account Optional

PayPal Account Optional is turned on by default for all U.S. Premier and Business accounts. Your customers who already have PayPal accounts will go through the same Website Payments experience to which they’re accustomed, which is shown in the “How It Works” section of the Creating Buy Now and Donations Buttons section of this manual.

Your new customers (or existing customers who are new to PayPal) will go through a checkout that doesn’t require PayPal signup, but they will have that option available after completing the payment. Whether customers sign up for a PayPal account or not, you can set your Buy Now, Donations, and Shopping Cart Buttons to return them to your website, and you will still receive the same notification emails as in the current checkout flow.

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.

4. Scroll down to the “PayPal Account Optional” section of the page. Select On to turn

PayPal Account optional on, or Off to turn it off and continue using the existing Website Payments flow for all of your customers.

5. Click Save to save your preference.

The setting you choose for PayPal Account Optional affects all of your existing and new Buy Now, Donations, and Shopping Cart buttons for customers who are new to PayPal. Your customers who already have PayPal accounts will see no change in their checkout experience—they will log in as usual at the time of payment and complete the transaction from within the PayPal account.

Merchant User Manual and Integration Guide May, 2005 35

PayPal Account Optional

Your Customer’s Experience

If you have turned PayPal Account Optional off, the checkout experience for a customer who doesn’t currently have a PayPal account is the same as in the past: the customer is required to sign up for a PayPal account to complete the payment and then returned to your website.

If you have PayPal Account Optional turned on, the checkout experience for a customer who doesn't currently have a PayPal account does not require the PayPal account signup to complete the transaction, thus shortening the time and effort necessary on the customer’s part.

What Your Customer Sees

Step 1: Bob goes to Alice’s website and clicks Buy Now.

Step 2: Bob is taken to a PayPal Payment Details page which shows the details of the payment

he is about to make. He is prompted to log in to his PayPal account, but he is not already a PayPal member, so he clicks Continue Checkout.

36 May, 2005 Merchant User Manual and Integration Guide

PayPal Account Optional

Your Customer’s Experience

Step 3: Bob is prompted to enter the shipping information for his purchase, and to let Alice know if the shipping address he has entered is the same as the billing address on his credit card. If it is, he clicks Yes. Bob is then taken to the Billing Information page, as shown in Step 4, where the Billing and Shipping Address information has been prepopulated; however, Bob will still need to enter his credit card information, email, phone, and security measure code.

NOTE: If your Payment Receiving Preferences are set to only accept payments from customers

with Confirmed addresses, then the buyer will skip over this Shipping Information screen and go directly to Billing Information in Step 4.

Merchant User Manual and Integration Guide May, 2005 37

PayPal Account Optional

Your Customer’s Experience

Step 4: Bob is then prompted to fill in his billing information for the credit card he wishes to use for the purchase. The purchase will be shipped to the shipping address he has provided.

38 May, 2005 Merchant User Manual and Integration Guide

PayPal Account Optional

Your Customer’s Experience

Step 5: Bob is taken to a Review page containing the details of his purchase. Because Alice has activated Profile-based Shipping for all of her transactions, the Shipping amount for this purchase ($2.00) is automatically added to Bob’s purchase. He clicks Complete Checkout to complete his purchase.

NOTE: For more information about setting Shipping preferences, see Chapter 9, “Calculating

Shipping, Handling, and Tax.”

Merchant User Manual and Integration Guide May, 2005 39

PayPal Account Optional

Your Customer’s Experience

Step 6: Bob is taken to a payment completion page where he sees his Receipt ID for this transaction, and Alice's customer service contact information. He can use both to contact Alice with any questions about his purchase.

If Bob clicks Save My Info, he will be 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 has already entered to complete the transaction will automatically carry forward.

If he clicks Continue, he will be redirected to either Alice’s site or to PayPal, depending on how she has set her return preferences for the button.

40 May, 2005 Merchant User Manual and Integration Guide

PayPal Account Optional

Your Customer’s Experience

Step 7: If Bob clicked Save My Info, he is taken to a page where he can complete signup 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.

If he clicks Continue, he will be redirected to either Alice’s site or to PayPal, depending on how she has set her return preferences for the button.

Merchant User Manual and Integration Guide May, 2005 41

PayPal Account Optional

Your Customer’s Experience

Step 9: Bob receives an email receipt for this transaction, confirming his payment and including a copy of his Payment details.

42 May, 2005 Merchant User Manual and Integration Guide

Creating Buy Now and Donation Buttons

PayPal makes it easy to accept payments for single items through your own website. The Buy Now and Donations Buttons features can be implemented in minutes, giving you easy access to business and donors from PayPal’s millions of members, and any other buyer on the Web.

The flexibility of our Buy Now and Donations Buttons feature will keep your website working for you. You can accept payments from current PayPal members as well as people who have just signed up for our service, and you won’t lose your customers after they have made a purchase or donation—the payment process lets you return buyers to your website, not lose them to ours.

Other benefits of Buy Now and Donations Buttons include:

z Easy to implement—no CGI scripting necessary.

z No up-front costs—you’ll have the same low fee schedule used as when you receive other

PayPal payments.

z Sell with ease—PayPal maintains detailed transaction records on our website.

z Improve buyer experience—with customizable buttons and secure payments, happy

customers become repeat customers.

How Buy Now and Donations Work

Bob, who is new to PayPal, is going to make a purchase or a donation on Alice's Used Books website. Depending on the PayPal Account Optional setting Alice has chosen in the Website Payments Preferences of her Profile, Bob's purchasing experience may differ from what is shown here.

The following example depicts the flow that occurs when PayPal Account Optional is turned off, and the user must create a PayPal account to complete the transaction. For more information about the PayPal Account Optional setting, see Chapter 4, “PayPal Account

Optional.”

Merchant User Manual and Integration Guide May, 2005 43

Creating Buy Now and Donation Buttons

How Buy Now and Donations Work

What Your Customer Sees

Step 1: Bob goes to Alice’s website and clicks Buy Now or Donations.

Step 2: Bob is taken to a PayPal Payment Details page which shows the details of the

payment he is about to make.

Step 3: Bob is prompted to log in to his PayPal account; however, he is not already a PayPal member, so he clicks If you have never paid through PayPal, Click Here, as shown in the following picture.

44 May, 2005 Merchant User Manual and Integration Guide

Creating Buy Now and Donation Buttons

How Buy Now and Donations Work

Step 4: To pay for his purchase or donation, Bob is prompted to add a credit card, email address, and password, which creates his new PayPal account.

Merchant User Manual and Integration Guide May, 2005 45

Creating Buy Now and Donation Buttons

How Buy Now and Donations Work

Step 5: Bob is taken to a Payment Details page that contains the details of his purchase or donation. Bob clicks Pay to complete his purchase or donation, as shown in the following diagram. For donations, Bob would choose a shipping address before clicking Pay so Alice can send him a tax receipt.

The Shipping amount for this purchase, $2.00, is automatically added to Bob’s purchase because Alice has activated Profile-based Shipping for all of her transactions. To learn more about automatically calculating shipping for all of your transactions, see Chapter 9,

“Calculating Shipping, Handling, and Tax.”

46 May, 2005 Merchant User Manual and Integration Guide

Creating Buy Now and Donation Buttons

How Buy Now and Donations Work

Step 6: Bob is taken to a payment completion page where he sees the details of his transaction. He is also given Alice’s customer service email address. He clicks the Continue link and is returned to a page on Alice’s website, which she specified when she created her payment or donation button.

With Auto Return for Website Payments, Bob is redirected back to Alice's site immediately after clicking Pay on the Payment Confirmation page.

The Payment Completion page can be merchant-hosted if the merchant has turned on Auto Return. To learn more about Auto Return, see Chapter 11, “Auto Return.”

Merchant User Manual and Integration Guide May, 2005 47

Creating Buy Now and Donation Buttons

How Buy Now and Donations Work

Step 7: Bob receives an email receipt for this transaction, confirming his payment and including a copy of his payment details.

What You See

Step 8: Alice receives an email notification of Bob’s payment.

48 May, 2005 Merchant User Manual and Integration Guide

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

Step 9: Alice logs in to her PayPal account to check the payment or donation Bob has sent.

Step 10: The funds from Bob’s payment are now reflected in Alice’s PayPal account balance.

She ships the book to Bob, or sends him a tax receipt for a donation.

NOTE: For more information about PayPal’s fees, please click the Fees link at the bottom of

any PayPal Web page, or visit

https://www.paypal.com/fees.

Buy Now and Donations Button Factory

One Buy Now button can be used to sell a single Mozart CD for $15 or, if you choose, it can allow your customer to purchase multiple copies of the same CD at once. If, however, you would like to sell a Mozart CD and a Beethoven CD, you will need to create separate Buy Now Buttons for each item or use PayPal’s Shopping Cart.

Donations buttons can be used to collect a pre-determined amount, (i.e. donations of $50), or you can allow your donors to choose the amounts of their donations.

Use the following steps to create your Buy Now and Donations buttons. Or, if you are comfortable using HTML, you can use the variables that are available in Appendix A to code your own buttons.

Getting Started

1. Log in to your PayPal account at https://www.paypal.com.

2. Click the Merchant Tools tab.

3. Click the Buy Now Buttons or Donations link under the Website Payments heading to

open the Button Factory.

Merchant User Manual and Integration Guide May, 2005 49

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

Creating a Buy Now Button

Step 1: Enter the details for your item (all fields are optional):

– 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 will be able to complete it at the 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 will not be displayed to your customers at the time of payment, but they will 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 will complete it. PayPal recommends entering an Item Price to make it easier for you to collect the correct amount.

– Currency: Choose the currency in which you would like this payment to be

denominated. This field will default to the currency of your primary balance.

Step 2: Choose a payment button to put on your website.

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.

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 will display a message that the payment page contains insecure items.

If you are creating an email link, skip to Step 4.

Step 3: 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.

NOTE: PayPal highly recommends encrypting your button code; however, doing so has three

limitations:

– The HTML code generated for an encrypted button is not editable, so if you are

accustomed to modifying your button code manually, you might want to select No for this option.

– You will not be able to 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. then you will want to turn encryption off by selecting No.

– Also, you will not be able to create an email link if you choose to encrypt your 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 Step 11. Otherwise, click Add More Options.

50 May, 2005 Merchant User Manual and Integration Guide

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

Step 4: Shipping and Sales Tax

– Shipping Cost Calculation: If you have already specified shipping rates in your Profile,

they will be listed here. To learn more about charging for shipping, see Chapter 9,

“Calculating Shipping, Handling, and Tax.”

– Sales or Value Added Tax Calculation: If you have already specified your tax rate

from your Profile, it will be listed here. For more information about charging for tax, see

Chapter 9, “Calculating Shipping, Handling, and Tax.”

Step 5: Add Option fields to your button

Let your customers specify information about their purchases by creating an option field. You can use Option fields to specify things like color, size, or gift-wrapping. 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 may have up to two option fields, and may you use a drop-down menu or text box to collect the information.

Unfortunately, Option fields and button encryption cannot currently be used if you are creating an email hyperlink. If you would still like to send out Buy Now links in emails, you may try either sending an HTML email, 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 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 for the

Option Name field.

– 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. – Step 6: 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 Buy

Now button. To learn more about creating page styles, see Chapter 8, “Custom Payment

Pages.”

Step 7: Customize Your Buyer Experience

– Successful Payment URL: Enter the URL for the page to which you want your

customer redirected after he has completed his payment. Unless you have enabled Auto

Return, once your customer has completed his payment he will see a payment

completion 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 payments at any point in the Buy Now payment flow. If you do not enter

a Cancel Payment URL, customers who click this link will be taken to a PayPal Web

page.

Merchant User Manual and Integration Guide May, 2005 51

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

Step 8: Miscellaneous Options

– Quantity: If you would like to let your customers purchase more than one of your item

or service, choose Yes. They will then be prompted to enter the quantity of the item they

want to buy. If you choose No, the quantity will be set to 1 and your customers will only

be able to purchase one item per payment. – Shipping Address: If you would like your customers to be prompted to provide a

shipping address, choose Yes. If you choose No, for items such as digital goods, your

customers will not be asked to provide a shipping address. – Step 9: 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 payment. If you select No, your customers will not be given the opportunity to

include a note. – Note Title: If you are allowing your customers to include a note with their payments,

you may 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. There is a 40-

character limit on your note field title. If you do not enter a title, your customers will see

Special Instructions (optional) as the note field title.

Step 10: Choose an email address to receive payment

If you have more than one confirmed email address added 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.

Step 11: Copy and paste the HTML code

When you have finished filling out the Buy Now Button Factory form, click Create Button

Now.

If your customers will be making purchases through your website: Copy the code from the For Web Pages 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.

In your website files, open the code for the Web page from which you wish to collect payment. Paste the code you just copied into your Web page file wherever you would like the image 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 the Paste option.

NOTE: HTML Tips: Please ensure that the HTML code on your Web page exactly matches

the code you copied from PayPal. Some HTML editors may add, delete, or change some characters in your code. If this is the case, please change the code on your Web page to exactly match the code you copied You can copy the code into a new Notepad document, reselect all of the code, copy, then paste it into your Web editor.

Please be sure that when you paste the HTML code for your button, you are pasting this information into a field that accepts HTML code. If you paste this code into a standard text field, the code will be posted to your Web page as standard text.

For more tips on placing your payment on your Web page, please refer to the Help section of your Web page editor.

52 May, 2005 Merchant User Manual and Integration Guide

If you will be sending your customers the payment link via email: Copy the code from the For Emails text 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 the email you wish to send.

Paste the code you just copied into your email by either pressing Ctrl+V or by right-clicking on your mouse and selecting the Paste option.

When your customers receive the email, the code will appear as a link. Clicking the link will take them to your PayPal payments page.

NOTE: If you enable button encryption, you will not be able to create an email link.

Creating a Donations Button

Step 1: Enter the details for your donations.

NOTE: All fields are optional.

– 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 may

complete this field. – Donation ID/Number: You may use this field to differentiate payments (e.g. to enter a

campaign name). This field will not be displayed to your donors at the time of payment,

but they will see it in their transaction details on the PayPal website. – Donation Amount: If you would like to collect a pre-determined amount, you may enter

it in the Donation Amount field. If you would like your donors to determine their

donation amounts, do not enter a price in this field. Users will be prompted to enter a

donation amount when they make payment.

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

NOTE: If you leave the Donations Amount field blank, your donors can choose the

amounts of their donations.

– Currency: Choose the currency in which you would like this payment to be

denominated. This field will default to the currency of your primary balance.

Step 2: Choose a Donations button to put on your website

Choose the image for the button you would like your donors to click to make their purchase. To display your own image, enter the URL of the image’s location in the URL field.

If you are also creating an email link, continue to Step 8. If you have no further details to add to your Donations button, click Create Button Now. Otherwise, click Add More Options.

Step 3: Customize Your Payment Pages

– Custom Payment Page Style: Give your donors 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 donor clicks your Donate

button. To learn more about creating page styles, Chapter 8, “Custom Payment Pages.”

Merchant User Manual and Integration Guide May, 2005 53

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

Step 4: Customize Your Donors’ Experience

– Successful Payment URL: Enter the URL where you would like to send your donors

after they have completed payment. Once your donor has completed his payment, he will

see a payment confirmation page. From this page, he will click Click to Continue and

return to the successful payment URL you have specified. If you do not enter a successful

payment URL, donors who click this link will be taken to a PayPal Web page. – Cancel Payment URL:

cancel a payment at any point in the Donations payment flow. If you do not enter a cancel

payment URL, donors who click this link will be taken to a PayPal Web page.

Step 5: Miscellaneous

– 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.

Step 6: Collect additional information from your customers

– Note Title: If you are allowing your donors to include a note with their payment, you

may choose a title for the note field. By including 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 will see

‘Special Instructions (optional)’ as the note field title.

Enter the URL where you would like to send your donors if they

NOTE: Select Yes if you would like your donors to be able to include a note to you with

their payment. If you select No, your donors will not be given the opportunity to include a note.

Step 7: Choose an email address 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 donors pay you.

Step 8: Copy and Paste the Donations code

When you have finished filling out the Donations Button Factory form, click Create Button Now.

If your donors will be donating through your website:

1. Copy the code from the Ctrl+C, or by highlighting all of the text, right-clicking your mouse, and clicking Copy.

2. In your website files, open the code for the Web page from which you wish to collect payment.

3. Paste the code you just copied into your Web page file wherever you would like the image to appear (typically, next to the description of the donation service) by pressing Ctrl+V, or right-clicking on your mouse and selecting Paste.

For Web pages text box by highlighting all of the text and pressing

If you will be sending your donors the Donations link via email:

54 May, 2005 Merchant User Manual and Integration Guide

Creating Buy Now and Donation Buttons

Buy Now and Donations Button Factory

1. Copy the code from the For Emails text box by highlighting all of the text and pressing Ctrl+C, or by highlighting all of the text, right-clicking on your mouse, and selecting

Copy.

2. Open the email you wish to send.

3. Paste the code you just copied into your email by either pressing Ctrl+V, or right-clicking

on your mouse and selecting Paste.

When your donors receive the email, the code will appear as a link. Clicking the link will take them to your PayPal payments page.

NOTE: HTML Tips: Please ensure that the HTML code on your Web page exactly matches

How You Get Your Money

After your customer has made his payment:

1. You will receive an email notification of the payment.

2. Your customer will receive an email receipt for the payment.

3. Your PayPal account will reflect the payment (you can view this information from your

account history or download it as part of your history transaction log).

For more information about payment-related notifications, see “Notifications You Receive”

on page 56 and Chapter 12, “Backend Integration - Payment Notifications.”

Merchant User Manual and Integration Guide May, 2005 55

Creating Buy Now and Donation Buttons

Notifications You Receive

You can be notified of payments in these three ways: email, history transaction log, and downloadable history transaction log.

You can be notified of payments in these four ways: email, history transaction log, downloadable history transaction log, and (if you have activated it) Instant Payment Notification (IPN).

Email

You receive an email notification in the following cases:

z Successful Payment

z Pending Payment

z Cancelled Payment

If you do not want to receive payment notifications via email:

1. Click the Profile subtab of the My Account tab.

2. Click the Notifications link from the left-hand menu.

3. Find the Payment Notifications heading and clear the I receive PayPal Website Payments and Instant Purchase checkbox.

4. Click Save.

History

Your transaction history log (“History”) contains information about your payments. Each payment will have one of these options as its status:

z Completed: The transaction was successful and the money was credited to your account.

z Cleared: The eCheck payment has cleared the sender’s account and has been credited to

your account.

z Uncleared: The eCheck payment has not cleared the sender’s account yet.

Downloadable Logs

Log in to your PayPal account, go to the History subtab of the My Account tab and choose the Download My History link in the Quick Links menu. Click the All Activity radio button or enter the dates of the entries you want to download, choose the type of file you would like to download (Comma delimited, Tab delimited, Quicken, or QuickBooks), and click Download My History. The downloaded file will contain a record of all of your payments.

56 May, 2005 Merchant User Manual and Integration Guide

Instant Payment Notification (IPN)

If you have Instant Payment Notification activated, you will receive an IPN when a payment is first sent, which will state the status of the payment (Completed or Pending). If the payment was Pending, you will receive another IPN when the payment clears, fails, or is denied.

To learn more about IPN, see “Instant Payment Notification (IPN) ” on page 103.

Creating Buy Now and Donation Buttons

Notifications You Receive

Merchant User Manual and Integration Guide May, 2005 57

Creating Buy Now and Donation Buttons

Notifications You Receive

58 May, 2005 Merchant User Manual and Integration Guide

Creating Shopping Cart Buttons

Save time and money with PayPal’s hassle-free Shopping Cart:

z Easy to implement — no CGI scripting necessary

z No up-front costs — you’ll have the same low fee schedule as when you receive other

PayPal payments

z Sell with ease — PayPal maintains detailed transaction records on our website

The PayPal Shopping Cart also offers customizable buttons and secure payments to help you improve your buyer experience, so happy customers become repeat customers.

Get the most out of your website today: start using the PayPal Shopping Cart!

How It Works

Bob, who is new to PayPal, is going to purchase several books from Alice’s website.

What Your Customer Sees

Step 1: Bob goes to Alice’s website and clicks Add to Cart. When he has chosen all of the books he wants, he clicks View Cart.

Merchant User Manual and Integration Guide May, 2005 59

Creating Shopping Cart Buttons

How It Works

Step 2: Bob looks at the contents of his cart and clicks Checkout.

Step 3: Bob is taken to a PayPal Payment Details page which shows the items he has added to

his Cart.

Step 4: Bob is prompted to log in to his PayPal account, but he is not already a PayPal member, so he follows the instructions at the top of the screen.

60 May, 2005 Merchant User Manual and Integration Guide

Creating Shopping Cart Buttons

How It Works

Step 5: Bob is then prompted to enter his credit card information, email address, and password, creating his new PayPal account.

NOTE: Existing PayPal users log in to their accounts directly and skip Step 5.

Merchant User Manual and Integration Guide May, 2005 61

Creating Shopping Cart Buttons

How It Works

Step 6: Bob is taken to a Confirmation page containing the details of his payment. Because Alice has activated her Shipping Preferences, the shipping costs are automatically added to Bob’s order. He clicks Pay to complete the payment.

62 May, 2005 Merchant User Manual and Integration Guide

Creating Shopping Cart Buttons

How It Works

Step 7: Bob is taken to a Confirmation page where he sees the details of his successful payment. He is also given Alice’s customer service email.

With Auto Return for Website Payments, Bob would be redirected back to your site immediately after clicking the Pay button on the Payment Confirmation page. To learn more about Auto Return, see Chapter 11, “Auto Return.”

Step 8: Bob receives an email receipt for this transaction, confirming payment and including a copy of the Payment details.

Merchant User Manual and Integration Guide May, 2005 63

Creating Shopping Cart Buttons

PayPal Shopping Cart Button Factory

What You See

Step 9: Alice receives an email notification of Bob’s payment.

Step 10: Alice logs into her PayPal account to check the payment Bob has sent.

Step 11: The funds from Bob’s payment are now reflected in Alice’s PayPal account balance.

She ships the books to her satisfied customer.

PayPal Shopping Cart Button Factory

With the PayPal Shopping Cart, your buyers can make a single payment when they purchase multiple items.

It’s easy to set up and use: just create a separate Add to Cart button for each item you sell, and place the automatically generated HTML code for that button on your website next to the item.

Use the following steps to create your Shopping Cart buttons, or if you are comfortable using HTML, you can use the variables that are available in Appendix A to code your own buttons.

64 May, 2005 Merchant User Manual and Integration Guide

NOTE: You also have the option of prepopulating your customer’s signup information during

the checkout flow. For more information, and a list of variables, see “Prepopulating

Your Customer’s PayPal Sign-Up ” on page 141.

Getting Started

1. Log in to your PayPal account at https://www.paypal.com.

2. Click the Merchant Tools tab.

3. Select the PayPal Shopping Cart link under the Website Payments heading to get to the

Button Factory.

Creating Your Shopping Cart Button

Step 1: Enter the details for the item you wish to sell.

– 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 will default to the currency of your primary balance

Creating Shopping Cart Buttons

PayPal Shopping Cart Button Factory

Step 2: Choose an image for your button.

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. Once one item is added to a Cart, buyers will not be allowed to add any items listed in other currencies to that Cart.

To change the currency, buyers must either Checkout and purchase the items in the first currency, or remove all existing 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.

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 Step 12. Otherwise, click Add More Options to see the fields listed in Step 3 -12.

Step 3: Calculate shipping and tax.

If you have already specified shipping rates in your Profile, they will be listed under Shipping Cost Calculation. For more information about calculating shipping, see Chapter 9,

“Calculating Shipping, Handling, and Tax.”

Merchant User Manual and Integration Guide May, 2005 65

Creating Shopping Cart Buttons

PayPal Shopping Cart Button Factory

If you have already specified your tax rate from your Profile, it will be listed under Sales Tax Calculation. For more information about calculating tax, see Chapter 9, “Calculating

Shipping, Handling, and Tax.”

Step 4: Add option fields to your button.

Let your customers specify information about their purchases by creating an option field. You can use option fields to specify information such as color, size, or gift wrapping. Options must not change the price of an item, but will let you collect additional information from your customer without extra email communication. Each Shopping Cart Button may have up to two option fields, and you may 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.

Step 5: Select a View Cart button.

Choose the image for the button 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.

Step 6: 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 Chapter 8, “Custom Payment Pages.”

Step 7: Customize your buyer’s experience.

– Successful Payment URL: Enter the URL where you would like to send your customers

after they have completed payment. Once your customer has completed his payment, he

will see 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.

Step 8: Select other options.

– Shipping Address: If you would like your customers to be prompted to provide a

shipping address, choose Yes. If you choose

provide a shipping address.

No, your customers will not be asked to

66 May, 2005 Merchant User Manual and Integration Guide

Creating Shopping Cart Buttons

PayPal Shopping Cart Button Factory

Step 9: 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 payment. If you select No, your customers will not be given the opportunity to

include a note. – Note Title: If you are allowing your customers to include a note with their payment, you

may 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. There is a 40-character

limit on your note field title. If you do not enter a title, your customers will see Special

Instructions (optional) as the note field title.

Step 10: Choose the email address at which you want to receive payment.

Step 11: Copy and paste the PayPal Shopping Cart code.

– When you have finished filling out the PayPal Shopping Cart Button Factory form, click

Continue. – Copy the code from the For Web pages 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. – Open the Web page file into which you’d like to add your Shopping Cart Button. – 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 choosing Paste.

NOTE: HTML Tip: Please ensure that the HTML code on your Web page exactly matches

Step 12: Create Add to Cart buttons for all of your items.

Click Create Another Button to create more Add to Cart buttons following the previous Steps 1-5. Once you have created Add to Cart buttons for all of the items you are selling, proceed to Step 13.

Step 13: 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.

Merchant User Manual and Integration Guide May, 2005 67

Creating Shopping Cart Buttons

How You Get Your Money

1. 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.

2. Open each Web page from which you would like your customers to be able to get to their PayPal Shopping Carts.

3. 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 on your mouse and choosing Paste.

NOTE: You also have the option of prepopulating your customer’s information. For more

information, and a list of variables, see “Prepopulating Your Customer’s PayPal Sign-

Up ” on page 141.

How You Get Your Money

After your customer has made his payment:

1. You will receive an email notification of the payment.

2. Your customer will receive an email receipt for the payment.

3. Your PayPal account will reflect the payment. You can view this information from your

Account History or download it as part of your History transaction log.

Notifications You Receive

You can be notified of payments in these three ways: email, history transaction log, and downloadable history transaction log.

You can be notified of payments in these four ways: email, history transaction log, downloadable history transaction log, and, if you have activated it, Instant Payment Notification (IPN).

Email

You receive an email notification in the following cases:

z Successful Payment

z Pending Payment

z Cancelled Payment

If you do not want to receive payment notifications via email:

1. Click the Profile subtab of the My Account tab.

68 May, 2005 Merchant User Manual and Integration Guide

2. Click the Notifications link from the left-hand menu.

3. Find the Payment Notifications heading and clear the I receive PayPal Website Payments and Instant Purchase checkbox.

4. Click Save.

History

Your transaction history log (“History”) contains information about your payments. Each payment has one of the following statuses:

z Completed: The transaction was successful and the money was credited to your account.

z Cleared: The eCheck payment has cleared the sender’s account and has been credited to

your account.

z Uncleared: The eCheck payment has not cleared the sender’s account yet.

Downloadable Logs

Creating Shopping Cart Buttons

Notifications You Receive

Log in to your PayPal account, go to the History subtab of the My Account tab and choose the Download My History link in the “Quick Links” menu. Choose the All Activity radio button or enter the dates of the entries you want to download, choose the type of file you would like to download (Comma delimited, Tab delimited, Quicken, or QuickBooks), and click Download History. The downloaded file will contain a record of all of your payments.

Instant Payment Notification (IPN)

If you have Instant Payment Notification activated, you will receive an IPN when a payment is first sent, which will state the status of the payment (Completed or Pending). If the payment was “Pending,” you will receive another IPN when the payment clears, fails, or is denied.

To learn more about IPN, see “Instant Payment Notification (IPN) ” on page 103.

Merchant User Manual and Integration Guide May, 2005 69

Creating Shopping Cart Buttons

Notifications You Receive

70 May, 2005 Merchant User Manual and Integration Guide

Adding PayPal to Your Thirdparty Shopping Cart

Some Web developers may wish to integrate PayPal payment processing with their own thirdparty shopping cart instead of the standard PayPal Shopping Cart. Please use the following instructions and variables to 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.

There are now two ways to integrate your third-party shopping cart with the PayPal payment flow. The first is to pass in the aggregate amount of the Cart payment, rather than of the individual items. The second is to pass details of the items that have been selected to PayPal, instead of an aggregated amount for the entire Cart.

For a complete list of variables, see “PayPal Shopping Cart HTML and Variables” on

page 137.

NOTE: Posting the necessary variables to PayPal as described in the following instructions

will probably require you to implement some scripting on your website.

Passing the Aggregate Shopping Cart Amount to PayPal

If you wish, you may aggregate your entire shopping cart and pass the total amount into PayPal’s Buy Now code. In other words, you will need to post a single name for the entire cart and the total price of the cart’s contents as though it were a purchase of a single item.

One drawback of this method is that your buyers will not be able to see the individual items appearing in their carts. In addition, you cannot change our variable names, nor can you add your own variable names.

Passing Individual Items to PayPal

If your third-party shopping cart can be configured to pass individual items to PayPal, information about the items will be included in the buyer’s and seller’s History logs and notifications. To include information about the items, you will post HTML form elements to a new version of PayPal’s Shopping Cart flow. This process is much like the one described in Passing Aggregate Shopping Cart Amount to PayPal, with the following exceptions:

1. Set the cmd variable to _cart.

2. Replace this required HTML line:

with

Merchant User Manual and Integration Guide May, 2005 71

Adding PayPal to Your Third-party Shopping Cart

Passing the Aggregate Shopping Cart Amount to PayPal

3. Add a new variable called upload by adding the following line between the <form> and </form> tags:

4. Define item details.

For each of the following item-specific parameters, define a new set of values that correspond to each item that was purchased via your third-party cart. Append _ variable name, where

x is the item number, starting with 1 and increasing by one for each

item that is added.

5. Repeat for each item included in cart.

Include a set of required variables and any optional variables from the table above for each item included in your buyer’s cart. The first item included in the cart should be defined with parameters ending in _1, such as item_name_1, amount_1, and so on. Similarly, the second item should be denoted with variables like item_name_2, amount_2, 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.

x to the

To specify currency: 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 itemspecific, there is no need to append _

x to the currency_code variable name. If no

currency_code variable is posted, we will assume that all monetary values are in U.S.

Dollars.

To specify cart-wide tax: 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 peritem tax amount specified with tax_

For a complete list of variables, see the Passing Individual Items to PayPal section of Appendix A in this manual.

72 May, 2005 Merchant User Manual and Integration Guide

Custom Payment Pages

Examples of Custom Payment Pages

The pictures in this section demonstrate the types of customization you can add to your PayPal Website Payment buttons.

Figure 8.1, “Payment Page in Standard PayPal Page Style,” shows a payment page without

any customization.

FIGURE 8.1 Payment Page in Standard PayPal Page Style

Merchant User Manual and Integration Guide May, 2005 73

Custom Payment Pages

Examples of Custom Payment Pages

Figure 8.2, “Payment Page with Custom Style: Header Image and Header Border,” shows a

custom header image and header border color.

FIGURE 8.2 Payment Page with Custom Style: Header Image and Header Border

74 May, 2005 Merchant User Manual and Integration Guide

Custom Payment Pages

Getting Started

Figure 8.3, “Payment Page with Custom Style: Header Image, Image Border, and Background Color,” shows a custom header image, header border color, and page background color.

FIGURE 8.3 Payment Page with Custom Style: Header Image, Image Border, and

Background Color

Getting Started

1. Log in to your PayPal account at https://www.paypal.com

2. Click the Profile sub-tab.

3. Click the Custom Payment Pages link under the Selling Preferences heading to get to the

Custom Payment Page Styles page.

4. From this page, you can add, edit, preview, and remove page styles, as well as make any page style your primary style.

Merchant User Manual and Integration Guide May, 2005 75

Custom Payment Pages

Adding a Page Style

You can add up to three page styles. To add a page style:

1. Begin at the Custom Payment Page Styles page.

2. Click Add.

3. Enter your page style preferences:.

– Page Style Name (required)

Enter a name up to 30 characters in length. The name can contain letters, numbers, and the underscore mark - but no other symbols or spaces. The Page Style Name will be used to refer to the page style within your PayPal account and in the HTML code for your PayPal Website Payment buttons.

– Header Image URL (optional)

Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg, .png, and .swf. The image will appear at the top left of the payment page.

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.

– 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, then the header will be 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 will be reduced to 45 pixels.

– 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 2 pixel perimeter around the header space.

– 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.

The next time you create a button, you have the option to apply a page style to the payment pages associated with it. To do so, click Add More Options on the button creation page, and select a page style from the Custom Payment Page Style menu.

NOTE: The settings described here can also be specified with HTML <FORM> input variables

passed through at a transaction level. For more information, see Table A.2, “Shopping

Cart Variables” on page 138.”

76 May, 2005 Merchant User Manual and Integration Guide

Editing a Page Style

To edit a page style:

FIGURE 8.4 Editing Page Style Settings

Custom Payment Pages

Editing a Page Style

1. Begin at the Custom Payment Page Styles page. For more information, see “Getting

Started” on page 75.

2. Click the radio button next to the page style you wish to edit.

3. Click Edit.

Merchant User Manual and Integration Guide May, 2005 77

Custom Payment Pages

Previewing a Page Style

4. Keep or modify your page style preferences:

– Page Style Name (required)

– Header Image URL (optional)

NOTE: PayPal recommends that you enter an image URL only if the image is stored on a

– Header Background Color (optional)

– Header Border Color (optional)

– Background Color (optional)

Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg, .png, or .swf. The image will appear at the top left of the payment page.

secure (https) server. Otherwise, your customer's Web browser will display a message that the payment page contains insecure items.

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.

5. Click Preview to preview your page style, or click Save to save it.

Previewing a Page Style

To preview a page style:

1. Begin at the Custom Payment Page Styles page. For more information, see “Getting

Started” on page 75.

2. Click the radio button next to the page style you wish to preview.

3. Click Preview.

78 May, 2005 Merchant User Manual and Integration Guide

Making a Page Style Primary

When you make a page style Primary, it is applied to all of your payment pages unless you specify otherwise. To learn how to apply a page style other than your Primary style, Chapter 8,

“Custom Payment Pages.”

NOTE: If you do not designate page style as Primary, the default PayPal page style is used.

To make a page style Primary:

1. Begin at the Custom Payment Page Styles page.

For more information, see “Getting Started” on page 75.

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.

Custom Payment Pages

Making a Page Style Primary

Removing a Page Style

When you remove a page style, the payment pages to which the style applied will no longer be customized with those specifications. Instead, your Primary page style will be applied to those pages. If you remove your Primary page style, the PayPal page style will become Primary.

To remove a page style:

1. Begin at the Custom Payment Page Styles page.

For more information, see “Getting Started” on page 75.

2. Click the radio button next to the page style you wish to remove.

3. Click Remove.

4. Click Remove to confirm your choice.

Overriding Page Style Settings

Your Primary page style will automatically be applied to all of your payment pages unless you specify otherwise.

To apply a page style other than your Primary style, select a different one when creating your button. Just click Add More Options on the button creation page, and select a page style from the Custom Payment Page Style menu.

Merchant User Manual and Integration Guide May, 2005 79

Custom Payment Pages

Overriding Page Style Settings

To change the page style for a button you have already created, you can modify the button's HTML code, replacing the value of the page_style variable with the Page Style Name of the style you wish to apply. The next time the button is clicked, its payment pages will appear in the new style.

When passed through at a transaction-level, Custom Payment Page variables are used to customize the payment pages and override any page styles set in profile settings or page_settings. Customization variables are applied in the following order:

TABLE 8.1 Order of Customization Variables

Custom Option Description

1 Custom Payment Pages

Variable at a Transaction level

2 Primary Page Style at a

Transaction level

3 Primary Page Style in

Profile

4 Default PayPal Page

Style in Profile

See

Table A.2, “Shopping Cart Variables” on page 138.

A valid page style can be passed through at a Transaction level that overrides any page styles set in profile settings or page_settings.

You can create and select the primary style in profile settings.

The default page style used when an alternative is not selected and designated as primary.

80 May, 2005 Merchant User Manual and Integration Guide

Background Colors and Error Messages

PayPal’s error message system highlights errors in red. PayPal does not allow certain background colors that make these error messages unreadable.

The background color of the following payment page is not allowed. The color makes the fields the customer must complete difficult to read.

FIGURE 8.5 Example of Unallowed Background Color

Custom Payment Pages

Merchant User Manual and Integration Guide May, 2005 81

Custom Payment Pages

Background Colors and Error Messages

The background color of the following payment page is allowed. Unlike in the previous example, the fields displayed in red are easy to read.

FIGURE 8.6 Example of Allowable Background Color

To verify that your background color is allowed, enter its hex code into the Background Color field on the Custom Payment Pages page under the Profile subtab of the My Account tab and click Preview. The 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 and you must choose a different color.

If a conflicting background color is passed through, it will be considered invalid and PayPal will automatically default your background color to white.

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.

Image Storage

PayPal recommends that you store your images on secure (https) servers. If your images are not stored on secure servers, your customers may be shown a browser warning indicating that you have insecure items on your page.

82 May, 2005 Merchant User Manual and Integration Guide

Calculating Shipping, Handling,

and Tax

You can set up your PayPal account to automatically calculate and charge shipping and sales tax (also called “value added tax”).

Getting Started

To view or modify your sales tax and shipping charges:

1. Log in to your PayPal account at

2. Click the Profile subtab of the My Account tab.

3. Click the Sales Tax or the Shipping Calculation link in the Selling Preferences column.

https:www.paypal.com.

Sales or Value Added Tax Collection

You can charge your customers tax by choosing a Country (such as, United Kingdom) or State (such as, California) from the Country and U.S. State drop-down menus, and entering your Tax Rate for that state in the Tax Rate field. All your 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.

There are radio buttons that allow you to apply tax to an item only, or to an item and any shipping and handling costs, as you desire.

Click Save to save your changes.

NOTE: If you are entering the rate for a U.S. state, ensure that the Country drop-down menu is

set to United States.

Overriding Tax Setting Per Transaction

The tax variable is an optional transaction-based tax override variable with which you can set a flat tax amount on a single transaction regardless of the buyer’s location.

For more information about this and other variables, see Appendix A, “HTML Samples.”

Merchant User Manual and Integration Guide May, 2005 83

Calculating Shipping, Handling, and Tax

Shipping Calculation

Determine whether you would like to charge your customers for shipping as a flat amount or a percentage of the total purchase amount.

Flat Amount

A flat amount is charged based on the subtotal of a purchase. Here’s an example.

EXAMPLE 9.1 Flat Amount Shipping Calculation

Your flat amount settings are:

$0.00 through $49.99 = $3.00 $50.00+ = $6.00

– If your customer’s subtotal is $36.50, your customer is charged $3.00 for shipping,

making the total purchase $39.50.

– If your customer’s subtotal is $66.50, your customer is charged $6.00 for shipping,

making the total purchase $72.50.

Choose the Flat Amount radio button (with the $ beneath it), and enter a flat amount for each dollar amount increment. Click Save to save your changes.

Percentage

A percentage is charged based on the subtotal of a purchase. Here’s an example.

EXAMPLE 9.2 Percentage Shipping Calculation

Your percentage settings are:

$0.00 through $49.99 = 5% $50.00+ = 4%

– If your customer’s subtotal is $36.50, your customer is charged 5% x $36.50 = $1.83 for

shipping, making the total purchase $38.33.

– If your customer’s subtotal is $66.50, your customer is charged 4% x $66.50 = $2.66 for

shipping, making the total purchase $69.16.

Choose the Percentage radio button (with the % beneath it), and enter a percentage for each dollar amount increment. Click Save to save your changes.

Overriding Your Shipping Calculation

In some cases, 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 charge a different shipping amount for an item, include the shipping cost in the HTML for that Buy Now button using the shipping, shipping2, and

84 May, 2005 Merchant User Manual and Integration Guide

Calculating Shipping, Handling, and Tax

Shipping Calculation

handling_cart variables. For more information and a complete list of the Buy Now button

variables, see “Sample Buy Now Button HTML” on page 131.

To make sure that the shipping HTML in your Shopping Cart Button overrides your Profile Shipping Calculation settings:

1. Go to the Shipping Calculations page in your Profile.

2. Click the Click here to allow transaction-based shipping values to override the profile shipping settings listed above (if profile settings are enabled) checkbox.

3. Click Save.

Merchant User Manual and Integration Guide May, 2005 85

Calculating Shipping, Handling, and Tax

Shipping Calculation

86 May, 2005 Merchant User Manual and Integration Guide

How It Works

Creating Customer Contact Telephone

The Customer Contact Information Telephone is an option that provides you with a contact telephone number for your buyer. When you activate this option, your customers are asked to include a Contact Telephone Number with their payment information. PayPal will share this number with you.

In accordance with our 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.

When you enter your payment preferences on the Website Payment Preferences page, you will have the opportunity to request a Contact Telephone Number from your buyer.

You can choose to make the Contact Telephone Number optional, required, or turn it off. Off is the recommended default option because buyers value their privacy and prefer to keep unsolicited communications to a minimum.

What You See

Step 1:

You can select the option you want to use to activate the Contact Telephone Number feature. If you do not want to request a contact telephone number from your buyer, you can select the Off radio button. You will see the following on the Website Payment Preferences page:

Step 2: On the Transaction Details page, you will see the buyer’s contact telephone number:

Merchant User Manual and Integration Guide May, 2005 87

Creating Customer Contact Telephone

Getting Started

What Your Customer Sees

Step 3: When you require the buyer’s contact telephone number, your buyer will see the information below:

Getting Started

Use the following instructions to activate the Customer Contact Information Telephone option:

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.

Notifications You Receive

You receive an email notification when a buyer makes a purchase.

https://www.paypal.com.

88 May, 2005 Merchant User Manual and Integration Guide

Auto Return

With Auto Return for Website Payments, merchants can eliminate the “Done” page in the Website Payments flow and automatically return or redirect buyers to their site upon payment completion. By decreasing the Website Payments purchasing process by 1/3 and automatically bringing buyers back to their site, merchants provide their buyers with a quicker, more seamless, and continuous purchasing experience.

Merchants with premier or business accounts can enable Auto Return by turning it on, specifying the URL to redirect the buyer upon payment completion, and agreeing to the terms that require that the merchant provide “payment done” messaging on the page assigned to the return URL.

Auto Return applies to all PayPal Website Payments, including Buy Now, Donations, Shopping Cart, and Subscriptions.

How Auto Return Works

This example shows the Auto Return flow with Custom Payment Pages, but without the PayPal Account Optional feature.

Bob is going to purchase a widget from the Widget Warehouse.

Step 1: Bob goes to the Widget Warehouse website, finds the widget he wants, and clicks Buy Now.

Merchant User Manual and Integration Guide May, 2005 89

Auto Return

How Auto Return Works

Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the payment he is about to make.

Step 3: Bob enters his PayPal account information into the PayPal Login fields. (These pages are not included in this example.)

NOTE: At this point, buyers that do not already have a PayPal account click the If you have

never paid through PayPal, Click Here button. The Payment Details page then

displays credit card, email, password, and security fields that can be used to create a new PayPal account. After the new account is created, the the buyer clicks Continue to proceed to the next step in the payment process.

90 May, 2005 Merchant User Manual and Integration Guide

Auto Return

How Auto Return Works

Step 4: Bob is then taken to a confirmation page that displays the details of his selection, information about how his automatic payments will be funded, and his shipping information. He clicks Pay to complete payment.

Step 5: A payment confirmation page appears that informs Bob that his payment has been completed and that he is being automatically redirected back to the Widget Warehouse site. The page also displays a success URL that the user can click manually if the redirect fails.

Merchant User Manual and Integration Guide May, 2005 91

Auto Return

How Auto Return Works

Step 6: The Widget Warehouse’s “Thank You” page appears, again informing Bob that his transaction is complete and that a receipt for the purchase has been emailed to him. The page also displays a link to PayPal that Bob can use to view details of the transaction if necessary, as well as links that he can use to continue shopping.

Step 7: Bob receives an email receipt for this transaction, confirming his purchase and including a copy of the payment details, the Widget Warehouse's business information, and his confirmed shipping address.

92 May, 2005 Merchant User Manual and Integration Guide

Setting Up Auto Return

To set up Auto Return:

Auto Return

Setting Up Auto Return

1. Log in to your PayPal account at

2. Click the Profile subtab.

3. Click the Website Payment Preferences link under the Selling Preferences column on

the right.

4. Under Auto Return for Website Payments, click the On radio button to enable Auto Return.

https://www.paypal.com.

Merchant User Manual and Integration Guide May, 2005 93

Auto Return

Subscription Password Management and Auto Return

5. Enter the Return URL to which you want your buyers redirected upon payment completion in the Return URL field.

You Return URL must meet the following requirements:

– Per the user agreement, you must provide content on the page displayed by the Return

URL that helps the buyer understand that the payment has been made and that the transaction has been completed.

– You must provide content on the page displayed by the Return URL that explains that

payment transaction details will be emailed to the buyer.

– Your Return URL must be specify a server that is available and be properly formatted.

NOTE: If the Return URL that you supply is not valid, PayPal displays the standard

Payment Done page upon payment completion.

6. Click Save.

Subscription 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 Manual, which is available on the PayPal website.

94 May, 2005 Merchant User Manual and Integration Guide

Emails

Backend Integration - Payment Notifications

PayPal offers two payment notification methods for backend integration: PayPal offers four payment notification methods for backend integration:

z Emails

z Reports

z Instant Payment Notification (IPN)

z Payment Data Transfer (PDT)

You will receive an email notification in the following cases:

z Successful Payment

z Pending Payment

z Cancelled Payment

If you do not want to receive payment notifications via email:

1. Click the Profile subtab of the My Account tab.

2. Click the Notifications link from the left-hand menu.

3. Find the Payment Notifications heading and clear the I receive PayPal Website

4. Click Save.

Reporting

PayPal’s Reporting Tools provide you with the information you need to effectively measure and manage your business. With PayPal’s Reporting Tools, you can:

z Analyze your revenue sources to better understand your customers’ buying behavior

z Automate time-consuming bookkeeping tasks

z Accurately settle and reconcile transactions

The available reports are:

z Monthly Account Statements: View a summary of all credits and debits that have

Payments and Instant Purchase checkbox.

affected your account balance each month.

z Merchant Sales Reports: Every week, receive valuable analysis of revenue by sales

channel and currency.

Merchant User Manual and Integration Guide May, 2005 95

Backend Integration - Payment Notifications

Payment Data Transfer

z History Log: View an online record of your received and sent payments.

z Downloadable Logs: Keep track of your transaction history by downloading it into

various file formats (suitable for financial settlements).

For more information about PayPal's reports, see

bin/webscr?cmd=p/xcl/rec/reports-intro-outside.

http://www.paypal.com/cgi-

Instant Payment Notification (IPN) and Payment Data Transfer (PDT)

PDT’s primary function is to display payment transaction details to buyers when they are automatically redirected back to your site upon payment completion; however, there are cases where you will not receive notification of all transactions, such as with pending transactions, refunds, and reversals. For these reasons, or if you are using this data to fulfill orders, PayPal strongly recommends that you also enable Instant Payment Notification (IPN).

Both IPN and PDT send back the same data; however, there are several important differences.

PDT:

z Requires Auto Return to be enabled.

z Auto Return will include an ID that can be used to query PayPal for the complete

transaction details.

z It is possible to miss a notification if the user closes the browser before the redirection is

complete.

IPN:

z Does not require Auto Return to be enabled.

z At the end of the website payment flow, PayPal POSTs the IPN data asynchronously (i.e.

not as part of the website payment flow).

z IPNs will also POST for eCheck clearings, reversals, and refunds.

SSL Security Not Required for IPN

Because credit card and bank information is not transmitted in Instant Payment Notification (IPN), PayPal does not require the use of SSL to encrypt IPN transmissions.

Payment Data Transfer

Payment Data Transfer (PDT) provides merchants with the ability to display transaction details to buyers who are redirected back to their site upon payment completion.

NOTE: You must enable Auto Return for Website Payments to use Payment Data Transfer.

Auto Return brings your buyers back to your website immediately after payment completion. Auto Return applies to PayPal Website Payments, including Buy Now, Donations, Subscriptions, and Shopping Cart. For more information on Auto Return,

Chapter 11, “Auto Return.”

96 May, 2005 Merchant User Manual and Integration Guide

How It Works

Bob is going to purchase a widget from the Widget Warehouse.

Step 1: Bob goes to the Widget Warehouse website, finds the widget he wants, and clicks Buy Now.

Backend Integration - Payment Notifications

Payment Data Transfer

Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the payment he is about to make.

Step 3: Bob enters his PayPal account information into the PayPal Login fields.

Merchant User Manual and Integration Guide May, 2005 97

Backend Integration - Payment Notifications

Payment Data Transfer

Step 5: A payment confirmation page appears that informs Bob that his payment has been completed and that he is being redirected back to the Widget Warehouse website.

Step 6: A transaction token is passed to the return URL provided by the Widget Warehouse. The Widget Warehouse fetches the transaction token and retrieves the transaction details from PayPal via an HTTP POST. Included in the HTTP post is the identity token that was given to the Widget Warehouse when PDT was enabled.

For more information about the PDT identity token, see “Getting and Using the Identity

Token” on page 100. For more information about the HTTP POST, see “Setting Up Payment Data Transfer” on page 101.

98 May, 2005 Merchant User Manual and Integration Guide

Backend Integration - Payment Notifications

Payment Data Transfer

Step 7: The Widget Warehouse's Thank You page appears and displays the transaction information, again informing Bob that his transaction has been completed and a receipt for the purchase has been emailed to him. The page also displays payment details, a link to PayPal that Bob can use to view more transaction details if necessary, as well as links that he can use to continue shopping.

For example, as shown in the following diagram: Thank you for your payment. Your transaction has been completed, and a receipt for your purchase has been emailed to you. You may log into your account at

www.paypal.com to view details of this transaction.

Step 8: Bob receives an email receipt for this transaction, confirming his purchase and including a copy of the payment details, the Widget Warehouse's business information, and his confirmed shipping address.

Enabling Payment Data Transfer

Turning On PDT

To turn on PDT:

1. Click the My Account tab.

2. Click the Profile subtab.

Merchant User Manual and Integration Guide May, 2005 99

Backend Integration - Payment Notifications

Payment Data Transfer

3. Click the Website Payment Preferences link, as shown in the following diagram.

The Website Payment Preferences page opens.

4. Click the Payment Data Transfer On radio button, as shown in the following diagram.

NOTE: You must enable Auto Return in order to use Payment Data Transfer. Auto Return can

also be enabled from the Website Payment Preferences page.

5. Click Save.

Getting and Using the Identity Token

When you click Save and save your PDT preferences, a message will appear at the top of the page indicating that you have successfully saved your preferences. Your identity token will also appear in the context of this message. You will need to pass this identity token, along with the transaction token, to PayPal in order to receive information that confirms that the payment is complete.

For security reasons, the identity token will not be sent to you; however, once you have enabled PDT, it will permanently appear below the Payment Data Transfer On/Off radio buttons on the Website Payments Preferences page.

100 May, 2005 Merchant User Manual and Integration Guide

PayPal Merchant - 2005 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Preface

Introduction

PayPal-Supported Currencies

Additional Information

PayPal Payments Overview

PayPal Account Optional

Buy Now and Donations Buttons

Shopping Cart

Custom Payment Pages

Calculating Shipping, Handling, and Tax

Contact Telephone Number

Auto Return

Back-end Integration Methods

Instant Payment Notification

Payment Receiving Preferences

Payment Data Transfer

Refunds

Multi-User Access

Reports

Subscriptions

Payment Flow Overview

Getting Started

Managing Your PayPal Merchant Account

Account Profile

Payment Receiving Preferences

PayPal Account Optional

Turning PayPal Account Optional On or Off

Your Customer’s Experience

What Your Customer Sees

Creating Buy Now and Donation Buttons

How Buy Now and Donations Work

What Your Customer Sees

What You See

Buy Now and Donations Button Factory

Getting Started

Creating a Buy Now Button

Creating a Donations Button

How You Get Your Money

Notifications You Receive

Email

History

Downloadable Logs

Instant Payment Notification (IPN)

Creating Shopping Cart Buttons

How It Works

What Your Customer Sees

PayPal Shopping Cart Button Factory

What You See

Getting Started

Creating Your Shopping Cart Button

How You Get Your Money

Notifications You Receive

Email

History

Downloadable Logs

Instant Payment Notification (IPN)

Passing the Aggregate Shopping Cart Amount to PayPal

Passing Individual Items to PayPal

Custom Payment Pages

Examples of Custom Payment Pages

Getting Started

Adding a Page Style

Editing a Page Style

Previewing a Page Style

Making a Page Style Primary

Removing a Page Style

Overriding Page Style Settings

Background Colors and Error Messages

Getting Started

Sales or Value Added Tax Collection

Overriding Tax Setting Per Transaction

Shipping Calculation

Flat Amount

Percentage

Overriding Your Shipping Calculation

How It Works