PP WebsitePaymentsStandard IntegrationGuide

Website Payments
Standard Integration
Guide
For Professional Use Only

Currently only available in English.
A usage Professional Uniquement

Disponible en Anglais uniquement pour l’instant.
Last updated: March 2008

PayPal Website Payments Standard Integration Guide
Document Number: 100000.en_US-200803
© 2008 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
PayPal Europe S.à.r.l. & Cie, S.C.A. is authorized and regulated by the Commission de Surveillance du Secteur Financier in Luxembourg as a bank.
PayPal RCS registration number: 118349
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 1 How Integration Using Website Payments Standard Works . 13

The Basic Page Sequence for Website Payments Standard . . . . . . . . . . . . . . . . 14
Begin: Buyer is Ready to Purchase . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1: Buyer Logs In to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2: Buyer Reviews Payment Details . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3: Buyer Views PayPal Payment Confirmation . . . . . . . . . . . . . . . . . . . . . 17
End: Buyer Returns to Merchant Website . . . . . . . . . . . . . . . . . . . . . . . . 18
How You Get Your Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Notifications You Receive About Payments . . . . . . . . . . . . . . . . . . . . . . . . . 19
Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Transaction History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Downloadable History Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Instant Payment Notification (IPN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Other Integration Features Used with Website Payments Standard . . . . . . . . . . . . . 21
Chapter 2 Using Your PayPal Account Profile . . . . . . . . . . . . . 23

The Account Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Account Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Financial Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Selling Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Correspondence Between Profile Settings and HTML Variables . . . . . . . . . . . . 24
Branding the PayPal Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Working with Custom Payment Pages. . . . . . . . . . . . . . . . . . . . . . . . . . 27
Adding or Editing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Making a Page Style Primary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Overriding Page Styles On Individual Transactions . . . . . . . . . . . . . . . . . . . 29
Tailoring the Payment Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
PayPal Account Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Website Payments Standard Integration Guide March 2008 3

Contents
Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Getting Contact Telephone Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Automatic Calculation of Sales Tax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Setting Up Domestic Sales Tax Rates . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Setting Up International Sales Tax Rates . . . . . . . . . . . . . . . . . . . . . . . . 45
Resolving Overlapping Sales Tax Rates. . . . . . . . . . . . . . . . . . . . . . . . . 45
Overriding Sales Tax Calculations on Individual Transactions . . . . . . . . . . . . . 46
Editing or Deleting Sales Tax Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Automatic Calculation of Shipping Charges (U.S. Merchants Only) . . . . . . . . . . . . 46
Shipping Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Shipping Rate Bases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Shipping Rate Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Shipping Rates and Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Adding Shipping Rates for the First Time . . . . . . . . . . . . . . . . . . . . . . . . 49
Adding One or More Shipping Methods for a Shipping Region Using a Wizard. . . . . 49
Viewing, Editing, and Adding Shipping Rates . . . . . . . . . . . . . . . . . . . . . . 51
Viewing the Configuration of an Existing Shipping Method . . . . . . . . . . . . . . . 53
Editing the Configuration Settings of an Existing Shipping Method . . . . . . . . . . . 53
Deleting One or More Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . 54
Examples of Rate Bases and Shipping Calculations . . . . . . . . . . . . . . . . . . 55
Overriding Shipping Calculations on Individual Transactions . . . . . . . . . . . . . . 56
Automatic Calculation of Shipping Charges (non-U.S. Merchants Only) . . . . . . . . . . 57
Examples of Cost Methods and Shipping Calculations . . . . . . . . . . . . . . . . . 59
Overriding Shipping Calculation on Individual Transactions . . . . . . . . . . . . . . . 60
Blocking Certain Kinds of Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Accessing Your Payment Receiving Preferences to Block Payments . . . . . . . . . . 61
Blocking Payments from U.S. Payers without a Confirmed Address . . . . . . . . . . 62
Blocking Payments in Currencies that You Do Not Hold. . . . . . . . . . . . . . . . . 63
Blocking Payments from Payers with Non-U.S. PayPal Accounts. . . . . . . . . . . . 63
Blocking Payments Initiated through the Pay Anyone Subtab. . . . . . . . . . . . . . 63
Blocking Payments by Credit Card Instead of Bank Account . . . . . . . . . . . . . . 64
Blocking Payments Funded with eChecks . . . . . . . . . . . . . . . . . . . . . . . 64
Adding Your Credit Card Statement Name. . . . . . . . . . . . . . . . . . . . . . . . . . 64
Language Encoding Your Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
About Language Encoding for Exchanging Data with PayPal . . . . . . . . . . . . . . 66
Changing Your Default Language Encoding . . . . . . . . . . . . . . . . . . . . . . . 66
Allowing Multiple Users to Access Your PayPal Account . . . . . . . . . . . . . . . . . . 69
Adding a User Login to Your Account . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Changing the Privileges for a User Login . . . . . . . . . . . . . . . . . . . . . . . . 70
4 March 2008 Website Payments Standard Integration Guide

Contents
Resetting the Password for a User Login . . . . . . . . . . . . . . . . . . . . . . . . 71

Removing a User Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Handling Multiple Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Managing Currency Balances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Accepting or Denying Cross-Currency Payments . . . . . . . . . . . . . . . . . . . . 74
Chapter 3 Single-Item Payment: Buy Now Buttons . . . . . . . . . . . 75

Creating Buy Now Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Adding More Details to the Buy Now Button. . . . . . . . . . . . . . . . . . . . . . . 78
Copying and Pasting the Buy Now Code . . . . . . . . . . . . . . . . . . . . . . . . 81
Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . . 83
Sample HTML Code for a Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . 83
Sample URL Code for a Buy Now Email Payment Link . . . . . . . . . . . . . . . . . . . 85
Chapter 4 Multiple-Item Payment: Shopping Carts . . . . . . . . . . . 87

How the PayPal Shopping Cart Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
What The Shopper Sees with the PayPal Shopping Cart . . . . . . . . . . . . . . . . 87
Creating PayPal Shopping Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Adding More Details to the PayPal Shopping Cart Button. . . . . . . . . . . . . . . . 93
Copying and Pasting the PayPal Shopping Cart HTML Code . . . . . . . . . . . . . . 97
Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . . 98
Pricing Items in Multiple Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Sample HTML Code for an Add to Cart Button . . . . . . . . . . . . . . . . . . . . . . . 99
Sample HTML Code for a View Cart Button . . . . . . . . . . . . . . . . . . . . . . . . .100
How A Third Party Shopping Cart Works . . . . . . . . . . . . . . . . . . . . . . . . . .101
What The Shopper Sees with Third Party Shopping Carts . . . . . . . . . . . . . . .102
What Merchants See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Integrating Third Party Shopping Carts with PayPal . . . . . . . . . . . . . . . . . . . . .108
Required Third Party Shopping Cart Variables . . . . . . . . . . . . . . . . . . . . .108
Passing Individual Item Details to PayPal . . . . . . . . . . . . . . . . . . . . . . . .108
Setting the Tax for the Entire Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Setting the Shipping Charge for the Entire Cart . . . . . . . . . . . . . . . . . . . . . 110
Passing the Aggregate Shopping Cart Amount to PayPal. . . . . . . . . . . . . . . . 110
Securing Your Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 5 Contribution Payment: Donation Buttons . . . . . . . . . 111

The Page Sequence for Donation Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . 111

Contents
Begin: Donor is Ready to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . 111

1: Donor Logs In to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
2: Donor Reviews Contribution Details . . . . . . . . . . . . . . . . . . . . . . . . . 114
3: Donor Views PayPal Payment Confirmation . . . . . . . . . . . . . . . . . . . . . 115
END: Donor Prints PayPal Contribution Receipt . . . . . . . . . . . . . . . . . . . . 116
Alternative ENDs: Returning Donors to Your Website . . . . . . . . . . . . . . . . . . 117
How You Get Your Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Notifications You Receive About Contribution Payments . . . . . . . . . . . . . . . . . . 118
Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Transaction History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Downloadable History Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Instant Payment Notification (IPN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Creating Donation Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Adding More Details to the Donation Button. . . . . . . . . . . . . . . . . . . . . . .121
Copying and Pasting the Donation Code . . . . . . . . . . . . . . . . . . . . . . . .124
Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . .125
Sample HTML Code for a Donation Button . . . . . . . . . . . . . . . . . . . . . . . . .126
Sample URL Code for a Donation Email Payment Link . . . . . . . . . . . . . . . . . . .127
Chapter 6 Using Authorization & Capture . . . . . . . . . . . . . . 129

Basic Authorization Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Honor Period and Authorization Period . . . . . . . . . . . . . . . . . . . . . . . . .129
Basic Authorization & Capture Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . .130
Capturing A Single Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Batch Capturing Multiple Authorizations . . . . . . . . . . . . . . . . . . . . . . . . .131
Voiding an Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Capture Within 3 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Capture From 4 - 29 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
One Authorization, Multiple Captures, and a Refund . . . . . . . . . . . . . . . . . .134
Lower Capture Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Capture Up to 115% . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Authorization Expires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Reattempted Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Recommendations for Best Use of Authorization & Capture . . . . . . . . . . . . . . . .140
Capturing Funds on Basic Authorizations . . . . . . . . . . . . . . . . . . . . . . . .140
Buyer Approval for Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . .140
Voiding Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Contents
Chapter 7 Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . 141

Refunding Within 60 Days of Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Refunding After 60 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Chapter 8 Securing Your Website Payments Standard Buttons . . . 143

Creating an Encrypted Button on the PayPal Website . . . . . . . . . . . . . . . . . . . .144
Verifying Each Payment Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Verifying Payments with Instant Payment Notification (IPN) . . . . . . . . . . . . . . . . .145
Encrypting Buttons Dynamically With Encrypted Website Payments (EWP) . . . . . . . .145
Prerequisites to Using EWP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Public Key Encryption Background . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Setting Up The Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Encrypting Your HTML Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Blocking Non-encrypted Website Payments . . . . . . . . . . . . . . . . . . . . . . . . .150
Chapter 9 Testing in the PayPal Sandbox . . . . . . . . . . . . . . 151
Chapter 10 HTML Form Basics for Website Payments Standard . . . 153

Form Attributes: ACTION and METHOD. . . . . . . . . . . . . . . . . . . . . . . . . . .153
Hidden Input Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Specifying the Website Payments Standard Product: cmd. . . . . . . . . . . . . . . . . .154
Variations on Basic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Prompting for Quantity in Buy Now Buttons: undefined_quantity . . . . . . . . . . . .154
Record Keeping with Passthrough Variables . . . . . . . . . . . . . . . . . . . . . .155
Setting the Character Set: charset. . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Setting The Return URL on Individual Transactions . . . . . . . . . . . . . . . . . . .155
Desired Currency on Individual Transactions . . . . . . . . . . . . . . . . . . . . . .156
Prepopulating FORMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Sample HTML for FORM Prepopulation . . . . . . . . . . . . . . . . . . . . . . . . .156
Overriding Addresses Stored with PayPal . . . . . . . . . . . . . . . . . . . . . . . . . .157
Sample HTML for Overriding Addresses Stored with PayPal . . . . . . . . . . . . . .157
Instant Payment Notification: notify_url . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Appendix A HTML Variables for Website Payments Standard . . . . . 161

Technical HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
HTML Variables for Individual Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162

Contents
HTML Variables for Payment Transactions . . . . . . . . . . . . . . . . . . . . . . . . .164

HTML Variables for Shopping Carts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
HTML Variables for Displaying PayPal Payment Pages . . . . . . . . . . . . . . . . . . .169
HTML Variables for Prepopulating PayPal Payment Pages . . . . . . . . . . . . . . . . .171
Appendix B Address Handling (U.S. Merchants Only) . . . . . . . . . 173

Address Handling in the Website Payments Standard Basic Page Sequence. . . . . . . .174
Endpoint A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Endpoints B, C, and D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Endpoint E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Endpoints F and H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Endpoints G and K. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Endpoint I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Endpoints J and L . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Address Handling in the PayPal Account Optional Page Sequence. . . . . . . . . . . . .176
Endpoint A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Endpoints B, C, and D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Endpoint E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Endpoints F and H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Endpoint G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Endpoint I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Endpoints J and L . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Endpoint K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . 179
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

P Preface
The Website Payments Standard Integration Guide describes how to integrate your website
with PayPal by using HTML buttons and forms. Website Payments Standard lets you accept
payments for:
z Single-item purchases with Buy Now buttons, which are suitable for items on websites that
offer single or mutually exclusive products.
z Multiple-item purchases with Add to Cart and View Cart buttons, which are suitable for
online stores with catalogs and shopping carts.
z Contribution payments with Donation buttons, which are suitable for giving financial
support to any cause.
Intended Audience
This manual is intended for:
z Website operators and developers who want to understand the payment page sequence that
people go through when they make payments with Website Payments Standard buttons
z Website operators and developers who want to understand how account profile settings
affect the way that Website Payments Standard works
z Developers who want to learn the technical details of implementing Website Payments
Standard
How to Use This Guide

The following table summarizes the contents of this guide.
TABLE P.1 How to Use This Guide
Feature Description See Also...

Basic Payment Page The basic sequence of PayPal payment pages that Chapter 1, “How Integration
Sequence people experience when they pay you with Website Using Website Payments
Payments Standard Standard Works”
Buy Now Paying for single items from your website Chapter 3, “Single-Item
Payment: Buy Now Buttons”
Shopping Carts Paying for multiple items from your website Chapter 4, “Multiple-Item
Payment: Shopping Carts”

Preface
P
How to Use This Guide
TABLE P.1 How to Use This Guide
Feature Description See Also...

Donations Accepting donations and contributions Chapter 5, “Contribution
Payment: Donation Buttons”
Authorization & Authorizing a payment and capturing payment Chapter 6, “Using
Capture amounts later on the PayPal website Authorization & Capture”
Refunds Refunding entire purchase payments or portions of Chapter 7, “Issuing Refunds”
them
Encrypted Website Payment buttons that you write or generate yourself “Encrypting Buttons
Payments and encrypt to protect against sending fraudulent Dynamically With Encrypted
payment information to PayPal Website Payments (EWP)” on
page 145
Custom Payment Pages Account profile settings that let you brand the “Branding the PayPal
PayPal payment pages with your own logo and Payment Pages” on page 25
colors.
PayPal Account An account profile setting that lets people pay by “PayPal Account Optional”
Optional credit card without having a PayPal account on page 30
Auto Return Account profile settings that redirects people to “Auto Return” on page 38
your website automatically after paying
Automatic Calculation Account profile settings that let you specify tax “Automatic Calculation of
of Sales Tax rates to let PayPal calculate taxes automatically Sales Tax” on page 42
Automatic Calculation Account profile settings that let you specify “Automatic Calculation of
of Shipping Charges shipping rates to let PayPal calculate shipping Shipping Charges (U.S.
charges automatically Merchants Only)” on page 46
or
“Automatic Calculation of
Shipping Charges (non-U.S.
Merchants Only)” on page 57
Payer Contact Account profile setting that prompts payers for “Getting Contact Telephone
Telephone their contact telephone numbers Numbers” on page 41
Multi-User Access Account profile settings that allow you to add “Allowing Multiple Users to
separate user logins to your PayPal Business Access Your PayPal Account”
account on page 69
N O T E : This feature is only available for merchants
who have PayPal Business accounts.

Preface
P
Revision History
Revision History
Revision history for PayPal Website Payments Standard Integration Guide.
TABLE P.2 Revision History
Date Description
March 2008 Changes to definition of authorization honor perioids; see “Honor Period and
Authorization Period” on page 129.”
January 2008 Separate page sequence and command for Donation buttons; see Chapter 5,
“Contribution Payment: Donation Buttons.”
August 2007 Shipping calculations with tiered rates in different destination regions; see
“Automatic Calculation of Shipping Charges (U.S. Merchants Only)” on
page 46.
May 2007 Added information on securing buttons.
April 2007 Updated screenshots and corresponding instructions.

Added Appendix B, “Address Handling (U.S. Merchants Only).”
October 2006 Minor clarifications.
August 2006 New PayPal Shopping Cart variable: shopping_url

The value _ext-enter of the cmd variable for FORM prepoulation is now no
longer necessary.
Clarification of values for the rm variable: 0, 1, or 2, not the strings "GET" or
"POST".
July 2006 New chapter on using Authorization & Capture with Website Payments
Standard, including capturing multiple authorizations in batches on
https://www.paypal.com/. Miscellaneous updates.
March 2006 Miscellaneous minor corrections.

Expanded description of creating Encrypted Website Payments buttons.

Preface
P
Revision History

1 How Integration Using Website
Payments Standard Works
Website Payments Standard uses HTML buttons and forms on your website to redirect people
to PayPal in order to pay you. People return to your website after they complete their
payments.
The basic page sequence for Website Payments Standard requires people to log in or sign up
for PayPal before they can complete their payments. Figure 1.1 , “Website Payments Standard
Basic Payment Page Sequence,” illustrates the basic page sequence that people experience
when they pay with Website Payments Standard.
FIGURE 1.1 Website Payments Standard Basic Payment Page Sequence
Website Payments Standard offers variations on the basic payment page sequence that is
shown above. The HTML variables and their values that you include with the payment buttons
that you place on your website, as well as the settings that you make in your PayPal account
profile, control which variations the people who pay you see.

How Integration Using Website Payments Standard Works
1
The Basic Page Sequence for Website Payments Standard
N O T E : The most common variation to the basic page sequence occurs when the PayPal
Account Optional profile setting is turned on. With the PayPal Account Optional page
sequence, people who are not currently PayPal members can pay by credit card without
first signing up for a PayPal account. For more information, see “PayPal Account
Optional” on page 30.

This section provides a visual example of the basic payment page sequence for payments
made with Website Payments Standard. In the example, Steve buys a photographic image from
a fictitious online store named DesignerFotos. Steve has a PayPal account before he buys.
N O T E : This
examples illustrates the use of Buy Now buttons, which are described more
completely in Chapter 3, “Single-Item Payment: Buy Now Buttons.”
Begin: Buyer is Ready to Purchase

The basic payment page sequence for Website Payments Standard begins when the buyer is
ready to make a purchase. In this example, Steve browses the catalog of images on the
DesignerFotos website. He finds the image he wants to buy and clicks the Buy Now button.
FIGURE 1.2 Basic Payment Page Sequence Begins on the Merchant Website
1: Buyer Logs In to PayPal

Steve’s browser redirects him to the PayPal website. Steve has an existing PayPal account, so
he enters his credentials and clicks the Log In button. Buyers without PayPal accounts
complete their payments by clicking the continue checkout link and following an alternative
page sequence.

1
FIGURE 1.3 Buyer Logs In to PayPal
When buyers visit a merchant website for the first time or if they disabled cookies in their
browsers, they may see the following alternative log-in page:

1
FIGURE 1.4 Buyer Creates a PayPal Account or Logs in
2: Buyer Reviews Payment Details

After logging in to PayPal, Steve sees the Review Your Payment page from PayPal. Steve can
select the funding source for the payment from his funding sources on file with PayPal.
Funding sources include bank accounts, credit cards, and debit cards. In addition, Steve can
select the shipping address from his addresses on file with PayPal.
After Steve is satisfied with the payment options and payment amount, he confirms the
payment by clicking the Pay $255.00 Now! button.

1
FIGURE 1.5 Buyer Reviews Payment Details
3: Buyer Views PayPal Payment Confirmation

After clicking the Pay Now! button, Steve sees a payment confirmation page from PayPal.
Steve can:
z View the PayPal confirmation number, which lets him track his payment within his
PayPal account.
z Click the View Printable Receipt link, which lets him print a receipt of his payment.
z Click the Return to DesignerFotos button, which returns him to the DesignerFotos
website and shop for more images.

1
FIGURE 1.6 Payment Confirmation Page on PayPal
End: Buyer Returns to Merchant Website

After reviewing the payment confirmation page, Steve returns to the DesignerFoto website by
clicking the Return to DesignerFotos button.
FIGURE 1.7 Buyer Returns to a Landing Page on the Merchant Website
The landing page that Steve returns to on the merchant website was specified with the return
variable of the Buy Now button that Steve clicked originally to begin the payment process.
The design of the merchant landing page is the responsibility of the merchant. Consider the
following when designing your own landing page:
z You must state clearly that the purchase made through PayPal was successful and that the
transaction has been completed.

1
How You Get Your Money
z You must tell the buyer that the payment and transaction details will arrive in an email sent
to the buyer.
z Offer the buyer a few products that might be of interest based on what the buyer just
purchased.
z If you enabled Auto Return, let buyers view and print a receipt. The alternative payment
confirmation page on the PayPal website disappears quickly and the page does not offer a
View Printable Receipt link.
For more information, see “Auto Return” on page 38.
z Provide a link or button that lets the buyer return to your product catalog and continue
shopping.
How You Get Your Money

After a buyer makes a payment, your PayPal account lists the payment in your Account
History, as shown below.
FIGURE 1.8 Account History: Recent Activity
Notifications You Receive About Payments

You can be notified of payments in four ways: email, transaction history, downloadable history
log, and Instant Payment Notification (IPN).
Email
You receive email notification when:
z a successful payment is made.

1
Notifications You Receive About Payments
z a payment is pending.
z a payment is canceled.
If you want to stop receiving email notification:
1. Click the Profile subtab of the My Account tab.
2. Under Account Information, click the Notifications link.
3. Under Payment Notifications, clear the I receive PayPal Website Payments and Instant
Purchase checkbox.
4. Click the Save button.
Transaction History
You transaction history is available from the History page. It provides information about your
payments and other account activity. The status of a payment can be:
z Completed: The transaction was successful and the money was credited to your account
z Cleared: The payment cleared the sender’s account and was credited to your account
z Uncleared: The payment has not cleared the sender’s account yet
To learn how to work with your transaction history, see the Order Management Integration
Guide.
Downloadable History Log

You can download copies of your transaction history to your computer. You can specify a date
range for the transactions and the file format of the downloadable history log.
To learn how to work with downloadable history logs, see the Order Management Integration
Guide.
Instant Payment Notification (IPN)

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

1
Other Integration Features Used with Website Payments Standard
Other Integration Features Used with Website Payments

Standard
Website Payments Standard works with other integration features not described in this guide:
z Instant Payment Notification (IPN) and Payment Data Transfer (PDT) are HTML
mechanisms that send information about payments to programs that run on your website.
IPN and PDT are described in the Order Management Integration Guide.
z Subscriptions and recurring payments, which are described in the Subscriptions and
Recurring Payments Guide
z Gift certificates that are redeemable for purchases made from your website. Gift
Certificates are described in the Gift Certificates Guide.

1
Other Integration Features Used with Website Payments Standard

2 Using Your PayPal Account
Profile
This chapter describes how to use your PayPal account profile settings to control how
Website Payments Standard works for people who pay you and how it works to let you accept
the payments that they make.
The Account Profile

Use your PayPal account profile to manage your PayPal account.
To view your account profile:
1. Log in to your PayPal account at https://www.paypal.com.
The My Account Overview page appears.
2. Click the Profile subtab.
The Profile Summary page appears.
Your account profile has three sections:
– Account Information
– Financial Information
– Selling Preferences
The following topics describes the use of each section in more detail.
Account Information
Use the Account Information column for basic account maintenance, including updating
your password, adding and confirming email addresses, managing your business information,
and for business accounts, configuring PayPal account for multi-user.
Financial Information
Use the Financial Information column to organize and maintain the financial instruments
associated with your PayPal account, including managing your credit cards and bank accounts,
activating and managing your PayPal Debit Card, managing multiple currency balances, and
viewing monthly account statements.

Using Your PayPal Account Profile
2
The Account Profile
Selling Preferences
Use the Selling Preferences column to configure the way you collect payments with PayPal,
including:
z Branding the PayPal payment pages with your logo and colors
z Tailoring the Website Payments Standard payment experience with:
– Auto Return
– PayPal Account Optional
– Getting contact telephone numbers from payers
z Setting sales tax rates to calculate sales taxes automatically
z Setting shipping rates to calculate shipping charges automatically
z Blocking certain kinds of payments
z Setting the language and character encoding of your data
FIGURE 2.1 Selling Preferences on the Profile Summary Page
Correspondence Between Profile Settings and HTML Variables

Many of the selling preferences that you can set in your account profile have equivalent
HTML variables that let you control the behavior of individual transactions. After you enable
settings in your account profile, you can include HTML variables with a transaction that take
advantage of those settings.

2
Branding the PayPal Payment Pages
See the following sections for more information:

z “Overriding Page Styles On Individual Transactions” on page 29
z “Overriding Sales Tax Calculations on Individual Transactions” on page 46
z “Overriding Shipping Calculations on Individual Transactions” on page 56
z “Setting the Character Set: charset” on page 155
z “Setting The Return URL on Individual Transactions” on page 155
z “Desired Currency on Individual Transactions” on page 156

Custom payment pages let you tailor the PayPal payment pages presented to payers to match
the style of your website. Custom payment pages work with all Website Payments Standard
buttons and with the PayPal Account Optional account profile setting turned on or off.
You can add up to three custom page styles.
The pictures in this section demonstrate the types of branding you can achieve with custom
payment pages. Figure 2.2 , “Default PayPal Payment Page Style,” shows a payment page
with no custom merchant branding.

2
FIGURE 2.2 Default PayPal Payment Page Style
Figure 2.3 , “Custom Page Style with All Branding Options,” shows all the options that you
can specify for your own, custom payment page styles.

2
FIGURE 2.3 Custom Page Style with All Branding Options
Working with Custom Payment Pages

To configure your custom payment pages:
3. In the Selling Preferences column, click the Custom Payment Pages link.
The Custom Payment Page Styles page appears, as shown below.

2
FIGURE 2.4 Custom Payment Page Styles
From this page, you can add, edit, preview, and remove page styles, and make one of the page
styles the primary page style.
N O T E : The PayPal page style is a default page style. You cannot edit or remove it.
Adding or Editing a Page Style

The settings described here can also be specified with HTML variables for individual
transactions. For more information, see “HTML Variables for Displaying PayPal Payment
Pages” on page 169.
To add a page style:
1. Begin at the Custom Payment Page Styles page.
2. Click the Add button or the Edit button.
Enter your custom page style preferences:
– Page Style Name (required)
Enter a name up to 30 characters long. The name can contain letters, numbers, and
underscores but no other symbols or spaces. The Page Style Name is used to refer to the
page style in your PayPal account and in the page_style HTML variable for your
Website Payment buttons.
– Header Image URL (optional)
Enter the URL for an image that should appear at the top left of the payment page.
Maximum size of the image is 750 pixels wide by 90 pixels high; larger images are
reduced to this size. The image must be in a valid graphics format such as gif, jpg, or
png.

2
IMPO RTANT: PayPal recommends that you enter an image URL only if the image is
stored on a secure (https) server. Otherwise, your payer’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, the header is a 750 pixel wide by 90 pixel high space at the top of the payment
page. If the Header Image URL is not present, the header height is only 45 pixels high.
– Header Border Color (optional)
Enter the border color for the header using HTML hex code. The color code must be six
digits long and should not contain the # symbol. The header border is a two-pixel
perimeter around the header space.
– 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.
3. Click the Preview button to view a mock-up of your page style, or click the Save button to
save it.
Making a Page Style Primary

When you make a page style primary, it is applied to all payment pages unless you specify
otherwise on individual transactions.
N O T E : If you do not designate a 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.
2. Click the radio button next to the page style you that want to make your primary style.
3. Click the Make Primary button.
The Make Custom Page Style Primary page appears.
4. Click the Make Primary button to confirm your choice.
Overriding Page Styles On Individual Transactions

Your primary page style is applied to all payment pages unless you specify otherwise. You can
override this behavior by specifying custom page style variables on individual transactions.
To change the page style for a button you already created, replace the value of the
page_style variable with the page style name you want to use. The next time that someone
clicks the button, the subsequent payment pages appear in the new style.

2
Tailoring the Payment Experience
When you specify custom payment page variables on individual transactions, the page
variables override page styles set in your account profile or the page_style variable. The
custom payment page variables take precedence in the following order:
TABLE 2.1 Order of Page Style Variables
Custom Option Description
1 Custom Payment Page See Table A.7, “HTML Variables for Displaying PayPal Payment
Variables on Individual Pages,” on page 169.
Transactions
2 Primary Page Style on With the page_style variable, you can specify a page style on
Individual Transactions individual transactions that overrides any page styles set in your
account profile.
3 Primary Page Style in You can create and set the primary style in your account profile.
Profile
4 Default PayPal Page The default page style used when an alternative is not selected
Style in Profile and designated as primary.

The following account profile settings let you tailor the payment experience for people who
pay with Website Payments Standard:
z PayPal Account Optional
z Auto Return
z Getting Contact Telephone Numbers
PayPal Account Optional

With PayPal Account Optional turned on, people who are not currently PayPal members can
pay by credit card without first signing up for a PayPal account. After making the payment,
payers can sign up with PayPal using the address and credit card that was used for the
completed transaction.
Figure 2.5 , “Page Sequence with PayPal Account Optional” illustrates the sequence of pages
that people experience when they pay by credit card without first signing up with PayPal.

2
FIGURE 2.5 Page Sequence with PayPal Account Optional
Compare the preceding page sequence with the basic page sequence shown in Figure 1.1 ,
“Website Payments Standard Basic Payment Page Sequence” on page 13.
What Payers See With Account Optional On
Step 1: Bob goes to the DesignerFotos website, makes his selections, and clicks the Add to
Cart button.

2
Step 2: Since Bob is new to PayPal, he is taken to a billing information page. If he had a
PayPal account, he could log in here to access his saved information. He is not a PayPal
member, so he enters in his information and clicks the Review Payment button.

2
N O T E : IfPayment Receiving Preferences are set to accept payments from payers only with
confirmed addresses, Bob skips the shipping information page and goes directly to
billing information in Step 3.
Step 3: Bob is taken to a review page. He clicks the Pay $505.00 Now! button to complete his
purchase.

2
Step 4: Bob is taken to a payment completion page and will receive an email receipt.

2
Because Bob is not a PayPal member, he can choose to sign up for a PayPal account on this
page by entering his email address, selecting a password, and clicking the Create Account
button.
Step 5: Bob sees a page that confirms the creation of his account.

2
If he clicks the Return to Merchant button, his browser is redirected back to the merchant’s
website.
Step 6: Bob receives an email receipt that confirms his payment and includes a copy of the
payment details for this transaction.

2
Turning PayPal Account Optional Off

PayPal Account Optional is on by default.
To turn PayPal Account Optional off:
3. Click the Website Payment Preferences link in the Selling Preferences column.
The Website Payment Preferences page appears.
4. Scroll down to the PayPal Account Optional section of the page.

2
5. Select the Off radio button to turn PayPal Account optional off.
6. Scroll to the bottom of the page, and click the Save button.
Auto Return
With Auto Return for Website Payments, you can avoid making your payers click an extra
button before returning to your website after they complete their payments. Auto Return
applies to all Website Payments, including Buy Now, Shopping Cart, Subscription, Gift
Certificate, and Donation buttons.
What Payers See with Auto Return On
With Auto Return on, instead of having to click a button on the payment receipt page
(identified in Figure 1.1 with a circled “3” and shown in Figure 1.6 ), payers see an alternative
payment confirmation page for a few seconds before their browsers redirect them
automatically to your website.

2
FIGURE 2.6 Momentary Payment Confirmation with Auto Return On
Turning On Auto Return

Auto Return is turned off by default.
To turn on Auto Return:
3. Under the Selling Preferences column, click the Website Payment Preferences link.
The Website Payment Preferences page appears, as shown below.

2
4. Under Auto Return for Website Payments, click the On radio button to enable Auto
Return.
5. In the Return URL field, enter the URL to which you want your payers redirected after
they complete their payments.
N O T E : If the Return URL you enter is invalid, PayPal displays the standard payment
confirmation page after people complete their payments.
Setting Return URL on Individual Transactions
With Auto Return turned on in your account profile, you can set the value of the return
HTML variable on individual transactions, which overrides the value of the return UL that you
stored on PayPal as part of the Auto Return feature. For example, you might want to redirect
payers to a URL on your site that is specific to that person, perhaps with a session-id or other
transaction-related data included in the URL.
To set the return URL for individual transactions, include the return variable in the HTML
Form:
<INPUT TYPE=”hidden” NAME=”return” value=”URLspecificToThisTransaction”>
N O T E : To
receive transaction-related data from PayPal, you must turn PDT on. For more
information on PDT, see the Order Management Integration Guide.
Subscriptions Password Management and Auto Return
If you use or plan to use Subscriptions Password Management, you must make sure that Auto
Return is turned off in order to display the PayPal-generated username and password to the
subscriber.
N O T E : Youcan use Auto Return with Subscriptions, which is a separate feature from
Subscription Password Management. For more information about Subscriptions, see
the Subscriptions and Recurring Payments Guide.

2
Getting Contact Telephone Numbers

“Contact Information Telephone” is an option that lets you collect a contact telephone number
for from people who pay you. When you activate this option, payers are prompted to include a
contact telephone number with their payment information.
IMPO RTANT: In accordance with the PayPal user agreement, you may use this contact
telephone number only to communicate with the payer about the related
payment. You may not use this number for unsolicited messages.
You can make the contact telephone number optional or required, or you can turn it off. “Off”
is the recommended default option because people value their privacy and prefer to minimize
unsolicited communications.
When you require payers’ contact telephone numbers, payers see the prompt during purchase.
FIGURE 2.7 Prompt for A Contact Telephone Number
Activating Contact Telephone Number

Follow these steps to activate the Contact Telephone Number option:
3. In the Selling Preferences column, click the Website Payment Preferences link.
4. Scroll down the page to the Contact Telephone Number section.
5. Select one of the following options:
– On (Optional Field): prompts payers to enter telephone numbers as an option.
– On (Required Field): requires payers to enter telephone numbers
– Off (Recommended): does not prompt payers to enter telephone numbers
6. Scroll to the bottom of the page and click the Save button.

2
Automatic Calculation of Sales Tax

You can set up your PayPal account to automatically calculate and charge sales tax (also called
value-added tax or VAT). You can create sales tax rates for domestic (U.S.-only) and
international buyers as follows:
z Domestic sales tax rates
can be for an individual state, a specific zip code, or for a range of zip codes.
z Sales tax rates for Canada can be for an individual province or for all provinces.
z Other international sales tax rates are for the entire county specified.
To view or modify your sales tax rates:
3. In the Selling Preferences column, click the Sales Tax link.

2
FIGURE 2.8 Sales Tax Rates Setup
Setting Up Domestic Sales Tax Rates

You can create sales tax rates for a state, zip code, or zip code range. To add a new rate, click
the Add New Sales Tax link in the Set Up Domestic Tax Rates box.
To create a rate for a state
1. Click State for Configure Sales Tax by.

2. Select one or more states for the rate you want to create. Hold down the Ctrl key to select
more than one state.
3. Enter the sales tax rate.
4. Click the checkbox labeled Apply rate to shipping amount, if applicable.
5. Click the Continue button to add the new rate and return to the Sales Tax page
(Figure 2.8 ).

2
6. Click the Create Another button to add the new rate and then add another domestic sales
tax rate.
To create a rate for a specific zip code
1. Click Zip Code for Configure Sales Tax by.
FIGURE 2.9 Setting Up a Domestic Sales Tax Rate by Zip Code
2. Click the Specific radio button.

3. Enter the zip code for the rate you want to create.
6. Click the Continue button to add the new rate and return to the Sales Tax page.
tax rate.
To create a rate for a zip code range
1. Click Zip Code for Configure Sales Tax by.

2. Click the Range radio button.
3. Enter the starting and ending zip code for the rate you want to create.
4. Enter a the sales tax rate.

2
6. Click the Continue button to add the new rate and return to the Sales Tax page.
tax rate.
Setting Up International Sales Tax Rates

You can create the following types of international sales tax rates:
z For Canada, sales tax rates can be for one or more provinces.
z For countries other than the U.S. and Canada, sales tax rates apply to the entire country.
To add a new rate, click Add New Sales Tax in the Set Up International Tax Rates box.
1. Select the country for the rate you want to create.
2. If you selected Canada for Country, select one or more provinces or select All Provinces.
Hold down the Ctrl key to select more than one province.
5. Click the Continue button to add the new rate and return to the Sales Tax page
(Figure 2.8 ).
6. Click the Create Another button to add the new rate and then add another international
sales tax rate.
Resolving Overlapping Sales Tax Rates

It is possible that more than one sales tax rate will apply to a buyer. For example, in
Figure 2.10 , all three of the domestic sales tax rates apply to a buyer in zip code 94044.

2
Automatic Calculation of Shipping Charges (U.S. Merchants Only)
FIGURE 2.10 Three Domestic Sales Tax Rates
When multiple rates apply, the most specific rate is used. For a buyer in zip code 94044, the
most specific rate is the single zip code rate of 8.25%. For a buyer in zip code 94056, the most
specific rate is the range of zip codes with a rate of 7.75%.
Overriding Sales Tax Calculations on Individual Transactions

Regardless of a buyer’s location, you can override automatic tax calculation on an individual
transaction or on individual items in a transaction. For more information, see “Setting Tax on
Individual Items” on page 109 and “Setting the Tax for the Entire Cart” on page 110.
Editing or Deleting Sales Tax Rates

To edit a sales tax rate, click the checkbox to the left of the rate and then click the Edit button.
To delete a sales tax rate, click the checkbox to the left of the rate and then click the Delete
button.
Automatic Calculation of Shipping Charges (U.S. Merchants

Only)
You can set up your PayPal account to calculate shipping charges automatically. Shipping
charges are calculated based on the shipping rates you specify in the Selling Preferences of
your account profile. You can set up different shipping rates for U.S. domestic and
international shipments, different rates for different domestic and international shipping
regions, and different rates for different levels of shipping service.
Shipping Regions
Your organize your shipping rates primarily by the states and countries to which you ship your
products. Some merchants make only domestic shipments. Other merchants make both
domestic shipments and international shipments. Depending on territorial size, some

2
merchants divide their domestic markets into smaller shipping regions, each with their own
shipping rates.
Before you begin setting up the shipping rates that PayPal uses to calculate shipping charges,
decide whether:
z You ship only domestically or both domestically and internationally
z You want one set of rates for all U.S. domestic shipments or you want rates for different
domestic regions, such as Europe and Asia.
z You want one set of rates for all international shipments or you want rates for different
international regions
You can establish one set of shipping rates for all domestic and international destinations, but
your shipping rates should reflect your costs of shipping, which generally vary between
different domestic and international regions.
Shipping Methods
Within each shipping region that you define, you specify specific shipping rates for the
different shipping methods you want to offer buyers. A shipping method specifies a mode of
shipment and the general time frame for delivery. For example, you might offer your domestic
buyers two shipping methods: “Standard Shipping” and “Priority.”
For each region in which you offer a specified shipping method, you generally select different
delivery time frames and different rates. Otherwise, you should not set up separate shipping
regions.
For example, your “Standard Shipping” method for the region where your shipments originate
might specify a time frame of “2-3 Days.” A more distant domestic shipping region might
specify a time frame of “3-7 Days.” You set the same rates for “Standard Shipping” in all
regions, but delivery times are longer for more distant ones.
As an alternative to differentiating on delivery time, you might differentiate on rates. For
example, your “Standard Shipping” method for all domestic regions might specify the same
time frame of “2-3 Days.” You set more expensive rates for “Standard Shipping” in more
distant regions, but delivery times are the same for all regions.
Shipping Rate Bases

For each shipping method in each shipping region that you define, you specify the basis upon
which your shipping rates are used to calculate the shipping charges for specific purchases.
You can choose from the following shipping rate bases:
z Total order amount
z Total order weight
z Total item quantity
Generally, you specify the same shipping rate basis for all shipping regions and shipping
methods that you define. Before you begin setting up the shipping rates that PayPal uses to

2
calculate shipping charges, decide which basis is most suitable for the kinds of products you
sell and the typical orders that your buyers place.
For more information, see “Examples of Rate Bases and Shipping Calculations” on page 55
Shipping Rate Tables

For each shipping method you define, fill in a rate table to specify the rates that PayPal uses to
calculate shipping charges. Rate tables let you specify tiered rates.
FIGURE 2.11 Shipping Rate Table With a Basis of Total Order Amount
Each row in a rate table represents a different tier. Each successive tier encompasses a
successively increasing range within the rate basis. You specify a separate rate for each tier.
In the preceding example rate table, each successive tier encompasses an increasing range of
order amounts. The first tier encompasses orders that total from $0.01 USD through and
including $10.00 USD. The shipping rate for orders that fall within the first tier is 5% of the
total order amount. The shipping charge for an order amount of $6.75 USD is $0.34 USD.
Shipping Rates and Currencies

When you set up shipping methods, specify the same currency for the shipping rates that you
used to price the products on your website. Specify shipping rates for both domestic shipments
and international shipments in your domestic currency, provided that you priced your products
for international buyers in your domestic currency.
If you price your products in multiple currencies, you should specify international shipping
rates in the same currencies that you priced your products for international buyers. For
example, a merchant in London might price products in Pounds Sterling for British buyers,
while also pricing the same products in Euros for Euro-zone buyers and U.S. Dollars for U.S.
buyers.

2
Adding Shipping Rates for the First Time

The first time you set up shipping rates, the page sequence is tailored for creating your initial
shipping regions, methods, and rates.
To begin adding shipping regions, methods, and rates for the first time:
3. In the Selling Preferences column, click the Set Up Shipping Calculations link.
This Shipping Calculations page appears, as shown below.
FIGURE 2.12 Shipping Calculations Setup Page
From the Shipping Calculations setup page, you can start a domestic or an international
shipping wizard.
Adding One or More Shipping Methods for a Shipping Region Using a

Wizard
Whenever you add a shipping method, you use one of two wizards to step you through the
process. The domestic shipping wizard lets you configure shipping regions within the U.S.,
and the international shipping wizard lets configure foreign shipping regions. Shipping
wizards let you configure a shipping region and all the shipping methods for it at one time.
You can start a shipping wizard in one of two ways:
z Click the Start button from the Shipping Calculations setup page, as shown in
Figure 2.12 , “Shipping Calculations Setup Page.

2
z Click the Add Another Shipping Method link from the Shipping Calculations review
page, as shown in Figure 2.14 , “Shipping Calculations Review Page (U.S. Merchants
Only).
The steps in domestic and international shipping wizards are the same.
FIGURE 2.13 Page Sequence in a Shipping Wizard
1. Setting Up the Shipping Region for a Shipping Wizard. Select the U.S. states or the foreign
countries for the shipping region, and select the currency in which you want to price the
shipping rates for the shipping region.
2. Configuring the Shipping Methods Within the Region of a Shipping Wizard. Select a name
and delivery time frame, a rate basis, and fill in the rate table. Repeat this step to configure
all of the shipping methods you want for the shipping region.

2
3. Saving the Shipping Methods Configured With a Shipping Wizard. Review the shipping
region and the shipping methods, and change them if you like before you save them.
The following sections describe each step in more detail.
Setting Up the Shipping Region for a Shipping Wizard
The first step of a shipping wizard lets you select the U.S. states or foreign countries for one or
your shipping regions. In addition, you select the currency in which you want to price the
shipping rates within the region.
N O T E : Youcan select the currency at the time you add shipping methods and rates. You
cannot change the currency later when you edit shipping methods. For more
information, see “Shipping Rates and Currencies” on page 48.
After you select the U.S. states or foreign countries you want for the shipping region, click the
Continue button to proceed to the second step of the shipping wizard.
Configuring the Shipping Methods Within the Region of a Shipping Wizard
As the second step of a shipping wizard, you configure the shipping methods that you want for
the shipping region. A shipping wizard lets you configure the name, delivery time frame, rate
basis, and rate table of shipping methods.
Repeat the second step of a shipping wizard to create additional shipping methods for the same
shipping region. Click the Create Another button after completing the configuration of the
current method to begin the configuration of the next one.
After you configure all the shipping methods for the shipping region, click the Continue
button to proceed to the third and final step of the shipping wizard.
Saving the Shipping Methods Configured With a Shipping Wizard
As the final step of a shipping wizard, you review the configuration of the shipping region and
the configuration of the shipping methods for the shipping region. You can change the
shipping region, and you can change and add shipping methods.
In addition, the final step of a shipping wizard lets you enable individual purchase transactions
to override the rates for the shipping methods you defined within the shipping region. Select
the Override profile shipping method... checkbox to permit individual transactions to
override automatic calculation of shipping charges. For more information, see “Overriding
Shipping Calculations on Individual Transactions” on page 56.
After you review the shipping region and its shipping methods, click the Save Shipping
Methods button to preserve the shipping methods that you set up with the shipping wizard.
The shipping methods become available to buyers as soon as you save them.
Viewing, Editing, and Adding Shipping Rates

After you set up some shipping regions, methods, and rates, the page sequence is tailored for
viewing and editing existing shipping methods, as well as for creating additional regions,
methods, and rates.
To begin viewing, editing, or creating additional shipping regions, methods, and rates:

2

3. In the Selling Preferences column, click the Shipping Calculations link.
The Shipping Calculations review page appears, as shown below.
FIGURE 2.14 Shipping Calculations Review Page (U.S. Merchants Only)
4. From the Shipping Calculations review page, perform one of the following actions:
– Viewing the Configuration of an Existing Shipping Method. Select the checkbox next to
the shipping method and click the View button.

2
– Editing the Configuration Settings of an Existing Shipping Method. Select the checkbox
next to the shipping method and click the Edit button.
– Deleting One or More Shipping Methods. Select the checkboxes next to the shipping
methods and click the Delete button.
– Adding One or More Shipping Methods for a Shipping Region Using a Wizard. Click the
Add Another Shipping Method link.
Viewing the Configuration of an Existing Shipping Method

To view the configuration of a shipping method:
1. From the Shipping Calculations review page, select the checkbox next to the shipping
method you want to view.
2. Click the View button.
The View Domestic Shipping Method page or the View International Shipping Method
page appears.
3. From the review page, perform one of the following actions:
– To change the shipping method, click the Edit Settings button.
– When you are finished viewing the shipping method, click the Back to Shipping
Methods button.
Editing the Configuration Settings of an Existing Shipping Method

To edit the configuration settings of an existing shipping method:
1. From the Shipping Calculations review page, select the checkbox next to the shipping
method you want to change.
2. Click the Edit button.
The Edit Domestic Shipping Method page or the Edit International Shipping Method
page appears.
3. Change any of the following settings:
TABLE 2.2 Shipping Method Settings
Setting Action
Status Select whether the shipping method is actively used to calculate

shipping charges. Possible values are:
z Active: the shipping method is available for buyers to choose
z Inactive: the shipping method is hidden from buyers

2
Setting Action
Region Displays the domestic regions or foreign countries currently selected

for the shipping region. To select different regions or countries, click
the Change link.
Override shipping methods Select whether the shipping rates can be overridden by individual
per transaction transactions if the information is passed to PayPal with HTML
variables in the transaction. Possible values are:
z Yes
z No
I M P O R T A N T : Changing the Override shipping methods per

transaction.setting of a specific shipping method
changes the setting for all U.S. domestic and
international shipping methods that use the same
currency.
Shipping Method Name From the dropdown menu, select a name for the shipping method.
Delivery Time (Optional) From the dropdown menu, select a delivery time.
Based On Select the rate basis for the shipping method. Possible values are:
z By Amount: based on the total amount of the order
z By Weight: based on the total weight of items in the order
z By Quantity: based on total quantity of items in the order
For more information, see “Examples of Rate Bases and Shipping

Calculations” on page 55
Shipping Rates Reconfigure the rows in the rate table to change the shipping rates
that PayPal uses to calculate shipping charges when buyer select the
shipping method.
N O T E : Changes that you make to active shipping methods become
effective after a momentary delay.
4. Click the Save Changes button.
Deleting One or More Shipping Methods

You can delete one or more domestic or international shipping methods at one time. Follow
the procedure below in either the Domestic Shipping Methods section or the International
Shipping Methods section of the Shipping Calculations review page.
IMPO RTANT: After you delete a shipping method, it cannot be recovered for use in future
shipping calculations.
To delete one or more shipping methods:
1. From the Shipping Calculations review page, select the checkboxes next to the shipping
methods that you want to delete.

2
2. Click the Delete button.

3. Click the Yes button in the Delete Confirmation message box.
Examples of Rate Bases and Shipping Calculations

The following examples demonstrate how the different kinds of shipping rates are applied
when calculating shipping charges:
z Calculating Shipping Charges Based on Amount of Purchase
z Calculating Shipping Charges Based on Weight of Shipment
z Calculating Shipping Charges Based on Quantity of Items Shipped
Calculating Shipping Charges Based on Amount of Purchase
When you choose Total Order Amount or By Amount as the basis for shipping rates, tiers in
the rate table represent increasing ranges of order amounts. Generally, you select By Amount
as the rate basis if you want to encourage your buyers to buy more with increasing discounts
on shipping charges.
You can choose between specifying a flat rate for each tier or specifying a percentage of the
order amount. Click the Flat Rate or the Percent links in the Shipping Rate section to make
your choice.
EXAMPLE 2.1 Flat Rate Shipping Calculations

Assume the following shipping rate table with a basis of By Order and fixed amount pricing
selected:
From(EUR) To(EUR) Rate(EUR)
0.01 49.99 3.00
50.00 and up 2.00
The shipping charge for an order amount of €36.50 EUR is €3.00 EUR. The shipping charge
for an order amount of €66.50 EUR is €2.00 EUR This rate structure encourages buyers to
purchase more with discounted shipping on larger orders.
EXAMPLE 2.2 Percentage Rate Shipping Calculation

Assume the following shipping rate table with a basis of By Order and percentage rate pricing
selected:
From(JPY) To(JPY) Rate(%)
0.01 49.99 5
50.00 and up 4
The shipping charge for an order amount of ¥36.50 JYP is ¥1.38 JYP (36.50 x 5%). The
shipping charge for an order amount of ¥66.50 JYP is ¥2.66 JYP (66.50 x 4%).

2
Calculating Shipping Charges Based on Weight of Shipment

When you choose Total Order Weight or By Weight as the basis for shipping rates, tiers in
the rate table represent increasing ranges of order weights. Generally, you select By Weight as
the rate basis if you want to recover your shipping costs.
You can choose between specifying order weights in pounds or kilograms. Click the Lbs or
the Kgs links in the Shipping Rate section to make your choice.
EXAMPLE 2.3 Weight-Based Shipping Calculations

Assume the following shipping rate table with a basis of By Weight:
From(Kgs) To(Kgs) Rate(GBP)
0.01 49.99 3.00
50.00 and up 6.00
The shipping charge for an order that weights 36.50 kg is £3.00 GBP. The shipping charge for
an order that weights 66.50 kg is £6.00 GBP.
Calculating Shipping Charges Based on Quantity of Items Shipped
When you choose Total Order Quantity or By Quantity as the basis for shipping rates, tiers
in the rate table represent increasing ranges of order item counts. Generally, select By
Quantity as the rate basis if all your products have a generally uniform size and weight, such
as shoes.
EXAMPLE 2.4 Quantity-Based Shipping Calculations

Assume the following shipping rate table with a basis of By Quantity:
From To Rate(USD)
1 49 3.00
50 and up 6.00
The shipping charge for an order with 36 items is $3.00 USD. The shipping charge for an order
with 66 items is $6.00 USD.
Overriding Shipping Calculations on Individual Transactions

Sometimes you want to set special shipping rates for certain items, such as especially heavy
ones that cost more to ship, or services and digital downloads that do not require shipping.
Prerequisites for Overriding Shipping Rates on Individual Transactions
To override your profile-based shipping rates:
z Enable overrides of your shipping rates; overrides are enabled for new shipping methods
by default
z Set the special shipping rates for individual items or entire transactions with special HTML
variables of Buy Now, Donation, Add to Cart, and View Cart buttons
For more information, see “Setting Shipping Charges on Individual Items” on page 109
and “Setting the Tax for the Entire Cart” on page 110.

2
Automatic Calculation of Shipping Charges (non-U.S. Merchants Only)
Disabling the Override of Shipping Rates on Individual Transactions

By default, shipping methods enable the override of shipping rates on individual transactions.
You can disable overrides by:
z Editing any shipping method and changing the Override shipping methods per
transaction.setting.
z Adding a new shipping method and changing the default value of the Override shipping
methods per transaction setting
Regardless of how you disable overrides, the override setting you specify for a specific
shipping methods applies to the setting for all shipping methods of the same currency.
To enable or disable overrides of a shipping method:
1. From the Shipping Calculations review page, select the checkbox next to any of the
shipping methods for a specific currency.
2. Click the Edit button.
The Edit Domestic Shipping Method or the Edit International Shipping Method page
appears.
3. For the Override shipping methods per transaction.setting, select one of the following
radio buttons:
– Yes: enables transaction-specific shipping charges to override the shipping rates
– No: prohibits transaction-specific shipping charges
IMPO RTANT: Changing the Override shipping methods per transaction.setting of a

specific shipping method changes the setting for all U.S. domestic and
international shipping methods that use the same currency.
4. Click the Save Changes button.
Automatic Calculation of Shipping Charges (non-U.S.

Merchants Only)
You can set up shipping rates in your account profile and let PayPal calculate shipping charges
automatically.
To view or modify your shipping rates:

2

The Shipping Calculations page appears, as shown below.

2
FIGURE 2.15 Shipping Calculations Page (non-U.S. Merchants Only)
Examples of Cost Methods and Shipping Calculations

The following examples demonstrate how different cost methods are applied when calculating
shipping charges.

2
Calculating Shipping Charges with the Flat Amount Cost Method

When you choose Flat Amount as the cost method for shipping rates, costs for each price
range are expressed as fixed amounts.
EXAMPLE 2.1 Flat Amount Cost Method and Shipping Calculations

Assume the following shipping rates with a cost method of Flat Amount:
Cost Price Ranges
€3,00 EUR €0,00 EUR - €49,99 EUR
€6,00 EUR €50,00 EUR - and up
The shipping charge for an order price of €36,50 is €3,00. The shipping charge for an order
price of €66,50 is €6,00. This rate structure helps you recover your shipping costs from buyers.
Calculating Shipping Charges with the Percentage Cost Method
When you choose Percentage as the cost method for shipping rates, costs for each price range
are expressed as percentages of the actual order price.
EXAMPLE 2.2 Percentage Cost Method and Shipping Calculations

Assume the following shipping rates with a cost method of Percentage:
Cost Price Ranges
5.00 GBP % £0.00 GBP - £49.99 GBP
4.00 GBP % £50.00 GBP - and up
The shipping charge for an order price of £36.50 is £1.83. The shipping charge for an order
price of £66.50 is £2.66. This rate structure encourages buyers to purchase more with
discounted shipping rates on larger orders
Overriding Shipping Calculation on Individual Transactions

Sometimes you want to set special shipping rates for certain items, such as especially heavy
ones that cost more to ship, or services and digital downloads that do not require shipping.
Prerequisites for Overriding Shipping Rates on Individual Transactions
To override your profile-based shipping rates:
z Enable overrides of your shipping rates for individual transactions; overrides are disabled
by default.
z Set the special shipping rates for individual items or entire transactions with special HTML
variables of Buy Now, Donation, Add to Cart, and View Cart buttons
For more information, see “Setting Shipping Charges on Individual Items” on page 109
and “Setting the Tax for the Entire Cart” on page 110.
Enabling the Override of Shipping Rates on Individual Transactions
To enable overrides of shipping rates:

2
Blocking Certain Kinds of Payments

The Shipping Calculations page appears
4. Click the checkbox labelled Click here to allow transaction-based shipping values to
override the profile shipping settings listed above (if profile settings are enabled).

Payment receiving preferences let you block.
z Payments from U.S. payers without a confirmed address
z Payments in currencies you do not hold
z Payments from payers with non-U.S. accounts
z Payments initiated through the Pay Anyone Subtab
z Payments by credit card instead of a bank account
z Payments funded with eChecks
Accessing Your Payment Receiving Preferences to Block Payments

To access your Payment Receiving Preferences to block different types of payments:
3. In the Selling Preferences column, click the Payment Receiving Preferences link.
The Payment Receiving Preferences page appears, as shown below.

2
FIGURE 2.16 Payment Receiving Preferences Page
Blocking Payments from U.S. Payers without a Confirmed Address

You can better manage your risk by blocking payments where the payer chooses not to share
his Confirmed Address with you. PayPal provides Confirmed Addresses to help you make
informed decisions when shipping goods. To be eligible for PayPal's Seller Protection Policy
(SPP), and to help reduce your risk of dealing with fraudulent buyers, ship to a buyer’s
Confirmed Address.
There are three choices for this preference:
z Yes: All payments from U.S. payers without a Confirmed Address are blocked. All U.S.
payers must provide a Confirmed Address in order to pay you.
z No: All payments are accepted. To maximize your sales, select No.
z Ask Me: You can choose whether to accept or deny payment without a Confirmed Address
on a case-by-case basis. This option lets decide whether to take on the risk of not having
the payer’s Confirmed Address for each transaction. If you accept the payment, it becomes
a completed transaction. If you deny a particular payment, the sender of the payment is

2
notified that the payment has been denied and is credited with the payment amount. PayPal
does not charge fees for denied payments.
For a detailed description of how Confirmed Address and other settings affect the PayPal
billing and shipping addresses, see Appendix B, “Address Handling (U.S. Merchants Only).”
Blocking Payments in Currencies that You Do Not Hold

When you receive a payment in a currency you do not hold, PayPal prompts you to open a
balance for that currency, convert it to your primary balance, or deny the payment. Payments
in currencies for which you hold a balance are applied to the appropriate balance. You see a
summary of each currency balance in your Account Overview page.
There are three choices for this preference:
z Yes: Accept the payment regardless of the currency in which the payment is made.
z No, accept them and convert them to U.S. Dollars: Accept the payment but
automatically converts to U.S. Dollars.
z Ask Me: Transaction-by-transaction, you can choose to accept or deny a payment in a
currency you do not currently hold. If you accept the payment, it becomes a completed
transaction. If you deny a particular payment, the sender of the payment is notified that the
payment has been denied and is credited with the payment amount. PayPal does not charge
fees for denied payments.
For more informations, see “Managing Currency Balances” on page 73.
Blocking Payments from Payers with Non-U.S. PayPal Accounts

Because many international addresses cannot be confirmed, you may choose to block
payments from users with non-U.S. PayPal accounts in order to qualify for the Seller
Protection Policy.
Blocking Payments Initiated through the Pay Anyone Subtab

You can choose whether or not to receive payments initiated via the Pay Anyone subtab of the
Send Money tab on the PayPal website. Selecting this option might help you manage your
account, because the payments you receive will be associated with a specific item or
transaction that you defined.
If you block these payments, you accept only payments initiated from Buy Now, PayPal
Shopping Cart, Gift Certificate, Subscription, and Donation buttons, as well as Winning Buyer
Notification, Mass Payments, Money Requests, Smart Logos, or eBay Checkout Payments.

2
Adding Your Credit Card Statement Name
Blocking Payments by Credit Card Instead of Bank Account

You can force people to pay you with a bank account or funds in their PayPal balances if they
are able to do so. However, if they cannot pay using a bank account or their PayPal balances,
they still have the option to pay with a credit card.
This preference can also help to reduce your risk of chargebacks. Verified members are people
who have confirmed their bank accounts with PayPal or who have been otherwise verified by
PayPal. Because most Verified members have the option of paying with their bank accounts
(via eCheck or Instant Transfer), this preference does not prevent them from sending you
money. When they pay with PayPal’s Instant Transfer, you receive the payment instantly, just
as when they pay with a credit card. Members who have not confirmed their bank accounts
with PayPal can still send you money funded by credit cards.
Blocking Payments Funded with eChecks

You can block payments from PayPal members who pay with eChecks. Because eCheck
payments take three to four business days to clear, you might want to block them for your
Instant Purchase and Buy Now buttons.
If you choose to block these payments, users who attempt to pay via eCheck are prompted to
add a credit card to their account before completing the transaction.
If you choose not to block these payments, you can receive eCheck payments through PayPal
Website Payments or Auction Logos. eCheck payments are listed as Pending and are not
credited to your PayPal account for three to four business days.
Adding Your Credit Card Statement Name

When PayPal members pay with credit cards on file with their PayPal accounts, the
transactions appear on their credit card statements in the following format in the description:
PAYPAL*MERCHANT
By default, MERCHANT is:
z For premiere accounts, the mailbox name of the email addressed that you specified when
you signed up your account.
z For business accounts, the business name that you specified when you signed up for your
account.
The value you specified is converted to all upper-case letters, spaces are removed, the result is
truncated to eleven characters. The result is stored in your account profile as your Credit Card
Statement Name
The default value for your Credit Card Statement Name may be difficult for payers to
understand. To reduce chargebacks and payer confusion, replace the default Credit Card
Statement Name with one that accurately reflects your business or legal name.
To specify your Credit Card Statement Name:

2
Language Encoding Your Data

3. In the Selling Preferences column, click the Payment Receiving Preferences link.
The Payment Receiving Preferences page appears.
4. Scroll down the page to the Credit Card Statement Name section, as shown below.
FIGURE 2.17 Specifying Your Credit Card Statement Name
5. Change the following settings:
Setting Action
Credit Card Statement Enter up to 11 characters and spaces. Do not include special
Name characters, such as “&,” “#”, or “_”. The value is converted to all
capital letters and might be truncated by some credit card processors.
Extended Credit Card Enter up to 19 characters and spaces. Do not include special
Statement Name characters, such as “&,” “#”, or “_”.The value is converted to all
capital letters and might be truncated by some credit card processors.
6. Scroll to the bottom of the page and click the Save button.

Websites that use PayPal in different parts of the world work with different languages and
different character encoding schemes. PayPal refers collectively to these differences as
language encoding.You can set the default language encoding that your website uses to

2
exchange data with PayPal. The default settings are used for all transactions sent from your
website to PayPal and all automated notifications sent from PayPal to your website. You can
override the default settings on individual transactions with the charset HTML Form
variable.
For more information on overrides, see “Setting the Character Set: charset” on page 155.
About Language Encoding for Exchanging Data with PayPal

Computer systems represent human languages in terms of character sets and character
encoding.
Character Sets
A character set is a defined set of individual letters and symbols used in a particular language.
For instance, the ASCII character is commonly used to define the character in written
American English. The Big 5 character is commonly used to define the characters in written
Chinese.
Character Encoding
Character encoding is the way a computer system represents internally the letters and symbols
of a particular character set. Computers use internal representation to store, transmit, and
process data.
Different character encoding schemes define the number of bytes each character requires and
the pattern of on/off bits that identify a particular character. For example, single-byte encoding
schemes, such as ANSI and extended ASCII, allocate one byte for each character or symbol in
character set for Western European languages. Other encoding schemes, such as Unicode and
UTF-8, allocate several bytes for each character in their character sets.
Changing Your Default Language Encoding

Your Language Encoding preferences let you can control which language and encoding
scheme is used to exchange data between your website and PayPal. When you sign up for a
PayPal account, the system determines your default language and encoding based on your
country of origin. For example, if you sign up with a French postal address, your language and
encoding are set for Western European languages.
You must set your language encoding preferences to match the language and encoding that
your website uses. Otherwise, data cannot be exchanged with PayPal. Generally, the default
selected by PayPal is appropriate. In some cases, particularly in Asian countries or with certain
operating systems, the language and/or encoding may not match those used by your website.
You can set these language encoding preferences.
z Your website’s language: the character set used on your website, such as Western
European, Japanese, or Russian
z Encoding: the character encoding used on your website, such as UTF-8, EUC-JP, or
KOI8-R.

2
N O T E : For a
complete list of supported language encodings, see “Table 10.2, “Character Sets
and Encodings Supported by PayPal,” on page 155.
Changing Your Default Website Language
To change your website language:
3. In the Selling Preferences column, click the Language Encoding link.
The Language Encoding page appears, as shown below.
FIGURE 2.18 Language Encoding Settings: Language Choice
4. From the Your website’s language dropdown menu, select an appropriate setting.
Changing the Character Encoding Used by Your Website
Sometimes setting your website’s language is insufficient to set the language encoding
correctly. You may need to specify the character encoding explicitly. In addition, you may
need to select separately the encoding for data that your website sends to PayPal with Website
Payments Standard buttons and the data sent by PayPal through IPN, downloadable logs, and
email notifications.
To change the character encoding used by your website:

2
3. In the Selling Preferences column, click the Language Encoding link.

The Language Encoding page appears, as shown in Figure 2.18 .
4. Ensure that setting for Your website’s language is correct.
5. Click the More Options button.
The More Encoding Options page appears, as shown below
FIGURE 2.19 Language Encoding Settings: Encoding Options
6. From the Encoding dropdown menu, select the appropriate character encoding scheme for
data that your website sends to PayPal.
– If you want to use the encoding scheme for receiving data that PayPal sends to your
website, ensure that the Yes radio button is selected.
– If you want to use a different encoding scheme, select the No radio button and select the
encoding scheme you want to use to receive data from PayPal from the No, use
dropdown menu.
7. Click the Save button to preserve both the encoding options that you selected on this page
and the website language you selected on the previous page.
IMPO RTANT: You can click the Cancel button to return to the previous page and review
your choice for website language. However, selections that you made on
the More Encoding Options page are lost.

2
Allowing Multiple Users to Access Your PayPal Account

If you have a PayPal business account, you can set up multiple logins with different
permissions to allow multiple people in your organization to access your PayPal account.
Multi-user access lets you give different employees access to different parts of your account,
based on their business functions.
For example, you can give your customer service representatives their own logins with limited
privileges that let them only view balances and make refunds but not let them edit profiles,
send money, or withdraw funds.
IMPO RTANT: Remember to remove user logins for people who leave your organization.
Adding a User Login to Your Account

To create a user login for your PayPal business account:
3. In the Account Information column, click the Multi-User Access link.
The Multi-User Access-Current Users page appears.
4. Click the Add User button if you have not added users yet, or the Add button if already
have additional users on your account.
The Add Users page appears.
5. Enter information in the following settings:
TABLE 2.4 New User Login Settings
Setting Action
User’s Name Enter the first and last name of the person to whom you want to give
access to your account.
User ID Enter a combination of between 10 and 16 letters and numbers.
Re-enter User ID Enter the same combination of letters and numbers that you entered
for User ID.
Password Enter a combination of between 8 and 20 letters and numbers.
Re-enter Password Enter the same combination of letters and numbers that you entered
for Password.

2
TABLE 2.4 New User Login Settings
Setting Action
Multi-User Access Select any of the checkboxes to grant the user specific privileges
within your account:
z Send Money
z Mass Payments
z Request Money
z Add Funds
z Refunds
z Withdraw Money
z Cancel Payments
z View Balance
z View Profile
z Edit Profile
z History and Reports
z API Activation & Authorization
z Discuss Account with Customer
z Authorization & Settlement
z PayPal Shipping
z Recurring Payments
Changing the Privileges for a User Login

After you add a user login, you can change the privileges of the login. You cannot change the
user’s name or the user ID.
To change the privileges of a user login:
The Multi-User Access - Current Users page appears, as shown below:

2
FIGURE 2.20 Multi-User Access - Current Users Page
4. Select the radio button next to the User Name, and click the Edit button.
The Change Multi-User Access page appears, with the User Name and User ID
displayed as read-only text.
5. Select and deselect checkboxes for the privileges you want to grant to or revoke from the
user login.
6. Click the Save changes.
Resetting the Password for a User Login

When employees forget or loose their passwords, you can log in and reset them.
To reset the password for a user login:
The Multi-User Access - Current Users page appears.
4. Select the radio button next to the User Name for the user login, and click the
Change Password button.
The Change User Password page appears, with the User Name and User ID displayed as
read-only text.

2
Handling Multiple Currencies
5. Enter a new password for the user login:
TABLE 2.5 Change User Login Password Settings
Setting Action
Password Enter a combination of between 8 and 20 letters and numbers.
Re-enter Password Enter the same combination of letters and numbers that you entered
for Password.
Removing a User Login

When someone leaves your organization, you should remove the person’s user login from your
account.
To remove a user login:
The Multi-User Access-Current Users page appears.
4. Select the radio button next to the User Name for the user login, and click the Remove
button.
The Remove User page appears, with the User Name and User ID displayed as read-only
text.
5. Click the Remove button to permanently remove the user login from your account, or click
the Cancel button to retain the user login.

PayPal helps you handle multiple currencies in the following ways:
z Managing Currency Balances
z Accepting or Denying Cross-Currency Payments

2
Managing Currency Balances

Use the Currency Balances section of your account profile to manage your currency
balances, including:
z Selecting your primary currency balance
z Opening or closing currency balances
z Converting funds from one currency balance to funds in another currency balance.
People can pay you in the following currencies; you maintain PayPal balances only in those
currencies that you specify.
TABLE 2.6 Currencies Allowed for Transactions and Balances
Currency ISO-4217 Code
Australian Dollar AUD
Canadian Dollar CAD
Swiss Franc CHF
Czech Koruna CZK
Danish Krone DKK
Euro EUR
Pound Sterling GBP
Hong Kong Dollar HKD
Hungarian Forint HUF
Japanese Yen JPY
Norwegian Krone NOK
New Zealand Dollar NZD
Polish Zloty PLN
Swedish Krona SEK
Singapore Dollar SGD
U.S. Dollar USD
N O T E : Use
the IS0-4217 code for the currency_code HTML variable of HTML buttons with
monetary amounts in currencies in other than USD.

2
Accepting or Denying Cross-Currency Payments

You choose which currencies you accept and how you would like to accept them. You can set
your Payment Receiving Preferences to handle cross-currency payments. See “Blocking
Certain Kinds of Payments” on page 61.
When people make payments in currencies that you hold, the funds appear in your account in
the balance of that currency. When people make payments in currencies that you do not hold,
you can accept or deny the payments.
FIGURE 2.21 Accepting or Denying a Cross-Currency Payment
Receiving fees are assessed in the currency in which the funds were sent. Payments converted
to your primary currency are converted at a competitive exchange rate.

3 Single-Item Payment: Buy Now
Buttons
Use Buy Now buttons to accept single-item purchase payments. A Buy Now button can sell
one or more units of a single item. Make additional Buy Now buttons for additional items that
you want to sell. “The Basic Page Sequence for Website Payments Standard” on page 14
shows how Buy Now buttons work.
You can make Buy Now buttons in two ways:
z Create the HTML code by using a tool on the PayPal website.
Follow the procedures in “Creating Buy Now Buttons” on page 75.
z Write the HTML code yourself using HTML authoring tools of your choice.
Use the example in “Sample HTML Code for a Buy Now Button” on page 83 and the
reference information in Appendix A, “HTML Variables for Website Payments Standard”
as guides.
Creating Buy Now Buttons

To create HTML code for a Buy Now button by using the button creation tool:
2. Click the Merchant Services tab.
3. Click the Buy Now Button link.
4. Enter the details of your item.
– Item name/service: Enter the name of the item or service that you wish to sell. If you do
not enter anything in this field, buyers can fill it in at the time of purchase. PayPal
recommends entering an item name to make it easier for you to ship the order.
– Item ID/number: (optional) Enter the inventory ID or tracking number of your item.
The value that you enter is displayed to buyers at the time of payment, and it is displayed
in the transaction details that both by merchants and buyers can view on the PayPal
website.
– Price: (optional) Enter a fixed price for your item. If you leave the field blank, buyers
“name their own price” after they click the Buy Now button.
IMPO RTANT: PayPal recommends that you enter an a price so that you collect an
appropriate amount for the item.
– Currency: From the dropdown menu, select the currency in which you priced the item
or in which you want the prices that buyers name to be denominated. The dropdown
menu automatically selects the currency of your primary balance.

Single-Item Payment: Buy Now Buttons
3
– Buyer’s default country: From the dropdown menu, select a country for the PayPal log-
in or sign-up page that buyers see when they click the button. The content on the page
will be appropriate for the country you select. Buyers can change the country that you
select, after the log-in or sign-up page appears.
5. Choose a button style for your Buy Now button.
If you are going to be receiving payments from your website instead of using an email
payment link, select the radio button next to the image that you want to use. The image that
you select is hosted by PayPal.
To display your own image that is hosted on your website:

– Click the Use your own button image link.
An additional radio button and text box appear.
– In the Button Image URL text box, enter the URL of your button image.
If your image is hosted securely, change the entry to begin with https//.
6. Specify whether to use button encryption.
– Select the Yes radio button to encrypt the generated code for the payment button.
– or –
– Select the No radio button to leave the generated code for the payment button and the
email payment link as clear text.
PayPal highly recommends that you use button encryption to protect the HTML code of
your payment button. Encryption protects payment details from fraudulent alteration by
third parties, thus increasing the security of the payments you accept. However, consider
the limitations that encryption imposes:
– Encrypted HTML code does not support option fields, which you can specify on the Buy
Now buttons – Page 2 page.
Select the No radio button if you want to add option fields to your Buy Now button.

3
– Encrypted HTML code cannot be edited.

Select the No radio button if you want to edit the HTML code for your button after the
code is generated.
– Encrypted HTML code cannot be used for email payment links.
Select the No radio button if you want to create an email payment link instead of or in
addition to your button.
If you select the No radio button for any reason, use an alternative strategy described in
Chapter 8, “Securing Your Website Payments Standard Buttons” to secure the payments
you receive from the payment button or the email payment link.
IMPO RTANT: Merchants with significant payment volume are required by the PayPal
user agreement to take precautions on securing Website Payment Standard
buttons.
7. Specify a shipping method option.
– Select the Use my shipping calculations radio button if you set up shipping rates for
your account and you want the shipping charges for the item to be calculated
automatically.
– or –
– Select the Use a flat rate amount this radio button if you have not set up shipping rates
for your account or you want to exclude the item from automatic calculation of shipping
charges.
In the text box, enter a fixed amount that will be added to the shipping charges for
purchases that include the item. Enter zero (0.00) for items that do not incur shipping
charges. The currency for the amount that you enter is the same as the currency for the
item.
For more information, see “Automatic Calculation of Shipping Charges (U.S. Merchants
Only)” on page 46 or “Automatic Calculation of Shipping Charges (non-U.S. Merchants
Only)” on page 57.
8. Specify a sales tax option.
– Select the Use my sales tax calculations radio button if you set up tax rates for your
account and you want taxes on the item to be calculated automatically.
– or –
– Select the Use a flat rate amount radio button if you have not set up sales tax
calculations for your account or you want to exclude the item from automatic calculation
of taxes.
In the text box, enter a fixed amount that will be added to the taxes for purchases that
include the item. Enter zero (0.00) for non-taxable items. The currency for the amount
that you enter is the same as the currency for the item.
For more information, see “Automatic Calculation of Sales Tax” on page 42.

3
9. If you have additional details to specify for your button, such as option fields or a custom
payment page style, click the Add More Options button and follow the instructions for
“Adding More Details to the Buy Now Button” on page 78.
– or –
If you entered all the details and options for your button, go to “Copying and Pasting the
Buy Now Code” on page 81.
Adding More Details to the Buy Now Button

Use the Buy Now buttons – Page 2 page to specify the following additional details for your
button.
1. Add option fields to your button.
Option fields lets buyers select or specify options when they purchase the item, such as
color or size. Options must not change the price of the item.
Add to Cart buttons can have one or two option fields. You can use a dropdown menu, with
choices that you specify, or a text box, in which buyers type their option choice.
– Option Field Type: Select either “drop-down menu” or “text box” as the type of option
field.
– Option Name: Enter the name of your option, for example, “Size” or “Color”. Enter no
more than 60 characters.
– Drop-Down Menu Choices: (if applicable) If you selected “drop-down menu” as the
type of option field, enter the menu choices. Choices cannot exceed 30 characters. Use a
carriage return (press ENTER) to separate choices. Enter no more than 10 choices.
IMPO RTANT: Option fields cannot be used if you are creating an email payment link. To
include Buy Now links in email messages for items with options, either
send HTML emails with links to Buy Now buttons on your website that
have option fields, or ask buyers to enter the option information in the Note
field.
2. Customize your payment pages.
Use these settings to give donors a visually seamless payment experience by customizing
the PayPal payment pages to match the visual style of your website.
– Primary Page Style: (display only) The payment pages that your donors see are
displayed with the page style that is specified here, unless you select a different custom
payment page style below.
– Custom Payment Page Style: (optional) If you already added Custom Payment Page
Styles in your account profile, they are listed here. Choose the page style you would like
to appear when donors click your Donation button.
To learn more about creating page styles, see “Branding the PayPal Payment Pages” on
page 25.
– Preview: Click the Preview button to see a mock-up of the payment page style that
donors see when they click your Donation button.

3
3. Customize your buyer’s experience.

Use these settings to give buyers a payment experience that is easy to navigate.
– Successful Payment URL: (optional) Enter the URL for the page on your website that
you want buyers redirected to after they complete their payments.
If Auto Return is off, the button uses the Successful Payment URL that you specify
here.
If Auto Return is on, this field contains the Return URL that you specified when you
turned Auto Return on. Click the Edit button to change the Return URL and the
Successful Payment URL that this button uses.
– Payment Data Transfer: Click the Edit button to turn PDT on or off for all your
payment buttons.
For more information about PDT, see the Order Management Integration Guide.
– Cancel Payment URL: (optional) Enter the URL for the page on your website that you
want buyers redirected to if they cancel their payments at any point in the basic payment
page sequence.
If you do not enter a cancel payment URL, buyers who cancel their payments are taken
to a PayPal webpage.

3
4. Select your quantity and shipping preferences.

Use these settings to control how many units of the item you want to let buyers and how
you collect shipping addresses from buyers.
– Select the Yes radio button to let buyers purchase more than one unit of the item or
service when they click the Buy Now button that you are creating.
If you leave the No radio button selected, buyers can purchase only a single unit of the
item when they click the Buy Now button.
– Select the radio button that matches your need to collect shipping addresses from buyers:
Make shipping optional. Select this radio button if you want to prompt buyers to enter
their shipping addresses as an option.
– or –
Yes, require shipping. Select this radio button if you want to require buyers to enter
their shipping addresses.
– or –
No shipping needed. Select this radio button if the product does not require shipping,
such as a digital good that buyers download, or if the item is a service that does not
require on-site delivery.

3
5. Collect customer notes and special instructions from buyers.

Use these settings to prompt buyers to enter notes or special handling instructions.
– Select the Yes radio button if you want buyers to enter notes to you when they make their
payments. If you leave the No radio button selected, buyers cannot include notes.
– Note Title: If you selected the Yes radio button, change the default value for the field
label to prompt buyers for specific information, such as their customer IDs or special
handling instructions. Enter no more than 30 characters.
6. Select an email address to receive payment.
(optional) In the Email Address dropdown menu, select the email address through which
you want to receive payments when people click the payment button that you are creating.
The dropdown menu selects your primary email address by default.
You can add up to eight email addresses to your PayPal account. Multiple email addresses
are useful to track payments accepted for different business purposes. All payments are
deposited to your PayPal account balance, regardless of which email address receives a
particular payment. Only confirmed email addresses can be used to receive payments.
7. If you want to change any of the details that you entered on the previous page, click the
Edit button and follow the instructions for “Creating Buy Now Buttons” on page 75,
beginning with Step 4.
– or –
If you have entered all the details and options for your button, go to “Copying and Pasting
the Buy Now Code” on page 81.
Copying and Pasting the Buy Now Code

After you enter the details and options that you want for your Buy Now button, click the
Create Button Now button. PayPal generates Buy Now code for:
z a payment button, which you can paste onto your website
z an email payment link, which you can paste into email

3
The Add a Buy Now button to your website page displays the generated code.
Copying and Pasting the HTML Code for the Buy Now Button
To copy and paste the HTML code for the Buy Now payment button:
1. Select everything in the HTML code for Websites text box, by:
– clicking the text with your mouse.
– or –
– clicking the Select All bottom that appears below the text box.
2. Copy the text that you selected to the clipboard, by:
– pressing Ctrl+C.
– or –
– right-clicking your mouse, and selecting Copy.
3. Open the webpage where you want the Buy Now button to be seen.
4. Paste the text that you copied from the clipboard onto your webpage where you want the
button to appear, by:
– pressing Ctrl+V.
– or –
– right-clicking your mouse, and selecting Paste.
Copying and Pasting the Code for the Buy Now Email Payment Link
PayPal does not generate code for email payment links if you select the Yes radio button in the
Button Encryption section on the first page of the button creation tool. To turn button
encryption off, return to the first page and click the No radio button in the Button Encryption
section. Then click the Create Button Now button again.
N O T E : Youcannot use Encrypted Website Payments (EWP) to encrypt the code for email
payment links. Secure the payments you receive from email payment links by using an
alternative method that does not involve encryption, as described in Chapter 8,
“Securing Your Website Payments Standard Buttons.”
To copy and paste the code for the Buy Now email payment link:
1. Select everything in the Link for Emails text box, by:
– or –
– or –

3
Sample HTML Code for a Buy Now Button
3. Open the email that you want to send.

4. Paste the text that you copied from the clipboard into your email, by:
– or –
Creating More Buy Now Buttons
After you copy and paste the Buy Now code, you can create another Buy Now button for a
different item. Scroll to the bottom of the Add a Buy Now button to your website page and
click the Create Another Button button. Then follow the instructions for “Creating Buy Now
Buttons” on page 75, beginning with Step 4. The pages of the button creation tool retain the
options that you previously specified.
Avoiding Problems With Pasted HTML Code

After you paste the code into your webpage or email, ensure that it matches exactly the code
that you copied from PayPal. Pasted code may not match the generated code for the following
reasons:
z You did not copy all of the generated code.
z Your editing tool may have special areas for pasting HTML code and other areas for
pasting URLs and display text. Be sure you paste the generated code into a field that
accepts HTML code or URLs.
z Your editing tool might change some characters in the pasted code.

You can write your own HTML code for Buy Now buttons.
To protect against malicious users tampering with the HTML code for your Buy Now buttons
and submitting fraudulent payments, see Chapter 8, “Securing Your Website Payments
Standard Buttons.”
IMPO RTANT: Merchants with significant payment volume are required by the PayPal user
agreement to take precautions on securing Website Payment Standard
buttons.
You can use the following HTML code as a starting point for writing your own HTML code
for Buy Now buttons.The value for the business variable must match a confirmed email
address on file with your PayPal account. You can change the values for other variables, with
the exception of cmd.
EXAMPLE 3.1 HTML For a Buy Now Button

<form target="paypal" action="https://www.paypal.com/cgi-bin/webscr"

3
method="post">
<input type=”hidden” name=”business" value="[email protected]">


<input type=”hidden” name=”cmd" value="_xclick">

<input type="hidden" name="item_name" value="Baseball Hat">
<input type="hidden" name="item_number" value="12345">
<input type=”hidden” name=”amount” value=”12.95”>
<input type="hidden" name="currency_code" value="USD">


<input type=”hidden” name=”undefined_quantity” value=”1”>

<table>
<tr>
<td>
<input type="hidden" name="on0" value="Size">Size
</td>
<td>
<select name="os0">
<option value="Select a Size">Select a Size
<option value="Small">Small
<option value="Medium">Medium
<option value="Large">Large
</select>
</td>
</tr>
</table>


<input type="image" name="submit" border="0"
src="https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif"
alt="PayPal - The safer, easier way to pay online">
<img alt="" border="0" width="1" height="1"
src="https://www.paypal.com/en_US/i/scr/pixel.gif" >
</form>
The sample code above produces the following result:
Paste the code onto your webpage below an image or a text description of the item.

3
Sample URL Code for a Buy Now Email Payment Link

You can write your own URL code for Buy Now email payment links.
The same variables and values that you include in HTML code for Buy Now buttons can be
used in Buy Now email payment links. Separate the variables and their values from each other
with ampersands (&). Do not enclose values in quotation marks; use plus signs (+) as
substitutes for spaces in values, if needed.
N O T E : You cannot include variables for option fields in email payment links.
You can use the following URL as a starting point for writing your own URL for Buy Now
email payment links.The value for the business variable must match a confirmed email
address on file with your PayPal account. You can change the values for other variables.
EXAMPLE 3.2 URL for a Buy Now Email Payment Link

https://www.paypal.com/_xclick/[email protected]&item_name=Bas
eball+Hat&item_number=12345&amount=12.95&currency_code=USD&undefined_quanti
ty=1

3

4 Multiple-Item Payment: Shopping
Carts
Use shopping carts to let people select multiple items and pay for them with a single purchase
payment. Shoppers browses your entire catalog of products and add the ones they want to
purchase to their virtual shopping carts. Shoppers review the items in their carts before
checking out and making their payments.
Shopping carts comes in two basic forms:
z The PayPal Shopping Cart, which is hosted by PayPal
z Third party shopping carts that are compatible with PayPal and Website Payments
Standard.
One distinction between the PayPal Shopping Cart and third party carts is the use of the
following HTML variables:
z add or display: Use these variables with the PayPal Shopping Cart.
z upload: Use this variable with third party shopping carts.
For more information, see Appendix A, “HTML Variables for Website Payments Standard.”
How the PayPal Shopping Cart Works

This example shows how the PayPal Shopping Cart works with the following account profile
settings:
z Account Optional is turned on. For more information, see “PayPal Account Optional” on
page 30.
z Auto Return is turned off. At the end of the transaction, shoppers can click the Return to
The Stuff Shop button to return to your website. For more information, see “Auto Return”
on page 38.
What The Shopper Sees with the PayPal Shopping Cart

Bob is shopping at the The Stuff Shop. He already has a PayPal account. He selects a baseball
hat by clicking the Add to Cart button.

Multiple-Item Payment: Shopping Carts
4
FIGURE 4.1 PayPal Shopping Cart Example: Add to Cart
The Stuff Shop is using Add to Cart buttons created with the button creation tool described in
“Creating PayPal Shopping Cart Buttons” on page 90.
N O T E : Fordetails about the HTML code for Add to Cart buttons, see “Sample HTML Code
for an Add to Cart Button” on page 99.
Bob is taken to the PayPal website where enters his PayPal username and password and clicks
the Log In button.
FIGURE 4.2 PayPal Shopping Cart Example: On the PayPal Website
Bob is taken to a review page showing the details of his payment.

4
FIGURE 4.3 PayPal Shopping Cart Example: Review Page
Because The Stuff Shop has not set up shipping preferences in its account profile, no shipping
charges are calculated and added to the order. For information about automatic shipping
calculation, see “Automatic Calculation of Shipping Charges (U.S. Merchants Only)” on
page 46 or “Automatic Calculation of Shipping Charges (non-U.S. Merchants Only)” on
page 57.
Bob clicks the Pay $12.95 Now! button to complete the payment. He is taken to a thank you
page upon payment completion.

4
Creating PayPal Shopping Cart Buttons
FIGURE 4.4 PayPal Shopping Cart Example: Thank You Page After Payment
Bob receives an email receipt for this transaction that confirms the payment and payment
details.
FIGURE 4.5 PayPal Shopping Cart Example: Email Transaction Receipt

With the PayPal Shopping Cart, shoppers can purchase multiple items with a single payment.

4
With the button creation tool for the PayPal Shopping Cart, you create individual Add to Cart
buttons for the items that you want to sell, and you place the generated HTML code for the
buttons next to the items on your website.
The tool also generates HTML code for View Cart buttons. You need to create only one View
Cart button for the PayPal Shopping Cart. Place copies of the generated HTML code for the
View Cart button wherever you want shoppers to click to view their shopping cart and begin
the checkout process.
N O T E : If
you are familiar with HTML programming, you can use the variables in
Appendix A, “HTML Variables for Website Payments Standard” to write the HTML
code yourself.
IMPO RTANT: The button creation tool for PayPal Shopping Cart buttons does not support
encryption of the code it generates. Secure your button code for Add to Cart
buttons by using an alternative strategy described in Chapter 8, “Encrypting
Buttons Dynamically With Encrypted Website Payments (EWP).” View Cart
buttons do not require encryption.
To create HTML code for an Add to Cart button using the button creation tool:
3. Click the Add to Cart Button link.
4. Enter the details of your item.
– Item name/service: Enter the name of your item or service.
– Item ID/number: (optional) Enter the inventory ID or tracking number of your item.
The value you enter is displayed to shoppers at the time of payment, and it is displayed
in the transaction details that both merchants and shoppers can view on the PayPal
website.
– Price: Enter a fixed price of your item.
– Currency: From the dropdown menu, select the currency in which you priced the item.
The dropdown menu automatically selects the currency of your primary balance.
For more information, see “Pricing Items in Multiple Currencies” on page 99.
in or sign-up page that shoppers see when they click the button. The content on the page
will be appropriate for the country you select. Shoppers can change the country that you
– Weight (optional): Enter the weight of the item. Select Lbs or Kgs from the dropdown
menu to specify the unit of measure. If you set up shipping rates for your account with a
basis of weight, PayPal uses the value you enter here to calculate shipping charges for
orders that include the item.
5. Choose a button style for your Add to Cart button.
Select the radio button next to the image you want to use, which is hosted by PayPal.

4
– or –
To display your own image that you host on your website:
6. Specify a shipping method option.
– Select the Use my shipping calculations radio button if you set up shipping rates for
your account and you want the shipping charges for the item to be calculated
automatically.
– or –
– Select the Use a flat rate amount this radio button if you have not set up shipping rates
for your account or you want to exclude the item from automatic calculation of shipping
charges.
In the text box, enter a fixed amount that will be added to the shipping charges for
purchases that include the item. Enter zero (0.00) for items that do not incur shipping
charges. The currency for the amount that you enter is the same as the currency for the
item.
7. Specify a sales tax option.
– Select the Use my sales tax calculations radio button if you set up tax rates for your
account and you want taxes on the item to be calculated automatically.
– or –

4
– Select the Use a flat rate amount radio button if you have not set up sales tax
calculations for your account or you want to exclude the item from automatic calculation
of taxes.
In the text box, enter a fixed amount that will be added to the taxes for purchases that
include the item. Enter zero (0.00) for non-taxable items. The currency for the amount
that you enter is the same as the currency for the item.
For more information, see “Automatic Calculation of Sales Tax” on page 42.
8. If you have additional details to specify for your button, such as option fields or a custom
payment page style, click the Add More Options button and follow the instructions for
“Adding More Details to the PayPal Shopping Cart Button” on page 93.
– or –
PayPal Shopping Cart HTML Code” on page 97.
Adding More Details to the PayPal Shopping Cart Button

Use the PayPal Shopping Cart – Page 2 page to specify the following additional details for
your button.
1. Add option fields to your button.
Option fields lets shoppers select or specify options when they purchase the item, such as
color or size. Options must not change the price of the item.
Add to Cart buttons can have one or two option fields. You can use a dropdown menu, with
choices that you specify, or a text box, in which shoppers type their option choice.
– Option Field Type: Select either “drop-down menu” or “text box” as the type of option
field.
– Option Name: Enter the name of your option, for example, “Size” or “Color”. Enter no
more than 60 characters.
– Drop-Down Menu Choices: (if applicable) If you selected “dropdown menu” as the
type of option, enter your menu choices. Choices cannot exceed 30 characters. Use a
carriage return (press ENTER) to separate choices. Enter no more than 10 choices.
2. Choose a button style for your View Cart button.
Select the radio button next to the image that you want to use. The image that you select is
hosted by PayPal.

4
– or –
N O T E : You
need to create only one View Cart button for the PayPal Shopping Cart. Place
copies of the generated HTML code for the View Cart button wherever you want
shoppers to click to view their shopping cart and begin the checkout process.
Use these settings to give shoppers a visually seamless payment experience by customizing
– Primary Page Style (display only): The payment pages that your shoppers see are
– Custom Payment Page Style (optional): If you already added Custom Payment Page
to appear when shoppers check out and pay from the PayPal Shopping Cart.
page 25.
shoppers see.

4
4. Customize your buyer’s experience.

Use these settings to give shoppers a payment experience that is easy to navigate.
you want shoppers redirected to after they complete their payments.
here.
payment buttons.
want shoppers redirected to if they cancel their payments at any point in the PayPal
Shopping Cart payment page sequence.
If you do not enter a cancel payment URL, shoppers who cancel their payments are
taken to a PayPal webpage.

4
5. Select your shipping preferences.

Select the radio button that matches your need to collect shipping addresses from shoppers:
Make shipping optional. Select this radio button if you want to prompt shoppers to enter
their shipping addresses as an option.
– or –
Yes, require shipping. Select this radio button if you want to require shoppers to enter
their shipping addresses.
– or –
No shipping needed. Select this radio button if your products not require shipping, such as
digital goods that shoppers download, or if your items are services that do not require on-
site delivery.
6. Collect customer notes and special instructions from shoppers.
Use these settings to prompt shoppers to enter notes or special handling instructions.
– Select the Yes radio button if you want shoppers to enter notes to you when they make
their payments. If you leave the No radio button selected, shoppers cannot include notes.
label to prompt shoppers for specific information, such as their customer IDs or special
handling instructions. Enter no more than 30 characters.
7. Select an email address to receive payment.
are useful to track payments accepted for different business purposes. All payments are

4
Edit button and follow the instructions for “Creating PayPal Shopping Cart Buttons” on
page 90, beginning with Step 4.
– or –
the PayPal Shopping Cart HTML Code” on page 97.
Copying and Pasting the PayPal Shopping Cart HTML Code

After you enter the details and options that you want for your Shopping Cart buttons, click the
Create Button Now button. PayPal generates HTML code for two PayPal Shopping Cart
buttons:
z an Add to Cart button, which is used for the item you want to sell.
z A View Cart button, which takes shoppers to a webpage hosted by PayPal that displays all
the items that shoppers have added to their carts and from where they check out and pay.
The Add a shopping cart to your site page displays the generated code.
Copying and Pasting the HMTL Code for the Add to Cart Button
To copy and past the HTML code for the Add to Cart button:
1. Select everything in the “Add to Cart” button code text box, by:
– or –
– or –
3. Open the webpage where you want the Add to Cart button to be seen.
– or –
Copying and Pasting the HTML Code for the View Cart Button
You need to paste at least one View Cart button onto your website. Paste the View Cart button
HTML code onto you website in locations where shoppers can easily see them and click to
checkout. PayPal generates the same HTML code for the View Cart button every time you
create an Add to Cart button. View Cart buttons do not contain any payment information.

4
To copy and past the HTML code for the View Cart button:
1. Scroll down the Add a shopping cart to your site page to the View Cart Button section.
2. Select everything in the “View Cart” button code text box, by:
– or –
– or –
4. Open the webpage where you want the View Cart button to be seen.
– or –
Creating More Add to Cart Buttons
After you copy and paste the PayPal Shopping Cart code, you can create another Add to Cart
button for a different item. Scroll to the bottom of the Add a shopping cart to your site page
and click the Create Another Button button. Then follow the instructions for “Creating
PayPal Shopping Cart Buttons” on page 90, beginning with Step 4. The pages of the button
creation tool retain the options that you specified previously.

After you paste the HTML code onto your webpage, ensure that it matches exactly the HTML
code you copied from PayPal. Pasted code may not match the generated code for the following
reasons:
z Your HTML editing tool may have special areas for pasting HTML code and other areas
for pasting display text. Be sure you paste the generated code into a field that accepts
HTML code.
z Your HTML editing tool might change some characters in the pasted code.

4
Sample HTML Code for an Add to Cart Button
Pricing Items in Multiple Currencies

All items that shoppers add to carts must be priced in the same currency. The first item that
shoppers add to carts or the currency specified with the currency_code variable determines
the currency for shopping carts.
After a shopper adds the first item to a shopping cart, the shopper cannot add items priced in
other currencies. To change the currency of a shopping cart, a shopper must purchase the items
in the cart with the current currency or empty the cart and add items priced in the other
currency.
To avoid shopping difficulties that arise with multiple currencies, price all of your items in the
same currency. If you must price items in multiple currencies, let shoppers choose the
currency for viewing your catalog and display prices on your website only in currency that the
shopper selected.
Sample HTML Code for an Add to Cart Button

You can write your own HTML code for Add to Cart buttons.
To protect against malicious users tampering with the HTML code for your Add to Cart
buttons and obtaining fraudulent prices, see Chapter 8, “Securing Your Website Payments
buttons.
Use the following HTML code as a starting point for writing your own HTML code for Add to
Cart buttons. The value for the business variable must match a confirmed email address on
file with your PayPal account. You can change the values for other variables, with the
exception of cmd and add.
EXAMPLE 4.1 HTML for PayPal Shopping Cart “Add to Cart” Button
method="post">
<input type="hidden" name="business" value="[email protected]">


<input type="hidden" name="cmd" value="_cart">
<input type="hidden" name=”add” value="1">


<input type="hidden" name="item_name" value="Baseball Hat">
<input type=”hidden” name=”amount” value=”12.95”>


4
Sample HTML Code for a View Cart Button
<table>
<tr>
<td>
<input type="hidden" name="on0" value="Size">Size
</td>
<td>
<select name="os0">
<option value="Select a Size">Select a Size
<option value="Small">Small
<option value="Medium">Medium
<option value="Large">Large
</select>
</td>
</tr>
</table>

src="https://www.paypal.com/en_US/i/btn/btn_cart_LG.gif"
</form>
Paste the code onto your webpage below an image or a text description of the item.
Sample HTML Code for a View Cart Button

You can write your own HTML code for View Cart buttons. View Cart buttons contain no
payment information, so you do not need to take on precautions on securing them.
Use the following HTML code as a starting point for writing your own HTML code for View
Cart buttons. The value for the business variable must match a confirmed email address on
file with your PayPal account, and it must match the value you used for the business
variables on your Add to Cart buttons. You can change the values for other variables, with the
exception of cmd and display.
EXAMPLE 4.2 HTML for PayPal Shopping Cart “View Cart” Button

4
How A Third Party Shopping Cart Works

method="post">


<input type="hidden" name=”display” value="1">


src="https://www.paypal.com/en_US/i/btn/btn_viewcart_LG.gif"
</form>
Paste the code onto the pages or your website wherever you want shoppers to click to view the
contents of their PayPal Shopping Carts and begin the checkout process.

This example shows how a third party shopping cart works with PayPal and Website Payments
Standard. The example merchant has the following account profile settings:
z PayPal Account Optional is turned on. The shopper can pay without an existing PayPal
account and is offered the chance to sign up for one after completing the payment.
For more information, see “PayPal Account Optional” on page 30.
z Shipping Calculations have been set up. PayPal calculates the shipping charges
automatically and adds them to the order.
z Auto Return is turned off. Shoppers must click a Return to Merchant button to redirect
their browsers to the merchant website after completing their payments with PayPal.

4
What The Shopper Sees with Third Party Shopping Carts

Bob is shopping for photos on the DesignerFotos website. He selects several photos for
purchase by clicking the Add to Cart button underneath each one.
FIGURE 4.6 Third Party Shopping Cart: Add to Cart
In this example integration, the third party shopping cart is programmed by the vendor to
display the contents of the cart each time Bob clicks an Add to Cart button. In addition, Bob
can click the View Cart link at any time to review the items already in the cart and to begin the
PayPal payment page sequence.

4
FIGURE 4.7 Third Party Shopping Cart: View Shopping Cart
After selecting the items he wants to buy and specifying their quantities, Bob clicks the
Proceed to Checkout button.
Bob’s browser is redirected to the PayPal website. Shoppers with PayPal accounts can enter
their PayPal account credentials and click the Log In button to access information already on
file with PayPal, such as shipping addresses.

4
FIGURE 4.8 Third Party Shopping Cart: PayPal Payment Login Page
Bob does not have a PayPal account, so he enters his payment and billing information on the
payment login page and clicks the Review Payment button. Bob is taken to a review page that
shows the details of his payment.

4
FIGURE 4.9 Third Party Shopping Cart: PayPal Payment Review Page
DesignerFotos has set up Shipping Calculations in the account profile, so PayPal calculates
shipping costs automatically and adds them to the order.
Bob clicks the Pay $505.00 Now! button to complete the payment.
In response, the browser takes Bob to a payment confirmation page. DesignerFotos has Auto
Return turned off in the account profile, so the page displays a button to return to the
DesignerFotos website.
Bob can:
z Click the Return to DesignerFotos button to return to the merchant website.
z Click the View Printable Receipt link to view and print a PayPal payment receipt.
z Click the Create Account button to sign up for a PayPal account.
Bob does not have a PayPal account yet, and he chooses to open one by entering his email
address, a password, and clicking the Create Account button. The payment and shipping
information he used for the transaction is added to his PayPal account automatically.

4
FIGURE 4.10 Third PartyShopping Cart: PayPal Payment Confirmation Page
PayPal sends Bob an email notice of his payment to DesignerFotos.

4
FIGURE 4.11 Email Payment Receipt from PayPal to Shopper
What Merchants See

PayPal sends DesignerFotos an email notice of Bob’s payment.
FIGURE 4.12 Email Payment Receipt from PayPal to Merchant
N O T E : DesignerFotos
(the user [email protected]) can also see the payment in the
PayPal account history.

4
Integrating Third Party Shopping Carts with PayPal

Instead of relying on the PayPal Shopping Cart, many merchants use third party shopping carts
that are already integrated with PayPal. The section describes how developers of third party
carts integrate with PayPal using Website Payments Standard.
Required Third Party Shopping Cart Variables

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

If you code your third party shopping cart to pass individual items to PayPal, information
about the items is included in shoppers’ and the merchants’ transaction histories and
notifications.
1. Set the cmd variable to _cart.
2. Include the upload variable:
<input type="hidden" name="upload" value="1">
3. Define item details for each item in the cart.

Specify the required variables and any optional variables listed inTable A.1, “Allowed Values
for the cmd HTML Variable.” Append _x to the variable name, where x is the item number,
starting with 1 and increasing by one for each item added to the cart. The first item in the cart
must be defined with variables ending in _1, like item_name_1, amount_1, and
quantity_1; the second item with variables like item_name_2, amount_2, and

4
quantity_2; the third item with variables like item_name_3, amount_3, and
quantity_3; and so on.
IMPO RTANT: The _x values must increment by one continuously in order to be recognized.
If you skip from item #1 to item #3 without defining an item #2, the third
item will be ignored.
The minimum required HTML for your post to PayPal looks similar to the following.
EXAMPLE 4.1 HTML for Passing Individual Item Detail to PayPal

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>
<input type=”hidden” name=”cmd” value=”_cart”>
<input type=”hidden” name=”upload” value=”1”>
<input type=”hidden” name=”business” value=”[email protected]”>
<input type=”hidden” name=”item_name_1” value=”Item Name 1”>
<input type=”hidden” name=”amount_1” value=”1.00”>
<input type=”hidden” name=”item_name_2” value=”Item Name 2”>
<input type=”submit” value=”PayPal”>
</form>
Setting Currency in the Cart

All monetary variables (amount_x., shipping_x., shipping2_x, handling_x, tax_x.,
and tax_cart) are interpreted in the currency designated by the currency_code variable
posted with the payment. Because currency_code is not item-specific, there is no need to
append _x to the currency_code variable name. If no currency_code variable is posted,
all monetary values default to U.S. Dollars.
Setting Tax on Individual Items
Use the tax_x variable to specify the tax for a particular item in the cart. For example, the
following line specifies that the tax on item 2 in the cart is 15 cents:
<INPUT TYPE="hidden" name="tax_2" value=".15">
Setting Shipping Charges on Individual Items

Use the weight_x and weight_unit variables to specify item weights if the merchant’s
profile-based shipping rates are based on weight. For example, the following lines specify the
weight of item 3 in the cart as 1.5 kg.
<INPUT TYPE="hidden" name="weight_3" value="1.5">
<INPUT TYPE="hidden" name="wieght_unit" value="kgs">
Use the quantity_x variable if the merchant’s profile-based shipping rates are based on
quantity. For example, the following line specifies that the quantity for item 3 in the cart is 6.
<INPUT TYPE="hidden" name="quantity_3" value="6">

4
Setting the Tax for the Entire Cart

Use the tax_cart variable to specify a tax amount that applies to the entire transaction,
rather than to individual items. The tax_cart variable overrides any per-item tax amount
specified with tax_x.
Setting the Shipping Charge for the Entire Cart

Use the shipping variable without additional shipping2 variables to specify the shipping
charge for the entire transaction. The value of shipping is used for the shipping charges,
regardless of the merchant’s profile-based shipping rates and rate basis.
Use the weight_cart and weight_unit variables to specify the total order weight if the
merchant’s profile-based shipping rates are configured with a basis of weight. The
weight_cart variable overrides any per-item weights specified with weight_x.
Passing the Aggregate Shopping Cart Amount to PayPal

You can aggregate your entire shopping cart and pass the total amount to PayPal. You must
post a single item_name_1 for the entire cart and the total price of the cart contents in
amount_1 as though it were a purchase of a single item.
N O T E : Onedrawback with passing aggregate cart information is that shoppers do not see the
individual items in their order on the PayPal payment pages.
The following HTML is identical to “HTML for Passing Individual Item Detail to PayPal” on
page 109 except the individual items amounts and item names are aggregated into a single
amount and a single item.
EXAMPLE 4.2 HTML for Aggregate Cart Detail to PayPal

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>
<input type=”hidden” name=”cmd” value=”_cart”>
<input type=”hidden” name=”upload” value=”1”>
<input type=”hidden” name=”business” value=”[email protected]”>
<input type=”hidden” name=”item_name_1” value=”Aggregated items”>
<input type=”submit”” value=”PayPal”>
</form>
Securing Your Shopping Cart

After you have customized you third party shopping cart, protect against malicious users
tampering with the button code and submitting an incorrect charge by using one of the
methods described in Chapter 8, “Encrypting Buttons Dynamically With Encrypted Website
Payments (EWP).”

5 Contribution Payment: Donation
Buttons
Use Donation buttons to collect contribution payments. Donation buttons can collect pre-
determined amounts or amounts entered by donors.
You can make Donation buttons in two ways:
z Create the HTML code by using a tool on the PayPal website.
Follow the procedures in “Creating Donation Buttons” on page 119.
z Write the HTML code yourself using HTML authoring tools of your choice.
Use the example in “Sample HTML Code for a Donation Button” on page 126 and the
reference information in Appendix A, “HTML Variables for Website Payments Standard”
as guides.
The Page Sequence for Donation Buttons

This section provides a visual example of the donations page sequence for payments made
with Donation buttons. In the example, a donor named Mary contributes money to a charity
that has a website. Mary has a PayPal account before she visits the charity website.
Begin: Donor is Ready to Contribute

The donation page sequence for payments made with Donation buttons begins when the donor
is ready to contribute. In this example, Mary browses the website of her favorite cause and
clicks the Donate button.

Contribution Payment: Donation Buttons
5
FIGURE 5.1 Donation Page Sequence Begins on the Charity Website
1: Donor Logs In to PayPal

Mary’s browser redirects her to the PayPal website. Mary is a PayPal member, so she enters
her PayPal credentials and clicks the Log In button.

5
FIGURE 5.2 PayPal Members Log In to PayPal
Unlike Mary, donors who do not have PayPal accounts click the continue link to complete
their contribution payments. Clicking the link leads to a page where they can make their
payments and sign up for their new PayPal accounts at the same time.

5
FIGURE 5.3 Non-Members Pay and Sign Up for New Accounts at the Same Time
2: Donor Reviews Contribution Details

After logging in to PayPal, Mary sees a donation review page from PayPal, where she reviews
the details of her contribution before she submits her payment. Mary can select the funding
source for the payment from her funding sources on file with PayPal. Funding sources include
credit cards, debit cards, and bank accounts. In addition, Mary can select a mailing address
from her addresses on file with PayPal.
After Mary is satisfied with the contribution details, she clicks the Donate $25.00 USD Now
button to submit here payment for processing.

5
FIGURE 5.4 Donors Review Contribution Details Before Submitting Their Payments
3: Donor Views PayPal Payment Confirmation

After payment processing completes, Mary sees a donation confirmation page from PayPal.
Mary can:
z View the PayPal confirmation number, which lets her track her payment within her
PayPal account.
z Click the View Printable Receipt link, which lets her print a receipt of her payment.
z Click the Go to PayPal Account Overview link after she finishes viewing the PayPal
donation confirmation page.

5
FIGURE 5.5 Donors View the PayPal Donation Confirmation Page
END: Donor Prints PayPal Contribution Receipt

After clicking the View Printable Receipt link, Mary sees a PayPal contribution receipt. She
can print the receipt and keep it for later use.

5
FIGURE 5.6 Donors Print Their PayPal Contribution Receipts
Alternative ENDs: Returning Donors to Your Website

To make it easy for people to navigate back to your website after completing their payments,
do one of the following:
z Enter a successful return URL in the button creation tool, or include the return HTML
variable in the HTML code for the Donation button. People return to a static “thank you”
page on your website if they click a “return” link or button on the PayPal payment
confirmation page.
To learn more, see “Creating Donation Buttons” on page 119 and “HTML Variables for
Displaying PayPal Payment Pages” on page 169.
z Turn Auto Return on, and specify a return URL. PayPal redirects people automatically to a
static “thank you” page on your website.
To learn more, see “Auto Return” on page 38.
z Turn PDT on, in addition to turning Auto Return on, and then add programming logic to
your website to capture the payment details from PDT. PayPal redirects people
automatically to a dynamic “thank you, print your receipt” page on your website.
To learn more, see the Order Management Integration Guide.
IMPO RTANT: PayPal recommends that you always turn PDT on when you turn Auto
Return on. With Auto Return on, PayPal redirects people to your website
from an alternative PayPal payment confirmation page that does not
display a View Printable Receipt link, so people cannot print PayPal
contribution receipts.

5
How You Get Your Contributions
How You Get Your Contributions

After a donor makes a contribution, your PayPal account lists the payment in your Account
History, as shown below.
FIGURE 5.7 Account History: Recent Activity
Notifications You Receive About Contribution Payments

You can be notified of contribution payments in four ways: email, transaction history,
downloadable history log, and Instant Payment Notification (IPN).
Email
You receive email notification when:
z a successful payment is made.
z a payment is pending.
z a payment is canceled.
If you want to stop receiving email notification:
2. Under Account Information, click the Notifications link.
3. Under Payment Notifications, clear the I receive PayPal Website Payments and Instant
Purchase checkbox.

5
Creating Donation Buttons
Transaction History
You transaction history is available from the History page. It provides information about your
payments and other account activity. The status of a payment can be:
z Completed: The transaction was successful and the money was credited to your account.
z Cleared: The payment cleared the sender’s account and was credited to your account.
z Uncleared: The payment has not cleared the sender’s account.
To learn how to work with your transaction history, see the Order Management Integration
Guide.
Downloadable History Log

You can download copies of your transaction history to your computer. You can specify a date
range for the transactions and the file format of the downloadable history log.
To learn to how work with downloadable history logs, see the Order Management Integration
Guide.
Instant Payment Notification (IPN)

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

To create HTML code for a Donation button by using the button creation tool:
3. Under the Create Buttons heading, click the Donate link.
4. Enter the donation details of your button.

5
– Donation name/service: Enter the reason for the donation or the name of your
organization. If you do not enter anything in this field, your donors can complete this
field.
– Donation ID/number: (optional) Enter a value to help identify different kinds of
contribution payments. For example, you might enter the name of your current fund-
raising campaign. The value that you enter is displayed to donors at the time of payment,
and it is displayed in the transaction details that both contribution coordinators and
donors can view on the PayPal website.
– Amount: (optional) Enter a fixed contribution amount. If you leave the field blank,
donors enter their own contribution amount after they click the Donation button.
– Currency: From the dropdown menu, select the currency in which you specified the
fixed contribution amount or in which you want the amounts that donors enter to be
denominated. The dropdown menu automatically selects the currency of your primary
balance.
in or sign-up page that donors see when they click the button. The content on the page
will be appropriate for the country you select. Donors can change the country that you
5. Choose a button style for your Donation button.
If you are going to be receiving payments from your website instead of by using an email
payment link, select the radio button next to the image that you want to use. The image you
select is hosted by PayPal.

6. Specify whether to use button encryption.

5
– Select the Yes radio button to encrypt the generated code for the payment button.
– or –
– Select the No radio button to leave the generated code for the payment button and the
email payment link as clear text.
PayPal highly recommends that you use button encryption to protect the HTML code of
your payment button. Encryption protects payment details from fraudulent alteration by
third parties, thus increasing the security of the payments you accept. However, consider
the limitations that encryption imposes:
– Encrypted HTML code cannot be edited.
Select the No radio button if you want to edit the HTML code for your button after the
code is generated.
– Encrypted HTML code cannot be used for email payment links.
Select the No radio button if you want to create an email payment link instead of or in
addition to your button.
If you select the No radio button for any reason, use an alternative strategy described in
Chapter 8, “Securing Your Website Payments Standard Buttons” to secure the payments
you receive from the payment button or the email payment link.
IMPO RTANT: Merchants with significant payment volume are required by the PayPal
buttons.
7. If you have additional details to specify for your button, such as custom payment pages,
click the Add More Options button and follow the instructions for “Adding More Details
to the Donation Button” on page 121.
– or –
Donation Code” on page 124.
Adding More Details to the Donation Button

Use the Donations – Page 2 page to specify the following additional details for your button.
Use these settings to give donors a visually seamless payment experience by customizing
– Primary Page Style: (display only) The payment pages that your donors see are
– Custom Payment Page Style: (optional) If you already added Custom Payment Page
to appear when donors click your Donation button.
page 25.

5
donors see when they click your Donation button.
2. Customize your donor’s experience.
Use these settings to give donors a payment experience that is easy to navigate.
you want donors redirected to after they complete their payments.
here.
payment buttons.
want donors redirected to if they cancel their payments at any point in the donation
payment page sequence.
If you do not enter a cancel payment URL, donors who cancel their payments are taken
to a PayPal webpage.

5
3. Select your shipping preferences.

Select the radio button that matches your need to collect addresses from donors:
Make shipping optional. Select this radio button if you want to prompt donors to enter
their addresses as an option.
– or –
Yes, require shipping. Select this radio button if you want to require donors to enter their
addresses.
– or –
No shipping needed. Select this radio button if you do not require addresses from donors.
You might want to collect addresses from donors so that you can send paper contribution
acknowledgement letters or ship contribution thank-you gifts.
4. Collect notes and special instructions from donors.
Use these settings to prompt donors to enter notes or special instructions.
– Select the Yes radio button if you want donors to enter notes to you when they make their
payments. If you leave the No radio button selected, donors cannot include notes.
label to prompt donors for specific information, such as In memory of. Enter no more
than 30 characters.
5. Choose an email address to receive payment.
are useful to track payments accepted for different contribution purposes. All payments are

5
Edit button and follow the instructions for “Creating Donation Buttons” on page 119,
beginning with Step 4.
– or –
the Donation Code” on page 124.
Copying and Pasting the Donation Code

After you enter the details and options that you want for your Donation button, click the
Create Button Now button. PayPal generates Donation code for:
z a payment button, which you can paste onto your website
z an email payment link, which you can paste into email
The Add a Donate button to your website page displays the generated code.
Copying and Pasting the HTML Code for the Donation Button
To copy and paste the HTML code for the Donation payment button:
1. Select everything in the HTML code for Websites text box, by:
– or –
– or –
3. Open the webpage where you want the Donation button to be seen.
– or –
Copying and Pasting the Code for the Donation Email Payment Link
PayPal does not generate code for email payment links if you select the Yes radio button in the
Button Encryption section on the first page of the button creation tool. To turn button
encryption off, return to the first page and click the No radio button in the Button Encryption
section. Then click the Create Button Now button again.

5
N O T E : Youcannot use Encrypted Website Payments (EWP) to encrypt the code for email
payment links. Secure the payments you receive from email payment links by using an
alternative method that does not involve encryption, as described in Chapter 8,
“Securing Your Website Payments Standard Buttons.”
To copy and paste the code for the Donation email payment link:
1. Select everything in the Link for Emails text box, by:
– or –
– or –
3. Open the email that you want to send.
4. Paste the text that you copied from the clipboard into your email, by:
– or –
Creating More Donation Buttons
After you copy and paste the Donation code, you can create another Donation button for a
different item. Scroll to the bottom of the Add a Donation button to your website page and
click the Create Another Button button. Then follow the instructions for “Creating Donation
Buttons” on page 119, beginning with Step 4. The pages of the button creation tool retain the
options that you previously specified.

After you paste the code into your webpage or email, ensure that it matches exactly the code
that you copied from PayPal. Pasted code may not match the generated code for the following
reasons:
z Your editing tool may have special areas for pasting HTML code and other areas for
pasting URLs and display text. Be sure you paste the generated code into a field that
accepts HTML code or URLs.
z Your editing tool might change some characters in the pasted code.

5
Sample HTML Code for a Donation Button
Sample HTML Code for a Donation Button

You can write your own HTML code for Donation buttons.
To protect against malicious users tampering with the HTML code for your Donation buttons
submitting fraudulent contributions, see Chapter 8, “Securing Your Website Payments
IMPO RTANT: Organizations with significant payment volume are required by the PayPal
buttons.
Use the following HTML code as a starting point for writing your own HTML code for
Donation buttons. The value for the business variable must match a confirmed email
address on file with your PayPal account. You can change the values for other variables, with
the exception of cmd.
EXAMPLE 5.1 HTML For a Donation Button

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="business"
value="[email protected]">


<input type="hidden" name="cmd" value="_donations">


<input type="hidden" name="item_name" value="Friends of the Park">
<input type="hidden" name="item_number" value="Fall Cleanup Campaign">

src="https://www.paypal.com/en_US/i/btn/btn_donate_LG.gif"
</form>
Paste the code onto your website wherever you want donors to click and make a contribution
in amounts that donors choose.

5
Sample URL Code for a Donation Email Payment Link

You can write your own URL code for Donation email payment links.
The same variables and values that you include in HTML code for Donation buttons can be
used in Donation email payment links. Separate the variables and their values from each other
with ampersands (&). Do not enclose values in quotation marks; use plus signs (+) as
substitutes for spaces in values, if needed.
You can use the following URL as a starting point for writing your own URL for Donation
email payment links.The value for the business variable must match a confirmed email
address on file with your PayPal account. You can change the values for other variables.
EXAMPLE 5.2 URL for a Donation Email Payment Link

https://www.paypal.com/_donations/[email protected]&item
_name=Friends+of+the+Park&item_number=Fall+Cleanup+Campaign&currency_code=U
SD

5

6 Using Authorization & Capture
PayPal Authorization & Capture is a settlement solution that provides merchants increased
flexibility in obtaining payments from their buyers. During a traditional sale at PayPal, the
authorization and capture action is completed simultaneously. PayPal Authorization &
Capture separates the authorization of payment from the capture of the authorized payment.
Authorization & Capture is for merchants who have a delayed order fulfillment process and
who typically make a $1 USD authorization at checkout. It enables merchants to modify the
original authorization amount due to order changes occurring after the initial order is placed
(such as taxes, shipping, or item availability). This chapter discusses the authorization and
capture process and provides steps to help you authorize, capture, reauthorize, and void funds.
There are two ways to use Authorization & Capture:
1. Create an order or authorization with Website Payments Standard HTML and capture or
void the authorization on the PayPal website (https://www.paypal.com/).
2. Use the Authorization & Capture Application Programming Interface (API), which is not
discussed in this book. For more information about the Authorization & Capture API, see
the Website Payments Pro Integration Guide.
Basic Authorization Process

Authorization & Capture starts when your buyer authorizes a payment amount during
checkout.
1. For example, you can send your buyer through the Website Payments payment flow,
passing in the paymentaction variable set to authorization or order.
2. After your buyer completes checkout, you can then use the payment’s transaction ID with
Authorization & Capture in the PayPal website (https://www.paypal.com). You can:
– Capture either a partial amount or the full authorization amount.
– Authorize a higher amount, up to 115% of the originally authorized amount (not to
exceed an increase of $75 USD).
– Void a previous authorization.
Honor Period and Authorization Period

When your buyer approves an authorization, the buyer’s balance can be placed on hold for a
29-day period to ensure the availability of the authorization amount for capture. You can
reauthorize a transaction only once, up to 115% of the originally authorized amount (not to
exceed an increase of $75 USD).

Using Authorization & Capture
6
Basic Authorization & Capture Scenarios
After a successful authorization (or reauthorization), PayPal will honor authorized funds for
three days, but PayPal cannot ensure that 100% of the funds will be available. A day is defined
as the start of the calendar day on which the authorization or reauthorization was made (from
12AM PST to 11:50PM PST).
You can settle without a reauthorization from day 4 to day 29 of the authorization period, but
PayPal cannot ensure that 100% of the funds will be available after the three-day honor period.
However, PayPal will not allow you to capture funds if the buyer’s account is restricted,
locked, or a fraudulent case occurs, or if your account has a high restriction level. You can use
Authorization & Capture only when your account has a low restriction level.
The honor period and authorization period for authorizations are described below:
If you attempt to capture funds outside the honor period, PayPal applies best efforts to capture
funds. However, there is a possibility that funds will not be available at that time.
The accounts of buyers and merchants cannot be closed if there is a pending (unsettled)
authorization.
Supported PayPal Payment Products
You can use Authorization & Capture with the PayPal products listed in Table 6.1 , “PayPal
Products Supporting Authorization & Capture.”
By default, these products assume that a transaction is a final sale. You must explicitly specify
that a transaction is a basic or order authorization.
N O T E : Youmust capture and void orders and order authorizations using the Authorization &
Capture APIs. That is, you cannot process order authorizations on the PayPal website
(https://www.paypal.com). The PayPal website supports processing only basic
authorizations, not order authorizations.
TABLE 6.1 PayPal Products Supporting Authorization & Capture
Product Typical Usage
Website Payments paymentaction=”authorization”
Buy Now paymentaction=”authorization”
Donations paymentaction=”authorization”
Shopping carts paymentaction=”authorization”

Included here are examples of some common scenarios you might encounter when
implementing basic authorizations and captures.

6
Capturing A Single Authorization

If you have authorized a transaction, you need to capture the funds in order to receive
payment.
N O T E : PayPal
recommends that you capture payments within three days of the original
authorization.
To initiate a capture:
1. Go to the History of your account on https://www.paypal.com.
2. Click the Capture button associated with the transaction.
3. Review the information on the Capture Funds page, enter the amount to capture, and then
click the Capture Funds button.
The funds are transferred to your account.
Batch Capturing Multiple Authorizations

On https://www.paypal.com, you can initiate the capture of an entire group of authorized
transactions at the same time. This feature is known as batch capture.
To capture a batch of authorized transactions:
1. Go to the History of your account on https://www.paypal.com.
2. Click the Capture button associated with any transaction.
3. On the displayed page, click the Batch Capture link that is located in the introductory
paragraph.
4. On the displayed page, either use the dropdown menu to choose a defined date or date
range, or enter a specific date range in the provided fields.

6
5. On the displayed page, check the authorizations you want to capture, set their capture
amount, choose whether you will make an additional capture later, and optionally enter a
note to the buyer.
6. Review the capture transactions, make any desired changes, and submit them for
processing.
Voiding an Authorization
If you initiated an authorization and now want to refund the buyer, you need to void the
authorization. Once you void an authorization, you cannot capture any funds associated with
the authorization, and the funds are returned to the buyer.
N O T E : Voiding an authorization cancels the entire open amount.
You can initiate a void in the following cases:
z The authorization is pending
z The authorized amount was captured at less than 100%

6
To void an authorization:
1. Click the Void button associated with the authorization.
2. Confirm the void details on the Void Authorization page, and then click the Void button.
N O T E : PayPal
recommends that you explain any unique circumstance to your buyer in the
Note field.
PayPal sends the buyer an email with the details of the voided authorization.
Capture Within 3 Days

1. Your buyer orders a camera from your website.
2. Your buyer enters payment information and authorizes payment.
3. Send your buyer to PayPal using a hosted flow, specifying the variable
paymentaction=authorization
4. PayPal initiates the authorization.
5. On day 3, you ship the camera and capture funds.
After you have captured funds, your Transaction Details shows the transaction with a
Completed status.
FIGURE 6.1 Transaction Details: Completed Transaction
Capture From 4 - 29 Days

1. Your buyer orders a DVD player from your website.
paymentaction=authorization.

6

5. The DVD player is discontinued. You order a different DVD player from your vendor and
notify your buyer of the change.
6. On day 14, the DVD player arrives from your vendor. Because the honor period has passed,
you complete a reauthorization for payment.You ship the DVD player and complete the
final capture.
Your Transaction Details shows that the transaction has been completed.
FIGURE 6.2 Transaction Details: Reauthorization, Final Capture
One Authorization, Multiple Captures, and a Refund

1. Your buyer orders two textbooks and a keyboard from your website.
5. One textbook and the keyboard are out of stock. You order additional inventory from your
vendors. You ship the in-stock textbook and capture the first partial capture on day 6.
6. You receive the second textbook from the vendor. You ship the textbook and capture the
second partial capture on day 11.
7. You receive the keyboard from the vendor. You reauthorize for payment on day 19.

6
8. Your buyer files a complaint that the textbook from the first shipment is damaged. You
issue a partial refund for the first capture.
Your Transaction Details shows the following:
FIGURE 6.3 Transaction Details: Partial Capture, Reauthorization, Refund
Lower Capture Amount

1. Your buyer orders a laser printer and a USB cable from your website.
5. Before you process the transaction, your buyer contacts you and requests to cancel the USB
cable from the order.
6. On day 6, you ship the laser printer and complete a partial capture for an amount less than
the original authorization amount.
7. You complete a void on the funds remaining on the authorization.

6
Your Transaction Details shows the following:
FIGURE 6.4 Transaction Details: Partial Capture, Voided Transaction
Capture Up to 115%
1. Your buyer places an order from your website.
5. You add shipping charges to the order and capture funds on day 1.
Your Transaction Details shows the completed transaction. The capture results in a total not
greater than 115% of the original authorization.

6
FIGURE 6.5 Transaction Details: Capture up to 115%
Authorization Expires
1. Your buyer orders a desktop computer from your website.
5. Before you process the transaction, your buyer contacts you to cancel the order.
6. You do not capture funds for the transaction.
7. The authorization expires.
Your Transaction Details shows the authorization with an Expired status.

6
FIGURE 6.6 Transaction Details: Expired Authorization
Void
1. Your buyer orders a stereo system from your website.
5. Before you process the transaction, your buyer contacts you to cancel the order.
6. You void the transaction.
Your History shows the transaction with a Voided status.

6
FIGURE 6.7 History: Voided Transaction
Reattempted Capture
1. Your buyer orders two sweatshirts from your website.
5. On day 3, you attempt to capture funds, but the capture fails. You receive an error message
similar to the following:
We are sorry, we cannot process the settlement at this time.
There was a restriction on the buyer’s account.
6. You contact the buyer to resolve the problem.
7. Your buyer resolves the account problem.
8. You reattempt and successfully capture funds. You ship the order to your buyer.
N O T E : The reauthorization scenario is similar to the Reattempted Capture scenario, as detailed
above.

6
Recommendations for Best Use of Authorization & Capture
Recommendations for Best Use of Authorization & Capture

Here are recommendations to ensure the best experience for buyers and to get the most from
Authorization & Capture.
Capturing Funds on Basic Authorizations

PayPal recommends that you capture funds within the honor period of three days because
PayPal will honor the funds for a 3-day period after the basic authorization. If you attempt to
capture funds after the three-day period and the authorization fails, your request to capture
funds may be declined.
After day 4 of the authorization period, you can initiate a reauthorization, which will start a
new three-day honor period. However, it will not extend the original authorization period past
29 days. For example, if you successfully complete a reauthorization on day 29 of the
authorization period, funds will only be honored until the end of the 29th day, and a new three-
day honor period will start but not extend beyond day 29.
You should capture funds within 24 hours after you ship your buyer’s order.
Buyer Approval for Basic Authorizations

A buyer-initiated authorization allows you to capture funds from the buyer’s account up to
115% of the originally authorized amount (not to exceed an increase of $75 USD) and up to
$10,000 USD.
IMPO RTANT: If you want to update any details of the purchase that change the original
authorization amount, PayPal requires that you obtain consent from the buyer
at the time of purchase or at the time of capture.
Voiding Basic Authorizations

You should void an authorization if the authorization or reauthorization will not be used.
Voiding the authorization unlocks the temporary hold placed on your buyer’s funding sources.

7 Issuing Refunds
When you issue a refund, the gross amount of the refund is sent to the buyer. The gross amount
equals the net amount of the original transaction plus the refunded fee from PayPal.
Gross Amount = Net Amount + Refund Fee
Refunding Within 60 Days of Payment

You can refund the entire amount of a transaction or portions of it. If you issue a refund within
60 days, the original transaction fee for receiving the payment is credited to your account. For
partial refunds, you are credited a percentage of the original transaction fee based on the
refunded amount.
To issue a refund within 60 days:
1. Log in to your PayPal account.
2. Click the History subtab.
3. Find the payment transaction you want to refund.
4. Click the Details link for the transaction.
5. Click the Refund Payment link on the Transaction Details page.
6. Enter the refund amount and click the Submit button.
7. Confirm the refund amount and click the Process Refund button.
If you refund a pending eCheck payment, no fees are charged because the pending payment is
effectively canceled.
Refunding After 60 Days

When you issue a refund after 60 days, your original transaction fee for receiving the payment
is not credited to your account.
To issue a refund after 60 days:
1. Log in to your PayPal account.
2. Click the Send Money tab.
3. Enter the required information.

Issuing Refunds
7
Refunding After 60 Days
4. Click the Continue button.

5. Review the information on the confirmation page, and click the Send Money button to
complete the refund.

8 Securing Your Website Payments
Standard Buttons
Because non-encrypted buttons are in clear text in the source view of your webpages, the
button code can be viewed by anyone. A malicious user could copy a page, change button
variables such as price, and make a fraudulent payment.
buttons.
PayPal provides the following strategies for securing Website Payments Standard buttons. Use
one or more of the following security strategies to prevent and/or detect tampering with your
buttons:
Creating an Encrypted Button on the Create an encrypted button by using a button creation tool
PayPal Website on the PayPal website.
Best if you sell just a few items and don’t need to change
pricing often. This is also the easiest way to secure your
buttons.
Verifying Each Payment Manually Manually check the price of each payment in your PayPal
account before shipping.
Good if you accept donations or you sell items individually
with prices thad do not change. You can review transaction
history on the PayPal website, or you can download a
transaction report from the PayPal website.
You are required to reconcile your payments, especially if
you have non-encrypted buttons.
Verifying Payments with Instant With Instant Payment Notification (IPN), PayPal posts a
Payment Notification (IPN) message to your server when someone pays you.
You are required to reconcile your payments, especially if
you have non-encrypted buttons. With IPN, you can
automate the reconciliation process or perform it manually.
Encrypting Buttons Dynamically Using a script and open-source libraries from OpenSSL,
With Encrypted Website Payments encrypt your buttons dynamically when rendering your
(EWP) webpages.
Good if you have previously built a custom payment
solution by using Buy Now or Donation buttons, or you are
using Add to Cart buttons with the PayPal Shopping Cart.
You must be comfortable programming in scripts like PHP
and ASP to use EWP.
Blocking Non-encrypted Website To add extra security to your encrypted buttons, update your
Payments PayPal account to block non-encrypted payments.

Securing Your Website Payments Standard Buttons
8
Creating an Encrypted Button on the PayPal Website
Creating an Encrypted Button on the PayPal Website

A simple way to make an encrypted button is to use a button creation tool on the PayPal
website. You can create encrypted Buy Now and Donation buttons by using a tool.
1. Log in to your Business or Premier account.
3. Click the Buy Now Button link or the Donate link, depending on the kind of encrypted
button that you want to create.
4. Enter details about your button, and choose a button image.
5. In the Security Settings section, select the Yes radio button to encrypt your button. This is
the default setting.
6. Click the Create Button Now button to generate the encrypted HTML code.
– or –
Click the Add More Options button to enter optional details about your button.
N O T E : Some
settings on the Add More Options page require that you change Security
Settings to No. In such cases, you will have to use an alternative strategy to secure
your buttons. See “Verifying Each Payment Manually” on page 144, and “Verifying
Payments with Instant Payment Notification (IPN)” on page 145.
7. Update the profile settings on your PayPal account to block non-encrypted website
payments, as described in “Blocking Non-encrypted Website Payments” on page 150.
Verifying Each Payment Manually

If you process a small number of transactions, you can verify each payment manually through
your transaction history and the reporting tools provided by PayPal.
To verify payments found in your transaction history:
2. In the My Account tab, click the History subtab.
3. In the Show dropdown menu, select “Payments Received”.
4. Specify a time frame for the payments you want to verify.
5. Click the Search button.
6. For each payment that was found, verify that the item amounts match the amounts you
charge.

8
Verifying Payments with Instant Payment Notification (IPN)
For detailed instructions on using the History subtab, see the Order Management Integration
Guide.
Verifying Payments with Instant Payment Notification (IPN)

With Instant Payment Notification (IPN), PayPal posts a message to your server when
someone pays you. You specify the URL through which you receive IPN messages in your
PayPal account. The IPN message is a text file that includes payment details, such as the name
of the payer and the amount paid. Verify the IPN amount by comparing it with the price of the
product in your database. You can automate this process by checking field values against your
database.
To learn more about IPN, see the Order Management Integration Guide.
Encrypting Buttons Dynamically With Encrypted Website

Payments (EWP)
To make online payments more secure, you can make Encrypted Website Payment (EWP)
buttons that rely on standard public key encryption for protection. With public and private
keys, you dynamically generate HTML code for payment buttons and encrypt the payment
details before displaying the buttons on your website.
EWP works in the following way.
TABLE 8.1 How Encrypted Website Payments Works
Website Actions Payer Actions PayPal Actions

Generate a public key for the website, upload it
to PayPal, and download the PayPal public
certificate to the website.
Generate HTML code for a payment button.
Encrypt the generated code by using the
PayPal public key and then signing the
encrypted code with the website’s private key.
Publish the signed, encrypted HTML code for Click the published PayPal Check the authenticity of the data
the payment button to the website. payment button. by using the merchant’s public
key previously uploaded to
PayPal.
Decrypt the protected button
code by using the PayPal private
key.

8
Encrypting Buttons Dynamically With Encrypted Website Payments (EWP)
TABLE 8.1 How Encrypted Website Payments Works
Website Actions Payer Actions PayPal Actions

Redirect the payer’s browser to
the PayPal payment page
sequence, as specified in the
HTML variables of the decrypted
button code.
Prerequisites to Using EWP

This section describes how to generate your private and public keys for EWP, upload your
public key to PayPal, and download a copy of the PayPal public key:
z Generate a private key
z Generate a public certificate
z Upload your public certificate to the PayPal website at https://www.paypal.com/us/cgi-
bin/webscr?cmd=_profile-website-cert
z Download the PayPal public certificate from https://www.paypal.com/us/cgi-
bin/webscr?cmd=_profile-website-cert
Public Key Encryption Background

Public key encryption (asymmetric encryption) improves security and convenience by
allowing senders and receivers to have separate public and private encryption keys:
z The public key: The public key is the portion of an asymmetric cryptographic key that
receivers give senders who want to send them encrypted information. I
z The private key: The private key is the portion of an asymmetric cryptographic key
receivers keep secret and do not send to anyone. The public certificate: The public
certificate consists of the public key and identity information, such as a person's name,
which could be signed by a certificate authority (CA). The CA guarantees that the public
key belongs to the named entity.
z The encryption process: Sender use both their private key and the receivers’ public key to
encrypt the information. Receiver use their private key and the senders’ public key to
decrypt the information that was encrypted. This encryption process is also used with
digital signatures to verify the origin of the information.
Setting Up The Certificates

EWP requires that you upload your public certificate to the PayPal website so that the
authenticity of the encrypted code can be verified.
PayPal accepts only X.509 public certificates, not public keys. The difference between a key
and a certificate is that a certificate includes the public key along with information about the

8
key, such as when the key expires and who the key belongs to. PayPal accepts public
certificates in OpenSSL PEM format from any established certificate authority, such as
VeriSign.
You can also generate your own private key and public certificate using open source software
such as OpenSSL (http://www.openssl.org), which is detailed in the following section.
Creating Your Private Key Using OpenSSL
Using the openssl program, enter the following command to generate your private key. The
command generates a 1024-bit RSA private key that is stored in the file my-prvkey.pem:
openssl genrsa -out my-prvkey.pem 1024
Creating Your Public Certificate Using OpenSSL

The public certificate must be in PEM format. To generate your certificate, enter the following
openssl command, which generates a public certificate in the file my-pubcert.pem:
openssl req -new -key my-prvkey.pem -x509 -days 365 -out my-pubcert.pem
Uploading Your Public Certificate

To upload your public certificates to the PayPal website:
1. Log in to your Business or Premier PayPal account.
3. In the Seller Preferences column, click the Encrypted Payment Settings link.
The Website Payment Certificates page appears.
4. Scroll down the page to the Your Public Certificates section, and click the Add button.
The Add Certificate page appears.
5. Click the Browse button, and select the public certificate that you want to upload to PayPal
from your local computer.
N O T E : The file you upload must be in PEM format.
6. Click the Add button.
After your public certificate is uploaded successfully, it appears in the Your Public
Certificates section of the Website Payment Certificates page.

8
7. Store the certificate ID that PayPal assigned to your public certificate in a secure place.
You need the certificate ID that PayPal assigned to encrypt your payment buttons by using
the Encrypted Website Payments program provided by PayPal.
Downloading the PayPal Public Certificate
To download the PayPal public certificate:
1. Log in to your Business or Premier PayPal account.
4. Scroll down the page to the PayPal Public Certificate section.
5. Click the Download button, and save the file in a secure location on your local computer.
Removing Your Public Certificate
IMPO RTANT: If you remove your public certificate, its associated certificate ID is no longer
valid for encrypting buttons, and any buttons made by your website that use
the ID will not function correctly.
To remove one or more of your public certificates:
4. Scroll down the page to the Your Public Certificates section.
5. Select the radio button next to the certificate you want to remove, and click the Remove
button.
The Remove Certificate page appears.
6. Click the Remove button to confirm the removal of the public certificate that you selected.

8
Encrypting Your HTML Code

PayPal provides Java and Microsoft Windows software to encrypt your Website Payments
Standard HTML Form variables. Download a program from the following location:
https://www.paypal.com/us/cgi-bin/webscr?cmd=p/xcl/rec/ewp-code
After you download and extract the software, copy your private key, public certificate, p12 file
and the PayPal public certificate to the folder where the software is located.
1. Prepare an input file of Website Payments Standard variables and values for each encrypted
button you want to generate. Each variable and value must be on its own separate line, as in
the following example.
N O T E : The
cert_id variable identifies the public certificate you uploaded to PayPal
website.
cert_id=Z24MFU6DSHBXQ
cmd=_xclick
[email protected]
item_name=Handheld Computer
item_number=1234
custom=sc-id-789
amount=500.00
currency_code=USD
tax=41.25
shipping=20.00
address_override=1
address1=123 Main St
city=Austin
state=TX
zip=94085
country=US
no_note=1
cancel_return=http://www.company.com/cancel.htm
2. Run the encryption program. with the appropriate syntax shown in Table 8.2 , “Command
Line Syntax for PayPal Encrypted Website Payments Software.”
3. Copy the encrypted code to your website.
TABLE 8.2 Command Line Syntax for PayPal Encrypted Website Payments Software
Software Command Line

Java java ButtonEncryption CertFile PKCS12File PPCertFile Password InputFile OutputFile [Sandbox]
Microsoft PPEncrypt CertFile PrivKeyFile PPCertFile InputFile OutputFile [Sandbox]
Windows

8
Blocking Non-encrypted Website Payments
where:
TABLE 8.3 Description of Arguments for EWP Commands
Argument Description
CertFile The pathname to your own public certificate
PKCS12File The pathname to the PKCS12-format of your own public certificate
PPCertFile The pathname to a copy of the PayPal public certificate
Password The passphrase to the PKCS12-format of your own public certificate
InputFile The pathname to file containing the non-encrypted Website Payments

HTML Form variables
OutputFile A file name for the encrypted output
[Sandbox] The optional word Sandbox to test EWP code in the PayPal Sandbox
Blocking Non-encrypted Website Payments

For extra security of your encrypted buttons, update your PayPal account profile to block non-
encrypted payments.
To block payments from non-encrypted Website Payments Standard buttons:
3. In the Selling Preferences column, click the Website Payment Preferences link.
4. Scroll down to the Encrypted Website Payments section.
5. Next to the Block Non-encrypted Website Payment label, select the On radio button.

9 Testing in the PayPal Sandbox
The PayPal Sandbox can be used to test the following functionality.
IMPO RTANT: The Sandbox does not process real money.

z Buy Now buttons: Test single-item payments. For more information, see Chapter 3,
“Single-Item Payment: Buy Now Buttons.”
z Shopping Cart buttons: Test multiple-item payments in a single purchase transaction. For
more information, see Chapter 4, “Multiple-Item Payment: Shopping Carts.”
z Donation buttons: Test contribution payments. For more information, see Chapter 5,
“Contribution Payment: Donation Buttons.”
z Refunds: Test the refunding of money paid by PayPal members.
z Instant Payment Notification (IPN): Test such IPN notifications as payments and
reversals. For more information about implementing IPN, see the Order Management
Integration Guide.
In the Sandbox environment, IPN notifications include the special variable ipn_test,
with the value 1. This variable provides clear differentiation between live and test IPN and
allows developers to modify existing scripts to work more easily with both.
IMPO RTANT: IPN notifications coming from the Sandbox cannot be verified against the
live PayPal website, and IPN notifications coming from the live PayPal
website cannot be verified against the Sandbox.
z Payment Data Transfer (PDT): Test your identity token, return URL, and PDT settings.
For more information about implementing PDT, see the Order Management Integration
Guide.
z Simulated transactions: Test scenarios, such as successful and failed eChecks.
To test in the Sandbox, you must first create a Developer Central account. With this account,
you can create multiple PayPal test accounts for buyers and merchants to simulate different
scenarios.
For complete details about using Developer Central and the Sandbox, see the Sandbox User
Guide.

Testing in the PayPal Sandbox
9

10 HTML Form Basics for Website
Payments Standard
This chapter describes in technical terms the basic functionality of Website Payments Standard
and its use of HTML Forms. Use the information in this chapter as a guide to writing the
HTML code yourself for Website Payments Standard payment buttons. A wide variety of
HTML authoring tools exist. This guide does not describe all the possibilities.
People who pay you through Website Payments Standard interact with HTML forms and
hidden HTML input variables that you place on your website. When someone clicks a
payment button in an HTML form on a webpage, the form submits the variables and their
values to PayPal. You set the values of the variables to produce the desired effect, such as
invoking the Buy Now, the PayPal Shopping Cart, or the Donation payment page sequences
and various other PayPal features.
N O T E : The
PayPal website offers tools that let you create the HTML code for Buy Now,
PayPal Shopping Cart, and Donation buttons. For more information, see Chapter 3,
“Single-Item Payment: Buy Now Buttons”, Chapter 4, “Multiple-Item Payment:
Shopping Carts”, and Chapter 5, “Contribution Payment: Donation Buttons”.
Form Attributes: ACTION and METHOD

The FORM tag includes two required attributes, action and method, which always looks like
this:
<FORM action="https://www.paypal.com/cgi-bin/webscr" method="post">
IMPO RTANT: Do not change these values.These attributes are required for all Buy Now
buttons, shopping cart buttons, and Donation buttons.
Hidden Input Variables

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

HTML Form Basics for Website Payments Standard
10
Specifying the Website Payments Standard Product: cmd
Specifying the Website Payments Standard Product: cmd

The cmd variable is always required in a FORM. Its value determines which Website Payments
Standard payment page sequence you are using to obtain payment.
TABLE 10.1 Allowed Values for cmd Variable
Value of cmd Description
_xclick For Buy Now buttons
_cart For shopping cart buttons; use these additional variables to specify the specific
shopping cart action of the button:
z add="1" for Add to Cart buttons used with the PayPal Shopping Cart
z display="1" for View Cart buttons used with the PayPal Shopping Cart
z upload="1" for third party shopping carts that upload to PayPal
_donations For Donation buttons
The input tag looks like one of the following:

z Buy Now buttons: <INPUT TYPE="hidden" name="cmd" value="_xclick">
z Shopping cart buttons: <INPUT TYPE="hidden" name="cmd" value="_cart">
z Donation buttons: <INPUT TYPE="hidden" name="cmd" value="_donations">
IMPO RTANT: These INPUT tags are required exactly as shown above. Do not alter them.
Variations on Basic Variables

This section highlights some useful miscellaneous ideas about Website Payments Standard
FORM variables.
The HTML variables interact in various ways. Sometimes their effect is cumulative,
sometimes they can cancel each other out, sometimes a variable requires that you also set
another variable. These interactions are detailed in the descriptions of the variables in
Appendix A, “HTML Variables for Website Payments Standard” and Appendix B, “Address
Handling (U.S. Merchants Only).”
Prompting for Quantity in Buy Now Buttons: undefined_quantity

With Buy Now buttons, you can require buyers to specify the desired quantity of the item by
using the undefined_quantity HTML variable:
<INPUT TYPE="hidden" name="undefined_quantity" value="1">

10
Variations on Basic Variables
Record Keeping with Passthrough Variables

Some variables are exclusively for your own use (such as for tracking orders) and are not
recorded or used by PayPal. The values that you send to PayPal are returned to you through
Instant Payment Notification (IPN) exactly as you set them. For this reason, they are called
passthrough variables.
The following are passthrough variables:
z custom
z item_number or item_number_x
z invoice
Setting the Character Set: charset

You can use the charset HTML variable to specify the character set or character encoding of
the data you collect in your website forms and send to PayPal. PayPal sends data to you in the
same character set or encoding you specify with the charset variable. For example, the
following INPUT tag sets the encoding to UTF-8:
<INPUT TYPE="hidden" name="charset" value="utf-8">
TABLE 10.2 Character Sets and Encodings Supported by PayPal
Big5 (Traditional ISO-2022-JP ISO-8859-8 UTF-16BE US-ASCII windows-1258

Chinese in Taiwan) ISO-2022-KR ISO-8859-9 UTF-16LE windows-1250 windows-874
EUC-JP ISO-8859-1 ISO-8859-13 UTF16_Platfor windows-1251 (Thai)
EUC-KR (Western ISO-8859-15 mEndian windows-1252 windows-949
EUC-TW European KOI8-R UTF16_Oppos windows-1253 (Korean)
gb2312 (Simplified Languages) (Cyrillic) iteEndian x-mac-greek
windows-1254
Chinese) ISO-8859-2 Shift_JIS UTF-32 x-mac-turkish
windows-1255
gbk ISO-8859-3 UTF-7 UTF-32BE x-mac-
windows-1256
HZ-GB-2312 ISO-8859-4 UTF-8 UTF-32LE centraleurroman
windows-1257
(Traditional ISO-8859-5 UTF-16 UTF32_Platfor x-mac-cyrillic
Chinese in Hong ISO-8859-6 mEndian ebcdic-cp-us
Kong) ISO-8859-7 UTF32_Oppos ibm-1047
ibm-862 (Hebrew iteEndian
with European
characters)
ISO-2022-CN
Setting The Return URL on Individual Transactions

With Auto Return turned on in your account profile, you can set the value of the return URL
on each individual transaction to override the value that you have stored on PayPal. For
example, you might want to return the payer’s browser to a URL on your site that is specific to
that payer, perhaps with a session ID or other transaction-related data included in the URL.

10
Prepopulating FORMs
To set the return URL for a transaction, include the return variable in the HTML FORM:
<INPUT TYPE="hidden" NAME="return" value="URLspecificToThisTransaction">
Desired Currency on Individual Transactions

Use the currency_code variable on individual transactions to specify the currency of the
payment:
<INPUT TYPE="hidden" NAME="currency_code" value="CurrencyCode">
The value of currency_code must be a code from Table 2.6, “Currencies Allowed for
Transactions and Balances,” on page 73.
N O T E : If the currency_code variable is not included, the currency USD is used.
Prepopulating FORMs
With Account Optional turned on in your account profile, you can accept payments from
people without a PayPal account. However, checking out with PayPal is often faster than
forcing people to re-enter information that is stored on PayPal. For repeat customers, it is to
your advantage to get people to sign up for their own PayPal accounts.
During a payment transaction, you can prepopulate a FORM by including HTML input
variables specifically for this purpose. A complete description of these variables is found in
“HTML Variables for Prepopulating PayPal Payment Pages” on page 171.
For a detailed description of how prepopulated forms and other settings affect the PayPal
Sample HTML for FORM Prepopulation

The following sample HTML code shows the optional prepopulation fields with the required
variables in payment buttons. Your website dynamically generates the field entries from
information that your website gathered about the payer and includes the fields and their values
in the URL to which payers are sent when they click a payment button.
EXAMPLE 10.1 HTML Code for FORM Prepopulation

<input type="hidden" name="item_name" value="hat">
<input type="hidden" name="amount" value="15.00">
<input type="hidden" name="first_name" value="John">
<input type="hidden" name="last_name" value="Doe">
<input type="hidden" name="address1" value="9 Elm Street">
<input type="hidden" name="address2" value="Apt 5">

10
Overriding Addresses Stored with PayPal
<input type="hidden" name="city" value="Berwyn">

<input type="hidden" name="state" value="PA">
<input type="hidden" name="zip" value="19312">
<input type="hidden" name="night_phone_a" value="610">
<input type="hidden" name="night_phone_b" value="555">
<input type="hidden" name="night_phone_c" value="1234">
</form>
Overriding Addresses Stored with PayPal

For people who already have PayPal accounts and whom you already prompted for a shipping
address before they choose to pay with PayPal, you can use the entered address instead of the
address the person has stored with PayPal. Set the address_override variable to 1, as in
the following example:
<INPUT TYPE="hidden" name="address_override" value="1">
You must also include FORM variables that contain the person’s address information, as
detailed in “HTML Variables for Prepopulating PayPal Payment Pages” on page 171.”
The payer is shown the passed-in address but cannot edit it. No address is shown if the address
is not valid, such as missing required fields like country, or if the address is not included at all.
For a detailed description of how overriding the address and other settings affect the PayPal
Sample HTML for Overriding Addresses Stored with PayPal

The following HTML code shows the address_override variable in conjunction with the
prepopulation variables for overriding a payer’s address that is stored with PayPal.
EXAMPLE 10.2 HTML for Overriding Addresses Stored with PayPal

<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="item_name"
value="Memorex 256MB Memory Stick">
<input type="hidden" name="item_number" value="MEM32507725">
<input type="hidden" name="amount" value="3">
<input type="hidden" name="tax" value="1">
<input type="hidden" name="quantity" value="1">
<input type="hidden" name="no_note" value="1">

<input type="hidden" name="address_override" value="1">

10
Instant Payment Notification: notify_url


<input type="hidden" name="first_name" value="John">
<input type="hidden" name="last_name" value="Doe">
<input type="hidden" name="address1" value="345 Lark Ave">
<input type="hidden" name="city" value="San Jose">
<input type="hidden" name="state" value="CA">
<input type="hidden" name="zip" value="95121">
<input type="hidden" name="country" value="US">
</form>

Instant Payment Notification consists of three parts:
1. Someone pays you.
2. PayPal POSTs FORM variables to a URL you specify that runs a program to process the
variables.
3. You validate the notification.
FIGURE 10.1 How IPN Works: Three General Steps
1. A payment or a refund triggers IPN. This payment can be via Website Payments Standard
FORMs or via the PayPal Web Services APIs for Express Checkout, MassPay, or
RefundTransaction. If the payment has a “Pending” status, you receive another IPN when
the payment clears, fails, or is denied.

10
2. PayPal posts HTML FORM variables to a program at a URL you specify. You can specify
this URL either in your account profile or with the notify_url variable on each
transaction. This post is the heart of IPN. Included in the notification is the payment
information, such as the payer’s name and the amount paid. All possible variables in IPN
posts are detailed in the Order Management Integration Guide.When your server receives a
notification, it must process the incoming data.
3. Your server must then validate the notification to ensure that it is legitimate. For details, see
the Order Management Integration Guide.

10

A HTML Variables for Website
Payments Standard
This appendix provides reference information for all HTML variables supported for use with
Buy Now, Add to Cart, View Cart, and Donation buttons, as well as HTML variables
supported for use by third party shopping carts and custom carts that integrate PayPal by using
Website Payments Standard.
Variables are grouped by:
z “Technical HTML Variables” on page 161
z “HTML Variables for Individual Items” on page 162
z “HTML Variables for Payment Transactions” on page 164
z “HTML Variables for Shopping Carts” on page 166
z “HTML Variables for Displaying PayPal Payment Pages” on page 169
z “HTML Variables for Prepopulating PayPal Payment Pages” on page 171
Technical HTML Variables

Technical HTML variables control how PayPal responds technically when people click Buy
Now, Add to Cart, View Cart, and Donation buttons or when third party shopping carts or
custom carts initiate payment processing.
TABLE A.1 Allowed Values for the cmd HTML Variable
Value of cmd Description
_xclick The button that the person clicked was a Buy Now button.
_cart The button that the person clicked was an Add to Cart button or a
View Cart button for the PayPal Shopping Cart, or the command was
sent by a third party shopping cart or a custom cart uploading the
cart contents to PayPal.
_oe-gift-certificate The button that the person clicked was a Gift Certificate button.
_donations The button that the person clicked was a Donation button.
_s-xclick The button that the person clicked is protected from tampering by
using encryption.

HTML Variables for Website Payments Standard
A
HTML Variables for Individual Items
TABLE A.2 HTML Variables: IPN Control notify_url
Required or Character
Name Description Optional Length
notify_url The URL to which PayPal posts information about the Optional 255
transaction.

HTML variables for individual items specify information about a product or service for Buy
Now and Add to Cart buttons, or they specify information about a contribution for Donation
buttons.
TABLE A.3 HTML Variables: Item Information
Required
or Character
amount The price or amount of the product, service, or contribution, not See
including shipping, handling, or tax. If omitted from Buy Now or description
Donation buttons, payers enter their own amount at the time of .
payment.
z Optional for Buy Now or Donation buttons
z Required for Add to Cart buttons
item_name Description of item. If omitted in Buy Now or Donation buttons, See 127
payers enter their own name at the time of payment. description
z Optional for Buy Now or Donation buttons .
z Required for Add to Cart buttons
item_number Pass-through variable for you to track product or service Optional 127
purchased or the contribution made. The value you specify
passed back to you upon payment completion.
quantity Number of items. If profile-based shipping rates are configured Optional
with a basis of quantity, the sum of quantity values is used to
calculate the shipping charges for the transaction. PayPal
appends a sequence number to uniquely identify the item in the
PayPal Shopping Cart (e.g., quantity1, quantity2).
N O T E : The value for quantity must be a positive integer. Null,
zero, or negative numbers are not allowed.
undefined_ 1: allows buyers to specify the quantity. Optional 1
quantity z Optional for Buy Now buttons
z Not allowed for Add to Cart buttons

A
TABLE A.3 HTML Variables: Item Information
Required
or Character
weight Weight of items. If profile-based shipping rates are configured Optional
with a basis of weight, the sum of weight values is used to
calculate the shipping charges for the transaction.
weight_unit The unit of measure if weight is specified. Possible values are: Optional
z lbs
z kgs
Defaults to lbs.
on0 First option field name. If omitted, no variable is passed back to Optional 64
you. The os0 variable contains the corresponding value for the
label specified in this variable. For example, if on0 is size, os0
could be large.
on1 Second option field name. If omitted, no variable is passed back Optional 64
to you. The os1 variable contains the corresponding value for
the label specified in this variable. For example, if on1 is color
then os1 could be blue.
os0 Option selected by the buyer from the first set of option values. If Optional 64 or 200
this option is selected through a text box or radio button, each See
value should be no more than 64 characters. If buyers enter this description.
value in a text field, there is a 200-character limit. If omitted, no
variable is passed back to you.
N O T E : on0 must also be defined set. For example, it could be
size.
os1 Option selected by the buyer from the Second set of option Optional 64 or 200
values. If this option is selected through a text box or radio See
button, each value should be no more than 64 characters. If description.
buyers enter this value in a text field, there is a 200-character
limit. If omitted, no variable is passed back to you.
N O T E : on1 must also be set. For example, it could be color.

A
HTML Variables for Payment Transactions

HTML variables for payment transactions provide information about entire transactions,
regardless of the individual items involved with the payment. You can use these variables with
Buy Now, Donation, and View Cart buttons.
TABLE A.4 HTML Variables for Payment Transactions
Required
or Character
address_ 1: The address specified in prepopulation variables overrides the Optional 1
override PayPal member’s stored address. See Table A.8, “HTML
Variables for Prepopulating Payment Pages With Payer
Information.” The payer is shown the passed-in address but
cannot edit it. No address is shown if the address is not valid,
such as missing required fields like country, or is not included at
all,.
currency_ The currency of the payment. Defines the currency in which the Optional 3
code monetary variables (amount, shipping, shipping2, handling, tax)
are denoted.
Default: all monetary fields are interpreted as U.S. Dollars.
custom Passthrough variable never presented to the payer. Optional 256
Default: no variable is passed back to you.
handling Handling charges. This is not quantity-specific. The same Optional
handling cost applies, regardless of the number of items on the
order.
Default: no handling charges are included.
invoice Passthrough variable you can use to identify your invoice Optional 127
number for this purchase.

A
TABLE A.4 HTML Variables for Payment Transactions
Required
or Character
shipping The cost of shipping this item, if you enabled the override of Optional
automatic shipping calculations per transaction through your
Account Profile. If you specify shipping and shipping2 is
not defined, this flat amount is charged regardless of the quantity
of items purchased.
N O T E : If you use this variable, you do not need to set up
shipping rates in your Account Profile. However,
shipping rates you set up in your Profile take priority over
values specified with this variable, unless you select the
Override shipping methods per transaction
checkboxes in the shipping methods you defined; the
checkboxes are deselected by default. For more
information, see “Overriding Shipping Calculations
on Individual Transactions” on page 56.
Default: if profile-based shipping rates are configured, buyers are
charged an amount according to the shipping methods they
choose.
shipping2 The cost of shipping each additional item. If omitted and profile- Optional
based shipping rates are configured, buyers are charged an
amount according to the shipping methods they choose.
tax Transaction-based tax override variable. Set this to a flat tax Optional
amount to apply to the transaction regardless of the buyer’s
location. This value overrides any tax settings set in your account
profile. Default: Profile tax settings (if any) apply.
tax_cart Cart-wide tax, overriding any individual item tax_x value Optional
weight_cart If profile-based shipping rates are configured with a basis of Optional
weight, this value is used to calculate the shipping charges for the
transaction. This value overrides the weight values of
individual items.
weight_unit The unit of measure if weight_cart is specified. Possible Optional
values are:
z lbs
z kgs
Defaults to lbs.

A
HTML Variables for Shopping Carts

HTML variables for shopping carts can be used with Add to Cart and View Cart buttons, as
well as with third party shopping carts or custom carts that initiate payment processing.
TABLE A.5 HTML Variables for Shopping Carts
Required
or
Name Optional Description Allowable Values
add See Add an item to the PayPal Shopping Cart. 1
description This variable must be set as follows:
add=1
The alternative is the display=1 variable, which
displays the contents of the PayPal Shopping Cart
to the buyer.
If both add and display are specified, display
takes precedence.
amount Required Price of the item or the total price of all items in the Any valid currency
shopping cart. amount
business Required An email address associated with your PayPal Your email address
account.
display See Display the contents of the PayPal Shopping Cart 1
description. to the buyer. This variable must be set as follows:
display=1
The alternative is the add=1 variable, which adds
an item to the PayPal Shopping Cart.
If both add and display are specified, display
takes precedence.
handling_ Optional Single handling fee to be charged cart-wide. If Any valid currency
cart handling_cart is used in multiple Add to Cart amount
buttons, the handling_cart value of the first
item is used.
item_name Required Name of the item or a name for the entire Shopping
Cart

A
TABLE A.5 HTML Variables for Shopping Carts
Required
or
Name Optional Description Allowable Values
paymentaction Optional Indicates whether the transaction is payment on a sale
final sale or an authorization for a final sale, to be authorization
captured later using the PayPal Authorization & order
Capture API. The default value is sale. Set the
value to authorization to set up the
authorization for a single capture. Set the value to
order to set up the authorization for multiple
captures.
For more information, see the Website Payments
Pro Integration Guide.
I M P O R T A N T : If you set paymentaction to
authorization or order, you
must capture payment with the
Authorization & Capture API. You
cannot capture payments with the
merchant tools on PayPal.
upload See Upload the contents of a third party shopping cart 1
description or a custom shopping cart.
This variable must be set as follows:
upload=1
The alternatives are the add=1 variable and the
display=1 variable, which are used with the
PayPal Shopping Cart.
TABLE A.6 HTML Variables for Individual Items in Third Party Shopping Carts
Required
or Character
Name Optional Description Length
amount_x Required Price of item #x. This is only required if you specify
upload=1.
handling_x Optional The cost of handling for item #x.
item_name_x Required Name of item #x in the cart. Must be alphanumeric. 127
item_number_x Optional Passthrough variable for you to track order or other 127
purchase.
on0_x Optional First option field name for item #x 64
on1_x Optional Second option field name for item #x. 64

A
TABLE A.6 HTML Variables for Individual Items in Third Party Shopping Carts
Required
or Character
Name Optional Description Length
os0_x Optional First set of option value(s) for item #x. Requires that on0_x 200
also be set.
os1_x Optional Second set of option value(s) for item #x. Requires that 200
on1_x also be set.
quantity_x Optional Quantity of the item #x. If profile-based shipping rates are
configured with quantity as the basis, the sum of all
quantity_x values are used to calculate the shipping
charges.
N O T E : The value of quantity_x must be a positive
integer. Null, zero, or negative numbers are not
allowed.
shipping_x Optional The cost of shipping #x. This variable excludes the item
from automatic shipping calculations; the amount is added
to the shipping charges calculated automatically on other
items in the cart.
tax_x Optional The tax amount for item #x. This variable excludes the item
from automatic tax calculations; the amount is added to the
taxes calculated automatically on other items in the cart.
weight_x Optional The weight of item #x.
weight_unit Optional The unit of measure if weight_x is specified. Possible
values are:
z lbs
z kgs
Defaults to lbs.

A
HTML Variables for Displaying PayPal Payment Pages

HTML variables for displaying PayPal payment pages control how the pages appear and
function.
TABLE A.7 HTML Variables for Displaying PayPal Payment Pages
Required
or Character
cancel_ A URL to which the payer’s browser is redirected if payment is Optional 1,024
return cancelled; for example, a URL on your website that displays a
“Payment Canceled” page.
Default: Browser is redirected to a PayPal web page.
cbt Sets the text for the Continue button on the PayPal Payment Optional 60
Complete page.
N O T E : The return variable must also be set.
cn Label above the note field. This value is not saved and does not Optional 40
appear in any of your notifications. If omitted, no variable is
passed back to you.
cpp_header_ Sets the image at the top left of the payment page. The image’s Optional No limit
image maximum size is 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored only on a
secure (https) server. For more information, see “Branding the
PayPal Payment Pages” on page 25.
cpp_ Sets the background color for the header of the payment page. Optional
headerback_ Valid value is case-insensitive six-character HTML hexadecimal
color color code in ASCII.
cpp_ Sets the border color around the header of the payment page. The Optional
headerborder_ border is a 2-pixel perimeter around the header space, which has
color a maximum size of 750 pixels wide by 90 pixels high.
Valid value is case-insensitive six-character HTML hexadecimal
color code in ASCII.
cpp_payflow_ Sets the background color for the payment page below the Optional
color header. Valid value is case-insensitive six-character HTML
hexadecimal color code in ASCII.
N O T E : Background colors that conflict with PayPal’s error
messages are not allowed; in these cases, the default color
is white.
cs Sets the background color of your payment pages. Optional
Default or 0 = background color is white.
1 = background color is black.

A
TABLE A.7 HTML Variables for Displaying PayPal Payment Pages
Required
or Character
image_url The URL of the 150x50-pixel image displayed as your logo in Optional 1,024
the upper left corner of PayPal’s pages.
Default: your business name (if you have a business account) or
your email address (if you have premier account).
no_note Prompt payer to include a note with payment. Allowed values Optional 1
are:
z 0: (default) payer is prompted to include a note
z 1: payer is not prompted to include a note
no_shipping Prompt buyer for shipping address. Allowed values are: Optional 1
z 0: (default) buyer is prompted to include a shipping address.
z 1: buyer is not asked for a shipping address
z 2: buyer must provide a shipping address
page_style Sets the Custom Payment Page Style for payment pages Optional 30
associated with this button/link. Allowed values are:
z somePageStyleName: the name of a page style you have
defined
z primary: always use the page style set in the account profile
as primary.
z paypal: use the PayPal page style.
Alphanumeric ASCII lower 7-bit characters only, plus

underscore. No spaces.
return The URL to which the payer’s browser is redirected after Optional 1,024
completing the payment; for example, a URL on your site that
displays a “Thank you for your payment” page.
Default: payer is redirected to a PayPal web page.
rm “Return method”: FORM METHOD used to send data to the URL Optional 1
specified by the return variable after payment completion.
Allowed values are:
z 0: (default) all shopping cart transactions use the GET method
z 1: the payer’s browser is redirected to the return URL by the
GET method, and no transaction variables are sent
z 2: The payer’s browser is redirected to the return URL by the
POST method, and all transaction variables are also posted
N O T E : The rm variable takes effect only if the return variable
is also set.
shopping_url The value of the Continue Shopping button on PayPal: the URL Optional 255
on your site to which buyers will return when they click
Continue Shopping during purchase of merchant gift certificates
on PayPal. Valid only with Gift Certificate buttons.

A
HTML Variables for Prepopulating PayPal Payment Pages

HTML variables for prepopulating PayPal payment pages let you specify information about
the payer.
TABLE A.8 HTML Variables for Prepopulating Payment Pages With Payer Information
Character
Variable Description Requirements Limit
address1 Street (1 of 2 fields) Alphanumeric 100
address2 Street (2 of 2 fields) Alphanumeric 100
city City Alphanumeric 40
country Sets shipping and billing country. See Alphabetic 2
Appendix C for allowable country codes.
first_name First name Alphabetic 32
last_name Last name Alphabetic 64
lc Defines the payer’s language for the Login Alphabetic 2
page only.
Allowable values: any two-character
country code listed in Appendix C,
“Country Codes.”
Any other value will default to US.
night_ The area code for U.S. phone numbers, or Numeric
phone_a the country code for phone numbers
outside the U.S. This will prepopulate the
payer’s home phone number.
night_ The three-digit prefix for U.S. phone Numeric
phone_b numbers, or the entire phone number for
phone numbers outside the U.S.,
excluding country code. This will
prepopulate the payer’s home phone
number.
night_ The four-digit phone number for U.S. Numeric 4
phone_c phone numbers. This will prepopulate the
payer’s home phone number.
state State Must be two-character official 2
U.S. abbreviation.
zip Postal code Numeric 32

A

B Address Handling (U.S.
Merchants Only)
Various HTML variables and PayPal account settings determine whether buyers can change,
add, or override the billing and shipping addresses on PayPal payment pages.
TABLE B.1 HTML Variables and Account Profile Settings for Buyer Addresses
Variables or Settings
Is the address prepopulated? Use address variables to specify the buyer’s

address, which appears automatically on the
PayPal payment pages.
See “HTML Variables for Prepopulating
PayPal Payment Pages” on page 171.
Allow override of buyer’s stored address? Use the address_override variable.
See Appendix A, “HTML Variables for
Website Payments Standard.”
Require confirmed address? Use the Block payments from U.S. users who
do not provide a Confirmed Address account
profile setting.
See “Blocking Payments from U.S. Payers
without a Confirmed Address” on page 62.
Prompt for shipping address? Use the no_shipping variable.
See “HTML Variables for Displaying PayPal
Payment Pages” on page 169.”
In the following diagram, the letters “A” through “E” represent endpoints for the influence that
HTML variables and account profile settings have on how PayPal payment pages let buyers
handle billing and shipping addresses.

Address Handling (U.S. Merchants Only)
B
Address Handling in the Website Payments Standard Basic Page Sequence
FIGURE B.1 How HTML Variables and Profile Account Setting Affect Buyer Addresses
The following sections describe the endpoints are under different scenarios:
z Address Handling in the Website Payments Standard Basic Page Sequence
z Address Handling in the PayPal Account Optional Page Sequence
Address Handling in the Website Payments Standard Basic

Page Sequence
This section describes the billing and shipping address behavior in the Website Payments
Standard basic page sequence. This basic page sequence is described in Chapter 1, “How
Integration Using Website Payments Standard Works. In the basic page sequence, buyers must
log in to PayPal or sign up for PayPal before they can complete their payments.
N O T E : The
endpoint letters in this section refer to Figure B.1, “How HTML Variables and
Profile Account Setting Affect Buyer Addresses” on page 174.
Endpoint A
If the prepopulated address is a confirmed address, the Shipping Address on the Review
Your Payment page displays the prepopulated address. The buyer cannot change the shipping
address.

B
Address Handling in the Website Payments Standard Basic Page Sequence
If the prepopulated address is not confirmed, PayPal displays the Add Credit Card or Debit
Card page with the prepopulated address as the billing address. The page displays a message
that the address must match the one displayed on their statement. The Cancel button is
displayed if the merchant has provided a cancel_return URL.
Endpoints B, C, and D
The Shipping Address on the Review Your Payment page displays the prepopulated address.
The buyer cannot change the shipping address.
If the prepopulated address is invalid, the payment cannot be processed. PayPal displays an
error message.
Endpoint E
If the prepopulated address is a confirmed address, the Shipping Address on the Review
Your Payment page displays the prepopulated address. The buyer can select or add another
address. If the buyer selects Add New Address, PayPal displays the Add Credit Card or
Debit Card page.
If the prepopulated address is not a confirmed address or there is no confirmed address in the
profile, PayPal displays the Add Credit Card or Debit Card page with the address
prepopulated.
Endpoints F and H
The Shipping Address on the Review Your Payment page displays the prepopulated address.
The buyer can select or add another address.
If the prepopulated address is invalid, the address is dropped and the address in the profile is
displayed, if available. The buyer can select or add another address directly in the page.
Endpoints G and K
The Review Your Payment page does not contain a Shipping Address.
Endpoint I
If there is a confirmed address in the account, PayPal displays the Review Your Payment
page. The buyer can select another confirmed address or add another address. If the buyer
selects Add New Address, they are taken to the Add Credit Card or Debit Card page.
If there is not a confirmed address in the account, PayPal displays the Add Credit Card or
Debit Card page.

B
Address Handling in the PayPal Account Optional Page Sequence
Endpoints J and L
The Shipping Address on the Review Your Payment page displays the buyer’s primary
address. The buyer can select another address or add another address directly in the page.
Address Handling in the PayPal Account Optional Page

Sequence
This section describes the billing and shipping address behavior in the PayPal payment pages
when PayPal Account Optional is turned on in the account profile. This alternative page
sequence is described in “PayPal Account Optional” on page 30. In the PayPal Account
Optional page sequence, buyers can pay by credit card without first logging in or signing up
for a PayPal account.
N O T E : The
endpoint letters in this section refer to Figure B.1, “How HTML Variables and
Profile Account Setting Affect Buyer Addresses” on page 174.
Endpoint A
The billing page displays the prepopulated address. If the buyer modifies the address and
attempts to submit the page, PayPal returns an error that the address cannot be modified. The
Shipping Address on the Review Your Payment page displays this address. The buyer
cannot change the shipping address.
If the prepopulated address is bad, PayPal displays an error page indicating the buyer cannot
proceed with payment because the merchant provided an invalid address.
Endpoints B, C, and D
The billing page displays the prepopulated address. The buyer can modify the billing address.
The Shipping Address on the Review Your Payment page displays this address. The buyer
cannot change the shipping address.
If the prepopulated address is bad, PayPal prepopulates the billing page and the buyer can
modify it. There is no Shipping Address on the Review Your Payment page.
Endpoint E
The Shipping Address on the Review Your Payment page displays the address from the
billing page. The buyer cannot change the shipping address. The shipping address always
matches the billing address, so modifications to the billing address updates the shipping
address.
If the prepopulated address is invalid, the billing page displays the address and the buyer can
modify it.

B
Endpoints F and H
billing page. The buyer can change the shipping address.
If the prepopulated address is invalid, the billing page displays the address and the buyer can
modify it.
Endpoint G
There is no Shipping Address on the Review Your Payment page.
Endpoint I
billing page. The buyer cannot change the shipping address. The shipping address should
always match the billing address, so if the user modifies the billing information and address,
the shipping address will be updated as well.
Endpoints J and L
billing page. The buyer can change the shipping address.
Endpoint K
There is no Shipping Address on the Review Your Payment page.

B

C Country Codes
N O T E : This table lists country codes defined by ISO 3166-1.
Table 1: Country Codes
Country Code
AFGHANISTAN AF
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA DZ
AMERICAN SAMOA AS
ANDORRA AD
ANGOLA AO
ANGUILLA AI
ANTARCTICA AQ
ANTIGUA AND BAR- AG
BUDA
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
BARBADOS BB

Country Codes
C
Country Code
BELARUS BY
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOLIVIA BO
BOSNIA AND HERZE- BA
GOVINA
BOTSWANA BW
BOUVET ISLAND BV
BRAZIL BR
BRITISH INDIAN IO
OCEAN TERRITORY
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
BURUNDI BI
CAMBODIA KH
CAMEROON CM
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN CF
REPUBLIC
CHAD TD
CHILE CL
CHINA CN

Country Codes
C
Country Code
CHRISTMAS ISLAND CX
COCOS (KEELING) CC
ISLANDS
COLOMBIA CO
COMOROS KM
CONGO CG
CONGO, THE DEMO- CD
CRATIC REPUBLIC OF
THE
COOK ISLANDS CK
COSTA RICA CR
COTE D'IVOIRE CI
CROATIA HR
CUBA CU
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
EQUATORIAL GUINEA GQ
ERITREA ER
ESTONIA EE
ETHIOPIA ET

Country Codes
C
Country Code
FALKLAND ISLANDS FK
(MALVINAS)
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN TF
TERRITORIES
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUATEMALA GT
GUERNSEY GG
GUINEA GN
GUINEA-BISSAU GW
GUYANA GY
HAITI HT

Country Codes
C
Country Code
HEARD ISLAND AND HM

MCDONALD ISLANDS
HOLY SEE (VATICAN VA
CITY STATE)
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRAN, ISLAMIC REPUB- IR
LIC OF
IRAQ IQ
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KENYA KE
KIRIBATI KI
KOREA, DEMOCRATIC KP
PEOPLE'S REPUBLIC OF
KOREA, REPUBLIC OF KR
KUWAIT KW

Country Codes
C
Country Code
KYRGYZSTAN KG
LAO PEOPLE'S DEMO- LA
CRATIC REPUBLIC
LATVIA LV
LEBANON LB
LESOTHO LS
LIBERIA LR
LIBYAN ARAB JAMA- LY
HIRIYA
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA, THE MK
FORMER YUGOSLAV
REPUBLIC OF
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALDIVES MV
MALI ML
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX

Country Codes
C
Country Code
MICRONESIA, FEDER- FM
ATED STATES OF
MOLDOVA, REPUBLIC MD
OF
MONACO MC
MONGOLIA MN
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
MYANMAR MM
NAMIBIA NA
NAURU NR
NEPAL NP
NETHERLANDS NL
NETHERLANDS ANTI- AN
LLES
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIGERIA NG
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA MP
ISLANDS
NORWAY NO
OMAN OM
PAKISTAN PK

Country Codes
C
Country Code
PALAU PW
PALESTINIAN TERRI- PS
TORY, OCCUPIED
PANAMA PA
PAPUA NEW GUINEA PG
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
SAINT HELENA SH
SAINT KITTS AND KN
NEVIS
SAINT LUCIA LC
SAINT PIERRE AND PM
MIQUELON
SAINT VINCENT AND VC
THE GRENADINES
SAMOA WS
SAN MARINO SM

Country Codes
C
Country Code
SAO TOME AND PRINC- ST

IPE
SAUDI ARABIA SA
SENEGAL SN
SERBIA AND MON- CS
TENEGRO
SEYCHELLES SC
SIERRA LEONE SL
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOMALIA SO
SOUTH AFRICA ZA
SOUTH GEORGIA AND GS
THE SOUTH SANDWICH
ISLANDS
SPAIN ES
SRI LANKA LK
SUDAN SD
SURINAME SR
SVALBARD AND JAN SJ
MAYEN
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
SYRIAN ARAB REPUB- SY
LIC

Country Codes
C
Country Code
TAIWAN, PROVINCE OF TW
CHINA
TAJIKISTAN TJ
TANZANIA, UNITED TZ
REPUBLIC OF
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
TRINIDAD AND TT
TOBAGO
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS TC
ISLANDS
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIR- AE
ATES
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR UM
OUTLYING ISLANDS
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU

Country Codes
C
Country Code
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRIT- VG
ISH
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW

Country Codes
C

Index
Symbols View Cart buttons 90

Buy Now buttons
_cart 99, 101, 108, 109, 110, 154, 156, 161 button creation tool 75
_donations 154, 161 buyer experience 75
_oe-gift-certificate 161
page sequence 14
_s-xclick 161
_xclick 84, 154, 157, 161
C
A cancel_return 169
carts. See “shopping cart.”
Account Information 23 cbt 169
Account Optional 30, 156, 176 cert_id 149
payer experience 31
character encoding 66
account profile summary. See “Profile.” character set 66
add 87, 99, 101, 166 chargebacks 64
Add to Cart buttons
charset 66, 155
button creation tool 90 city 157, 158, 171
address handling 176 cmd 84, 99, 101, 109, 110, 154, 156
address_override 157, 164
cn 169
address1 156, 158, 171 confirmation 38
address2 156, 171 confirmed addresses 33, 62
amount 84, 99, 108, 156, 162, 166
contact telephone number 41
amount_1 110 country 158, 171
amount_x 109, 167 cpp_header_image 169
authorization 129
cpp_headerback_color 169
Authorization & Capture 129
cpp_headerborder_color 169
Authorization Period 129 cpp_payflow_color 169
Auto Return 38, 105 cs 169
enabling 39
Currency Balances 73
payer experience 38 currency_code 84, 99, 109, 126, 156, 164
custom 155, 164
B custom page style variables 169
basic page sequence 14

batch capture 131 D
blocking kinds of payments 61
Developer Central 151
business 84, 99, 101, 108, 109, 110, 156, 166
display 87, 166
button creation tool
Donation buttons
Add to Cart buttons 90
button creation tool 119
Buy Now buttons 75
donor experience 111
Donation buttons 119
page sequence 111
PayPal Shopping Cart buttons 90

Index
downloadable history log 20, 119 item_name 84, 99, 156, 162, 166
item_name_1 108, 110
item_name_x 167
E item_number 84, 99, 126, 155, 156, 162
eChecks 64 item_number_x 155, 167
email notification 19, 118
disabling 20, 118
encoding 66
J
Encrypted Website Payments 82, 125, 145 jpg 28
EWP. See “Encrypted Website Payments.”
example
HTML for BUY Now 83, 126 L
HTML for individual items in shopping cart 109 language encoding 66
HTML for overriding PayPal-stored shipping last_name 156, 158, 171
address 157 lc 171
shopping cart with aggregated item information 110
M
F
METHOD 170
Financial Information 23
first_name 156, 158, 171
FORM ACTION and METHOD definitions 153 N
funding sources 16, 114 night_phone_a 157, 171
night_phone_b 157, 171
G night_phone_c 157, 171
no_note 170
gif 28 no_shipping 170
notify_url 162
H
handling 164 O
handling_cart 56, 60, 166 on0 84, 100, 163
handling_x 109, 167 on0_x 167
Honor Period 129 on1 163
HTML on1_x 167
for aggregated shopping cart 110 OpenSSL 147
for Buy Now button 83, 126 order 129
shopping cart with individual items 109 Order Management Integration Guide 21
os0 84, 100, 163
os0_x 168
I
os1 163
image_url 170 os1_x 168
INPUT tag 154 overriding
Instant Payment Notification 19, 20, 21, 118, 119, 145 page styles 29
Sandbox testing 151 PayPal-stored shipping address 157, 164
invoice 155, 164 return URL on individual transactions 40, 155
IPN. See “Instant Payment Notification.”

Index
tax calculations on individual transactions 46 R

receipts 38
P refund 141
required variables for third party shopping cart 108
page
return 18, 40, 156, 169, 170
payment confirmation page 38
rm 170
payment receipt page 38
page sequences
basic page sequence 14 S
donatons page sequence 111
PayPal Shopping Cart page sequence 87 sales tax 24
page_style 28, 29, 30, 170 automatic calulation 42
overriding on individual transactions 109
partial refund 141
passthrough variables, defined 155 setting for entire shopping cart 110
Pay Anyone 63 Sandbox 151
Seller Protection Policy 62, 63
payment confirmation page 38
Payment Data Transfer 40 Send Money 141
payment receipt page 38 shipping 56, 60, 110, 165
overriding on individual transactions 51, 56
Payment Receiving Preferences 33, 61
paymentaction 129, 130, 167 shipping calculations 105
PayPal Account Optional 176 shipping preferences 89
shipping rates 24
PayPal Shopping Cart 87, 108
button creation tool 90 shipping_x 109, 168
page sequence 87 shipping2 110, 165
shipping2_x 109
shopper experience 87
PDT. See “Payment Data Transfer.” shopping cart
PEM 147 hosted by PayPal 87
PayPal Shopping Cart 87
png 28
prepopulating PayPal FORMs 156 third party carts 108
private key 146 thrid-party 87
SPP. See “Seller Protection Policy.”
Profile
state 157, 158, 171
Account Information 23
Auto Return 39 subscriptions 21
Automatic shipping, handling, and tax calculation 42 Subscriptions and Recurring Payments Guide 40
Custom Payment Pages 27
Financial Information 23 T
Shipping Calculations 58
public certificate 146 tax 165
tax rates
domestic 43
Q international 43, 45
setting up 42
quantity 162
tax. See “sales tax.” 109
allowing buyers to specify with Buy Now 80, 162
tax_cart 110, 165
quantity_x 109, 168
tax_x 109, 110, 165, 168
taxes 42
Transaction Details 141

Index
U
undefined_quantity 84, 154, 162
upload 87, 108, 167
example of aggregate cart 110
example of individual item detail 109
UTF-8 155
V
variables
display information 169
for shopping carts 166
general format of 153
hidden 153
individual items in shopping carts 167
item information 162
prepopulating PayPal FORMs 171
transaction information 164
VAT 42
verified members, defined 64
View Cart buttons
button creation tool 90
W
webscr 99, 101, 109, 110, 153, 156, 157
weight_cart 110
weight_unit 109, 110
weight_x 109, 110
X
X.509 146
Z
zip 157, 158, 171

PP WebsitePaymentsStandard IntegrationGuide

Uploaded by

Copyright:

Available Formats

PP WebsitePaymentsStandard IntegrationGuide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PP WebsitePaymentsStandard IntegrationGuide

Uploaded by

Copyright:

Available Formats

Website Payments

For Professional Use Only

A usage Professional Uniquement

Last updated: March 2008

Document Number: 100000.en_US-200803

Chapter 1 How Integration Using Website Payments Standard Works . 13

Chapter 2 Using Your PayPal Account Profile . . . . . . . . . . . . . 23

Website Payments Standard Integration Guide March 2008 3

4 March 2008 Website Payments Standard Integration Guide

Resetting the Password for a User Login . . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 3 Single-Item Payment: Buy Now Buttons . . . . . . . . . . . 75

Chapter 4 Multiple-Item Payment: Shopping Carts . . . . . . . . . . . 87

Chapter 5 Contribution Payment: Donation Buttons . . . . . . . . . 111

Website Payments Standard Integration Guide March 2008 5

Begin: Donor is Ready to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 6 Using Authorization & Capture . . . . . . . . . . . . . . 129

6 March 2008 Website Payments Standard Integration Guide

Chapter 7 Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . 141

Chapter 8 Securing Your Website Payments Standard Buttons . . . 143

Chapter 9 Testing in the PayPal Sandbox . . . . . . . . . . . . . . 151

Chapter 10 HTML Form Basics for Website Payments Standard . . . 153

Appendix A HTML Variables for Website Payments Standard . . . . . 161

Website Payments Standard Integration Guide March 2008 7

HTML Variables for Payment Transactions . . . . . . . . . . . . . . . . . . . . . . . . .164

Appendix B Address Handling (U.S. Merchants Only) . . . . . . . . . 173

Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . 179

8 March 2008 Website Payments Standard Integration Guide

How to Use This Guide

TABLE P.1 How to Use This Guide

Feature Description See Also...

Website Payments Standard Integration Guide March 2008 9

TABLE P.1 How to Use This Guide

Feature Description See Also...

10 March 2008 Website Payments Standard Integration Guide

TABLE P.2 Revision History

April 2007 Updated screenshots and corresponding instructions.

October 2006 Minor clarifications.

August 2006 New PayPal Shopping Cart variable: shopping_url

March 2006 Miscellaneous minor corrections.

Website Payments Standard Integration Guide March 2008 11

12 March 2008 Website Payments Standard Integration Guide

FIGURE 1.1 Website Payments Standard Basic Payment Page Sequence

Website Payments Standard Integration Guide March 2008 13

The Basic Page Sequence for Website Payments Standard

Begin: Buyer is Ready to Purchase

1: Buyer Logs In to PayPal

14 March 2008 Website Payments Standard Integration Guide

FIGURE 1.3 Buyer Logs In to PayPal

Website Payments Standard Integration Guide March 2008 15

FIGURE 1.4 Buyer Creates a PayPal Account or Logs in

2: Buyer Reviews Payment Details

16 March 2008 Website Payments Standard Integration Guide

FIGURE 1.5 Buyer Reviews Payment Details

3: Buyer Views PayPal Payment Confirmation

Website Payments Standard Integration Guide March 2008 17

FIGURE 1.6 Payment Confirmation Page on PayPal

End: Buyer Returns to Merchant Website

FIGURE 1.7 Buyer Returns to a Landing Page on the Merchant Website

18 March 2008 Website Payments Standard Integration Guide

How You Get Your Money