Pp website paymentsstandard_integrationguide

PayPal Payments
Standard Integration
Guide

Last updated: June 2012

PayPal Payments Standard Integration Guide

Document Number: 100000.en_US-201204

© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-
2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 1 Single-Item Payments – Buy Now Buttons . . . . . . . . . 21
Getting Started With Buy Now Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using the Button Creation Tool for a Basic Buy Now Button . . . . . . . . . . . . . . 22
Creating Buy Now Buttons Before You Create Your PayPal Account . . . . . . . . . . 23
The Checkout Experience With Buy Now Buttons . . . . . . . . . . . . . . . . . . . . . . 25
Begin – Buyers are Ready to Purchase Your Item on Your Website . . . . . . . . . . 27
1 – Buyers Enter Their Billing Information, or They Log In to PayPal . . . . . . . . . . 27
2 – Buyers Confirm Their Transaction Details Before Paying . . . . . . . . . . . . . . 29
3 – Buyers View and Print Their PayPal Payment Confirmations . . . . . . . . . . . . 30
End – Buyers Receive Payment Authorization Notices by Email . . . . . . . . . . . . 31
Enhancing the Checkout Experience With Buy Now Buttons . . . . . . . . . . . . . . 31
Managing Buy Now Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Using Email Notices to Track Buy Now Transactions . . . . . . . . . . . . . . . . . . 33
Using Recent Activity to Track Buy Now Transactions . . . . . . . . . . . . . . . . . 34
Using Transaction History to Track Buy Now Transactions . . . . . . . . . . . . . . . 34
Using Downloadable History Logs to Track Buy Now Transactions . . . . . . . . . . . 34
Using Instant Payment Notification to Track Buy Now Transactions . . . . . . . . . . 35
Advanced Features of Buy Now Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Offering Product Options With Buy Now Buttons . . . . . . . . . . . . . . . . . . . . 35
Prompting for Item Quantities With Buy Now Buttons . . . . . . . . . . . . . . . . . . 36
Offering Discounts With Buy Now Buttons. . . . . . . . . . . . . . . . . . . . . . . . 37
Creating Advanced Buy Now Buttons on the PayPal Website . . . . . . . . . . . . . . . . 37
The Basic Steps for Using the Button Creation Tool With Buy Now Buttons . . . . . . 38
Saving Buy Now Buttons in Your PayPal Account . . . . . . . . . . . . . . . . . . . . 38
Tracking Inventory and Tracking Profit and Loss . . . . . . . . . . . . . . . . . . . . 39
Adding Advanced Features to Buy Now Buttons With HTML Variables . . . . . . . . . 39

PayPal Payments Standard Integration Guide June 2012 3

Contents

Generating Code for Payment Buttons and Email Payment Links . . . . . . . . . . . 40
Protecting HTML Code for Payment Buttons . . . . . . . . . . . . . . . . . . . . . . 40
Step 1 – Specifying Basic Features of Your Buy Now Button . . . . . . . . . . . . . . 40
Step 2 – Tracking Inventory With Your Buy Now Button . . . . . . . . . . . . . . . . . 44
Step 3 – Adding Advanced Features to Your Buy Now Button . . . . . . . . . . . . . 48
Copying and Pasting the Buy Now Code . . . . . . . . . . . . . . . . . . . . . . . . 50
Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . . 52
Sample HTML Code for Buy Now Buttons . . . . . . . . . . . . . . . . . . . . . . . . . 52
Sample HTML Code for a Basic Buy Now Button . . . . . . . . . . . . . . . . . . . . 53
Sample Code for a Buy Now Button With Product Options . . . . . . . . . . . . . . . 54
Sample Code for a Buy Now Button With Product Options With Prices . . . . . . . . . 54
Sample Code for a Buy Now Button With Product Options as a Text Box. . . . . . . . 56
Sample HTML Code for a Buy Now Button that Prompts for Quantities. . . . . . . . . 57
Sample HTML Code for a Buy Now Button With Discounts . . . . . . . . . . . . . . . 59
Sample URL Code for a Buy Now Email Payment Link . . . . . . . . . . . . . . . . . . . 62
Creating Buy Now Buttons with JavaScript Disabled . . . . . . . . . . . . . . . . . . . . 62
Getting Started with Buy Now Buttons with JavaScript Disabled . . . . . . . . . . . . 63
Creating Advanced Buy Now Buttons With JavaScript Disabled . . . . . . . . . . . . 64
Limitations When Creating Buy Now Buttons With JavaScript Disabled . . . . . . . . 73
Enabling JavaScript in Your Browser . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 2 Contribution Payments – Donate Buttons . . . . . . . . . . 75
Getting Started With Donate Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using the Button Creation Tool for a Basic Donate Button . . . . . . . . . . . . . . . 76
Creating Donate Buttons Before You Create Your PayPal Account . . . . . . . . . . . 77
The Checkout Experience With Donate Buttons . . . . . . . . . . . . . . . . . . . . . . . 79
Begin – Donors are Ready to Contribute on Your Website . . . . . . . . . . . . . . . 81
1 – Donors Enter Their Billing Information or They Log In to PayPal . . . . . . . . . . 82
2 – Donors Confirm Their Contribution Details Before Paying. . . . . . . . . . . . . . 83
3 – Donors View and Print Their PayPal Contribution Confirmations . . . . . . . . . . 84
End – Donors Receive Contribution Authorization Notices by Email . . . . . . . . . . 85
Enhancing the Checkout Experience With Donate Buttons . . . . . . . . . . . . . . . 85
Managing Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using Email Notices to Track Donate Transactions . . . . . . . . . . . . . . . . . . . 87
Using Recent Activity to Track Donate Transactions . . . . . . . . . . . . . . . . . . 87
Using Transaction History to Track Donate Transactions . . . . . . . . . . . . . . . . 88
Using Downloadable History Logs to Track Donate Transactions . . . . . . . . . . . . 88
Using Instant Payment Notification to Track Donate Transactions . . . . . . . . . . . 88
Creating Advanced Donate Buttons on the PayPal Website. . . . . . . . . . . . . . . . . 89

4 June 2012 PayPal Payments Standard Integration Guide

Contents

The Basic Steps for Using the Tool With Donate Buttons . . . . . . . . . . . . . . . . 89
Saving Donate Buttons in Your PayPal Account. . . . . . . . . . . . . . . . . . . . . 90
Adding Advanced Features to Donate Buttons With HTML Variables . . . . . . . . . . 90
Generating Code for Payment Buttons and Email Payment Links . . . . . . . . . . . 91
Protecting HTML Code for Payment Buttons . . . . . . . . . . . . . . . . . . . . . . 91
Step 1 – Specifying Basic Features of Your Donate Button . . . . . . . . . . . . . . . 91
Step 2 – Saving Your Donate Button in Your PayPal Account . . . . . . . . . . . . . . 94
Step 3 – Adding Advanced Features to Your Donate Button . . . . . . . . . . . . . . 95
Copying and Pasting the Donate Code . . . . . . . . . . . . . . . . . . . . . . . . . 97
Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . . 98
Sample HTML Code for Donate Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Sample HTML Code for a Basic Donate Button . . . . . . . . . . . . . . . . . . . . . 99
Sample HTML Code for a Donate Button With a Fixed Contribution Amount . . . . . .100
Creating Donate Buttons with JavaScript Disabled . . . . . . . . . . . . . . . . . . . . .101
Getting Started with Donate Button With JavaScript Disabled. . . . . . . . . . . . . .101
Creating Advanced Donate Buttons With JavaScript Disabled . . . . . . . . . . . . .102
Limitations When Creating Payment Buttons With JavaScript Disabled . . . . . . . .109
Enabling JavaScript in Your Browser . . . . . . . . . . . . . . . . . . . . . . . . . .109

Chapter 3 Recurring Payments – Subscribe Buttons . . . . . . . . 113
Getting Started with Subscribe Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Creating a Basic Subscribe Button on the PayPal Website . . . . . . . . . . . . . . . 114
Creating Subscribe Buttons Before You Create Your PayPal Account . . . . . . . . . 115
The Checkout Experience with Subscribe Buttons . . . . . . . . . . . . . . . . . . . . . 117
Checkout Starts on Your Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Buyers Choose a Way to Pay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Buyers Review Their Payment Details . . . . . . . . . . . . . . . . . . . . . . . . .120
Buyers View and Print Payment Confirmations . . . . . . . . . . . . . . . . . . . . .121
Enhancing the Checkout Experience with Subscribe Buttons . . . . . . . . . . . . . .122
Managing Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Tracking Subscription Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .124
How Billing Cycles and Recurring Payments Work . . . . . . . . . . . . . . . . . . .127
Downloading Subscriber Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Canceling Individual Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Canceling Multiple Subscriptions at One Time . . . . . . . . . . . . . . . . . . . . .131
Suspending Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Editing a Subscription Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
End-of-Term Messages Sent Through Instant Payment Notification . . . . . . . . . .135
Advanced Features of Subscribe Buttons . . . . . . . . . . . . . . . . . . . . . . . . . .136


Contents

Offering Trial Periods and Introductory Rates with Subscribe Buttons . . . . . . . . .136
Limiting the Number of Billing Cycles with Subscribe Buttons . . . . . . . . . . . . .137
Offering Product Options with Subscribe Buttons . . . . . . . . . . . . . . . . . . . .138
Working with Modify Subscription Buttons. . . . . . . . . . . . . . . . . . . . . . . .138
Working with Unsubscribe Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Generating Usernames and Passwords with Subscribe Buttons . . . . . . . . . . . .143
Reattempting Failed Recurring Payments with Subscribe Buttons . . . . . . . . . . .144
Creating Advanced Subscribe Buttons on the PayPal Website . . . . . . . . . . . . . . .146
The Basic Steps for Using the Tool with Subscribe Buttons . . . . . . . . . . . . . . .146
Saving Subscribe Buttons in Your PayPal Account . . . . . . . . . . . . . . . . . . .147
Tracking Inventory and Profit and Loss for Subscribe Buttons . . . . . . . . . . . . .148
Adding Advanced Features to Subscribe Buttons with HTML Variables . . . . . . . .148
Generating Code for Subscribe Buttons and Email Payment Links . . . . . . . . . . .148
Protecting HTML Code for Subscribe Buttons . . . . . . . . . . . . . . . . . . . . . .148
Step 1 – Specifying Basic Features of Your Subscribe Button . . . . . . . . . . . . .149
Step 2 – Tracking Inventory and Profit and Loss with Your Subscribe Button . . . . . .153
Step 3 – Adding Advanced Features to Your Subscribe Button . . . . . . . . . . . . .156
Copying and Pasting the Subscribe Code . . . . . . . . . . . . . . . . . . . . . . . .158
Avoiding Problems with Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . .159
Using the Button Creation Tool for an Unsubscribe Button . . . . . . . . . . . . . . .160
Sample HTML Code for Subscribe Buttons . . . . . . . . . . . . . . . . . . . . . . . . .162
Sample HTML Code for a Basic Subscribe Button . . . . . . . . . . . . . . . . . . .162
Sample HTML Code for a Subscribe Button with Trial Periods . . . . . . . . . . . . .163
Sample HTML Code for a Subscribe Button with Limits on Billing Cycles. . . . . . . .164
Sample HTML Code for Subscribe Buttons with Product Options . . . . . . . . . . .165
Sample HTML Code for a Modify Subscription Button . . . . . . . . . . . . . . . . .167
Sample HTML Code for an Unsubscribe Button. . . . . . . . . . . . . . . . . . . . .168
Sample HTML Code for a Subscribe Button with Password Management . . . . . . .169
Sample HTML Code for a Subscribe Button That Reattempts Payments . . . . . . . .170
Sample URL Code for Subscribe Email Payment Links . . . . . . . . . . . . . . . . . . .171
Creating Subscribe Buttons with JavaScript Disabled . . . . . . . . . . . . . . . . . . .171
Getting Started with Subscribe Buttons with JavaScript Disabled . . . . . . . . . . .171
Creating Advanced Subscribe Buttons with JavaScript Disabled . . . . . . . . . . . .173
Limitations When Creating Payment Buttons with JavaScript Disabled . . . . . . . . .183

Chapter 4 Recurring Payments – Automatic Billing Buttons . . . . 185
Getting Started with Automatic Billing Buttons . . . . . . . . . . . . . . . . . . . . . . .185
The Checkout Experience with Automatic Billing Buttons . . . . . . . . . . . . . . . . . .189


Contents

Checkout Starts on Your Website . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Buyers Choose a Way to Pay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Buyers Review Their Payment Details . . . . . . . . . . . . . . . . . . . . . . . . .192
Enhancing the Checkout Experience with Automatic Billing Buttons . . . . . . . . . .194
Managing Automatic Billing Agreements. . . . . . . . . . . . . . . . . . . . . . . . . . .195
Using the Recurring Payments Dashboard to Track Automatic Billing Plans . . . . . .195
Using Recent Activity to Track Automatic Billing Payments . . . . . . . . . . . . . . .196
Billing Your Customer Automatically . . . . . . . . . . . . . . . . . . . . . . . . . .197
Creating Advanced Automatic Billing Buttons on the PayPal Website . . . . . . . . . . .199
Basic Steps in the Button Creation Tool for Automatic Billing Buttons . . . . . . . . .199
Saving Automatic Billing Buttons in Your PayPal Account . . . . . . . . . . . . . . .200
Tracking Inventory and Profit and Loss for Automatic Billing Buttons . . . . . . . . .201
Adding HTML Variables to Automatic Billing Buttons . . . . . . . . . . . . . . . . . .201
Generating Code for Automatic Billing Buttons and Email Payment Links . . . . . . .201
Protecting HTML Code for Automatic Billing Buttons . . . . . . . . . . . . . . . . . .201
Step 1 – Specifying Basic Features of Your Automatic Billing Button . . . . . . . . . .202
Step 2 – Tracking Inventory for Your Automatic Billing Button . . . . . . . . . . . . .206
Step 3 – Adding Advanced Features to Your Automatic Billing Button . . . . . . . . .208
Copying and Pasting the Automatic Billing Code . . . . . . . . . . . . . . . . . . . .210
Avoiding Problems with Pasted Automatic Billing Code . . . . . . . . . . . . . . . .212
Sample HTML Code for Automatic Billing Buttons . . . . . . . . . . . . . . . . . . . . .212
Sample HTML Code for a Basic Automatic Billing Button . . . . . . . . . . . . . . .212
Sample HTML Code for Choosing Limits with Automatic Billing Buttons . . . . . . . .214

Chapter 5 Recurring Payments – Installment Plan Buttons . . . . . 217
Getting Started with Installment Plan Buttons . . . . . . . . . . . . . . . . . . . . . . . .217
The Checkout Experience with Installment Plan Buttons . . . . . . . . . . . . . . . . . .220
Checkout Starts on Your Website . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Buyers Choose a Way to Pay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Buyers Review Their Payment Details. . . . . . . . . . . . . . . . . . . . . . . . . .223
Enhancing the Checkout Experience with Installment Plan Buttons . . . . . . . . . .225
Managing Installment Plans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Using the Recurring Payments Dashboard to Track Installment Plans . . . . . . . . .226
Using Recent Activity to Track Installment Plan Payments . . . . . . . . . . . . . . .227
Creating Advanced Installment Plan Buttons on the PayPal Website . . . . . . . . . . . .228
Basic Steps in the Button Creation Tool for Installment Plan Buttons . . . . . . . . . .229
Saving Installment Plan Buttons in Your PayPal Account . . . . . . . . . . . . . . . .230


Contents

Tracking Inventory and Profit and Loss for Installment Plan Buttons . . . . . . . . . .230
Adding HTML Variables to Installment Plan Buttons . . . . . . . . . . . . . . . . . .231
Generating Code for Installment Plan Buttons and Email Payment Links . . . . . . .231
Protecting HTML Code for Installment Plan Buttons . . . . . . . . . . . . . . . . . .231
Step 1 – Specifying Basic Features of Your Installment Plan Button . . . . . . . . . .231
Step 2 – Tracking Inventory for Your Installment Plan Button . . . . . . . . . . . . . .235
Step 3 – Adding Advanced Features to Your Installment Plan Button . . . . . . . . .237
Copying and Pasting the Installment Plan Code . . . . . . . . . . . . . . . . . . . .239
Avoiding Problems with Pasted Installment Plan Code . . . . . . . . . . . . . . . . .241
Sample HTML Code for Installment Plan Buttons . . . . . . . . . . . . . . . . . . . . . .241
Sample HTML Code for a Basic Installment Plan Button . . . . . . . . . . . . . . . .241
Sample HTML Code for an Installment Button with 2 Plan Options . . . . . . . . . .243

Chapter 6 The PayPal Shopping Cart – Add to Cart and View Cart
Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Getting Started With The PayPal Shopping Cart. . . . . . . . . . . . . . . . . . . . . . .247
Getting Started With Add To Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . .248
Getting Started With View Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . .251
The Checkout Experience With the PayPal Shopping Cart . . . . . . . . . . . . . . . . .255
Begin – Buyers Add Your Items to the PayPal Shopping Cart. . . . . . . . . . . . . .257
1 – Buyers Enter Their Billing Information or They Log In To PayPal . . . . . . . . . .258
2 – Buyers Confirm Their Transaction Details Before Paying . . . . . . . . . . . . . .260
3 – Buyers View and Print Their PayPal Payment Confirmations . . . . . . . . . . . .261
End – Buyers Receive Payment Authorization Notices by Email . . . . . . . . . . . .262
Enhancing the Checkout Experience With Add to Cart Buttons . . . . . . . . . . . . .262
Managing PayPal Shopping Cart Transactions . . . . . . . . . . . . . . . . . . . . . . .264
Using Email Notices to Track PayPal Shopping Cart Transactions . . . . . . . . . . .264
Using Recent Activity to Track PayPal Shopping Cart Transactions . . . . . . . . . .265
Using Transaction History to Track PayPal Shopping Cart Transactions . . . . . . . .265
Using Downloadable History Logs to Track PayPal Shopping Cart Transactions . . . .265
Using Instant Payment Notification to Track PayPal Shopping Cart Transactions . . .266
Advanced Features of Add to Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . .266
Offering Product Options With Add to Cart Buttons . . . . . . . . . . . . . . . . . . .266
Offering Discounts With Add to Cart Buttons . . . . . . . . . . . . . . . . . . . . . .267
Creating Advanced PayPal Shopping Cart Buttons on the PayPal Website . . . . . . . . .267
The Basic Steps for Using the Tool With Add to Cart Buttons . . . . . . . . . . . . . .268
Saving Add to Cart Buttons in Your PayPal Account . . . . . . . . . . . . . . . . . .269
Tracking Inventory and Tracking Profit and Loss . . . . . . . . . . . . . . . . . . . .270
Adding Advanced Features to Add to Cart Buttons With HTML Variables . . . . . . .270


Contents

Pricing Items in Multiple Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . .270
Working with View Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
Generating Code for Payment Buttons and Email Payment Links . . . . . . . . . . .271
Protecting HTML Code for Payment Buttons . . . . . . . . . . . . . . . . . . . . . .271
Step 1 – Specifying Basic Features of Your Add to Cart Button . . . . . . . . . . . .271
Step 2 – Tracking Inventory With Your Add to Cart Button . . . . . . . . . . . . . . .275
Step 3 – Adding Advanced Features to Your Add to Cart Button . . . . . . . . . . . .279
Copying and Pasting the Add to Cart Code . . . . . . . . . . . . . . . . . . . . . . .281
Using the Button Creation Tool for a View Cart Button . . . . . . . . . . . . . . . . .283
Avoiding Problems With Pasted HTML Code . . . . . . . . . . . . . . . . . . . . . .285
Sample HTML Code for Add to Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . .285
Sample HTML Code for a Basic Add to Cart Button. . . . . . . . . . . . . . . . . . .285
Sample HTML Code for Add to Cart Buttons With Product Options. . . . . . . . . . .286
Sample HTML Code for Add to Cart Buttons that Open the Shopping Cart in the Merchant
Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
Sample HTML Code for Add to Cart Buttons that Continue Shopping on the Current
Merchant Webpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Sample HTML Code for Add to Cart Buttons with Discounts . . . . . . . . . . . . . .296
Sample HTML Code for View Cart Buttons . . . . . . . . . . . . . . . . . . . . . . . . .300
Sample HTML Code for a View Cart Button . . . . . . . . . . . . . . . . . . . . . . .300
Sample HTML Code for a View Cart Button That Opens the Shopping Cart in the Merchant
Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .301
Sample HTML Code for View Cart Buttons that Continue Shopping on the Current
Merchant Webpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Creating PayPal Shopping Cart Buttons with JavaScript Disabled . . . . . . . . . . . . .303
Getting Started with Add to Cart Buttons With JavaScript Disabled . . . . . . . . . . .304
Getting Started with View Cart Buttons With JavaScript Disabled . . . . . . . . . . . .305
Creating Advanced Shopping Cart Buttons With JavaScript Disabled . . . . . . . . .306
Limitations When Creating Shopping Cart Buttons With JavaScript Disabled. . . . . .314

Chapter 7 Third-Party Shopping Carts – The Cart Upload Command 317
The Checkout Experience With the Cart Upload Command . . . . . . . . . . . . . . . .317
What Buyers See With Third-Party Shopping Carts . . . . . . . . . . . . . . . . . .317
Implementing the Cart Upload Command . . . . . . . . . . . . . . . . . . . . . . . . . .322
Required Third-Party Shopping Cart Variables . . . . . . . . . . . . . . . . . . . . .322
Passing Individual Item Details to PayPal . . . . . . . . . . . . . . . . . . . . . . . .323
Setting the Tax for the Entire Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Setting the Weight for the Entire Cart . . . . . . . . . . . . . . . . . . . . . . . . . .325
Setting Discounts for the Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325


Contents

Passing the Aggregate Shopping Cart Amount to PayPal. . . . . . . . . . . . . . . .325
Securing Your Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326
Implementing the Instant Update API With the Cart Upload Command . . . . . . . . . . .326
About the Instant Update API and the Cart Upload Command . . . . . . . . . . . . .326
Best Practices for Implementing Instant Update . . . . . . . . . . . . . . . . . . . .329
Other Considerations for Implementing Instant Update . . . . . . . . . . . . . . . . .330
Setting Up the Callback for Instant Update . . . . . . . . . . . . . . . . . . . . . . .332
Responding to the Callback for Instant Update . . . . . . . . . . . . . . . . . . . . .333

Chapter 8 Securing Your PayPal Payments Standard Buttons . . . . 337
Creating Protected Payment Buttons on the PayPal Website . . . . . . . . . . . . . . . .338
How Protected Payment Buttons Help Prevent Fraudulent Payments . . . . . . . . .338
Using the Button Creation Tool to Create a Protected Payment Button . . . . . . . . .338
Creating a Protected Payment Button with JavaScript Disabled . . . . . . . . . . . .339
Saving Payment Buttons in Your PayPal Account . . . . . . . . . . . . . . . . . . . . . .340
Reconciling Payments Manually Through Transaction History . . . . . . . . . . . . . . .341
Reconciling Payments Through Instant Payment Notification . . . . . . . . . . . . . . . .342
Protecting Payment Buttons by Using Encrypted Website Payments . . . . . . . . . . . .342
How Encrypted Website Payments Helps Prevent Fraudulent Payments . . . . . . . .343
Public Key Encryption Used by Encrypted Website Payments . . . . . . . . . . . . .343
Setting Up Certificates Before Using Encrypted Website Payments . . . . . . . . . .344
Using Encrypted Website Payments to Protect Your Payment Buttons . . . . . . . . .346
Blocking Unprotected and Non-encrypted Website Payments. . . . . . . . . . . . . . . .348

Chapter 9 Using Your PayPal Account Profile . . . . . . . . . . . . 349
Co-Branding the PayPal Checkout Pages . . . . . . . . . . . . . . . . . . . . . . . . . .349
Overriding Page Styles On Individual Payment Buttons . . . . . . . . . . . . . . . . .350
Overriding Co-Branding Options on Individual Payment Buttons . . . . . . . . . . . .350
Tailoring the Checkout Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Getting Contact Telephone Numbers . . . . . . . . . . . . . . . . . . . . . . . . . .354
PayPal Account Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
Automatic Calculation of Sales Tax . . . . . . . . . . . . . . . . . . . . . . . . . . . . .363
Displaying the Sales Tax that PayPal Calculates During Checkout . . . . . . . . . . .363
Accessing Your Sales Tax Rates in Your Account Profile . . . . . . . . . . . . . . . .364
Setting Up Domestic Sales Tax Rates . . . . . . . . . . . . . . . . . . . . . . . . . .365
Setting Up International Sales Tax Rates . . . . . . . . . . . . . . . . . . . . . . . .367
Resolving Overlapping Sales Tax Rates. . . . . . . . . . . . . . . . . . . . . . . . .367


Contents

Editing or Deleting Sales Tax Rates . . . . . . . . . . . . . . . . . . . . . . . . . . .368
Overriding Sales Tax Calculations on Individual Transactions . . . . . . . . . . . . .368
Automatic Calculation of Shipping Charges (U.S. Merchants Only) . . . . . . . . . . . .368
Displaying the Shipping Charges that PayPal Calculates During Checkout. . . . . . .369
Shipping Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372
Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Shipping Rate Bases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Shipping Rate Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Shipping Rates and Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374
Adding Shipping Rates for the First Time . . . . . . . . . . . . . . . . . . . . . . . .374
Adding Shipping Methods by Using a Wizard . . . . . . . . . . . . . . . . . . . . . .375
Viewing, Editing, and Adding Shipping Rates . . . . . . . . . . . . . . . . . . . . . .378
Viewing the Configuration of an Existing Shipping Method . . . . . . . . . . . . . . .379
Editing the Configuration Settings of an Existing Shipping Method . . . . . . . . . . .379
Deleting Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
Examples of Rate Bases and Shipping Calculations . . . . . . . . . . . . . . . . . .381
Overriding Shipping Calculations on Individual Transactions . . . . . . . . . . . . . .383
Automatic Calculation of Shipping Charges (non-U.S. Merchants Only) . . . . . . . . . .384
Examples of Cost Methods and Shipping Calculations . . . . . . . . . . . . . . . . .386
Overriding Shipping Calculation on Individual Transactions . . . . . . . . . . . . . . .386
Language Encoding Your Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387

Chapter 10 Using Authorization & Capture . . . . . . . . . . . . . . 389
Basic Authorization Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
Honor Period and Authorization Period . . . . . . . . . . . . . . . . . . . . . . . . .389
Basic Authorization & Capture Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . .390
Capturing A Single Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . .390
Batch Capturing Multiple Authorizations . . . . . . . . . . . . . . . . . . . . . . . . .392
Voiding an Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393
Capture Within 3 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393
Capture From 4 - 29 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
One Authorization, Multiple Captures, and a Refund . . . . . . . . . . . . . . . . . .395
Lower Capture Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
Capture Up to 115% . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396
Authorization Expires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
Reattempted Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398
Recommendations for Best Use of Authorization & Capture . . . . . . . . . . . . . . . .399
Capturing Funds on Basic Authorizations . . . . . . . . . . . . . . . . . . . . . . . .399


Contents

Buyer Approval for Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . .399
Voiding Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399

Chapter 11 Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . 401
Refunding Within 60 Days of Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . .401
Refunding After 60 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403

Chapter 12 Testing Payment Buttons in the PayPal Sandbox . . . . . 405

Chapter 13 HTML Form Basics for PayPal Payments Standard . . . . 407
Form Attributes – ACTION and METHOD . . . . . . . . . . . . . . . . . . . . . . . . . .407
Hidden Input Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
Specifying the Kind of Payment Button – cmd . . . . . . . . . . . . . . . . . . . . . . . .408
Variations on Basic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .409
Record Keeping with Passthrough Variables . . . . . . . . . . . . . . . . . . . . . .409
Setting the Character Set – charset . . . . . . . . . . . . . . . . . . . . . . . . . . .409
Setting The Return URL on Individual Transactions . . . . . . . . . . . . . . . . . . .410
Desired Currency on Individual Transactions . . . . . . . . . . . . . . . . . . . . . .410
Using HTML Variables With Saved Payment Buttons . . . . . . . . . . . . . . . . . . . . 411
Filling Out FORMs Automatically with HTML Variables . . . . . . . . . . . . . . . . . . . 411
Overriding Addresses Stored With PayPal. . . . . . . . . . . . . . . . . . . . . . . . . .414
Instant Payment Notification – notify_url . . . . . . . . . . . . . . . . . . . . . . . . . . .415

Appendix A HTML Variables for PayPal Payments Standard . . . . . 417
Technical HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
HTML Variables for Individual Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
HTML Variables for Payment Transactions . . . . . . . . . . . . . . . . . . . . . . . . .426
HTML Variables for Shopping Carts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
HTML Variables for Recurring Payments Buttons . . . . . . . . . . . . . . . . . . . . . .429
HTML Variables for Displaying PayPal Checkout Pages . . . . . . . . . . . . . . . . . .434
HTML Variables for Filling Out PayPal Checkout Pages Automatically . . . . . . . . . . .439
HTML Variables for the Instant Update API . . . . . . . . . . . . . . . . . . . . . . . . .441
Instant Update Variables to Set Up a Payment for the Instant Update API . . . . . . .441
Instant Update Variables for Dimensions of Individual Items . . . . . . . . . . . . . .442


Contents

Appendix B Address Handling (U.S. Merchants Only) . . . . . . . . . 445
Address Handling with PayPal Account Optional Turned On . . . . . . . . . . . . . . . .446
Result A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446
Results B, C, or D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447
Result E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447
Results F or H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447
Result G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447
Result I. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447
Results J and L . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448
Results K. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448
Address Handling With PayPal Account Optional Turned Off . . . . . . . . . . . . . . . .448
Result A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448
Results B, C, or D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448
Result E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449
Results F or H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449
Results G or K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449
Result I. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449
Results J or L . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449

Appendix C Countries and Regions Supported by PayPal . . . . . . 451

Appendix D Currencies Supported by PayPal . . . . . . . . . . . . . 459

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461


Contents


Preface

About This Guide
The PayPal Payments Standard Integration Guide (previously called Website Payments
Standard) describes how to integrate your website with PayPal by using HTML buttons and
forms. PayPal Payments Standard lets you accept payments for:
 Single-item purchases with Buy Now buttons – Sell from websites that offer single or
mutually exclusive products.
 Contribution payments with Donate buttons – Raise financial support for any cause.
 Recurring payments with Subscribe, Automatic Billing, and Installment Plan buttons
– Collect membership dues and offer other subscription services, get authorization to bill
customers automatically, and set up installment plans.
 Multiple-item purchases with Add to Cart and View Cart buttons – Sell from online
stores with catalogs and shopping carts.
The following table summarizes the contents of this guide.

Summary of the Contents of This Guide

Feature Description See
Buy Now Buttons Accept payments for single items at one time. “Single-Item Payments – Buy
Now Buttons” on page 21
Donate Buttons Accept payments for donation and contributions. “Contribution Payments –
Donate Buttons” on page 75
Subscribe Buttons Let customers sign up for subscriptions to goods or “Recurring Payments –
services, like books or online content. Subscribe Buttons” on page 113
Automatic Billing Let customers sign up for automatic payment plans “The Checkout Experience with
Buttons that let you bill them each month, up to a limit. Automatic Billing Buttons” on
page 189
Installment Plan Let customers sign up for installment plans that “The Checkout Experience with
Buttons collect payments from customers over time. Installment Plan Buttons” on
page 220
The PayPal Shopping Accept payments for multiple items at one time. “The PayPal Shopping Cart –
Cart Add to Cart and View Cart
Buttons” on page 247
Third-Party Shopping Develop a third-party shopping cart that is “The PayPal Shopping Cart –
Carts compatible with PayPal and PayPal Payments Add to Cart and View Cart
Standard. Buttons” on page 247


About This Guide

Summary of the Contents of This Guide

Feature Description See
Button Protection and Protect against fraudulent payments using the “Securing Your PayPal Payments
Encrypted Website encryption setting or Encrypted Website Payments Standard Buttons” on page 337”
Payments for your payment buttons.
Automatic Calculation Specify tax rates that PayPal uses to calculate taxes “Automatic Calculation of Sales
of Sales Tax automatically. Tax” on page 363
Automatic Calculation Specify shipping rates that PayPal uses to calculate “Automatic Calculation of
of Shipping Charges shipping charges automatically. Shipping Charges (U.S.
Merchants Only)” on page 368
– or –
“Automatic Calculation of
Shipping Charges (non-U.S.
Merchants Only)” on page 384
Custom Payment Pages Brand the PayPal checkout pages with your own “Co-Branding the PayPal
logo and colors. Checkout Pages” on page 349
PayPal Account Let people pay by credit card without having to “PayPal Account Optional” on
Optional sign up for a PayPal account. page 356
Auto Return Redirect people to your website automatically after “Auto Return” on page 351
they pay you on PayPal.
Payer Contact Prompt people for their contact telephone numbers “Getting Contact Telephone
Telephone when they pay you on PayPal. Numbers” on page 354
Authorization & Authorize payments during checkout, and capture “Using Authorization &
Capture payment amounts or portions of them later. Capture” on page 389”
Refunds Refund entire payments or portions of them. “Issuing Refunds” on page 401”


Intended Audience

Intended Audience
This guide is for:
 Merchants and developers who want to understand:
– The checkout experiences that people go through when they make payments with PayPal
Payments Standard payment buttons
– The influence of account profile settings on the way PayPal Payments Standard works
 Developers who want to learn how to integrate PayPal with websites by using PayPal
Payments Standard

Revision History
The following table lists the revisions made to the PayPal Payments Standard Integration
Guide.

Date Published Description

June 2012 Maintenance release.

April 2012 Updated references to Website Payments Standard and Website Payments Pro to
PayPal Payments Standard and PayPal Payments Pro, respectively.

November 2011 Updated screen shots to show the user interface changes. See “Single-Item
Payments – Buy Now Buttons” on page 21, “The PayPal Shopping Cart – Add
to Cart and View Cart Buttons” on page 247, and “Third-Party Shopping Carts –
The Cart Upload Command” on page 317.

May 2010 Added Automatic Billing and Payment Plan buttons, see “The Checkout
Experience with Automatic Billing Buttons” on page 189 and “The Checkout
Experience with Installment Plan Buttons” on page 220. Updated Subscribe
buttons with priced options for different billing cycles. See “Recurring
Payments – Subscribe Buttons” on page 113.

January 2010 For third-party shopping carts, added the Instant Update API to “The PayPal
Shopping Cart – Add to Cart and View Cart Buttons” on page 247 and added
Instant Update HTML variables to ““HTML Variables for PayPal Payments
Standard” on page 417.

October 2009 Updated screen shots to show the user interface changes. See “Securing Your
PayPal Payments Standard Buttons” on page 337, “Using Your PayPal Account
Profile” on page 349, and “Using Authorization & Capture” on page 389.
Added screen shots to illustrate the refund process. See “Issuing Refunds” on
page 401.


Revision History


July 2009 Added information about prepopulated billing information. See “Single-Item
Payments – Buy Now Buttons” on page 21, “The PayPal Shopping Cart – Add
to Cart and View Cart Buttons” on page 247, “Third-Party Shopping Carts – The
Cart Upload Command” on page 317, and “HTML Form Basics for PayPal
Payments Standard” on page 407.
Updated the payment review page information. See “Single-Item Payments –
Buy Now Buttons” on page 21, “Contribution Payments – Donate Buttons” on
page 75, “Recurring Payments – Subscribe Buttons” on page 113, “The PayPal
Shopping Cart – Add to Cart and View Cart Buttons” on page 247, and “Third-
Party Shopping Carts – The Cart Upload Command” on page 317.
Revised cobranding and language encoding descriptions; removed section about
blocking payment, adding credit card names, adding multiple users, and
handling multiple currencies. See “Using Your PayPal Account Profile” on
page 349.
Added email and bn variables to HTML variables tables. Added information to
the prepopulation variables section. See “HTML Variables for PayPal Payments
Standard” on page 417.

April 2009 Added descriptions on how to use the discounts feature with Buy Now buttons,
Add to Cart buttons, and third-party carts. See “Single-Item Payments – Buy
Now Buttons” on page 21, “The PayPal Shopping Cart – Add to Cart and View
Cart Buttons” on page 247, and “Third-Party Shopping Carts – The Cart Upload
Command” on page 317.
Also added discount variables to the HTML variables tables. See “HTML
Variables for Payment Transactions” on page 426 and “HTML Variables for
Shopping Carts” on page 427.

September 2008 Revised information on creating payment buttons on the PayPal website,
including saving buttons in your PayPal account and tracking inventory. See
button-specific chapters for details.
Added sample code for Add to Cart buttons that open the PayPal Shopping Cart
in the same window as the merchant website. Also added how to use the
shopping_url variable to control which merchant page buyers return to when
they click the Continue Shopping button. See “Sample HTML Code for Add to
Cart Buttons” on page 285.

June 2008 Added chapter on Subscribe buttons. See “Recurring Payments – Subscribe
Buttons” on page 113. Added chapter on Third-Party Shopping Carts. See “The
PayPal Shopping Cart – Add to Cart and View Cart Buttons” on page 247.

March 2008 Made hanges to definition of authorization honor periods. See “Honor Period
and Authorization Period” on page 389.

January 2008 Added separate checkout experience and command for Donate buttons. See
“Contribution Payments – Donate Buttons” on page 75.

August 2007 Documented shipping calculations with tiered rates in different destination
regions. See “Automatic Calculation of Shipping Charges (U.S. Merchants
Only)” on page 368.


Where to Go for More Information


May 2007 Added information on securing buttons. See “Securing Your PayPal Payments
Standard Buttons” on page 337.

April 2007 Added “Address Handling (U.S. Merchants Only)” on page 445.

October 2006 Minor clarifications.

August 2006 Added new PayPal Shopping Cart variable, shopping_url.
Revised content to indicated that the value _ext-enter of the cmd variable for
FORM prepoulation is no longer necessary.
Clarified the values for the rm variable – 0, 1, or 2; not the strings "GET" or
"POST".

July 2006 Added information on how to use PayPal Authorization & Capture with PayPal
Payments Standard, including how to capture multiple authorizations in batches
on the PayPal website; see “Using Authorization & Capture” on page 389.

March 2006 Made miscellaneous minor corrections.
Expanded description of creating Encrypted Website Payments buttons.

Where to Go for More Information
 Merchant Gift Certificates Guide
 Merchant Setup and Administration Guide
 Sandbox User Guide
 PayPal Password Management Installation Guide
 Button Manager API for NVP
 Button Manager API for SOAP

Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com


Documentation Feedback


1 Single-Item Payments – Buy Now
Buttons

Use Buy Now buttons to accept single-item purchase payments. A Buy Now button can sell
one or more units of a single item. Make additional Buy Now buttons for additional items that
you want to sell.

You can create Buy Now buttons that you add to your website by using a tool on the PayPal
website, or you can write the HTML code for Buy Now buttons manually. You can create
buttons with limited functionality before you create your PayPal account or with JavaScript
disabled in your browser.
Read the following topics to learn more about Buy Now buttons:
 “Getting Started With Buy Now Buttons” on page 21
 “The Checkout Experience With Buy Now Buttons” on page 25
 “Managing Buy Now Transactions” on page 33
 “Advanced Features of Buy Now Buttons” on page 35
 “Creating Advanced Buy Now Buttons on the PayPal Website” on page 37
 “Sample HTML Code for Buy Now Buttons” on page 52
 “Sample URL Code for a Buy Now Email Payment Link” on page 62
 “Creating Buy Now Buttons with JavaScript Disabled” on page 62

Getting Started With Buy Now Buttons
The easiest way to add a Buy Now button to your website is by using the button creation tool
on the PayPal website. As soon as you add the button, you can begin accepting payments on
your website.


Single-Item Payments – Buy Now Buttons
1

Follow one of these procedures to get started creating your own Buy Now buttons:
 “Using the Button Creation Tool for a Basic Buy Now Button” on page 22
 “Creating Buy Now Buttons Before You Create Your PayPal Account” on page 23

Using the Button Creation Tool for a Basic Buy Now Button
1. Log in to your PayPal account at https://www.paypal.com.
The My Account Overview page opens.
2. Click the Profile subtab.
The Profile Summary page opens.
3. Under the Selling Preferences heading, click the My Saved Buttons link.
The My Saved Buttons page opens.
4. In the Related Items box on the right, click the Create new button link.
The Create PayPal payment button page opens.
5. In the Choose a button type dropdown menu, select “Buy Now.”
6. Enter the payment details of your item.
– Item name – Enter the name of the item or service that you wish to sell.
– Price – Enter the price of your item.
7. Scroll to the bottom of the page, and click the Create Button button.
The You've created your button page opens.
8. Click the Select Code button on the Websites tab to select all of the generated HTML
code.
9. Do one of the following to copy the selected text to the clipboard:
– For Windows and Mac, right-click on the code, and then select Copy.


1

– For Windows, press Ctrl+C.
– For Mac, press CMD+C.
10.In your web editing tool, open the webpage where you want to show the button.

IM PORT AN T : Be sure that your tool is ready for you to paste HTML code, such as by
switching to an HTML view from a design view of your webpage.
11. Do one of the following to paste the text from the clipboard onto your webpage, where you
want the button to appear:
– For Windows or Mac, right-click on the code, and then select Paste.
– For Windows, press Ctrl+V.
– For Mac, press CMD+V.

Creating Buy Now Buttons Before You Create Your PayPal Account
You can create basic Buy Now buttons, add them to your website, and begin accepting
payments before you sign up for your PayPal account. Read the following topics to learn more
about creating Buy Now buttons before you create your PayPal account.
 “Creating a Basic Buy Now Button Without a PayPal Account” on page 23
 “Limitations of Buy Now Buttons Created Without a PayPal Account” on page 24
 “Unclaimed Payments From Buttons Created Without a PayPal Account” on page 25
Creating a Basic Buy Now Button Without a PayPal Account

NOT E : You cannot create payment buttons without a PayPal account if JavaScript is disabled
in your browser.
1. Go to the PayPal website at https://www.paypal.com.
2. Click the Business tab.
3. Click Accept Credit Cards on a Website.
4. Under the PayPal Payments Standard heading, click the Select button.
A page that describes PayPal Payments Standard opens.
5. Click the Try it now button.


1

– Email address to receive payments– Enter the email address that you will use when you
sign up for your PayPal account.
code.
10.Do one of the following to copy the selected text to the clipboard:
11. In your web editing tool, open the webpage where you want to show the button.

12.Do one of the following to paste the text from the clipboard onto your webpage, where you

After Completing This Task:
Sign up for your PayPal account. You cannot collect payments that buyers make with your
payment button until you sign up successfully for your PayPal Premier account or Business
account.

Limitations of Buy Now Buttons Created Without a PayPal Account. Consider the
following limitations of payment buttons that you create and add to your website before you
 You cannot claim the payments that buyers authorize during checkout. PayPal collects and
holds the payments as unclaimed until you sign up for your PayPal account.
 Buyers must have a PayPal account to pay you. Any ability to pay by credit card is
disabled.
 PayPal limits the features that you can specify with the button creation tool, such as:
– Saving your buttons in your PayPal account
in your browser.


1
The Checkout Experience With Buy Now Buttons

Unclaimed Payments From Buttons Created Without a PayPal Account
For buttons that you create without a PayPal account, PayPal holds any payments authorized
by buyers until you sign up for an account. PayPal identifies these held payments as
“unclaimed.” PayPal holds your unclaimed payments under the email address that you specify
when you create the buttons. Make sure to use the same email address when you sign up for
your account. Otherwise, PayPal cannot transfer your unclaimed payments to your PayPal
account balance.
In their PayPal accounts, buyers see the unclaimed payments that they made to you in their
recent account activity and in their transaction history. Until you finish signing up for your
PayPal account, buyers can cancel your unclaimed payments and recover their funds.

Unclaimed Payments From Payment Buttons Created Without a PayPal Account

This section demonstrates the PayPal checkout experience for people who click Buy Now
buttons on your website. The following diagram illustrates the steps.


1

The Checkout Experience with Buy Now Buttons

Read these topics to better understand the checkout experience with Buy Now buttons:
 “Begin – Buyers are Ready to Purchase Your Item on Your Website” on page 27
 “1 – Buyers Enter Their Billing Information, or They Log In to PayPal” on page 27
 “2 – Buyers Confirm Their Transaction Details Before Paying” on page 29
 “3 – Buyers View and Print Their PayPal Payment Confirmations” on page 30
 “End – Buyers Receive Payment Authorization Notices by Email” on page 31
 “Enhancing the Checkout Experience With Buy Now Buttons” on page 31


1

Begin – Buyers are Ready to Purchase Your Item on Your Website
The basic checkout experience with Buy Now begins when someone on your website is ready
to purchase your item. Smoky

Buyers Begin on Your Website When They Are Ready To Buy Your Item

In this example, Steve begins on Herschel’s Hot Sauce website and decides to try a bottle. He
clicks the Buy Now button for a single 12 oz. bottle to check out.

1 – Buyers Enter Their Billing Information, or They Log In to PayPal
PayPal displays a billing information/log-in page, which lets buyers enter their credit card
information or log in to PayPal to pay.


1

Buyers Enter Their Billing information or Log In to PayPal

For Buy Now buttons, the PayPal billing information/log-in page shows transaction details on
the left, such as item name and transaction subtotal.
If buyers are satisfied with the details, they do one of the following to select a payment
method:
 Have a PayPal account? – Buyers click the link, enter their PayPal credentials, and click
the Log in button.
 Don’t have a PayPal account? – Buyers enter their billing information. They also enter
their contact information – email address and home phone number – so that PayPal can
send them their PayPal transaction receipts and can contact them if necessary to complete
the transaction. Then, they click the Review Order and Continue button.
If your website gathers information about your buyer, you can define HTML code to
prepopulate (prefill) the corresponding billing information fields. In this case, the buyers


1

see a collapsed version of the billing information section. For example, if you prefilled the
billing address, the address information displays on the page without the entry fields. Each
prefilled section of information is followed by a change link to let the buyers modify the
information, if necessary.
For more information about prepopulation, see “Filling Out FORMs Automatically with
HTML Variables” on page 411.
In this case, Steve is satisfied with the total transaction amount of $5.95 USD. He doesn’t have
a PayPal account. Instead, he enters his billing and contact information, and then he clicks the
Review Order and Continue button.

2 – Buyers Confirm Their Transaction Details Before Paying
PayPal displays a transaction confirmation page to let buyers confirm the details before they
complete their transactions and authorize their payments.

Buyers Confirm Their Payment Details Before Paying

In this case, Steve reviews the transaction details and clicks the Pay Now button to complete
the transaction and make his payment.


1

3 – Buyers View and Print Their PayPal Payment Confirmations
PayPal displays a payment confirmation page after buyers pay to let them know that they have
completed their transactions and authorized their payments successfully.

Buyers View Their Payment Confirmations

From the payment confirmation page, buyers can:
 View the PayPal Receipt ID – the transaction ID – to reconcile their payments.
 Click the Print receipt link to print receipts for their records.


1

Buyers Print Their PayPal Payment Receipts

In this case, Steve prints the PayPal payment receipt for his records.

End – Buyers Receive Payment Authorization Notices by Email
PayPal sends buyers a payment authorization notice by email to confirm the transaction that
they made with the merchant.

Enhancing the Checkout Experience With Buy Now Buttons
PayPal Payments Standard offers these features to enhance the basic checkout experience for
your buyers:
 “Calculating Tax and Shipping Amounts” on page 31
 “Co-Branding the Checkout Pages with Your Logo and Colors” on page 32
 “Prepopulating the Checkout Pages With Billing and Shipping Addresses” on page 32
 “Returning Buyers to Your Website After They Check Out” on page 32
Calculating Tax and Shipping Amounts
The basic checkout experience handles tax and shipping, if you provide the information. You
can enhance the checkout experience by specifying tax and shipping rates in your account


1

profile. PayPal calculates the charges automatically for each transaction. In addition, you can
specify tax and shipping charges individually for items in the payment buttons that you create.
For more information, see:
 “Automatic Calculation of Sales Tax” on page 363
 “Automatic Calculation of Shipping Charges (U.S. Merchants Only)” on page 368
 “Automatic Calculation of Shipping Charges (non-U.S. Merchants Only)” on page 384
Co-Branding the Checkout Pages with Your Logo and Colors
The basic checkout experience displays your email address or your business name in the upper
left corner of the checkout pages. You can enhance the checkout experience by setting up
custom page payments in your account profile to specify logos and colors that match the style
of your website. PayPal uses the logo and colors to display the checkout pages. In addition,
you can specify logos and colors with advanced HTML variables that you add to the code of
your button.
 “Co-Branding the PayPal Checkout Pages” on page 349
 “HTML Variables for Displaying PayPal Checkout Pages” on page 434
Prepopulating the Checkout Pages With Billing and Shipping Addresses
The basic checkout experience has forms for filling in billing and shipping information. You
can enhance the checkout experience by prepopulating the forms with buyer information that
you have on your website.
To learn more about prepopulation, see “Filling Out FORMs Automatically with HTML
Variables” on page 411.
To learn more about the HTML variables to use, see “HTML Variables for Filling Out PayPal
Checkout Pages Automatically” on page 439.
Returning Buyers to Your Website After They Check Out
The basic checkout experience leaves buyers on the PayPal website after they check out. Use
one of the following techniques to enhance the checkout experience so that buyers return to
your website, instead.
 Return URL – Let buyers return to a page on your website if they click a return link or
button on the PayPal payment confirmation page.
To learn more, see Step 5 of “Step 3 – Adding Advanced Features to Your Buy Now
Button” on page 48 or “HTML Variables for Displaying PayPal Checkout Pages” on
page 434.
 Auto Return – Have PayPal return people automatically to a page on your website.

IM PORT AN T : PayPal recommends that you turn Payment Data Transfer on when you turn
Auto Return on. With Auto Return on, PayPal redirects buyers to your
website from an alternative PayPal payment confirmation page, which does
not allow them to print PayPal receipts. Payment Data Transfer provides


1
Managing Buy Now Transactions

the transaction information that you need to let buyers print receipts from
your website.
To learn more, see “Auto Return” on page 351.
 Payment Data Transfer – PayPal includes information about the completed transaction
when you use a return URL or Auto Return to send people back to your website. Use the
information that Payment Data Transfer provides to display a “thank you, print your
receipt” page on your website.
To learn more, see the Payment Data Transfer webpage on PayPal X Developer Network..

Read the following topics to learn how PayPal helps you manage Buy Now transactions:
 “Using Email Notices to Track Buy Now Transactions” on page 33
 “Using Recent Activity to Track Buy Now Transactions” on page 34
 “Using Transaction History to Track Buy Now Transactions” on page 34
 “Using Downloadable History Logs to Track Buy Now Transactions” on page 34
 “Using Instant Payment Notification to Track Buy Now Transactions” on page 35

Using Email Notices to Track Buy Now Transactions
PayPal sends you email notices when:
 Payments are made.
 Payments are pending.
 Payments are canceled.
Generally, PayPal sends email notices to the primary email address of your account.
PayPal can send email notices to an alternate email address, such as to someone in your
organization who handles order processing or accounting. Add the additional email address to
your account profile. Then, use that email address as the one to receive payments when you
use the button creation tool on the PayPal website. Specify the alternate email address as the
value for the business HTML variable when you write the HTML code yourself.
For more information, see Step 10 in the instructions for “Step 1 – Specifying Basic Features
of Your Buy Now Button” on page 40, or “HTML Variables for PayPal Payments Standard”
on page 417.”


1

Using Recent Activity to Track Buy Now Transactions
PayPal displays Buy Now transactions in your recent activity, soon after buyers complete their
transactions by clicking Buy Now buttons on your website.

Using Recent Activity to Track Buy Now Transactions

To view your recent history:
1. Log in to you PayPal account.
2. Navigate to My Account > Overview.
The My Account Overview opens.
3. Scroll down to the Recent Activity table near the bottom of the page.

Using Transaction History to Track Buy Now Transactions
PayPal lets you search for Buy Now transactions on the History page. The status of payments
found there can be:
 Completed – Transactions were successful, and funds were credited to your account.
 Cleared – Payments cleared senders’ accounts, and funds were credited to your account.
 Uncleared – Payments have not cleared sender’s accounts, and funds were not credited.
To learn how to work with transaction history, see the Merchant Setup and Administration Guide.

Using Downloadable History Logs to Track Buy Now Transactions
PayPal lets you download your Buy Now transactions to your computer from the History page.
You can specify a date range for the transactions and the file format of the download file.
To learn how to work with downloadable history logs, see the Merchant Setup and
Administration Guide.


1
Advanced Features of Buy Now Buttons

Using Instant Payment Notification to Track Buy Now Transactions
PayPal lets your web server receive messages about Buy Now transactions and payment
activity on your account. If you activate Instant Payment Notification, PayPal sends messages
when:
 Payments are first made, with a status of completed or pending.
 Payments clear, fail, or are denied, if the initial status was pending.
To learn more about Instant Payment Notification, see “Instant Payment Notification –
notify_url” on page 415 and the Instant Payment Notification Guide.

Read the following topics to learn about these advanced features of Buy Now buttons:
 “Offering Product Options With Buy Now Buttons” on page 35
 “Prompting for Item Quantities With Buy Now Buttons” on page 36
 “Offering Discounts With Buy Now Buttons” on page 37

Offering Product Options With Buy Now Buttons
Prompt buyers for product options, such as size or color. You can prompt buyers for their
option selections with dropdown menus or with text boxes.
 PayPal provides up to 7 product options on a single button.
 Up to 5 of those options allow selections in dropdown menus.
 Up to 2 of those options allow selections in text boxes.

With Buy Now buttons, you can offer a product option that has separate prices for each
selection by using 1 of the 5 allowable dropdown menus.
Specifying Product Options With Buy Now Buttons
Do one of the following to create Buy Now buttons that offer product options:
 Specify the product options when you create your Buy Now buttons by using the creation
tool on the PayPal website.
See Step 7 of “Step 1 – Specifying Basic Features of Your Buy Now Button” on page 40.


1

 Specify the product options in the HTML button code that you write manually.
See “Sample Code for a Buy Now Button With Product Options” on page 54.

Prompting for Item Quantities With Buy Now Buttons
By default, PayPal allows buyers to purchase single quantities of your product items with Buy
Now buttons. Optionally, you can have PayPal prompt buyers for item quantities.

Do one of the following to create Buy Now buttons that prompt for item quantities:
 Select the Yes radio button for prompting buyers for item quantities when you create Buy
Now buttons by using the creation tool on the PayPal website.
See Step 1 of “Step 3 – Adding Advanced Features to Your Buy Now Button” on page 48.
 Specify that you want PayPal to prompt buyers for item quantities in the HTML button
code that you write manually.
See “Sample HTML Code for a Buy Now Button that Prompts for Quantities” on page 57.


1
Creating Advanced Buy Now Buttons on the PayPal Website

Offering Discounts With Buy Now Buttons
PayPal allows you to offer a discount for an item. You can offer discounts either as an amount
or a percentage.
 Set a discount amount that applies to single or multiple quantities of the item. You can set a
discount for the first item and a different discount for the additional quantity, and you can
limit the total quantity to which the discount applies.
 Set a discount percentage that applies to single or multiple quantities of the item. You can
set a discount for the first item and a different discount for the additional quantity, and you
can limit the total quantity to which the discount applies.
When you set a discount amount or percentage, you can limit the number of items to which the
discount applies. Any applicable tax calculations occur after subtracting the discount.
The discount amount displays on all pages, email messages, and reports that show payment
information.
Specifying Item Discounts
Do one of the following to create Buy Now buttons that specify discounts:
 Specify the discount amounts or percentages when you create your Buy Now buttons by
using the creation tool on the PayPal website.
See Step 6 of “Step 3 – Adding Advanced Features to Your Buy Now Button” on page 48.
See “Sample HTML Code for a Buy Now Button With Discounts” on page 59.

Read the following topics to learn more about creating Buy Now buttons on the PayPal
website:
 “The Basic Steps for Using the Button Creation Tool With Buy Now Buttons” on page 38
 “Saving Buy Now Buttons in Your PayPal Account” on page 38
 “Tracking Inventory and Tracking Profit and Loss” on page 39
 “Adding Advanced Features to Buy Now Buttons With HTML Variables” on page 39
 “Generating Code for Payment Buttons and Email Payment Links” on page 40
 “Protecting HTML Code for Payment Buttons” on page 40
 “Step 1 – Specifying Basic Features of Your Buy Now Button” on page 40
 “Step 2 – Tracking Inventory With Your Buy Now Button” on page 44
 “Step 3 – Adding Advanced Features to Your Buy Now Button” on page 48
 “Copying and Pasting the Buy Now Code” on page 50


1

 “Avoiding Problems With Pasted HTML Code” on page 52

The Basic Steps for Using the Button Creation Tool With Buy Now Buttons
The button creation tool for Buy Now buttons is a single webpage with three sections:
 Step 1: Choose button type and enter payment details – This section lets you specify the
details of your Buy Now button. You can specify product options that buyers can choose,
and you can specify item-specific charges for shipping and tax.
 Step 2: Track inventory, profit and loss (optional) – This section lets you control
whether to save your button in your PayPal account. If you save your button, you can enter
information that PayPal uses to track inventory and to track your profit and loss on the
item.
 Step 3: Customize advanced features (optional) – This section lets you work with
advanced features of Buy Now buttons, including letting buyers change item quantities. If
you are familiar with HTML programming and the advanced HTML variables supported
by PayPal Payments Standard buttons, you can enter them here.
One section at a time is open for you to work with. To work with another section, click its step
bar to expand it.

You can switch between the sections as often as you like, until you click the Create Button
button at the bottom of the page. Then, PayPal generates the code for your button and displays
it on the You are viewing your button code page. Copy the code and paste it onto your
webpage, and your payment button is complete.

Saving Buy Now Buttons in Your PayPal Account
By default, the button creation tool saves payment buttons in your PayPal account. The tool
saves your button and generates the code when you click the Create Button. You must copy
and paste the generated code onto your webpages, whether or not you save your button at


1

PayPal. The generated code is shorter for saved buttons, because PayPal keeps most of the
information about your button in your account instead of placing it in the code that you add to
your website.
Saving your payment buttons in your PayPal account has these benefits:
 Your payment buttons are more secure, because the generated code that you add to your
website contains no information that can be tampered with to produce fraudulent payments.
 You can edit the details and options for your payment buttons in your PayPal account,
without changing the button code that you added to your website.
NOT E : If you change product options, you must copy and paste the code newly generated
by PayPal to replace the code that you pasted previously.
 You can track inventory, and you can track profit and loss.
Use the Step 2 section of the button creation tool to control whether your button is saved in
your PayPal account. You can have a maximum of 1,000 saved buttons in your PayPal
account.

Tracking Inventory and Tracking Profit and Loss
PayPal can track inventory and can track profit and loss for items that you sell with Buy Now
buttons if you save them in your PayPal account. You can track inventory for the item itself or
by its product options.
If you track inventory, PayPal helps you avoid oversold situations. PayPal sends you an alert
by email when your inventory on hand falls to or below the alert level you specify. You have
the option to let oversold transactions finish or to warn buyers and prevent them from buying
more than your quantity on hand.
If you track profit and loss, PayPal helps you understand the profitability of your items. You
enter the cost of your item, including the price that you pay to acquire the item, as well as other
activity costs that you incur, such as warehousing, quality control, and administrative
overhead. PayPal then provides profit and loss reports based on the volume of sales.
Use the Step 2 section of the button creation tool to specify the information that PayPal uses to
track inventory and to track profit and loss.

Adding Advanced Features to Buy Now Buttons With HTML Variables
Some advanced features of payment buttons can be specified only with HTML variables. If
you are familiar with HTML programming and the advanced HTML variables supported by
PayPal Payments Standard payment buttons, you can enter them in the button creation tool
before generating the button code.
Use the Step 3 section of the button creation tool to enter advanced HTML variables that you
want to include in your payment button.
For more information, see Step 6 of “Step 3 – Adding Advanced Features to Your Buy Now
Button” on page 48.


1

Generating Code for Payment Buttons and Email Payment Links
When you create Buy Now buttons with tools on the PayPal website, PayPal generates HTML
code for website payment buttons. Then, you copy and paste the HTML code onto the pages of
your website.
In addition to HTML code, PayPal generates URL code for email payment links. Use email
payment links to add Buy Now functionality to your email messages. If your web editing tool
or your service provider does not allow you to paste HTML code onto your webpages, you
might be able to paste the URL code for email payment links onto your webpages instead.

Protecting HTML Code for Payment Buttons
When you create Buy Now code with tools on the PayPal website, PayPal lets your protect the
HTML button code that it generates by encrypting part of it. Protecting the HTML code of
your payment buttons helps protect against malicious tampering and fraudulent payments.

IM PORT AN T : Merchants with significant payment volume are required to take precautions
on securing PayPal Payments Standard buttons.
For more information, see “Securing Your PayPal Payments Standard
Buttons” on page 337.”

Step 1 – Specifying Basic Features of Your Buy Now Button
To begin using the button creation tool for Buy Now buttons:
1. Log in to your PayPal Premier or Business account at https://www.paypal.com.
3. Under the Selling Preferences heading, do one of the following:
– Click the My Saved Buttons link, and then click the Create new button link in the
upper right of the page, if you previously saved payment buttons in your PayPal account.
To create a new button that is similar to a button that you saved, find the saved button in
the list. Then, click the Action dropdown menu at the right and click the Create similar
button link.


1

– Click the Create New Button link, if you have no buttons saved in your PayPal account.

– Item ID – (optional) Enter the inventory ID or tracking number of your item, if you
assign such IDs to your products.
If you want to set up your item so that PayPal tracks inventory levels, enter a value that
is unique among all the items that you sell and want PayPal to track. For more
information, see “Step 2 – Tracking Inventory With Your Buy Now Button” on
page 44.

If you want to add product options with different prices for each option that buyers can
select, do not enter a price here. For more information, see Step 6 below.

– Currency – Select the currency in which you priced the item; the dropdown menu
automatically selects the currency of your primary balance.
If you want to customize the country and language of the button, make sure that you
select an appropriate currency here. For more information, see Step 7 below.


1

6. Customize your button with product options (optional).
Do any of the following:
– Add dropdown menu with price/option – Select this checkbox to add a dropdown
menu of product options, with a separate price for each option.
Enter a name for the dropdown menu, such as “Color”. For each menu option, enter a
name, such as “Red”, “Blue”, or “Green”, and the price you want buyers to pay. Select
the currency for your prices from the dropdown menu. You can add a maximum of 10
priced options to the menu.
Click the Done button to preview the dropdown menu in the Buyer’s View pane.
Click the Edit link to change the name and options of your dropdown menu. To remove
an option, clear the menu option name and price, and then click the Done button.
Click the Delete link to remove the dropdown menu from your button.

– Add dropdown menu without prices – Select this checkbox to add a dropdown menu
of product options, without separate prices.
Enter a name for the dropdown menu, such as “Size”. For each menu option, enter a
name, such as “Small”, “Medium”, or “Large”.
an option, clear the menu option name and click the Done button.
Click the Add another dropdown menu link to open a set of fields for another
dropdown menu of options without prices. You can add a maximum of 4 dropdown
menus, with a maximum of 10 options per menu.

– Add text field – Select this checkbox to add a text box in which buyers can enter option
information.
Enter a name for the text box, such as “Enter the text you want engraved”.
Click the Done button to preview the text field in the Buyer’s View pane.
Click the Edit link to change the name of the text field.
Click the Delete link to remove the text box from your button.
Click the Add another text box link to open a field for the name of another text box.
You can add a maximum of 2 text boxes.
For more information, see “Offering Product Options With Buy Now Buttons” on page 35.
7. Customize the appearance and the language of your button (optional).
Click the Customize appearance link and select one of the following:


1

– PayPal button – Select this radio button to use a button image that is hosted by PayPal.
You can configure the size of the button, specify whether the button displays payment
card logos, and specify the country and language for the button text.
If you change the country, ensure the currency that you selected in Step 5 above is
appropriate.
– Use your own button – Select this radio button to specify the URL of your own button
image that is not hosted by PayPal. Use your own button image if the buttons hosted by
PayPal do not fit the look of your website.
If your image is hosted securely, change the text box to begin with https//.
8. Add shipping charges and tax rates to your item (optional).
You can add shipping charges and tax rates for your item here. They override the tax and
shipping rates that PayPal calculates automatically based on rates that you specify in your
account profile.
– Shipping – Enter a specific amount to charge for shipping this item.
The currency for the amount is the same as the currency for the item. Enter zero (0.00)
for items that do not incur shipping charges. The amount you enter here overrides the
automatic calculation of shipping charges on the item.
NOT E :Before you can accept payments from Buy Now buttons with specific shipping
costs entered here, you must enable the override of shipping methods in the
Shipping Calculations section of your account profile. You can create your
button successfully, but you cannot accept payments from your button until you
enable shipping cost overrides. Ensure that you enable shipping cost overrides
for all the shipping methods that you set up for your account. For more
information, see “Automatic Calculation of Shipping Charges (U.S. Merchants
Only)” on page 368 or “Automatic Calculation of Shipping Charges (non-U.S.
Merchants Only)” on page 384.
– Tax – Enter a percentage to calculate the tax on this item, regardless of quantity.
The currency for the calculated tax will be the same as the currency for the item. Enter
zero (0.000) for non-taxable items to override automatic sales tax calculation on the
item.
9. Choose between your merchant ID and your email address.
Select one of the following radio buttons to associate transactions from your button with
your PayPal account.
– Secure merchant account ID – Select this radio button to associate your button with
your PayPal account by using your merchant ID. PayPal assigns a unique merchant ID
to your account and includes it automatically in the code for your button.
Only PayPal can match your secure merchant ID and PayPal account. When you use a
secure merchant ID, your PayPal email address is not exposed in the HTML button code
of your webpages.
– Plain text email – Select this radio button to associate your button with your PayPal
account by using your email address. Select from the email addresses in your PayPal
account. For example, you might select the email address of the person in your


1

organization who handles order fulfillment or accounting. All payments are deposited to
your PayPal account balance, regardless of which email address receives payments from
this button. Only confirmed email addresses can be used to receive payments.

IM PORT AN T : Your email address is a less secure way to associate your button with your
PayPal account than use of your merchant ID. Your email address is
exposed on webpages wherever you paste the HTML code for your button.
10.Do one of the following:

– Click the Create Button button if you specified all the features for your button.
Follow the instructions for “Copying and Pasting the Buy Now Code” on page 50.
– Click the Step 2 bar if you want PayPal to track inventory levels for your item or if you
do not want to save your button in your PayPal account.
Follow the instructions for “Step 2 – Tracking Inventory With Your Buy Now Button”
on page 44.
– Click the Step 3 bar if you want to specify advanced features for your button, such as
prompting buyers for item quantities.
Follow the instructions for “Step 3 – Adding Advanced Features to Your Buy Now

Step 2 – Tracking Inventory With Your Buy Now Button
Use the Step 2 section of the button creation tool to control whether to save the important
details of your button in your PayPal account and to provide inventory tracking information
for your item.
For more information, see “Tracking Inventory and Tracking Profit and Loss” on page 39.
1. Select the Save button at PayPal checkbox to save your button in your PayPal account
and to enable your ability to track inventory for your item and to track profit and loss.


1

2. Select the Track inventory checkbox to enable entering information that PayPal uses to
track inventory for your item. Then, do one of the following:
– By Item – Select this radio button if you want to track inventory regardless of product
options selected by buyers.
Enter the quantity that you currently have in stock and an alert level. PayPal sends you
an alert by email when your inventory on hand falls to or below the alert level.
– By Option – Select this radio button if you want to track inventory by the product options
you specified during Step 7 of “Step 1 – Specifying Basic Features of Your Buy Now
Button” on page 40. If you set up product options with prices, the button creation tool
automatically selects this radio button.
For each option listed, enter a unique item ID, the quantity that you currently have in
stock, and an alert level. PayPal sends you an alert by email when your inventory on
hand for any option falls to or below its alert level.
Under the Can customers buy an item when it is sold out? heading, do one of the
following:
– Yes – Select this radio button to let buyers checkout and authorize their payments, even
when inventory tracking shows that your item would become oversold. Buyers are not
informed of oversold or out-of-stock situations nor that their items will be on back order
after they complete their transactions.
– No – Select this radio button to prevent buyers from checking out and authorizing their
payments when inventory tracking shows that your item would become oversold. In the
text box, enter the URL of a page on your website where you want PayPal to send buyers
of out of stock items. When PayPal detects an oversold situation, PayPal lets buyers
know that the item is out of stock.
If there are some items in stock, but not enough to fulfill a buyer’s request, PayPal
displays the amount currently available and adjusts the number in Quantity.


1

Buyers can accept the quantity entered by PayPal or adjust the quantity to a lower
number.
If there are no items in stock, PayPal lets buyers know that the item is completely sold
out.

Buyers click the Continue Shopping button to return to the webpage at the URL that
you specified.
“No” is the default choice for this feature.
3. Select the Track profit and loss checkbox to enable entering information that PayPal uses
to track profit and loss for your item. You do not have to track inventory to track profit and


1

loss. If you track inventory, you can track profit and loss only in the same way – either by
item or by option.
If you only track profit and loss and do not track inventory, do one of the following:
– By Item – Select this radio button if you want to track profit and loss regardless of
product options selected by buyers.
– By Option – Select this radio button if want to track profit and loss by product options
that you specified during “Step 1 – Specifying Basic Features of Your Buy Now Button”
on page 40. If you set up product options with prices, the button creation tool
automatically selects this radio button and you cannot change it.
Enter the cost to you of your item or for each product option. Include the price that you pay
to acquire the item, as well as other activity costs that you incur, such as warehousing,
quality control, and administrative overhead.
4. Do one of the following:

Follow the instructions for “Step 3 – Adding Advanced Features to Your Buy Now
– Scroll to the top of the page and click the Step 1 bar if you want to adjust the basic
features of your button.
Follow the instructions for “Step 1 – Specifying Basic Features of Your Buy Now
Button” on page 40, beginning with Step 6.


1

Step 3 – Adding Advanced Features to Your Buy Now Button
Use the Step 3 section of the button creation tool to specify advanced features of your button.
1. Do you want to let buyers change order quantities (optional)?
– Yes – Select this radio button to prompt buyers for item quantities. PayPal prompts
buyers for quantities after they click your Buy Now button.

Use this feature cautiously, because buyers could specify quantities greater than you
could fulfill.
If you save your button in your PayPal account and you set up inventory tracking for
your item in “Step 2 – Tracking Inventory With Your Buy Now Button” on page 44,
PayPal can help prevent buyers from purchasing more items than you can fulfill.
– No – Select this radio button to let buyers purchase only one item at a time. “No” is the
default choice for this advanced feature.
2. Can your buyers add special instructions in a message to you (optional)?
– Yes – Select this radio button to let buyers add special instructions to you during
checkout. In the Name of message box text box, enter the text that you want displayed
for the text box in which buyers enter their special instructions; the default value is “Add
special instructions to merchant”.


1

“Yes” is the default choice for this feature.
– No – Select this radio button if you do not want a text box for special instructions.
3. Do you need your buyers’ shipping addresses (optional)?
– Yes – Select this radio button to prompt buyers to select or enter shipping addresses
during checkout.
– No – Select this radio button if you do not want to prompt buyers for shipping addresses.
Select this option for items that do not require shipping, such as digital goods that buyers
download, or if the item is a service that does not require on-site delivery.
4. Take buyers to a specific webpage (URL) after checkout cancellation (optional)?
Select the checkbox and enter a URL in the text box if you have a special page on your
website where you want buyers to return if they cancel their checkouts before completing
their transactions.
5. Take buyers to a specific webpage (URL) after successful checkout (optional)?
website where you want buyers to return after they complete their checkouts successfully.
NOT E : If you have a special webpage for buyers who return to your website after checking
out successfully, consider implementing Payment Data Transfer so that you can
display information about the completed transactions.
To learn more, see the Payment Data Transfer webpage on PayPal X Developer
Network..


1

6. Add advanced variables to the HTML code of your payment button (optional).
If you are familiar with the HTML programming and the advanced HTML variables
supported by PayPal Payments Standard payment buttons, you can enter them here. Select
the checkbox, and then enter the variables in the text box below it.
Enter any advanced HTML variables in the following name/value-pair format:
variableName=allowableValue
For example, if you want to handle purchases as orders rather than as final sales, use the
HTML variable paymentaction with the value order. If you were to include the
variable in HTML code that you write manually, you would use the standard HTML
format:

<input type="hidden" name="paymentaction" value="order">
Enter the variables in the text box using the shortened, name/value-pair format instead:
paymentaction=order
Do not enclose values in quotes, even if values contain spaces. PayPal surrounds the value
from the equal sign (=) to the end of the line with quotes in the generated HTML code.
For more information, see “HTML Form Basics for PayPal Payments Standard” on
page 407.”
– Scroll to the top of the page and click the Step 2 bar if you want to adjust information
that PayPal uses to track inventory levels or if you do not want to save your button in

Copying and Pasting the Buy Now Code
After you click the Create Button button, PayPal displays the You are viewing your button
code page. The page contains tabs with Buy Now code for specific situations:
 Website – Copy and paste the HTML button code on this tab onto the pages of your
website.
 Email – Copy and paste the URL email payment link code on this tab into email templates
and messages, or paste it onto webpages if your hosting provider does not allow you to
paste HTML code.


1

Regardless of saving your buttons in your PayPal account, you must copy and paste the code
that PayPal generates onto your own webpages and into email templates and messages.
Copying and Pasting the HTML Code for the Buy Now Button
The Website tab on the You are viewing your button code page contains the generated
HTML code for your payment button.

If you chose not to save your button in your PayPal account, PayPal protects the generated
HTML code with encryption automatically. Protected HTML code helps secure your buttons
against malicious tampering and fraudulent payments.
You can expose the code of your payment button by clicking the Remove code protection
link at the upper right of text box. For example, you might remove protection so that you can
edit the code later to change the item price. If you remove code protection, use other methods
that PayPal recommends for securing your payment button. Click the Protect code link to
restore the button protection that you removed.

code.


Copying and Pasting the Code for the Buy Now Email Payment Link
The Email tab on the You are viewing your button code page contains the generated URL
code for your email payment link.


1
Sample HTML Code for Buy Now Buttons

IM PORT AN T : PayPal cannot protect the URL code for email payment links. Secure the
payments you receive from email payment links by using an alternative
method that does not involve encryption
1. Click the Select Code button on the Email tab to select all of the generated URL code.
3. Open the email template or message that you want to send.

Avoiding Problems With Pasted HTML Code
After you paste the code onto your webpage or into your email, ensure that it matches exactly
the code that you copied from PayPal. Pasted code might not match the generated code for the
following reasons:
 You did not copy all of the generated code.
 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.
 Your editing tool might change some characters in the pasted code.

The sample HTML code in this section demonstrates various features of Buy Now buttons:
 “Sample HTML Code for a Basic Buy Now Button” on page 53
 “Sample Code for a Buy Now Button With Product Options” on page 54
 “Sample HTML Code for a Buy Now Button that Prompts for Quantities” on page 57
 “Sample HTML Code for a Buy Now Button With Discounts” on page 59


1

To protect against malicious users tampering with the HTML code for your Buy Now buttons
and submitting fraudulent contributions, see “Securing Your PayPal Payments Standard

IM PORT AN T : Organizations with significant payment volume are required to take
precautions on securing PayPal Payment Standard buttons.

Sample HTML Code for a Basic Buy Now Button
The sample following HTML code illustrates a basic Buy Now button with these features:
 An item named “Hot Sauce–12 oz. Bottle”.
 An item price of $5.95 USD.
 PayPal calculates tax and shipping based on rates that you set up in your PayPal account.

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


<input type="hidden" name="business" value="herschelgomez@xyzzyu.com">


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


<input type="hidden" name="item_name" value="Hot Sauce-12 oz. Bottle">
<input type="hidden" name="amount" value="5.95">
<input type="hidden" name="currency_code" value="USD">


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

1

Sample Code for a Buy Now Button With Product Options
The following sample code illustrates a basic Buy Now button with a dropdown menu of
product options.






<input type="hidden" name="on0" value="Type">Type of sauce <br />
<select name="os0">
<option value="Select a type">-- Select a type --</option>
<option value="Red">Red sauce</option>
<option value="Green">Green sauce</option>
</select> <br />

</form>
The sample code above produces the following result on your webpage:

Paste the code onto your webpage below an image or a text description of the item.

Sample Code for a Buy Now Button With Product Options With Prices
The following sample code illustrates a basic Buy Now button with a dropdown menu of
product options that have separate prices for each option. Only one of the dropdown menus in
the set of product options that your Buy Now button offers can have prices.

1

Product options with prices specify the prices in two places:
 The dropdown menu displays the prices for each option. Buyers see the prices they pay for
each option.
 A list of hidden HTML variables repeats the prices for each option. PayPal uses these
prices to charge buyers for the options they choose.
Dropdown menus with option prices use the following variables:
 currency_code – sets the currency for option prices
 item_index – identifies which dropdown menu of product option has prices
 option_select* and option_amount* – repeats the prices for each option
NOT E : You cannot specify item IDs for product options with prices to have PayPal track
inventory for your item. PayPal can track inventory by product option only for buttons
that you save in your PayPal account.




<input type="hidden" name="item_name" value="Hot Sauce">

<input type="hidden" name="on0" value="Type">Type of sauce <br />
<select name="os0">
<option value="Select a type">-- Select a type --</option>
<option value="Red">Red sauce</option>
<option value="Green">Green sauce</option>
</select> <br />


<input type="hidden" name="on1" value="Size">Size <br />
<select name="os1">
<option value="06oz">6 oz. bottle - $5.95 USD</option>
<option value="12oz">12 oz. bottle - $9.95 USD</option>
<option value="36oz">3 12 oz. bottles - $19.95 USD</option>
</select> <br />


<input type="hidden" name="option_index" value="1">
<input type="hidden" name="option_select0" value="06oz">
<input type="hidden" name="option_amount0" value="5.95">

1


</form>


Sample Code for a Buy Now Button With Product Options as a Text Box
The following sample code illustrates a basic Buy Now button with a text box for entering
product options.






<input type="hidden" name="on0"

1

value="Size">Enter your size (S, M, L, X, XX) <br />
<input type="text" name="os0" maxlength="60"> <br />

</form>


Sample HTML Code for a Buy Now Button that Prompts for Quantities
The following sample HTML code illustrates a basic Buy Now button that prompts buyers to
specify item quantities. Use this feature cautiously, because buyers could specify quantities
greater than you could fulfill.






1


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

</form>
The sample code above produces the following result during checkout.

Use this feature cautiously, because buyers could specify quantities greater than you could
fulfill.
If you save your button in your PayPal account and you set up inventory tracking for your item
in “Step 2 – Tracking Inventory With Your Buy Now Button” on page 44, PayPal can help
prevent buyers from purchasing more items than you can fulfill.
For more information, see “Prompting for Item Quantities With Buy Now Buttons” on
page 36.

1

Sample HTML Code for a Buy Now Button With Discounts
 “Sample Code for a Buy Now Button with a Flat Discount Amount” on page 59
 “Sample Code for a Buy Now Button with a Multiple Discount Amounts” on page 60
 “Sample Code for a Buy Now Button with Discount Percentages” on page 60
 “Sample Code for a Buy Now Button with a Buy One, Get One Free Discount” on page 61
Sample Code for a Buy Now Button with a Flat Discount Amount
The following sample HTML code illustrates a basic Buy Now button that provides a $2.00
discount on the entire order. The HTML code prompts buyers to specify item quantities. Use
this feature cautiously, because buyers could specify quantities greater than you could fulfill.







<input type="hidden" name="discount_amount" value="2.00">


</form>

1

Sample Code for a Buy Now Button with a Multiple Discount Amounts
The following sample HTML code illustrates a basic Buy Now button that provides a $0.15
discount on the 1st item ordered and a $0.20 discount on the next 4 items.






<input type="hidden" name="discount_amount2" value="0.20">
<input type="hidden" name="discount_num" value="4">


</form>

Sample Code for a Buy Now Button with Discount Percentages
The following sample HTML code illustrates a basic Buy Now button that provides a 5%
discount on the 1st item ordered and a 10% discount on the next 4 items. The HTML code
prompts buyers to specify item quantities. Use this feature cautiously, because buyers could
specify quantities greater than you could fulfill.


input type="hidden" name="business" value="herschelgomez@xyzzyu.com">

1



<input type="hidden" name="discount_rate" value="5">
<input type="hidden" name="discount_rate2" value="10">


</form>

Sample Code for a Buy Now Button with a Buy One, Get One Free Discount
The following sample HTML code uses the discount percentage variables to offer a “Buy one,
get one free” discount. To receive the discount, the buyer must purchase 2 of the item; the 2nd
one is free (100% discount).
If the buyer purchases only 1 unit of the item, it is the full price. If the buyer purchases more
than 2 units, the 2nd unit is free and any additional units are full price.

1
Sample URL Code for a Buy Now Email Payment Link


</form>

Sample URL Code for a Buy Now Email Payment Link
You can write your own URL code for Buy Now email payment links.
Use the same variables and values that you include in HTML code for Buy Now buttons in
Buy Now email payment links. Use ampersands (&) to separate the variables and their values
from each other. Do not enclose values in quotation marks. Use plus signs (+) in place of
spaces within values.
NOT E : You cannot include variables for product options in email payment links.
Use the following sample URL as a starting point for your own URL for Buy Now email
payment links.The value for the business variable must match a confirmed email address in
your PayPal account. You can change the values for other variables in the sample URL, with
the exception of _xclick.

Sample URL for a Buy Now Email Payment Link

https://www.paypal.com/cgi-
bin/webscr?cmd=_xclick&business=herschelgomez@xyzzyu.com&item_name=Hot
Sauce-12+oz.+Bottle&item_number=12345&amount=5%2e95&currency_code=USD

Creating Buy Now Buttons with JavaScript Disabled
The button creation tool on the PayPal website requires JavaScript. If JavaScript is disabled in
your browser, PayPal offers you an alternative tool that does not require JavaScript.
 “Getting Started with Buy Now Buttons with JavaScript Disabled” on page 63
 “Creating Advanced Buy Now Buttons With JavaScript Disabled” on page 64
 “Limitations When Creating Buy Now Buttons With JavaScript Disabled” on page 73
 “Enabling JavaScript in Your Browser” on page 73


1

Getting Started with Buy Now Buttons with JavaScript Disabled
A message box opens.
5. Click the Buy Now link.

The Buy Now buttons page opens.
6. Enter the details of your item.
– Item name/service – Enter the name of the item or service that you wish to sell.
– 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.
IM PORT AN T : PayPal recommends that you enter a price so that you collect an appropriate
amount for the item.

7. Scroll to the bottom of the page, and click the Create Button Now button.
The Add a Buy Now button to your website page displays the generated code.
8. Click the HTML code for Websites text box to select all of the generated HTML code.


1


Creating Advanced Buy Now Buttons With JavaScript Disabled
The button creation tool for Buy Now buttons on the PayPal website requires JavaScript. If
JavaScript is disabled in your browser, PayPal automatically offers you an alternative button
creation tool that does not require JavaScript.
Read the following topics to learn how to create Buy Now buttons with JavaScript disabled.
 “The Pages in the Button Creation Tool for Buy Now Buttons” on page 64
 “Page 1 – Specifying the Basic Features of the Buy Now Button” on page 64
 “Page 2 – Specifying Advanced Features of Your Buy Now Button” on page 68
 “Copying and Pasting the Buy Now Code With JavaScript Disabled” on page 71
NOT E : The alternative tool lets you create Buy Now buttons on the PayPal website, but it
does not allow you to save your buttons in your PayPal account.
The Pages in the Button Creation Tool for Buy Now Buttons
The button creation tool for Buy Now buttons with JavaScript disabled has three pages:
 Buy Now buttons – the initial page to specify the required and most often used optional
features
 Buy Now buttons – Page 2 – an optional page to specify additional, advanced features
 Add a Buy Now button to your website – the final page that has the generated code for
your payment button
You can switch between the first and second pages until you click the Create Button Now
button to display the third page that has the generated code.
Page 1 – Specifying the Basic Features of the Buy Now Button
To create code for a Buy Now button or email payment link by using a tool on the PayPal
website with JavaScript disabled:
2. Click the Edit Profile link.


1

3. Under the Selling Preferences heading, click the Create New Button link.
4. Under the Create button without JavaScript enabled heading, click the Buy Now link.

The Buy Now buttons page opens.
– Item name/service – (optional) 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 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.

IM PORT AN T : PayPal recommends that you enter 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.
– 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.
6. Choose a button style for your Buy Now button.
If you will accept payments through your website instead of an email link, select the radio
button next to the image that you want to use. Use a “Pay Now” button image if you accept
payments for single services instead of single goods. PayPal hosts the button image you
select.


1

To display your own image that you host on your website:
– Click the Use your own button image link.
An additional radio button and text box appear.
– In the Button Image URL text box, enter the URL of your button image.
If your image is hosted securely, change the entry to begin with https//.
Use your own button image if the buttons hosted by PayPal do not fit the look of your
website.
7. 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.
– 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.


1

– Encrypted HTML code cannot be used for email payment links.
Select the No radio button if you want to create an email payment link instead of or in
addition to your button.
If you select the No radio button for any reason, use an alternative strategy described in
“Securing Your PayPal Payments Standard Buttons” on page 337,” to secure the payments
you receive from the payment button or the email payment link.

IM PORT AN T : Merchants with significant payment volume are required to take
8. 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 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 368 or “Automatic Calculation of Shipping Charges (non-U.S. Merchants
9. 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.

IM PORT AN T :If you specify that buyers can purchase quantities of your item, in Step 4 of
“Page 2 – Specifying Advanced Features of Your Buy Now Button” on
page 68, do not specify a flat rate amount for sales tax. PayPal applies the
flat rate amount as the tax for the item, regardless of the quantity that the
buyer selects.
For more information, see “Automatic Calculation of Sales Tax” on page 363.
10.If you have additional details to specify for your button, such as option fields or a custom
payment page style that has your own logo and colors, click the Add More Options button


1

and follow the instructions for “Page 2 – Specifying Advanced Features of Your Buy Now
– or –
If you entered all the basic and advanced features for your button, go to “Copying and
Pasting the Buy Now Code With JavaScript Disabled” on page 71.
Page 2 – Specifying Advanced Features of Your Buy Now Button
Use the Buy Now buttons – Page 2 page to specify advanced features of your button with
JavaScript disabled.
1. Add option fields to your button.
Option fields let buyers select or specify options when they purchase the item, such as
color or size. Options must not change the price of the item.
Buy Now 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.

IM PORT AN T : 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 buyers 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 buyers 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 that you would
like to appear when buyers click your Buy Now button.
To learn more about creating page styles, see “Co-Branding the PayPal Checkout
Pages” on page 349.
– Preview – Click the Preview button to see a mock-up of the payment page style that
buyers see when they click your Buy Now button.


1

3. Customize your buyer’s experience.
Use these settings to give buyers a payment experience that is easy to navigate.

– Successful Payment URL – (optional) Do one of the following:
Enter the URL of a page on your website that you want buyers redirected to after they
complete their payments. Only this payment button uses the URL that you enter.
Click the Edit button to change the return URL that this button and all your other
payment buttons use to redirect buyers to your website after they complete their
payments. For more information, see “Auto Return” on page 351.
– Payment Data Transfer – Click the Edit button to turn Payment Data Transfer on or
off for all your payment buttons.
– 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 before completing
the checkout. If you do not enter a URL, buyers see a PayPal webpage instead of your
webpage. Only this payment button uses the URL that you enter.
4. Select your quantity and shipping preferences.
Use these settings to control how many units of the item you want to let buyers purchase
and how you obtain their shipping addresses.


1

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

IM PORT AN T : If you allow buyers to purchase more than one unit of your item, do not
specify a flat rate amount as your tax option in Step 9 of “Page 1 –
Specifying the Basic Features of the Buy Now Button” on page 64. PayPal
applies the flat rate amount as the tax for the item, regardless of the quantity
that the buyer selects.
– 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.
5. Collect customer notes and special instructions from buyers.
Use these settings to prompt buyers to enter notes or special handling instructions.


1

– 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 might select the
email address of the person in your organization who handles order fulfillment or
accounting. All payments are deposited to your PayPal account balance, regardless of
which email addresses receive particular payments. 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 “Page 1 – Specifying the Basic Features of the
Buy Now Button” on page 64, beginning with Step 5.
– or –
If you have entered all the details and options for your button, go to “Copying and Pasting
the Buy Now Code With JavaScript Disabled” on page 71.
Copying and Pasting the Buy Now Code With JavaScript Disabled
After you enter the basic and advanced features that you want for your Buy Now button, click
the Create Button Now button. PayPal generates Buy Now code for:
 A payment button, which you can paste onto your website
 An email payment link, which you can paste into email
The Add a Buy Now button to your website page displays the generated code.


1

Copying and Pasting the HTML Code for the Buy Now Button With JavaScript
Disabled.


Copying and Pasting the Code for the Buy Now Email Payment Link With JavaScript
Disabled.

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.
NOT E : You cannot use Encrypted PayPal Payments 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 “Securing Your
PayPal Payments Standard Buttons” on page 337.”
1. Click the Link for Emails text box to select all of the generated URL code.



1


Creating More Buy Now Buttons With JavaScript Disabled.
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 “Page 1 –
Specifying the Basic Features of the Buy Now Button” on page 64, beginning with Step 5. The
pages of the button creation tool retain the options that you previously specified.

Limitations When Creating Buy Now Buttons With JavaScript Disabled
The alternative tool that works with JavaScript disabled lets you create Buy Now buttons on
the PayPal website. However, the following features are not supported by the alternative tool:
 Saving your buttons in your PayPal account
 Creating product options with separate pricing
 Choosing the language to use with button images
 Creating payment buttons before you create your PayPal account
To use any of the above features when creating payment buttons on the PayPal website, enable
JavaScript in your browser.

Enabling JavaScript in Your Browser
PayPal recommends that you keep JavaScript enabled at all times. Many features of the PayPal
website require that JavaScript be enabled in your browser.
Read one of the following topics to learn how to enable JavaScript in your browser.
 Enabling JavaScript in Internet Explorer
 Enabling JavaScript in Firefox
Enabling JavaScript in Internet Explorer
To enable JavaScript in Internet Explorer:
1. Select Tools > Internet Options… from the menu bar.
The Internet Options dialog box opens.
2. Click the Security tab.
3. Click the Trusted sites icon.
4. Click the Custom level… button.
The Security Settings dialog box opens.


1

5. Scroll down to the Scripting section, and then select the Enable radio button as the option
for active scripting.

6. Click the OK button to dismiss the Security Settings dialog box.
A Warning message box asks if you are sure you want to change the security settings.
7. Click the Yes button to dismiss the message box.
8. Click the OK button to dismiss the Internet Options dialog box.
Enabling JavaScript in Firefox
To enable JavaScript in Firefox:
1. Select Tools > Options… from the menu bar.
The Options dialog box opens.
2. Select the Content icon at the top of the dialog box.
3. Select the Enable JavaScript checkbox.
4. Click the OK button.


2 Contribution Payments – Donate
Buttons

Use Donate buttons to collect contribution payments. Donate buttons let you collect pre-
determined amounts or amounts entered by donors.

You can create Donate buttons that you add to your website by using a tool on the PayPal
website, or you can write the HTML code for Donate buttons manually. You can create
Read the following topics to learn more about Donate buttons:
 “Getting Started With Donate Buttons” on page 75
 “The Checkout Experience With Donate Buttons” on page 79
 “Managing Contributions” on page 87
 “Creating Advanced Donate Buttons on the PayPal Website” on page 89
 “Sample HTML Code for Donate Buttons” on page 99
 “Creating Donate Buttons with JavaScript Disabled” on page 101

Getting Started With Donate Buttons
The easiest way to add a Donate button to your website is by using the button creation tool on
the PayPal website. As soon as you add the button, you can begin accepting contribution
payments on your website.

Follow one of these procedures to get started creating your own Donate buttons:
 “Using the Button Creation Tool for a Basic Donate Button” on page 76
 “Creating Donate Buttons Before You Create Your PayPal Account” on page 77


Contribution Payments – Donate Buttons
2

Using the Button Creation Tool for a Basic Donate Button
To use the button creation tool for a basic Donate button:
5. In the Accept payments for dropdown menu, select “Donations”.
6. (Optional) In the Organization name/service text box, enter the purpose for the donation
or the name of your organization. If you do not enter anything in this field, your donors can
complete this field during checkout.
The You are viewing your button code page opens.
code.
9. Copy the text that you selected to the clipboard, by:
– Pressing Ctrl+C.
– or –
– Right-clicking your mouse, and selecting Copy.
10.In your web editing tool, open the webpage where you want the button.

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


2

Creating Donate Buttons Before You Create Your PayPal Account
You can create basic Donate buttons, add them to your website, and begin accepting
contributions before you sign up for your PayPal account. Read the following topics to learn
more about creating Donate buttons before you create your PayPal account.
 “Creating a Basic Donate Button Without a PayPal Account” on page 77
 “Limitations of Donate Buttons Created Without a PayPal Account” on page 78
Creating a Basic Donate Button Without a PayPal Account

in your browser.
5. In the Accept payments for dropdown menu, select “Donations.”
6. Enter the payment details for your Donate button.
– Organization name/service – Enter the purpose for the donation or the name of your
organization. If you do not enter anything in this field, your donors can complete this
field during checkout.
code.


2


Sign up for your PayPal account. You cannot collect payments that buyers make with your
payment button until you sign up successfully for your PayPal Premier account or Business
account.
Limitations of Donate Buttons Created Without a PayPal Account
Consider the following limitations of payment buttons that you create and add to your website
before you sign up for your PayPal account.
 You cannot claim the payments that people authorize during checkout. PayPal collects and
 Donors must have a PayPal account to pay you. Any ability to pay by credit card is
disabled.
 PayPal limits the features that you can specify with the button creation tool, such as saving
your buttons in your PayPal account.
NOT E : You cannot create payment buttons without a PayPal account if Javascript is disabled
in your browser.
For buttons that you create without a PayPal account, payments that donors authorize are held
as unclaimed by PayPal until you sign up. PayPal holds your unclaimed payments under the
email address that you specify when you create the buttons. Make sure to use the same email
address when you sign up for your account. Otherwise PayPal cannot transfer your unclaimed
payments to your PayPal account balance.
In their PayPal accounts, donors see unclaimed payments that they made to you from Donate
buttons that you created without a PayPal account. Such unclaimed payments are displayed in
their recent account activity and in their transaction history. Until you finish signing up for
your PayPal account, donors can cancel your unclaimed payments and recover their funds.


2
The Checkout Experience With Donate Buttons


This section demonstrates the PayPal checkout experience for people who click Donate


2

The Checkout Experience with Donate Buttons

Read these topics to better understand the checkout experience with Donate buttons:
 “Begin – Donors are Ready to Contribute on Your Website” on page 81
 “1 – Donors Enter Their Billing Information or They Log In to PayPal” on page 82


2

 “2 – Donors Confirm Their Contribution Details Before Paying” on page 83
 “3 – Donors View and Print Their PayPal Contribution Confirmations” on page 84
 “End – Donors Receive Contribution Authorization Notices by Email” on page 85
 “Enhancing the Checkout Experience With Donate Buttons” on page 85

Begin – Donors are Ready to Contribute on Your Website
The basic checkout experience with Donate buttons begins when someone on your website is
ready to contribute.

Donors Begin on Your Website When They Are Ready to Contribute

In this example, Mary begins on the website of her favorite cause and wants to contribute to
the Fall Cleanup Campaign. Mary clicks the Donate button to check out.


2

1 – Donors Enter Their Billing Information or They Log In to PayPal
PayPal displays a billing information/log-in page, which lets donors enter their credit card

Donors Enter Their Billing information or Log In to PayPal

For Donate buttons, the PayPal billing information/log-in page shows transaction details near
the top, such as the name of the contribution and the contribution total.
If donors are satisfied with the details, they do one of the following to select a payment
method:
 To pay with a credit card – Donors enter their billing information. They also enter their
contact information – email address and home phone number– so that PayPal can send
them their PayPal transaction receipts and can contact them if necessary to complete the
transaction. Then, they click the Review Order and Continue button.
 To pay with a PayPal account – Donors enter their PayPal credentials and click the Log
in button.
In this case, Mary is satisfied with her contribution to Friends of the Park in the amount of
$25.00 USD. She enters her billing and contact information, and then she clicks the Review
Order and Continue button.


2

2 – Donors Confirm Their Contribution Details Before Paying
PayPal displays a transaction confirmation page to let donors confirm the details before they

Donors Confirm Their Contribution Details Before Paying

In this case, Mary reviews the transaction details clicks the Pay Now button to complete the
transaction and make her payment.


2

3 – Donors View and Print Their PayPal Contribution Confirmations
PayPal displays a payment confirmation page after donors pay to let them know that they have
made their contributions successfully.

Donors View Their Donation Confirmations

From the payment confirmation page, donors can:
 View the PayPal Confirmation number – the transaction ID – to reconcile their payments.
 Click the View Printable Receipt link to print receipts for their records.


2

Donors Print Their PayPal Contribution Receipts

In this case, Mary prints the PayPal contribution receipt for her records.

End – Donors Receive Contribution Authorization Notices by Email
PayPal sends donors a contribution authorization notice by email to confirm the transaction
that they made with the contribution coordinator.
In this case, PayPal sends Mary an email message notifying her of her transaction with Friends
of the Park and her authorization for payment of $25.00 USD.

Enhancing the Checkout Experience With Donate Buttons
your donors:
 Co-Branding the Checkout Pages with Your Logo and Colors
 Prepopulating the Checkout Pages With Billing Addresses
 Returning Donors to Your Website After They Check Out


2

your button.
Prepopulating the Checkout Pages With Billing Addresses
The basic checkout experience has forms for filling in billing addresses. You can enhance the
checkout experience by prepopulating the forms with donor information from your website.
Checkout Pages Automatically” on page 439
Returning Donors to Your Website After They Check Out
The basic checkout experience leaves donors on the PayPal website after they check out. Use
one of the following techniques to enhance the checkout experience so that donors return to
your website instead of the PayPal website.
 Return URL – Let donors return to a page on your website if they click a return link or
To learn more, see Step 2 of “Page 2 – Specifying Advanced Features of Your Donate
page 434.
 Auto Return – Have PayPal return donors automatically to a page on your website.

Auto Return on. With Auto Return on, PayPal redirects donors to your
the transaction information that you need to let donors print receipts from
your website.


2
Managing Contributions

Read the following topics to learn how PayPal helps you manage Donate transactions.
 “Using Email Notices to Track Donate Transactions” on page 87
 “Using Recent Activity to Track Donate Transactions” on page 87
 “Using Transaction History to Track Donate Transactions” on page 88
 “Using Downloadable History Logs to Track Donate Transactions” on page 88
 “Using Instant Payment Notification to Track Donate Transactions” on page 88

Using Email Notices to Track Donate Transactions
organization who handles accounting. Add the additional email address to your account
profile. Then, use that email address as the one to receive payments when you use the button
creation tool on the PayPal website. Specify the alternate email address as the value for the
business HTML variable when you write the HTML code yourself.
For more information, see Step 5 in the instructions for “Page 2 – Specifying Advanced
Features of Your Donate Button” on page 105, or “HTML Variables for PayPal Payments
Standard” on page 417.”

Using Recent Activity to Track Donate Transactions
PayPal displays Donate transactions in your recent activity, soon after donors complete their
transactions by clicking Donate buttons on your website.


2

Using Recent Activity to Track Donate Transactions


Using Transaction History to Track Donate Transactions
PayPal lets you search for Donate transactions on the History page. The status of payments
found there can be:
 Completed – Transactions were successful, and funds were credited to your account.
 Cleared – Payments cleared senders’ accounts, and funds were credited to your account.
 Uncleared – Payments have not cleared sender’s accounts, and funds were not credited.

Using Downloadable History Logs to Track Donate Transactions
PayPal lets you download your Donate transactions to your computer from the History page.
You can specify a date range for the transactions and the file format of the download file.

Using Instant Payment Notification to Track Donate Transactions
PayPal lets your web server receive messages about Donate transactions and payment activity
on your account. If you activate Instant Payment Notification, PayPal sends messages when:


2
Creating Advanced Donate Buttons on the PayPal Website

notify_url” on page 415 and the Instant Payment Notification Guide.

Read the following topics to learn more about creating advanced Donate buttons on the PayPal
website:
 “The Basic Steps for Using the Tool With Donate Buttons” on page 89
 “Saving Donate Buttons in Your PayPal Account” on page 90
 “Adding Advanced Features to Donate Buttons With HTML Variables” on page 90
 “Step 1 – Specifying Basic Features of Your Donate Button” on page 91
 “Step 2 – Saving Your Donate Button in Your PayPal Account” on page 94
 “Step 3 – Adding Advanced Features to Your Donate Button” on page 95
 “Copying and Pasting the Donate Code” on page 97

The Basic Steps for Using the Tool With Donate Buttons
The button creation tool for Donate buttons is a single webpage with three sections:
 Step 1 – Choose button type and enter payment details – This section lets you specify
the details of your Donate button. You can specify whether donors enter their own
contribution amount or a fixed amount.
 Step 2 – Save your buttons (optional) – This section lets you control whether to save your
button in your PayPal account.
 Step 3 – Customize advanced features (optional) – This section lets you work with
advanced features of Donate buttons. If you are familiar with HTML programming and the
advanced HTML variables supported by PayPal Payments Standard buttons, you can enter
them here.
bar to expand it.


2


Saving Donate Buttons in Your PayPal Account
information about your button in your account, instead of placing it in the code that you add to
your website.
account.

Adding Advanced Features to Donate Buttons With HTML Variables
before generating the button code.


2

For more information, see Step 5 of “Step 3 – Adding Advanced Features to Your Donate

When you create Donate buttons with tools on the PayPal website, PayPal generates HTML
your website.
payment links to add Donate functionality to your email messages. If your web editing tool or
your service provider does not allow you to paste HTML code onto your webpages, you might
be able to paste the URL code for email payment links onto your webpages instead.

When you create Donate code with tools on the PayPal website, PayPal lets you protect the

For more information, see “Securing Your PayPal Payments Standard Buttons” on page 337.”

Step 1 – Specifying Basic Features of Your Donate Button
To begin using the button creation tool for Donate buttons:
button link.


2

4. In the Accept payments for dropdown menu, select “Donations.”
5. Enter the details for your payment button.
– Organization name/service – (optional) Enter the purpose for the donation or the name
of your organization. If you do not enter anything in this field, your donors can complete
this field during checkout.
– Donation ID – (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. Donors see the value that you entered at the time of payment. The value
appears in the transaction details that contribution coordinators and donors can view on
the PayPal website.
Click the Customize appearance link and select one of the following.

7. From the Currency dropdown menu, select the currency in which contributions are made;
the dropdown menu automatically selects the currency of your primary balance.


2

8. Under Contribution amount, select one of the following radio buttons.
– Donors enter their own contribution amount – Select this radio button to let donors
enter their contribution amounts during checkout.
This is the default choice for this feature.
– Donors contribute a fixed amount – Select this radio button and enter a fixed amount
that donors contribute when they click this Donate button.
of your webpages.
This is the default choice for this feature.


PayPal account than use of your merchant ID. Your email address is


2

Follow the instructions for “Copying and Pasting the Donate Code” on page 97.
– Click the Step 2 bar if you do not want to save your button in your PayPal account.
Follow the instructions for “Step 2 – Saving Your Donate Button in Your PayPal
Account” on page 94.
– Click the Step 3 bar if you want to specify advanced features for your button.
Follow the instructions for “Step 3 – Adding Advanced Features to Your Donate

Step 2 – Saving Your Donate Button in Your PayPal Account
details of your button in your PayPal account.
– Clear the Save button at PayPal checkbox to avoid saving your button in your PayPal
account.
The HTML code that PayPal generates and that you paste onto your webpage contains
all payment details and information identifying your PayPal account. You may need to
take extra precautions to secure your buttons against fraudulent payments.
For more information, see “Securing Your PayPal Payments Standard Buttons” on
page 337.”
– Select the Save button at PayPal checkbox to save the payment details of your donate
button in your PayPal account.
no payment or identifying information.
For more information, see “Saving Donate Buttons in Your PayPal Account” on
page 90.”


2

Follow the instructions for “Step 3 – Adding Advanced Features to Your Donate
Follow the instructions for “Step 1 – Specifying Basic Features of Your Donate Button”
on page 91, beginning with Step 5.

Step 3 – Adding Advanced Features to Your Donate Button
1. Can your donors add special instructions in a message to you (optional)?
– Yes – Select this radio button to let donors add special instructions to you during
checkout.
In the Name of message box text box, enter the text that you want displayed for the text
box in which donors enter their special instructions; the default value is “Add special
instructions to the seller”. Change the default value to prompt donors for specific
information, such as In memory of. Enter no more than 40 characters.

2. Do you need your donors’ shipping addresses (optional)?
– Yes – Select this radio button to prompt donors to select or enter shipping addresses
during checkout.
– No – Select this radio button if you do not want to prompt donors for shipping addresses.


2

3. Take donors to a specific webpage (URL) after checkout cancellation (optional)?
website where you want donors to return if they cancel their checkouts before completing
their transactions.
4. Take donors to a specific webpage (URL) after successful checkout (optional)?
website where you want donors to return after they complete their checkouts successfully.
NOT E : If you have a special webpage for donors who return to your website after checking
Network..

the checkbox, and then enter the variables in the text box that appears below it.
For example, you want PayPal to display custom payment pages during checkout that you
set up in your account profile. Use the HTML variable page_style with the name you
gave to your custom payment page. If you were to include the variable in HTML code that
you write manually, you would use the standard HTML format:

<input type="hidden" name="page_style" value="myPageStyle">
page_style=myPageStyle
Do not enclose values in quotes, even if values contain spaces. PayPal surrounds the value
page 407.”
Follow the instructions for “Step 1 – Specifying Basic Features of Your Donate Button”
on page 91, beginning with Step 5.


2

– Scroll to the top of the page and click the Step 2 bar if you want to change whether to
save your button in your PayPal account.
Follow the instructions for “Step 2 – Saving Your Donate Button in Your PayPal
Account” on page 94.

Copying and Pasting the Donate Code
code page. The page contains tabs with Donate code for specific situations:
website.
paste HTML code.
Copying and Pasting the HTML Code for the Donate Button
HTML code for your Donate payment button.
If in “Step 2 – Saving Your Donate Button in Your PayPal Account” on page 94 you specified
that you do not want to save your button in your Paypal account, PayPal protects the generated
HTML button code with encryption. Protected HTML code helps secure your buttons against
malicious tampering and fraudulent payments.
You can the expose the code of your payment button by clicking the Remove code protection
edit the code later to change the item price. If you remove code protection, you must use other
methods that PayPal recommends to secure your payment button. Click the Protect code link
to restore the button protection that you removed.

To copy and paste the HTML code for your Donate payment button:
code.
– or –


2

3. In your web editing tool, open the webpage where you want the button.

– or –
Copying and Pasting the Code for the Donate Email Payment Link
code for your Donate email payment link.
NOT E : PayPal cannot protect the URL 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 “Securing Your PayPal Payments Standard
To copy and paste the URL code for your Donate email payment link:
– or –
4. Paste the text that you copied from the clipboard into your email, by:
– or –

the code that you copied from PayPal. Pasted code may not match the generated code for the
following reasons:


2
Sample HTML Code for Donate Buttons

The sample HTML code in this section demonstrates various features of Buy Now buttons:
 “Sample HTML Code for a Basic Donate Button” on page 99
 “Sample HTML Code for a Donate Button With a Fixed Contribution Amount” on
page 100
To protect against malicious users tampering with the HTML code for your Donate buttons
and submitting fraudulent contributions, see “Securing Your PayPal Payments Standard

precautions on securing PayPal Payments Standard buttons.

Sample HTML Code for a Basic Donate Button
The sample HTML code below illustrates a basic Donate button where donors enter their own
contribution amount during checkout. The code uses the currency_code variable to set the
currency for the contribution amounts that donors enter.


<input type="hidden" name="business"
value="donations@kcparkfriends.org">


<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>
The sample code above produces the following result:

2

Paste the code onto your website wherever you want donors to click and make a contribution
in amounts that donors choose.

Sample HTML Code for a Donate Button With a Fixed Contribution Amount
The sample HTML code below illustrates a Donate button where the contribution amount that
donors make is fixed and cannot be changed. The code uses the amount and the
currency_code variables to set fixed contribution amount at $25.00 USD.


<input type="hidden" name="business"
value="donations@kcparkfriends.org">


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

2
Creating Donate Buttons with JavaScript Disabled

 “Getting Started with Donate Button With JavaScript Disabled” on page 101
 “Creating Advanced Donate Buttons With JavaScript Disabled” on page 102
 “Limitations When Creating Payment Buttons With JavaScript Disabled” on page 109

Getting Started with Donate Button With JavaScript Disabled
To create a basic Donate button for your website with JavaScript disabled:
4. Click the Donate link.

The Donations page opens.
5. Enter the donation details of your button.
– Donation name/service – Enter the reason for the donation or the name of your
The Add a Donate button to your website page displays the generated code.


2

– or –

10.Paste the text that you copied from the clipboard onto your webpage where you want the
– or –

Creating Advanced Donate Buttons With JavaScript Disabled
The button creation tool for Donate buttons on the PayPal website requires JavaScript. If
JavaScript is disabled in your browser, PayPal automatically offers you an alternative button
creation tool that does not require JavaScript.
Read the following topics to learn how to create Donate buttons with JavaScript disabled.
 “The Pages in the Button Creation Tool for Donate Buttons” on page 102
 “Page 1 – Specifying the Basic Features of the Donate Button” on page 103
 “Page 2 – Specifying Advanced Features of Your Donate Button” on page 105
 “Copying and Pasting the Donate Code With JavaScript Disabled” on page 108
NOT E : The alternative tool lets you create Donate buttons on the PayPal website, but it does
not allow you to save your buttons in your PayPal account.
The Pages in the Button Creation Tool for Donate Buttons
The button creation tool for Donate buttons with JavaScript disabled has three pages:
 Donations – the initial page to specify the required and most often used optional features
 Donations – Page 2 – an optional page to specify additional, advanced features
 Add a Donate button to your website – the final page that has the generated code for your
payment button


2

Page 1 – Specifying the Basic Features of the Donate Button
To create code for a Donate button or email payment link by using a tool on the PayPal
website with JavaScript disabled:
4. Under the Create button without JavaScript enabled heading, click the Donate link.

The Donations page opens.
5. Enter the donation details of your button.
– Donation name/service – Enter the reason for the donation or the name of your
– 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 Donate 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.
log-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 select, after the log-in or sign-up page appears.


2

6. Choose a button style for your Donate button.
Select the radio button next to the image that you want to use, if you are going to be
accepting payments from your website instead of by using an email payment link. The
image that you select is hosted by PayPal.

– or –
code is generated.


2


precautions on securing PayPal Payments Standard buttons.
8. If you have additional details to specify for your button, such as a custom payment page
that has your own logo and colors, click the Add More Options button and follow the
instructions for “Page 2 – Specifying Advanced Features of Your Donate Button” on
page 105.”
– or –
If you entered all the details and options for your button, go to “Copying and Pasting the
Donate Code With JavaScript Disabled” on page 108.”
Page 2 – Specifying Advanced Features of Your Donate Button
Use the Donations – Page 2 page to specify advanced features of your button with JavaScript
disabled.
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
Styles in your account profile, they are listed here. Choose the page style that you would
like to appear when donors click your Donate button.
donors see when they click your Donate button.
2. Customize your donor’s experience.
Use these settings to give donors a payment experience that is easy to navigate.


2

Enter the URL of a page on your website that you want donors redirected to after they
complete their payments. Only this payment button uses the URL that you enter.
payment buttons use to redirect donors to your website after they complete their
want donors redirected to if they cancel their payments at any point before completing
the checkout. If you do not enter a URL, subscribers see a PayPal webpage. Only this
payment button uses the URL that you enter.


2

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.
(optional) In the Email Address dropdown menu, select the email address through which
email address of the person in your organization who handles accounting. All payments are
deposited to your PayPal account balance, regardless of which email addresses receive
particular payments. Only confirmed email addresses can be used to receive payments.


2

Donate Button” on page 103, beginning with Step 5.
– or –
the Donate Code With JavaScript Disabled” on page 108.
Copying and Pasting the Donate Code With JavaScript Disabled
After you enter the basic and advanced features that you want for your Donate button, click the
Create Button Now button. PayPal generates Donate code for:
 a payment button, which you can paste onto your website
 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 Donate Button With JavaScript
Disabled. To copy and paste the HTML code for the Donate payment button:
– or –
– or –

Copying and Pasting the Code for the Donate Email Payment Link With JavaScript
Disabled. 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.
NOT E : You cannot use Encrypted Website Payments to encrypt the code for email payment
PayPal Payments Standard Buttons” on page 337.”


2

To copy and paste the code for the Donate email payment link:
– or –
– or –

Creating More Donate Buttons With JavaScript Disabled. After you copy and paste the
Donate code, you can create another Donate button for a different contribution purpose or
amount. Scroll to the bottom of the Add a Donate button to your website page and click the
Create Another Button button. Then follow the instructions for “Page 1 – Specifying the
Basic Features of the Donate Button” on page 103, beginning with Step 5. The pages of the
button creation tool retain the options that you previously specified.

Limitations When Creating Payment Buttons With JavaScript Disabled
The alternative tool that works with JavaScript disabled lets you create Donate buttons on the
PayPal website. However, the following features are not supported by the alternative tool:
 Language choices for button images
To use any of the above features when creating payment buttons on the PayPal website, you
must enable JavaScript in your browser.
For more information, see “Enabling JavaScript in Your Browser” on page 109.

 “Enabling JavaScript in Internet Explorer” on page 110
 “Enabling JavaScript in FireFox” on page 111


2

After you enable JavaScript in your browser, you can create a basic Donate button by
following the instructions for “Using the Button Creation Tool for a Basic Donate Button” on
page 76.



2

Enabling JavaScript in FireFox


2


3 Recurring Payments – Subscribe
Buttons

Use Subscribe buttons to obtain subscription payments automatically from buyers for access
to online content and services or for regular delivery of goods.

You can create Subscribe buttons that you add to your website by using a tool on the PayPal
website, or you can write the HTML code for Subscribe buttons manually. You can create
Read the following topics to learn more:
 “Getting Started with Subscribe Buttons” on page 113
 “The Checkout Experience with Subscribe Buttons” on page 117
 “Managing Subscriptions” on page 123
 “Advanced Features of Subscribe Buttons” on page 136
 “Creating Advanced Subscribe Buttons on the PayPal Website” on page 146
 “Sample HTML Code for Subscribe Buttons” on page 162
 “Sample URL Code for Subscribe Email Payment Links” on page 171
 “Creating Subscribe Buttons with JavaScript Disabled” on page 171

Getting Started with Subscribe Buttons
The easiest way to add a Subscribe button to your website is by using the button creation tool
on the PayPal website. As soon as you add the button, you can begin selling subscriptions on
your website.


Recurring Payments – Subscribe Buttons
3

Follow one of these procedures to get started creating your own Subscribe buttons:
 “Creating a Basic Subscribe Button on the PayPal Website” on page 114
 “Creating Subscribe Buttons Before You Create Your PayPal Account” on page 115

Creating a Basic Subscribe Button on the PayPal Website

The following instructions create a basic Subscribe button that sets up subscriptions with a
monthly billing cycle that recurs until subscriptions are cancelled.
5. In the Choose a button type dropdown menu, select “Subscriptions.”
6. Enter the payment details of your subscription.
– Subscription name – Enter a name for the subscription. For example, enter “Alice’s
Monthly Digest”.
– Recurring amount to be billed – Enter the amount you want to bill subscribers for each
monthly billing cycle. For example, enter “20.00”.
code.



3


To learn how to create buttons for other kinds of subscriptions, see “Creating Advanced
Subscribe Buttons on the PayPal Website” on page 146.

Creating Subscribe Buttons Before You Create Your PayPal Account
You can create basic Subscribe buttons and add them to your website to see how they look
before you sign up for your PayPal account. However, for the buttons to work, you need a
PayPal Premier or Business account.
Read the following topics to learn more about creating Subscribe buttons before you create
 “Creating a Basic Subscribe Button Without a PayPal Account” on page 115
 “Limitations of Subscribe Buttons Created Without a PayPal Account” on page 116
Creating a Basic Subscribe Button Without a PayPal Account

in your browser.
4. Under the Website Payments Standard heading, click the Select button.
A page that describes Website Payments Standard opens.
7. Enter the payment details of your subscription.
– Subscription name – Enter a name for the subscription. For example, enter “Alice’s
Monthly Digest”.


3

– Recurring amount to be billed – Enter the amount you want to bill subscribers for each
monthly billing cycle.
code.


Sign up for your PayPal account. Your Subscribe button will not work fully until you sign up
successfully for your PayPal Business Account.
Limitations of Subscribe Buttons Created Without a PayPal Account
Consider the following limitations of payment buttons that you create and add to your website
before you sign up for your PayPal Premiere or Business account.
 The buttons that you place on your website will not work fully.
– Tracking inventory or profit and loss
NOT E : You cannot create payment buttons without a PayPal account if JavaScript is


3
The Checkout Experience with Subscribe Buttons

This section demonstrates the PayPal checkout experience for people who click Subscribe


Read these topics to better understand the checkout experience with Subscribe buttons:
 “Checkout Starts on Your Website” on page 118
 “Buyers Choose a Way to Pay” on page 118
 “Buyers Review Their Payment Details” on page 120
 “Buyers View and Print Payment Confirmations” on page 121
 “Enhancing the Checkout Experience with Subscribe Buttons” on page 122


3

Checkout Starts on Your Website
The basic checkout experience begins on your website when a buyer is ready to sign up.

Buyers Begin PayPal Checkout on Your Website

In this example, Bob begins on Alice’s Used Books website and decides to sign up for a
subscription to Alice’s Weekly Digest. He clicks the Subscribe button to check out.

Buyers Choose a Way to Pay
information to sign up. Buyers with PayPal accounts log in to sign up.


3

Buyers Enter Billing Information to Sign Up by Credit Card

In this case, Bob does not have a PayPal account. He enters his billing information. He also
enters his contact information – email address and home phone number– so that PayPal can
send him a PayPal transaction receipt and can contact him if necessary to complete the
transaction. Then, he clicks the Continue button.
Buyers who already have PayPal accounts click the PayPal radio button near the top of the
billing information page in order to sign up. The page changes to let them log in to PayPal.


3

Buyers with PayPal Accounts Log in To Sign Up

Buyers Review Their Payment Details
PayPal displays a payment review page to let buyers check the details of their automatic
payment plans before they complete their agreements.


3

Buyers Review Payment Details Before They Sign Up

In this case, Bob reviews the details of his subscription and recurring payments. Then, he
clicks the Pay button to complete his signup for the subscription.

Buyers View and Print Payment Confirmations
PayPal displays a payment confirmation page to let buyers know that they checked out
successfully.


3

Buyers View and Print Their Payment Confirmations

In this case, Bob prints the confirmation page for his records.

Enhancing the Checkout Experience with Subscribe Buttons
Website Payments Standard offers these features to enhance the basic checkout experience for
your subscribers:
 Prepopulating the Checkout Pages with Billing Addresses
 Returning Buyers to Your Website After They Check Out
left corner of the checkout pages. You can set co-branding options to help blend the PayPal
checkout pages with the rest of your website and maintain your brand throughout the checkout
experience.
Enhance the checkout experience by setting up custom page payments in your account profile
to specify your logo and colors. Then, PayPal uses your logo and colors to display the
checkout pages. In addition, you can specify you logo and colors with advanced HTML
variables in the code of your payment buttons.


3
Managing Subscriptions

Prepopulating the Checkout Pages with Billing Addresses
The basic checkout experience has forms for filling in billing addresses. You can enhance the
checkout experience by prepopulating the forms with subscriber information that you have on
your website.
The basic checkout experience with Subscribe buttons leaves subscribers on a PayPal
webpage when they complete their subscription signups. Use one of the following techniques
to alter the basic checkout experience so that subscribers return to your website:
 Return URL – Let people return to a page on your website if they click a return link or
To learn more, see Step 3 of “Step 3 – Adding Advanced Features to Your Subscribe
page 434.

Read the following topics to learn about managing subscriptions:
 “Tracking Subscription Transactions” on page 124
 “How Billing Cycles and Recurring Payments Work” on page 127
 “Downloading Subscriber Lists” on page 129
 “Canceling Individual Subscriptions” on page 130
 “Canceling Multiple Subscriptions at One Time” on page 131
 “Suspending Subscriptions” on page 133
 “Editing a Subscription Profile” on page 134


3

Tracking Subscription Transactions
Read the following topics to learn how PayPal helps you manage Subscribe transactions.
 Using the Recurring Payments Dashboard to Track Subscription Plans
 Using Email Notices to Track Subscription Transactions
 Using Recent Activity to Track Subscribe Transactions
 Using Transaction History to Track Subscribe Payments
 Using Downloadable History Logs to Track Subscribe Payments
 Using Instant Payment Notification to Track Subscribe Transactions
Using the Recurring Payments Dashboard to Track Subscription Plans

PayPal displays subscription plans in the Recurring payments dashboard, soon after buyers
complete their subscription signups.
1. Log in to your PayPal account.
2. Navigate to My Account > Profile.
The Profile Summary opens.
3. Under the Financial Information heading, click Recurring payments dashboard.
The Recurring payments dashboard opens.

Result:
From the Overview section of the dashboard, do any of the following:
 See counts of Active and New plans, counts of plans with Outstanding Payments, and
counts of plans that are Suspended or Canceled.


3

 See only plans with a specific status in the My customers list by clicking the
corresponding status link. Or, choose a status from the Filter status by dropdown menu,
and then click the Go button.
 Manage a specific plan by clicking the Customer Name link in the row for the plan.
 Cancel plans by selecting checkboxes in the rows of plans, and then clicking the Cancel
link at the top of the list.
Using Email Notices to Track Subscription Transactions
 Buyers sign up for new subscriptions.
 Subscription payments occur.
 Subscriptions end or buyers cancel them.
organization who handles accounting or manages access to members-only content. Add the
additional email address to your account profile. Then, use that email address as the value for
the business HTML variable when you write the HTML code yourself for your Subscribe
buttons.
For more information, see “HTML Variables for PayPal Payments Standard” on page 417.
Using Recent Activity to Track Subscribe Transactions
PayPal displays Subscribe transactions in your recent activity, soon after subscribers complete
their subscription signups.
If you accepted your first subscription payment before October 15, 2009:
Subscription information displays on your Account Overview page as shown in the figure
below.

Using Recent Activity to Track Subscribe Transactions

If you accepted your first subscription payment after October 15, 2009:
Subscription information displays on your Account Overview page as shown in the figure
below.


3

Using Transaction History to Track Subscribe Payments
PayPal lets you search for Subscribe payments on the History page. The status of payments
found there can be:
 Completed – Transactions were successful, and funds were credited to your account
 Cleared – Payments cleared senders’ accounts, and funds were credited to your account
 Uncleared – Payments have not cleared sender’s accounts, and funds were not credited
1. Visit the History page.
2. Above the activity list, click the Subscriptions link.
NOT E : If the link is not shown, select More filters > Subscriptions and agreements >
Subscriptions.
The activities list displays subscription payments, which are identified as "Subscription
Creation From" or "Payment From" in the Type column.
1. Visit the History page.
2. Above the activity list, select More filters > Subscriptions and agreements > Recurring
payments > Transactions.
The activities list displays subscription payments, which are identified as "recurring
payments" in the Type column.


3

Using Downloadable History Logs to Track Subscribe Payments
PayPal lets you download a file that contains all of your subscription payment history for a
time frame that you specify. You can choose comma delimited, tab delimited, Quicken, or
QuickBooks as the file format.
To download a file with your subscription payment history:
2. Move your mouse over the History tab and then click the Download History link.
The Download History page opens.
3. Click the Customize Download Fields link.
The Customize My Download History page opens.
4. Scroll down the page, and select the Subscription Number checkbox.
5. Click the Save button.
The Download History page opens again.
6. Specify the time frame for the subscription payments you want to download and the file
type you want.
7. Click the Download History button, and follow the onscreen instructions.
For more information on the Download History page, see the Merchant Setup and Administration
Guide.

Using Instant Payment Notification to Track Subscribe Transactions
PayPal lets your web server receive messages about Subscribe transactions and payment
activity on your account. If you activate Instant Payment Notification, PayPal sends messages
when:
 Payments first occur with a status of Completed or Pending.
 Payments clear, fail, or are denied, if the initial status was Pending.
 Subscriptions begin, end, or are canceled, if you use Subscriptions Password Management.
To learn more, see:
 “Instant Payment Notification – notify_url” on page 415
 “Generating Usernames and Passwords with Subscribe Buttons” on page 143
 Instant Payment Notification Guide

How Billing Cycles and Recurring Payments Work
PayPal attempts to collect recurring payments from subscribers on the day after the previous
billing cycle or trial period ends. Billing cycles can be daily, weekly, monthly or yearly,
depending on the terms of the original subscription.


3

How Subscriptions with Weekly Billing Cycles Work
For weekly billing cycles, recurring payments are collected on the same day of the week.

When Weekly Recurring Payments Are Due and Collected
The subscription terms are:
 $10 USD a week; the subscriber signs up on Tuesday, December 23.
The subscriber is billed as follows:
 Tuesday, December 23 = $10.00 USD
 Tuesday, January 6 = $10.00 USD
 and so on...
How Subscriptions with Monthly Billing Cycles Work
For monthly billing cycles, recurring payments are collected on the same day of the month. If
the initial recurring payment falls on the 31st, PayPal eventually adjusts the billing cycle to the
1st of the month. If the initial recurring payment falls on the 29th or 30th, PayPal adjusts the
billing cycle to the 1st of the month on the following February.

When Monthly Recurring Payments Are Due and Collected on the 31st
 $25.99 USD a month; the subscriber signs up on Thursday, July 31.
 Thursday, July 31 = $25.99 USD
 Saturday, August 31 = $25.99 USD
 Wednesday, October 1= $25.99 USD
 Saturday, November 1= $25.99 USD
 and so on...
Notice that no recurring monthly payment was collected in September, but recurring payments
were collected roughly every 30 days.

When Monthly Recurring Payments Are Due and Collected on the 30th
 $25.99 USD a month; the subscriber signs up on Tuesday, December 30.
 Friday, January 30 = $25.99 USD


3

 Sunday, March 1= $25.99 USD
 Wednesday, April 1= $25.99USD
 and so on...
Notice that no recurring monthly payment was collected in February, but recurring payments
were collected roughly every 30 days.
How Subscriptions with Yearly Billing Cycles Work
For yearly billing cycles, recurring payments are collected on the same month and day each
year. If the initial recurring payment falls on February 29th of a leap year, PayPal adjusts the
billing cycle to March 1st the following year.

When Yearly Recurring Payments Are Due and Collected
 $125.99 USD a year; the subscriber signs up on a Friday, February 29.
 Friday, February 29, 2008 = $125.99 USD
 Sunday, March 1, 2009 = $125.99 USD
 Sunday, March 1, 2010 = $125.99 USD
 and so on...

Downloading Subscriber Lists
You can download a text file that contains all of your non-payment subscription history –
signups, cancellations, and ends of term. You can manipulate the download file to produce
these kinds of lists:
 All current and past subscribers – Exclude “Subscription Cancellation” and
“Subscription Completion” activity
 All active subscribers – Include activity with an “active,” “active-completed,” or “active-
cancelled” status
To download a file with your non-payment subscription history:
2. Move your mouse over the History tab and then click the Download History link.
The Download History page opens.
3. Specify the time frame for the subscription activity that you want to download.
4. From the File Types for Download dropdown menu, select “Subscriptions.”


3

NOT E : The “Subscriptions” choice is available in the dropdown menu only after someone
has signed up for a subscription with you.
5. Click the Download History button, and follow the onscreen instructions.
For more information on the Download History page, see the Merchant Setup and Administration
Guide.

Canceling Individual Subscriptions
As a subscription service provider, you can the cancel the subscriptions of individual
subscribers from the Subscription Details pages of your PayPal account. In addition, your
subscribers can cancel the subscriptions that they have with you from their Subscription
Details pages. The procedure, described below, is the same in either case. Canceled
subscriptions cannot be reactivated.
NOT E : For the convenience of you and your subscribers, consider adding a Cancel
Subscription button to your website.
For more information, see “Working with Unsubscribe Buttons” on page 141.
2. Click the History subtab.
The History page opens.
3. Specify the time frame in which the subscription was set up.
4. From the More Filters dropdown menu, select Subscriptions and agreements >
Subscriptions.
The History pages displays a list of subscription transactions.
5. In the Subscriptions list, locate the subscription you want to cancel.
Make sure of the following:
– The Type column reads, “Subscription Creation.”
– The Status column reads, “Active.”
6. In the row for the subscription that you want to cancel, click the Details link.
The Subscription Details page opens.
7. Scroll to the bottom of the page, and click the Cancel Subscription button.


3

3. Specify the time frame in which the subscription was set up.
Recurring payments > My profiles.
The History pages displays a list of recurring payment setup transactions.
5. In the My profiles list, locate the subscription that you want to cancel.
6. In the row for that subscription, click the Details link.
The Recurring Payments : Profile Details page opens.
7. Click the Cancel link under Profile Status.
8. Click the Yes button to confirm the cancellation.
The Recurring Payments : Profile Details page refreshes with a message confirming that
the subscription is canceled.

Canceling Multiple Subscriptions at One Time
As a subscription service provider, you can cancel multiple subscriptions at one time from the
Subscription Details page of your PayPal account.
Follow the procedures described in this section to cancel multiple subscriptions at one time:
 Requesting Mass Subscription Cancellations
 Monitoring the Progress of Mass Subscription Cancellations
Requesting Mass Subscription Cancellations
Before you begin this procedure, create a text file that contains the email addresses of the
subscribers whose subscriptions you want to cancel. Enter each email address on a separate
line. You will upload this mass cancellation file during Step 7 of the procedure below.

IM PORT AN T : If a subscriber in your text file has more than one subscription with you, all of
that person’s subscriptions will be canceled.
To request the cancellation of multiple subscriptions at one time:
3. From the Show dropdown menu, select “Subscriptions.”


3

4. Click the Search button.
The History page displays a list of subscription transactions.
5. In the row for any subscription where the Status column reads “Active,” click the Details
link.
The Subscription Details page opens.
6. Scroll to the bottom of the page, and click the Cancel several subscribers link.
The Mass Subscription Cancellation page opens.
7. In the Attach Mass Cancellation File text box, enter the path and filename of the mass
cancellation file that you created earlier, or click the Browse… button to locate the file on
your local computer.
8. Click the Continue button.
The Mass Cancellation page opens to display the number of email addresses that PayPal
found in your mass cancellation file.
9. Confirm the number of email addresses found by PayPal against the number of email
addresses in your mass cancellation file. Then, click then Cancel Subscriptions button.
The Mass Cancellation page refreshes to inform you that your mass cancellation file has
been registered by PayPal and will be processed.
Monitoring the Progress of Mass Subscription Cancellations
It may take PayPal a while to process your mass cancellation file. You can monitor the
progress from the History page by looking at the status of the cancellation transaction.
NOT E : It may take up to one hour to process your mass subscription cancellation.
To check the status of your mass subscription cancellation:
3. From the Show dropdown menu, select “All Activity - Simple View.”
4. Specify the time frame in which you requested the mass subscription cancellation.
Generally, select the Within radio button and select “The Past Day” from the dropdown
menu.
The History page displays a list of subscription transactions.


3

6. In the Subscriptions list, locate the row where the Type column reads “Mass Subscription
Cancellation.”
The Status column reads “Processed” after PayPal finishes processing your mass
cancellation file.
7. Click the Details link to see statistics about your mass subscription cancellation and to
download a mass cancellation log file.
The Transaction Details page opens to display the following statistics:
– Total Emails – Number of email addresses uploaded from your file.
– Emails Matched – Number of email addresses that matched one or more active
subscriptions.
– Emails Not Matched – Number of email addresses that matched no active subscriptions
or matched subscriptions that were already completed or canceled.
– Successful Cancellations – Number of subscriptions canceled. This number may be
higher than the number of emails matched if any email address had more than one active
subscription.
8. Click the View Details button to download a mass cancellation log file.
PayPal prompts you to open or save a file named BatchLog.txt. Each line in the file
represents the actions taken against a subscription. Each line begins with the subscription
ID and has the email address of the subscriber and the processing date. The log file reports
the following processing results:
– Success – The subscription was canceled.
– Failed Already cancelled – The subscription was canceled already.
– Failed Already completed – The subscription ended already.
– Failed – A general failure occurred, as identified by the failure code.
– No Match – The email address did not match any of your subscriptions.

Suspending Subscriptions
You can suspend a buyer’s subscription. Suspending a subscription lets you stop charging the
buyer, but keep their subscription profile active so you can use it for future charges. For
example, if your subscriber is going on vacation and wants to stop receiving the subscription
material during that time, you can suspend their subscription. Only PayPal merchants can
suspend subscriptions.


3

4. In the My profiles list, locate the subscription that you want to suspend.
6. Click the Suspend link under Profile Status.
7. Click the Yes button to confirm the suspension.
The Recurring Payments : Profile Details page refreshes with a message confirming that
the subscription is suspended and no further amounts will be collected.
NOT E : You can reactive the subscription later to resume the collection of payments by
returning to the profile and clicking the Reactivate link under Profile status.

Editing a Subscription Profile
As a subscription service provider, you can edit a buyer’s subscription profile in the Edit
Profile page. Use this page to update buyer information, adjust the cost or cycles of the
subscription, and specify how to handle missing or failed payments.
4. In the My profiles list, locate the subscription that you want to edit.
6. Scroll to the bottom of the page and then click the Edit Profile button.
The Recurring Payment Details page opens.
7. Change the subscription service name by entering the new name in the Product/service
text field.
8. Change the limit of failed payments allowed for this subscription in the Failed payments
maximum field.


3

– To set a limit, click the Suspend after radio button and enter a number in the failed
payments field.
– To remove a limit, click the No limit radio button.
9. Indicate whether to include missing payments in the next billing by selecting Yes or No
from the Add missing payments to next billing dropdown menu.
10.Edit the subscription payment cycle in the Total Number of cycles section. Click the
payments radio button and enter the number of payments, or click the Indefinite radio
button to continue payments until the account is cancelled.
11. Enter any changes to the subscription cost in the Cost section.
12.Update the buyer’s shipping information in the Shipping address section. You can change
the name, address, city, state, or zip code. You cannot change the shipping country.
13.Click the Save button.

End-of-Term Messages Sent Through Instant Payment Notification
This feature is available only if you accepted your first subscription payment before
October 15, 2009.
Instant Payment Notification sends end-of-term messages when subscriptions end. Use these
messages to automatically terminate subscription password access to members-only content.
For more information about Subscriptions Password Management, see “Generating
Usernames and Passwords with Subscribe Buttons” on page 143.
For subscriptions with no recurring payments, end-of-term messages are sent when the
subscription period ends. For subscriptions with recurring payments and a limited number of
billing cycles, end-of-term messages are sent at the end of the last billing cycle. For
subscriptions that are canceled, end-of-term messages are sent when the subscription period or
the current billing cycle ends. For subscriptions that PayPal cancels due to failures in attempts
to collect recurring payments, end-of-term messages are sent immediately.

End-of-Term Examples
 Term – $10 USD for 6 months, paid on the 1st of March
 End-of-Term – sent on the 1st of September, 7 months after signup

 Term – $9.99 USD per month, paid on the 1st of March
 Cancellation – manually on the 15th of June
 End-of-Term – sent on the 1st July, at the end of the current billing cycle

 Term – $10 USD for 6 months, paid on the 1st of March, with reattempts of failed
recurring payments enabled


3
Advanced Features of Subscribe Buttons

 Payment failure – on the 1st of June
 1st reattempt failure – on the 4th of June
 2nd reattempt failure – on the 9th of June
 Cancellation – final payment failure on the 9th of June
 End-of-Term – sent on the 9th of June
For more information, see “Reattempting Failed Recurring Payments with Subscribe Buttons”
on page 144.

Read the following topics to learn about these advanced features of Subscribe buttons:
 “Offering Trial Periods and Introductory Rates with Subscribe Buttons” on page 136
 “Limiting the Number of Billing Cycles with Subscribe Buttons” on page 137
 “Offering Product Options with Subscribe Buttons” on page 138
 “Working with Modify Subscription Buttons” on page 138
 “Working with Unsubscribe Buttons” on page 141
 “Generating Usernames and Passwords with Subscribe Buttons” on page 143
 “Reattempting Failed Recurring Payments with Subscribe Buttons” on page 144

Offering Trial Periods and Introductory Rates with Subscribe Buttons
Offer trial periods to let people try your subscription service before their regular subscription
and its recurring payments begin. You can set the prices and durations of trial periods
independently of the regular subscription price and billing cycle.
How Subscriptions with Trial Periods Work
The following example shows how subscribers are billed for trial periods.

Subscriptions That Include Trial Periods
Subscription Terms:
 An initial trial period, free of charge, that lasts for 7 days
 A second trial period for $5 USD, that lasts three additional 3 weeks
 A regular subscription for $10 USD per month starting after both trial periods expire
The Subscriber signs up on Aug.1, and is billed as follows:
 Aug. 1 = $0.00 USD
 Aug. 9 = $5.00 USD
 Aug. 31 = $10.00 USD


3

Specifying Trial Periods with Subscribe Buttons
Do one of following to add Subscribe buttons to your website that include trial periods:
 Specify single trial periods when you create Subscribe buttons by using the creation tool on
the PayPal website.
See Step 9 of “Step 1 – Specifying Basic Features of Your Subscribe Button” on page 149.
 Specify initial and second trial periods in the HTML button code that you write manually.
See “Sample HTML Code for a Subscribe Button with Trial Periods” on page 163.

Limiting the Number of Billing Cycles with Subscribe Buttons
If you want subscribers to renew periodically, limit the number of billing cycles with your
subscriptions. Recurring subscription payments stop after that number of billing cycles has
been reached.
How Subscriptions with Limited Billing Cycles Work
The following example shows how subscribers are billed on installment plans with a limited
number of billing cycles.

Subscription Terms That Limit the Number of Billing Cycles
Subscription Terms:
 A regular subscription for $19.95 USD a month, for a total of 3 months
The Subscriber signs up on Aug.15, and is billed as follows:
 Aug. 15 = $19.95 USD
 Sept. 15 = $19.95 USD
 Oct. 15 = $19.95 USD
Specifying the Limit on Billing Cycles with Subscribe Buttons
Do one of following to add Subscribe buttons to your website that limit the number of billing
cycles:
 Specify the limit that stops recurring payments after a certain number when you create
Subscribe buttons by using the creation tool on the PayPal website.
 Specify the limit in the HTML button code that you write manually.
See “Sample HTML Code for a Subscribe Button with Limits on Billing Cycles” on
page 164.


3

Offering Product Options with Subscribe Buttons
Prompt subscribers for product options, such as size or color. You can prompt buyers for their
option selections with dropdown menus or with text boxes. PayPal limits you to 7 product
options on a single Subscribe button. One option can prompt for selections that affect the price
with a dropdown menu. Up to 4 options can prompt for selections with dropdown menus, and
up to 2 options can prompt for selections with text boxes.

Specifying Product Options with Subscribe Buttons
Do one of the following to create Subscribe buttons that offer product options:
 Specify the product options when you create Subscribe buttons by using the creation tool
on the PayPal website.
See “Sample HTML Code for Subscribe Buttons with Product Options” on page 165.

Working with Modify Subscription Buttons
Let subscribers modify their active subscriptions by adding a Modify Subscription button to
your website. If you offer different subscriptions levels, Modify Subscription buttons let your
subscribers upgrade to a higher level without an interruption in service.
How PayPal Lets Subscribers Modify Their Subscriptions
Modify Subscription buttons let subscribers accept a new set of subscriptions terms and
pricing for their current, active subscriptions.
You can write the HTML code for Modify Subscription buttons that allow subscribers to:
 Modify their active subscriptions, or sign up for new subscriptions
 Modify their active subscriptions only
The following example shows how subscribers use Modify Subscription buttons to upgrade
their subscriptions from one level of service to another.

Subscribers Use Modify Subscription Buttons
Subscription terms:
 A basic subscription for $29.95 USD a month, for one year
 A premium subscription for $69.95 USD every six months


3

Bob signed up on Feb. 15 for a basic subscription.
 On Apr. 26, he decides to upgrade his basic subscription to a premium subscription:
– Bob visits the subscription website, finds a webpage that lets him upgrade his
subscription, and clicks the Subscribe button.

– PayPal displays a log-in page. Bob enters his PayPal credentials and logs in.
– PayPal displays the Review Subscription Details page, which lets Bob see his current
subscription terms and the new terms he is about to agree to.
 Bob retains his current subscription with Alice’s Used Books.
 The new terms take effect at the end of the current billing cycle, May. 15.
Specifying Options for Modify Subscription Buttons
To create a Modify Subscription button, you must be able to write HTML code. You can
generate most of the button code with the button creation tool on the PayPal website. Then,
you manually add your own code to the generated code.
Do one of the following:
 “Using the Button Creating Tool for Modify Subscription Buttons” on page 139
 “Creating Modify Subscription Buttons with JavaScript Disabled” on page 140

Using the Button Creating Tool for Modify Subscription Buttons. To create a Modify
Subscription button by using the button creation tool on the PayPal website:
1. Follow the procedure for “Step 1 – Specifying Basic Features of Your Subscribe Button”
on page 149.
– Select a button image that reads “Subscribe.”
– Specify the terms and pricing that will apply after subscriptions are modified.
2. (Optional) Click the Step 2 bar, depending on whether you want to save your button in
your PayPal account and whether you want to track inventory for the items you are selling


3

by subscription. Follow the instructions for “Step 2 – Tracking Inventory and Profit and
Loss with Your Subscribe Button” on page 153.
3. Click the Step 3 bar, and then follow the instructions for “Step 3 – Adding Advanced
Features to Your Subscribe Button” on page 156.
– Add any advanced features that you want for the modified subscription.
– Select the Add Advanced Variables checkbox; then in the text box below it, enter one
of the following lines of code:
modify="1" – Add this line of code to let subscribers modify their active subscriptions
or sign up for new, additional subscriptions. If a subscriber has an active subscription,
PayPal displays a page during checkout for accepting the new terms and pricing, with a
link to a page to sign up for a new, additional subscription with the new terms and
pricing. If a subscriber has a prior subscription that ended or was canceled, PayPal lets
the subscriber sign up for a new subscription with the modified terms and prices.
modify="2" – Add this line of code to let subscribers modify existing subscriptions
only. If a a subscriber has an active subscription, PayPal displays a page during
checkout for accepting the new terms and pricing. The page does not allow subscribers
to sign up for new subscriptions.
4. Click the Create Button button.
The Add a Subscribe button to your website page or the You've created your button
pages opens, depending on whether you are saving the button in you PayPal account.
5. Follow the procedure for “Copying and Pasting the Subscribe Code” on page 158.
For more information, see “Sample HTML Code for a Modify Subscription Button” on
page 167.

Creating Modify Subscription Buttons with JavaScript Disabled. To create a Modify
Subscription button with JavaScript disabled:
1. Follow the procedure for “Creating Advanced Subscribe Buttons on the PayPal Website”
on page 146.
– Specify the terms and pricing that will apply after the subscriptions are modified.
– Select a button image that reads “Subscribe.”
– Make sure you select the No radio button in the section about button encryption.
2. Click the Create Button Now button.
The Add a Subscribe button to your website page opens.
3. For a payment button, follow the procedure for “Copying and Pasting the HTML Code for
Your Subscribe Button” on page 158 to copy and paste everything in the HTML code for
Websites text box onto your webpage. Then, add the following code.
Do one of the following between the <form> and </form> tags in the pasted code:


3

– To let subscribers modify their active subscriptions or sign up for new, additional
subscriptions, insert the following line of code:
<input type="hidden" name="modify" value="1">
If a subscriber has an active subscription, PayPal displays a page during checkout for
accepting the new terms and pricing, with a link to a page to sign up for a new,
additional subscription with the new terms and pricing.
If a subscriber has a prior subscription that ended or was canceled, PayPal lets the
subscriber sign up for a new subscription with the modified terms and prices.
– To let subscribers modify existing subscriptions only, insert the following line of code:
If a a subscriber has an active subscription, PayPal displays a page during checkout for
accepting the new terms and pricing. The page does not allow subscribers to sign up for
new subscriptions.
4. For an email payment link, follow the procedure for “Copying and Pasting the Code for the
Email Payment Link” on page 159 to copy and paste everything in the Link for Emails
text box into your email. Then, add the following code.
Do one of the following at the end of the pasted URL:
– To let subscribers modify their active subscriptions or sign up for new, additional
subscriptions, add the following variable and value:
modify=1
– To let subscribers modify existing subscriptions only, add the following variable and
value:
modify=2
For more information, see “Sample HTML Code for a Modify Subscription Button” on
page 167.

Working with Unsubscribe Buttons
Let subscribers cancel their active subscriptions by adding Unsubscribe buttons to your
website.
How PayPal Cancels Subscriptions
When subscribers cancel subscriptions, they avoid future recurring payments. If subscribers
cancel their subscriptions before payment is sent on the due date for the recurring payment,
PayPal cancels their subscriptions immediately and does not deduct the payments.
The following example shows how subscribers use Unsubscribe buttons to cancel their
subscriptions.


3

NOT E : Subscribers can cancel their subscriptions from the Subscription Details pages of their
PayPal accounts. For more information, see “Canceling Individual Subscriptions” on
page 130.

Subscribers Cancel Their Subscriptions
Subscription terms:
 A regular subscription for $20.00 USD a month, for one year
Bob signs up for a subscription on Feb. 15:
 On Aug. 28, Bob decides to cancel his subscription:.
– Bob visits the subscription website, finds a webpage that lets him cancel his subscription,
and clicks the Unsubscribe button.

– PayPal displays a log-in page. Bob enters his PayPal credentials and logs in.
– PayPal displays the Subscription Details page for his subscription.
– Bob scrolls to the bottom of the page and clicks the Unsubscribe button.
 Bob’s subscription remains active through Sep. 14.
 PayPal collects no more recurring payments from Bob.
Creating Unsubscribe Buttons
Do one of following to add Unsubscribe buttons to your website:
 Create an Unsubscribe button as an optional step when you create your Subscribe button by
using the creation tool on the PayPal website
See one of the following:
– “Using the Button Creation Tool for an Unsubscribe Button” on page 160


3

– Step 2 of “Page 2 – Specifying Advanced Features of Your Subscribe Button” on
page 177
 Write the HTML code for Cancel Subscription buttons manually.
See “Sample HTML Code for an Unsubscribe Button” on page 168.

Generating Usernames and Passwords with Subscribe Buttons
Let PayPal generate unique usernames and passwords for your subscribers when they sign up
for subscription memberships to your website. Use PayPal Subscriptions Password
Management to enable access to members-only content on your website automatically.

IM PORT AN T : Subscriptions Password Management and Auto Return are incompatible. Turn
Auto Return off if you want PayPal to manage subscription passwords.
For more information, see “Auto Return” on page 351.
How Subscriptions Password Management Works
After subscribers sign up for your subscription, PayPal generates their usernames and
passwords automatically. PayPal displays the generated values to subscribers on the PayPal
payment confirmation page and in the PayPal confirmation email. In addition, PayPal displays
generated usernames and initial passwords to subscribers from their PayPal accounts.
Your website uses the generated usernames and initial passwords to set up new accounts so
that your subscribers can log in. Your website receives new subscription messages through
Instant Payment Notification, which requires advanced programming skills to implement.
After you implement Instant Payment Notification on your website, you write additional
programming code that captures the generated usernames and initial passwords for new
subscriptions. You should also write code to capture cancellation and end-of-term notices, so
that you can update your member database to turn off access to members-only content.
For more information about Instant Payment Notification, see the Instant Payment Notification
Guide.

Downloading the Subscriptions Password Management Perl Script
PayPal provides a Perl script that you can use to help automate access to members-only
content for new subscribers, provided your website uses “Basic Authentication” with an
Apache web server that runs on Linux. The Perl script interacts with Instant Payment
Notification to automatically activate and deactivate subscriber accounts on your website.
NOT E : You must agree to the terms of use before you can download the installation manual
and the Perl script from the PayPal website.


3

To download the manual and the Perl script for use with Subscriptions Password
Management:
1. Log in to your PayPal Business account at https://www.paypal.com.
2. Click the Merchant Services tab.
The Tools for existing PayPal merchants page opens.
3. Under the Create Buttons heading, click the Subscribe link.
The Subscriptions & Recurring Payments button page opens.
4. In the text beside the first checkbox on the page, click the IPN and server modifications
required link.
The Subscriptions Password Management page opens.
5. Scroll to the bottom of the page, and click the Download the Perl script link.
The User Agreement page opens.
6. Read the PayPal software license agreement, and then click the I agree button.
The Subscriptions Download page opens.
7. Do both of the following:
– Click the Download Manual link to download the PayPal Password Management
Installation Guide in PDF format.
– Click the Download Script link to download a tar file with the Perl script and a copy of
the license agreement.
Specifying to Generate Usernames and Passwords with Subscribe Buttons
Do one of following to add Subscribe buttons to your website that generate usernames and
passwords automatically for subscribers:
 Specify that you want PayPal to generate usernames and passwords when you create
Subscribe buttons by using the creation tool on the PayPal website.
 Specify that you want PayPal to reattempt failed recurring payments in the HTML button
See “Sample HTML Code for a Subscribe Button with Password Management” on
page 169.

Reattempting Failed Recurring Payments with Subscribe Buttons
PayPal cancels subscriptions when recurring payments fail. A recurring payment fails if funds
cannot be moved from the subscriber’s PayPal account to your own. Limits on the availability
of funds in PayPal accounts occur rarely, for a variety of reasons.


3

Temporary limits that PayPal places on subscribers’ accounts are often lifted quickly. To avoid
unnecessary cancellations, you can specify that PayPal should reattempt failed payments
before canceling subscriptions.
How PayPal Reattempts Failed Recurring Payments
PayPal reattempts to collect recurring payments three days after the day on which recurring
payments fail. If the first reattempt to collect a recurring payment fails, PayPal waits 5 days to
reattempt a second time. If the second reattempt fails, PayPal cancels the subscription.
NOT E : PayPal automatically reattempts payments made with bank accounts 3 days after
PayPal notifies subscribers that their payments failed.
Reattempts will not occur if another subscription payment is scheduled within 14 days of the
failed payment, so that payments do not overlap.

PayPal Reattempts to Collect a Failed Recurring Payment
Subscription Terms:
 A regular subscription for $20.00 USD a month, for one year
Bob signs up for a subscription on Feb. 12.
 On Apr. 12, PayPal attempts to collect Bob’s recurring $20.00 payment, but the payment
fails because of a temporary limit placed on Bob’s PayPal account.
 On Apr. 15, PayPal reattempts to collect Bob’s recurring $20.00 payment for April, but the
payment fails again because the temporary limit remains on Bob’s PayPal account.
 On Apr. 18, Bob takes action on his PayPal account, and PayPal lifts the temporary limit.
 On Apr. 20, PayPal reattempts to collect Bob’s recurring $20.00 payment for April, and the
payment succeeds.
 On May 12, PayPal attempts to collect Bob’s recurring $20.00 payment for May, and the
payment succeeds.
Specifying to Reattempt Failed Recurring Payments with Subscribe Buttons
Subscribe buttons reattempt failed recurring payments by default. To override the default,
specify the sra HTML variable with the value set to 0.
For more information, see “Sample HTML Code for a Subscribe Button That Reattempts
Payments” on page 170.


3
Creating Advanced Subscribe Buttons on the PayPal Website

Creating Advanced Subscribe Buttons on the PayPal
We b s it e
Read the following topics to learn more about creating Subscribe buttons on the PayPal
website:
 “The Basic Steps for Using the Tool with Subscribe Buttons” on page 146
 “Saving Subscribe Buttons in Your PayPal Account” on page 147
 “Tracking Inventory and Profit and Loss for Subscribe Buttons” on page 148
 “Adding Advanced Features to Subscribe Buttons with HTML Variables” on page 148
 “Generating Code for Subscribe Buttons and Email Payment Links” on page 148
 “Protecting HTML Code for Subscribe Buttons” on page 148
 “Step 1 – Specifying Basic Features of Your Subscribe Button” on page 149
 “Step 2 – Tracking Inventory and Profit and Loss with Your Subscribe Button” on
page 153
 “Step 3 – Adding Advanced Features to Your Subscribe Button” on page 156
 “Copying and Pasting the Subscribe Code” on page 158
 “Using the Button Creation Tool for an Unsubscribe Button” on page 160

The Basic Steps for Using the Tool with Subscribe Buttons
The button creation tool on the PayPal website is a single webpage with three sections:
the basic details of your payment button.
 Step 2 – Save your buttons (optional) – This section lets you control whether PayPal
saves the important details of your button in your PayPal account.
advanced features of payment buttons. If you are familiar with HTML programming and
the advanced HTML variables supported by Website Payments Standard, you can enter
them here.
bar to expand it.


3


Saving Subscribe Buttons in Your PayPal Account
information about your button in your account, instead of placing it in the code that you add to
your website.
NOT E : If you change product options, you must copy and paste the code that is newly
generated by PayPal to replace the code that you pasted previously.
account.


3

Tracking Inventory and Profit and Loss for Subscribe Buttons
If you save payment buttons in your PayPal account, PayPal can track inventory and can track
profit and loss for the items that your buttons sell. PayPal can track inventory and profit and
loss for items themselves or separately by product options.
Use the Step 2 section of the button creation tool to specify the information that lets PayPal
track inventory and profit and loss.
Tracking Inventory
If you track inventory, PayPal helps avoid oversold situations. PayPal sends an alert by email
when your inventory on hand falls to or below the alert level you specify. You can let oversold
payments go through, or you can warn buyers and prevent them from specifying more than
your quantity on hand.
Tracking Profit and Loss
If you track profit and loss, PayPal helps you understand the profitability of your items. Enter
the cost of your item, and PayPal provides profit and loss reports based on the volume of sales.
Make sure to include all you costs to sell the item, including costs to acquire it and handle it
until sold.

Adding Advanced Features to Subscribe Buttons with HTML Variables
Website Payments Standard payment buttons, you can enter them in the button creation tool
before the button code is generated.

Generating Code for Subscribe Buttons and Email Payment Links
When you create Subscribe buttons with tools on the PayPal website, PayPal generates HTML
your website.
payment links to add Subscribe functionality to your email messages. If your web editing tool
or your service provider does not allow you to paste HTML code onto your webpages, you
may be able to paste the URL code for email payment links onto your webpages instead.

Protecting HTML Code for Subscribe Buttons
When you create Subscribe code with tools on the PayPal website, PayPal lets your protect the


3

on securing Website Payments Standard buttons.
For more information, see “Securing Your PayPal Payments Standard Buttons” on page 337.

Step 1 – Specifying Basic Features of Your Subscribe Button
Use the Step 1 section of the button creation tool to specify the basic features of your button.
In addition, you can customize the look of the button and choose whether the button includes
your email address or your merchant ID.
3. Under the Selling Preferences heading, click the My Saved Buttons link, and then do one
of the following:
– To create a button from scratch, in the Related Items box on the right, click the
Create New Button link.

– To create a button similar to one already in your list, at the end of the row for the button,
click the Action dropdown menu, and then click the Create similar button link.



3

5. Enter the payment details of your button.
– Item name – Enter a name for the subscription. If you enter nothing in this field, your
subscribers complete this field during checkout.
For example, enter “Alice’s Monthly Digest”.
– Subscription ID – (Optional) If you offer different kinds of subscriptions, such as
monthly and annual billing periods, enter an identifying code for this subscription.
If you want PayPal to track inventory levels, enter a value that is unique among all the
items that you sell by subscription and want PayPal to track. For more information, see
Step 2 of “Step 2 – Tracking Inventory and Profit and Loss with Your Subscribe
– Currency – Select the currency for the priced of your the item; the dropdown menu
If you customize the text of your button by changing the country elsewhere in the
Step 1 section, make sure here to select a currency to match.
6. (Optional) Customize your button with product options, by doing any of the following.
– Add dropdown menu with prices and options – Select this checkbox to add a
dropdown menu of options that set the price for the subscription.
In the Description field, enter a value, such as “Choose a payment.” For each Menu
Name, enter a value, such as “Daily.” In the Amount for each option, enter a price. In
the Frequency for each option, select “Daily,” “Weekly,” “Monthly,” or “Yearly.”
To preview your dropdown menu, click the Done button.

To change the description and options of your dropdown menu, click the Edit link.
To remove an option, clear the Menu name, and then click the Done button.
To remove the dropdown menu of prices and options from your button, click the Delete
link.
menu of product options that set the price for the item.
In the Menu option name, enter a value, such as “Color.” For each Menu option
name, enter values, such as “Red,” “Green,” or “Blue.” In the Price for each option,


3

enter the price of the item. In the Currency dropdown menu, select the currency for all
option prices.
To preview your dropdown menu, click the Done button.

To change the name and options of your dropdown menu, click the Edit link.
To remove an option, clear the Menu option name, and then click the Done button.
To remove the dropdown menu of price/options from your button, click the Delete link.
– Add text field – Select this checkbox to add a text box in which buyers enter option
information.
In the Enter name of text box field, enter a value, such as “Enter your size – S, M, L.”
To preview your text field, click the Done button.
To change the name of your text field, click the Edit link .
To remove the text box from your button, click the Delete link.
To add another text box, click the Add another text box link. Your button can have a
maximum of 2 text boxes.
For more information, see “Offering Product Options with Subscribe Buttons” on
page 138.
7. Click the link and do one of the following (optional).
– PayPal button – Select this radio button to use a button image that PayPal hosts on its
servers. You can configure the size of the button, whether the button displays payment
card logos, and the country and language for the button text.
If you change the country, make sure to select the currency elsewhere in the Step 1
section to match.
image, which PayPal does not host on its servers. Use your own button image if the
buttons that PayPal hosts do not match the look of your website.
If host your image on a secure server, change the text box to begin with https//.
8. Set the terms of the subscription.
– Have PayPal create user names and passwords for customers – To have PayPal
generate usernames and passwords for your subscribers, select this checkbox.
For more information, see “Generating Usernames and Passwords with Subscribe
Buttons” on page 143.


3

– Billing amount each cycle – Enter the amount you want to bill subscribers for each
billing cycle. The amount is drawn from subscribers’ PayPal accounts at the beginning
of each cycle.
– Billing Cycle – In the dropdown menus, select a number and a unit of duration for the
regular subscription billing cycle.
For example, to set a quarterly billing cycle, select “3” and “month(s).”
– (Optional) After how many cycles should billing stop? – If you want to limit the
number of regular billing cycles, select the number from the dropdown menu.
For more information, see “Limiting the Number of Billing Cycles with Subscribe
9. (Optional) Offer a trial period to your subscribers.
You can offer subscribers a trial period. You can offer the trial period at no charge or at a
discount compared to the regular billing amount. The trial period can differ in duration
from that of the regular billing cycle.
Select the I want to offer a trial period checkbox and set the following trial period
options:
– Amount to bill for the trial period – Enter the amount you want to charge for the trial
period. Leave the amount blank to offer a free trial period.
– Define the trail period – In the dropdown menus, select a number and a unit of time for
the trial period.
For example, you might select “1” and “month(s).”
– (Optional) Do you want to offer a second trial period? – Select the Yes radio button,
and then enter the amount to bill and how long the second trial period lasts.
For more information, see “Offering Trial Periods and Introductory Rates with Subscribe
10.Choose between your secure merchant account ID and your primary email address.
– Use my secure merchant account ID – Select this radio button to link your button with
your PayPal account by using your secure merchant ID.
Only PayPal can match your merchant ID with you and your PayPal account. Your
email address is never exposed in the HTML button code on your webpages.
NOT E : If you have a Premier account, your email address still might be exposed within
the <head> tag of your payment pages.
– Use my primary email address – Select this radio button to link your button with your
PayPal account by using your primary email address.
Your email address is exposed in the HTML button code on your webpages. Do not
select this option if you don’t save your button in your PayPal account and you do not
protect your payment button with encryption.

IM PORT AN T : Your email address is a less secure way to link your button with your
PayPal account than your secure merchant ID. Your email address is


3


– If you specified all the features for your button, click the Create Button button.
Follow the instructions for “Copying and Pasting the Subscribe Code” on page 158.
– If you want PayPal to track inventory for the item your button sells or if you do not want
to save your button in your PayPal account, click the Step 2 bar.
Follow the instructions for “Step 2 – Tracking Inventory and Profit and Loss with Your
Subscribe Button” on page 153.
– If you want to specify advanced features for your button, click the Step 3 bar.
Follow the instructions for “Step 3 – Adding Advanced Features to Your Subscribe

Step 2 – Tracking Inventory and Profit and Loss with Your Subscribe
Button
Use the Step 2 section of the button creation tool to track inventory and profit and loss for the
items that your button sells.

By default, the Step 2 section saves details about your button in your PayPal account. If you
do not save your button in your account, PayPal cannot track inventory or profit and loss for
your item.

until sold.


3

For more information, see “Tracking Inventory and Profit and Loss for Subscribe Buttons” on
page 148.
– Clear the Add you button to My saved buttons checkbox if you do not want to save the
important details of your button in your PayPal account.
If you do not save your button, PayPal cannot track inventory or profit and loss for your
item.
all payment details and information that identifies your PayPal account. You may need
to take extra precautions to secure your buttons against fraudulent payments.
page 337.
– Select the Add your button to My saved buttons checkbox to save the payment details
of your button in your PayPal account.
“Add your button to My saved buttons” is the default for this feature.
For more information, see “Saving Subscribe Buttons in Your PayPal Account” on
page 147.
2. Select the Track inventory checkbox to enter information that PayPal uses to track
inventory for your item. Then, do one of the following:
options that buyers select.
– By Option – Select this radio button if want to track inventory by product options that
you set up during Step 1 of the button creation tool.
3. Select the Track profit and loss checkbox to enter information that PayPal uses to track
profit and loss for your item.
You do not have to track inventory to track profit and loss. If you track inventory, you can
track profit and loss only in the same way – either by item or by product option.


3

that you set up during Step 1 of the button creation tool. If you set up product options
with prices, PayPal sets the radio button automatically and you cannot change it.
In the Item ID field, enter a unique ID for the item the button sells, if you did not enter it
during Step 1 of the button creation tool.
In the Price field, enter the cost to you of your item or for each product option. Make sure
to include all your costs to sell the item, including costs to acquire it and handle it until
sold.
4. Under the Do you want to let customers check out even if an item is sold out? heading,
do one of the following:
– Yes, let them checkout – Select this radio button to let buyers check out even when
inventory tracking shows that your item would become oversold. Buyers are not
after they complete checking out.
– No, don’t let them buy the item – Select this radio button to prevent buyers from
checking out when inventory tracking shows that your item would become oversold. In
the text box, enter the URL of a page on your website where you want PayPal to send
buyers of oversold items.
”No” is the default choice for this feature.
When the inventory falls to 0, PayPal lets buyers know that the item is completely out.

you specified.


3


Follow the instructions for “Copying and Pasting the HTML Code for Your Subscribe
Follow the instructions for “Step 3 – Adding Advanced Features to Your Subscribe
Button” on page 156“.
– If you want to adjust the basic features of your button, scroll to the top of the page and
click the Step 1 bar.
Follow the instructions for “Step 1 – Specifying Basic Features of Your Subscribe

Step 3 – Adding Advanced Features to Your Subscribe Button
Use the Step 3 section of the button creation tool to specify commonly used advanced features
for your button. In addition, use the Step 3 section to add advanced HTML variables to your
button for other, less commonly used features.
1. Do you need your customer’s shipping address?
Select this option for items that do not require shipping, such as digital goods that
buyers download, or for services that do not require on-site delivery.
during checkout.
2. Take customers to a specific webpage (URL) when they cancel their checkout?
You might have a special page on your website where buyers return when they cancel their
checkout. If so, select the checkbox and enter the URL for that page.


3

3. Take customers to a specific webpage (URL) after they finish checkout?
You might have a special page on your website where buyers return after they check out
successfully. If so, select the checkbox and enter the URL for that page.
NOT E : If you have a special webpage where buyers return after they finish checkout,
consider implementing Payment Data Transfer (PDT). It lets you display
information about the completed payment.
To learn more, see the Payment Data Transfer page on PayPal’s developer website.
4. Advanced variables
If you are familiar with HTML programming and the advanced HTML variables supported
by Website Payments Standard payment buttons, enter them here. Select the checkbox, and
then enter the variables in the text box below it.
Enter any advanced HTML variables by using the name/value-pair format
variableName=allowableValue.
Do not enclose values in quotes, even for values that contain spaces. PayPal surrounds
values from the equal sign (=) to the end of the line with quotes in the generated code
automatically.
For example, you want PayPal to display during checkout custom payment pages that you
set up in your Account Profile. When you include a page_style variable in HTML code
that you write manually, you use the standard HTML format <input type="hidden"
name="page_style" value="myPageStyle">. In the text box instead, enter the
variables using the shortened, name/value-pair format, page_style=myPageStyle.
page 407.
Follow the instructions for “Copying and Pasting the Subscribe Code” on page 158.
Follow the instructions for “Step 1 – Specifying Basic Features of Your Subscribe
to save your button in your PayPal account, scroll to the top of the page and then click
the Step 2 bar.
Follow the instructions for “Step 2 – Tracking Inventory and Profit and Loss with Your
Subscribe Button” on page 153.


3

Copying and Pasting the Subscribe Code
code page. The page contains tabs with button code for specific situations:
website.
paste HTML code.
Copying and Pasting the HTML Code for Your Subscribe Button


on securing Website Payments Standard buttons.
code.
3. In your web editing tool, open the webpage where you want to place your button.



3


Copying and Pasting the Code for the Email Payment Link


Avoiding Problems with Pasted HTML Code
following reasons:


3

Using the Button Creation Tool for an Unsubscribe Button

Each time you create a Subscribe button, PayPal gives you a chance to create an Unsubscribe
button. You can use the generated HTML code for any of these Unsubscribe buttons – the
code is identical. Paste the same HTML button code onto your webpages for as many
Unsubscribe buttons as you need.
NOT E : You cannot save Unsubscribe buttons in your PayPal account, and the HTML button
code that PayPal generates does not require protection.
For more information, see “Working with Unsubscribe Buttons” on page 141.
of the following:




3

5. In the Billing amount each cycle text box, enter any amount.
6. Scroll to the bottom of the page, and click the Step 2 bar.

The Step 2: Track inventory, profit and loss (optional) section of the tool expands to fill
the page.
7. Clear the Save button at PayPal checkbox.
The You’ve created your button page opens.
9. Click the Create an Unsubscribe button link.
10.Click the Create Button button.
code.



3
Sample HTML Code for Subscribe Buttons


The sample HTML code in this section demonstrates various features of Subscribe buttons:
 “Sample HTML Code for a Basic Subscribe Button” on page 162
 “Sample HTML Code for a Subscribe Button with Trial Periods” on page 163
 “Sample HTML Code for a Subscribe Button with Limits on Billing Cycles” on page 164
 “Sample HTML Code for Subscribe Buttons with Product Options” on page 165
 “Sample HTML Code for a Modify Subscription Button” on page 167
 “Sample HTML Code for an Unsubscribe Button” on page 168
 “Sample HTML Code for a Subscribe Button with Password Management” on page 169
 “Sample HTML Code for a Subscribe Button That Reattempts Payments” on page 170
To protect against malicious users tampering with the HTML code for your Subscribe buttons
and submitting fraudulent payments, see “Securing Your PayPal Payments Standard Buttons”
on page 337.

precautions on securing Website Payment Standard buttons.

Sample HTML Code for a Basic Subscribe Button
The sample HTML code below illustrates a basic Subscribe button with these features:
 No trial periods
 A subscription price of $5.00 USD
 A monthly billing cycle
 The subscription ends only when the merchant or subscriber cancel it.


<input type="hidden" name="business" value="alice@mystore.com">


<input type="hidden" name="cmd" value="_xclick-subscriptions">


<input type="hidden" name="item_name" value="Alice's Weekly Digest">
<input type="hidden" name="item_number" value="DIG Weekly">

3


<input type="hidden" name="a3" value="5.00">
<input type="hidden" name="p3" value="1">
<input type="hidden" name="t3" value="M">


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

src="https://www.paypal.com/en_US/i/btn/btn_subscribe_LG.gif"
</form>

Sample HTML Code for a Subscribe Button with Trial Periods
The sample HTML code below illustrates a Subscribe button with these features:
 An initial trial period that is free and lasts for 7 days.
 A second trial periods that costs $5.00 USD and lasts for an additional 3 weeks.
 The regular subscription begins 4 weeks after the subscriber signs up.






<input type="hidden" name="a1" value="0">
<input type="hidden" name="t1" value="D">


<input type="hidden" name="t2" value="W">

3

<input type="hidden" name="t3" value="Y">


</form>
For more information, see “Offering Trial Periods and Introductory Rates with Subscribe

Sample HTML Code for a Subscribe Button with Limits on Billing Cycles
The sample HTML code below illustrates a Subscribe button that require renewal, with these
features:
 A monthly billing cycle
 Expiration after 6 months, requiring renewal




<input type="hidden" name="item_name" value="Alice's Monthly Digest">

3

<input type="hidden" name="srt" value="6">

</form>
For more information, see “Limiting the Number of Billing Cycles with Subscribe Buttons” on
page 137.

Sample HTML Code for Subscribe Buttons with Product Options
When you add production options to your Subscribe buttons with HTML code that you write
yourself, you can have a maximum of 10 product options, each with their own sets of choices.
The options can be either dropdown menus or text boxes.
Read the following topics for sample code that illustrates various ways to add product options
to Subscribe buttons.
 “Sample Code for a Subscribe Button with Product Options” on page 165
 “Sample Code for a Subscribe Button with Product Options as Text Boxes” on page 166
For more information, see “Offering Product Options with Subscribe Buttons” on page 138.
Sample Code for a Subscribe Button with Product Options
The sample HTML code below illustrates a basic Subscribe button with a dropdown menu of
product options.








3


<input type="hidden" name="on0" value="Format">Format <br />
<select name="os0">
<option value="Select a format">-- Select a format --</option>
<option value="plaintext">Plain text</option>
<option value="HTML">HTML</option>
</select> <br />

</form>

Sample Code for a Subscribe Button with Product Options as Text Boxes
The sample code below illustrates a basic Subscribe button with a text box for entering
product options.








3



</form>


Sample HTML Code for a Modify Subscription Button
The sample HTML code in this topic illustrates a Modify Subscription button, which lets
subscribers convert their current subscriptions to a new set of terms. Modify Subscription
buttons are useful for letting subscribers upgrade from one subscription level to another. The
subscription number remains the same as before; only the terms of the subscription change.
The sample code illustrates a Modify Subscription button with these features:
 A subscription price of $69.95 USD.
 A 6-month billing cycle.
 No limit on the number of billing cycles.
 Subscription modification allowed for the above terms only. New subscriptions in addition
to the current subscriptions are not allowed.
The subscription ends only when the merchant or subscriber cancel it.


3










</form>
For more information, see “Working with Modify Subscription Buttons” on page 138

Sample HTML Code for an Unsubscribe Button
Instead of an HTML form like other payment buttons, Unsubscribe buttons are image links to
the subscription cancellation function on the PayPal website. The URL for the image link is
specified with the HREF attribute, and it includes these URL-encoded parameters:
 cmd – identifies the action as a request to cancel the active subscription of the PayPal
account holder who clicked the button.
 alias – identifies the email address on file with the subscription service provider’s PayPal
account through which the subscriber originally signed up, or identifies the provider’s
PayPal account by secure merchant account ID.
In the example below, the email address alice@mystore.com is URL encoded by
substituting “@” with “%40” and “.” with “%2e”.

3

The sample code below illustrates a Cancel Subscription button that lets subscribers cancel
their current, active subscriptions.

<A HREF="https://www.paypal.com/cgi-bin/webscr?cmd=_subscr-
find&alias=alice%40mystore%2ecom">
<IMG BORDER="0"
SRC="https://www.paypal.com/en_US/i/btn/btn_unsubscribe_LG.gif"></A>

Paste the code onto you webpage near text that explains how subscription cancellations work.
For more information, see “Working with Unsubscribe Buttons” on page 141

Sample HTML Code for a Subscribe Button with Password Management
The sample HTML code below illustrates a Subscribe button that has PayPal generate
usernames and passwords automatically.








3


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

</form>
For more information, see “Generating Usernames and Passwords with Subscribe Buttons” on
page 143.

Sample HTML Code for a Subscribe Button That Reattempts Payments
The sample HTML code below illustrates a Subscribe button that has PayPal reattempt failed
recurring payments before canceling subscriptions.







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

</form>

3
Sample URL Code for Subscribe Email Payment Links

For more information, see “Reattempting Failed Recurring Payments with Subscribe Buttons”
on page 144.

Sample URL Code for Subscribe Email Payment Links
The sample URL code below illustrates a basic Subscribe email payment link with these
features:
 No trial periods
 A 1-month billing cycle
 No limit on the number of billing cycles
The subscription ends only when the merchant or subscriber cancel it.

https://www.paypal.com/cgi-bin/webscr?cmd=_xclick-
subscriptions&business=alice@mystore.com&item_name=Alice%27s%20Weekly%20Dig
est&a3=5.00&p3=1&t3=M&currency_code=USD

Creating Subscribe Buttons with JavaScript Disabled
 “Getting Started with Subscribe Buttons with JavaScript Disabled” on page 171
 “Creating Advanced Subscribe Buttons with JavaScript Disabled” on page 173
 “Limitations When Creating Payment Buttons with JavaScript Disabled” on page 183

Getting Started with Subscribe Buttons with JavaScript Disabled



3

5. Click the Subscribe link.

The Subscriptions & Recurring Payments page opens.
6. Enter the following information:
– Subscription name – Enter a name for the subscription; for example, enter “Alice’s
Monthly Digest”.
– Subscription price – Enter the amount you want to bill subscribers for each monthly
billing cycle; for example, enter “20.00”.
The Add a Subscribe button to your website page opens.



3

Creating Advanced Subscribe Buttons with JavaScript Disabled
Read the following topics to learn how to create Subscribe buttons with JavaScript disabled.
 “The Pages in the Button Creation Tool for Subscribe Buttons” on page 173
 “Page 1 – Specifying the Basic Features of the Subscribe Button” on page 173
 “Page 2 – Specifying Advanced Features of Your Subscribe Button” on page 177
 “Copying and Pasting the Subscribe Code with JavaScript Disabled” on page 180
NOT E : With JavaScript disabled in your browser, you can create Subscribe buttons on the
PayPal website, but you cannot save your buttons in your PayPal account.
The Pages in the Button Creation Tool for Subscribe Buttons
The button creation tool with JavaScript disabled has three pages:
 Subscriptions & Recurring Payments button – the initial page to specify the required
and most often used optional features
 Subscriptions & Recurring Payments – Page 2 – an optional page to specify additional,
advanced features, including the button image for Unsubscribe buttons
 Add a Subscribe button to your website – the final page that has the generated code for
your payment button
Page 1 – Specifying the Basic Features of the Subscribe Button
Use the Subscriptions & Recurring Payments page to specify subscription details, select the
size of button image, and select encryption.
4. Under the Create button without JavaScript enabled heading, click the Subscribe link.


3

The Subscriptions & Recurring Payments button page opens.
5. Enter the subscription details of your button.
– Subscription name/service – Enter a name for the subscription that people sign up for
when they click the Subscribe button.
– Reference number – (optional) If you offer different kinds of subscriptions, such as
monthly and annual payment plans, enter an identifying code for this subscription.
– Currency – From the dropdown menu, select the currency in which you will specify the
prices for trial periods and the regular subscription. The dropdown menu automatically
selects the currency of your primary balance.
log-in or sign-up page that subscribers see when they click the button. The content on the
page will be appropriate for the country you select. Subscribers can change the country
that you select, after the log-in or sign-up page opens.
– Select the checkbox at the bottom of the details section if you would like PayPal to
generate usernames and passwords for your subscribers.
For more information, see “Generating Usernames and Passwords with Subscribe
6. Specify trial periods for the subscription (optional).
– In the Trial Period #1 text box, enter the amount you want to bill subscribers for the
initial trial period. Enter 0 for a free initial trial period.
– In the Trial Period #1 dropdown menus for how long this trial period should last,
select a number and a unit of duration.
The following example shows how to select three-day trial period:

– In the Trial Period #2 text box, enter the amount you want to bill subscribers for a
subsequent trial period.


3

– In the Trial Period #2 dropdown menus for how long this trial period should last,
select a number and a unit of duration.
For more information, see “Specifying Trial Periods with Subscribe Buttons” on page 137.
7. Specify the regular billing cycle for the subscription.
– Subscription Price – Enter the amount that you want to bill subscribers for regular
billing cycles that occur after trial periods end.
– Under the recurring basis link, select the No radio button if you want the subscription
to expire after the end of the first regular billing cycle.
– In the dropdown menus for the length of each billing cycle, select a number and a unit
of duration.
– Under the text that reads stop the recurring payments after a certain number, select
the Yes radio button if you want to limit the number of regular billing cycles for a
subscription.
– If you select the Yes radio button in the previous step, select the number of times you
that want the regular billing cycle to recur before the subscription expires.
– Under the text that reads if payment fails for the subscription, select the No radio
button if you want subscriptions to cancel immediately after attempts to collect recurring
payments fail.
For more information, see “Reattempting Failed Recurring Payments with Subscribe
Buttons” on page 144
The following example shows how to set up regular billing cycles for a year-long
installment plan with 12 equal, monthly payments.

For more information, see “Limiting the Number of Billing Cycles with Subscribe
8. Choose a button style for your Subscribe button.
Select the radio button next to the image that you want to use, if you are going to be
receiving payments from your website instead of by using an email payment link. The
image that you select is hosted by PayPal.


3

– or –
code is generated.

precautions on securing Website Payment Standard buttons.


3

10.If you have additional details to specify for your button, such as a custom payment page
that has your own logo and colors, or you want PayPal to generate a Cancel Subscription
button, click the Add More Options button and follow the instructions for “Page 2 –
Specifying Advanced Features of Your Subscribe Button” on page 177.
– or –
If you entered all the details and options for your button, go to “Copying and Pasting the
Subscribe Code with JavaScript Disabled” on page 180.
Page 2 – Specifying Advanced Features of Your Subscribe Button
Use the Subscriptions & Recurring Payments – Page 2 page to specify the following
additional details for your button.
Option fields lets subscribers select or specify options when they sign up for a subscription,
such as the choice of HTML or plain text format subscriptions to electronic newsletters.
Options must not change the price of the subscription.
Subscribe 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 subscribers type their option choice.
field.
– Option Name – Enter the name of your option, for example, “Format”. 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, for example “HTML” and “Plain Text”.
Choices cannot exceed 30 characters. Use a carriage return (press ENTER) to separate
choices. Enter no more than 10 choices.

IM PORT AN T : Option fields cannot be used if you are creating an email payment link. To
include Subscribe links in email messages for items with options, send
HTML emails with links to Subscribe buttons on your website that have
option fields.
2. Create a Cancel Subscription button (optional).
Choose a button style for your Cancel Subscription button, which PayPal generates
automatically when you visit Page 2 to create a Subscribe button.
Select the radio button next to the image that you want to use. The image that you select is
hosted by PayPal.


3

– or –
To learn more, see “Working with Unsubscribe Buttons” on page 141.
Use these settings to give subscribers 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 subscribers see are
Styles in your account profile, they are listed here. Choose the page style you would like
to appear when subscribers click your Subscribe button.
subscribers see when they click your Subscribe button.
4. Customize your subscribers’s experience.
Use these settings to give subscribers a payment experience that is easy to navigate.


3

Enter the URL of a page on your website that you want subscribers redirected to after
they complete their payments. Only this payment button uses the URL that you enter.
payment buttons use to redirect subscribers to your website after they complete their
want subscribers redirected to if they cancel their payments at any point before
completing the checkout. If you do not enter a URL, subscribers see a PayPal webpage.
Only this payment button uses the URL that you enter.


3

Select the radio button that matches your need to collect addresses from subscribers:
Make shipping optional – Select this radio button if you want to prompt subscribers to
enter their addresses as an option.
– or –
Yes, require shipping – Select this radio button if you want to require subscribers to enter
their addresses.
– or –
No shipping needed – Select this radio button if you do not require addresses from
subscribers.
Edit button and follow the instructions for “Step 1 – Specifying Basic Features of Your
Subscribe Button” on page 149, beginning with Step 5.
– or –
the Subscribe Code with JavaScript Disabled” on page 180.
Copying and Pasting the Subscribe Code with JavaScript Disabled
After you enter the details and options that you want for your Subscribe button, click the
Create Button Now button.
PayPal generates Subscribe code for:
 A payment button, which you can paste onto your website
 An email payment link, which you can paste into email
 Optionally, a button and an email link to let subscribers cancel their subscriptions
The Add a Subscribe button to your website page displays the generated code.

Copying and Pasting the HTML Code for the Subscribe Button with JavaScript
Disabled . 1.Click the HTML code for Websites text box to select all of the generated
HTML code.



3


Copying and Pasting the Code for the Subscribe Email Payment Link WIth JavaScript
Disabled. 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.
PayPal Payments Standard Buttons” on page 337.


Copying and Pasting the Code for the Cancel Subscription Button. PayPal generates
HTML code for the Cancel Subscription button if you visit the Subscriptions and Recurring
Payments – Page 2 page to add more options to your Subscribe button.
1. Select everything in the first text box under the Copy 'Cancel Subscription' Button
HTML heading by clicking the text with your mouse.


3


Copying and Pasting the Code for the Cancel Subscription Email Payment Link.

PayPal generates code for the Cancel Subscription email payment link if visit the
Subscriptions and Recurring Payments – Page 2 page to add more options. However,
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.
PayPal Payments Standard Buttons” on page 337.
1. Select everything in the second text box under the Copy 'Cancel Subscription' Button
HTML heading by clicking the text with your mouse.


Creating More Subscribe Buttons. After you copy and paste the Subscribe code, you can
create another Subscribe button for a different kind of subscription. Scroll to the bottom of the
Add a Subscribe button to your website page and click the Create Another Button button.
Then follow the instructions for “Page 1 – Specifying the Basic Features of the Subscribe


3

Button” on page 173, beginning with Step 5. The pages of the button creation tool retain the
options that you previously specified.

Limitations When Creating Payment Buttons with JavaScript Disabled
The alternative tool that works with JavaScript disabled lets you create Subscribe buttons on
the PayPal website. However, the following features are not supported by the alternative tool:
 Tracking inventory or profit and loss
 Language choices for button images
To use any of the above features when creating payment buttons on the PayPal website, you
must enable JavaScript in your browser.
For more information, see “Enabling JavaScript in Your Browser” on page 183.

 “Enabling JavaScript in Firefox” on page 184
After you enable JavaScript in your browser, you can create a basic Subscribe button by
following the instructions for “Creating a Basic Subscribe Button on the PayPal Website” on
page 114.


3

Enabling JavaScript in Firefox


4 Recurring Payments – Automatic
Billing Buttons

Use Automatic Billing buttons to obtain authorization from buyers to bill them for goods and
services that fluctuate from month to month. You can set up automatic billing plans with
monthly minimum payments or let buyers pay nothing in months when they do not spend.
Buyers set the maximum monthly payment by entering an amount or choosing a maximum
from a list that you specify.

You can create Automatic Billing buttons for your website by using a tool on the PayPal
website. If you’re a power user, you can write the HTML code for Automatic Billing buttons
yourself.
 “Getting Started with Automatic Billing Buttons” on page 185
 “The Checkout Experience with Automatic Billing Buttons” on page 189
 “Managing Automatic Billing Agreements” on page 195
 “Creating Advanced Automatic Billing Buttons on the PayPal Website” on page 199
 “Sample HTML Code for Automatic Billing Buttons” on page 212

IM PORT AN T : You must have a PayPal Business account to create and use Installment Plan
buttons. In addition, you must be approved for Websites Payment Standard
Enhanced Recurring Payments. For more information, contact your PayPal
representative.

Getting Started with Automatic Billing Buttons
The easiest way to add an Automatic Billing button to your website is by using the button
creation tool on the PayPal website. As soon as you add the button, buyers can begin signing
up for automatic billing plans on your website for purchases of goods and services that
fluctuate from month to month.



Recurring Payments – Automatic Billing Buttons
4

representative.

The following instructions create a basic Automatic Billing button that lets buyers enter their
monthly maximum billing limit in a text box or a dropdown menu.
5. In the Choose a button type dropdown menu, select “Automatic Billing.”
6. Select one of the following radio buttons to choose how your customers set their maximum
billing limits.
With Automatic Billing buttons, buyers agree to pay you automatically when you bill them,
up to a limit that they choose. You set the parameters for the limits they choose.
Select one of the following check boxes:
– Let my customers choose their own maximum payment limits
In the Minimum payment limit field, enter the lowest maximum billing limit that you
want customers to choose. Customers cannot check out with a lower maximum than the
amount you enter here.
(Optional) In the Description field, enter a description of the goods or services for
which you will bill customers. The description appears above the text box where they
choose the monthly maximum. For example, you might enter: Regular house cleaning.
Prior to checkout, buyers enter monthly maximums in a text box above the button.


4

– I’ll set the payment limits
For Option 1, enter the lowest maximum payment amount you want buyers to choose.
Add successively higher maximums for the remaining options.
which you will bill customers. The description appears above the dropdown menu
where they choose the monthly maximum. For example, you might enter: Regular
house cleaning.
Before checkout, buyers select the monthly maximum payment from a dropdown menu
with the options that you set.

code.


4


PayPal does not collect payments from buyers until you initiate a monthly bill. When you
know what amount you want to bill a customer each month, you must initiate a billing request.
After you enter your customer’s billing amount, PayPal collects the payment automatically.
PayPal lets you bill a customer only once in any monthly billing cycle.
For more information, see “Billing Your Customer Automatically” on page 197.


4
The Checkout Experience with Automatic Billing Buttons

The checkout experience starts on your website and ends after payments are made.

Read the following topics to learn more about the checkout experience:
 “Enhancing the Checkout Experience with Automatic Billing Buttons” on page 194


4

The basic checkout experience with Automatic Billing buttons begins on your website when a
buyer is ready to sign up.


In this example, John begins on Nora’s Cleaning Services website. He decides to sign up for
regular cleaning service, for which Nora has $240 USD as the monthly minimum. John clicks
the Automatic Billing button to check out.

In this case, John does not have a PayPal account. He enters his billing information. He also
enters his contact information – email address and home phone number– so that PayPal can
send him a PayPal payment notification and can contact him if necessary to complete the
transaction. Then, he clicks the Continue button.


4



4

billing information page in order to sign up. The page changes to let them log in to PayPal.


billing plan before they complete their agreements.


4


In this case, John reviews the details of his automatic billing plan. Then, he clicks the Agree
button to complete his signup.

PayPal displays a payment confirmation page to let buyers know that they signed up
successfully.


4

Buyers View and Print Their Automatic Billing Plan Confirmations

In this case, John prints the confirmation page for his records.

Enhancing the Checkout Experience with Automatic Billing Buttons
PayPal Payments Standard lets you enhance the basic checkout experience in the following
ways:
 “Filling Out the Checkout Pages With Billing Addresses” on page 195
experience.


4
Managing Automatic Billing Agreements

The basic checkout experience ends on a PayPal webpage. Use one of the following
techniques to enhance the basic checkout experience so that it ends on your website:
 Return URL – Let buyers return to a page on your website by clicking a link or button on
the PayPal payment confirmation page.
To learn more, “HTML Variables for Displaying PayPal Checkout Pages” on page 434.
 Auto Return – Have PayPal return buyers to a page on your website automatically.
Filling Out the Checkout Pages With Billing Addresses
The basic checkout experience has forms for filling out billing and shipping addresses. PayPal
lets you pass in these addresses when you initiate checkout processes.
Enhance the checkout experience by filling out the billing and shipping addresses for the
buyer, if you gather that information from buyers on your website. Use the shipping address
and billing address HTML form variables to pass the information that you have. PayPal
displays the forms during checkout with the fields filled out automatically. Buyers are more
likely to complete their payments when there is less data for them to re-enter.
To learn more, see “Filling Out FORMs Automatically with HTML Variables” on page 411.
To learn which HTML variables to use, see “HTML Variables for Filling Out PayPal

PayPal offers tools and features to help manage your automatic billing agreements.
 “Using the Recurring Payments Dashboard to Track Automatic Billing Plans” on page 195
 “Using Recent Activity to Track Automatic Billing Payments” on page 196
 “Billing Your Customer Automatically” on page 197

Using the Recurring Payments Dashboard to Track Automatic Billing Plans

PayPal displays Automatic Billing plans in the Recurring payments dashboard, soon after
buyers complete checkout.


4

3. Under the Financial Information heading, click Recurring payments dasboard.

Result:

Track payments that PayPal makes automatically when you bill your customers from
My Recent Activity or History.

Using Recent Activity to Track Automatic Billing Payments

PayPal displays Automatic Billing plans in your recent activity, soon after buyers complete
checkout. Also, your recent activity shows payments that PayPal makes automatically after
you bill your customers.


4


Result:
From the My recent activity list, do any of the following:
 See new plans and new automatic payments that were made under the terms of plans.
 Manage a specific plan by clicking the Details link in the row for the plan.

Billing Your Customer Automatically



4

4. In the My customers list, find the customer you want to bill, then click the customer’s
name.
The Automatic billing details page opens.
5. In the Billing Details section, click Bill now.

The Automatically bill your customer dialog opens.
6. In the Amount to bill text box, enter the amount you want to bill the customer for the
month.
Don’t exceed the billing limit shown – that’s the amount your customer set for the
maximum billing amount, during checkout.
7. Click Bill now.

Result:
PayPal automatically bills your customer for the amount you entered.


4
Creating Advanced Automatic Billing Buttons on the PayPal Website

Creating Advanced Automatic Billing Buttons on the PayPal
Website
Read the following topics to learn more.
 “Basic Steps in the Button Creation Tool for Automatic Billing Buttons” on page 199
 “Saving Automatic Billing Buttons in Your PayPal Account” on page 200
 “Tracking Inventory and Profit and Loss for Automatic Billing Buttons” on page 201
 “Adding HTML Variables to Automatic Billing Buttons” on page 201
 “Generating Code for Automatic Billing Buttons and Email Payment Links” on page 201
 “Protecting HTML Code for Automatic Billing Buttons” on page 201
 “Step 1 – Specifying Basic Features of Your Automatic Billing Button” on page 202
 “Step 2 – Tracking Inventory for Your Automatic Billing Button” on page 206
 “Step 3 – Adding Advanced Features to Your Automatic Billing Button” on page 208
 “Copying and Pasting the Automatic Billing Code” on page 210
 “Avoiding Problems with Pasted Automatic Billing Code” on page 212

Basic Steps in the Button Creation Tool for Automatic Billing Buttons
 Step 2 – Track inventory, profit and loss (optional) – This section lets you control
information that PayPal uses to track inventory and to track profit and loss on the item.
the advanced HTML variables supported by PayPal Payments Standard, you can enter
them here.
bar to expand it.


4


Saving Automatic Billing Buttons in Your PayPal Account
The button creation tool saves payment buttons in your PayPal account, by default. The tool
saves your button and generates the code when you click the Create Button button.
Make sure you copy and paste the generated code onto your webpages, regardless of whether
you save your button at PayPal. The generated code is shorter for saved buttons. PayPal keeps
most of the information about your button in your account, instead of placing it in the code that
you add to your website.
 Your payment buttons are more secure. The generated code that you add to your website
contains no information that can be tampered with to produce fraudulent payments.
 You can edit the details and options of your payment buttons from a central location in
your PayPal account. Otherwise, you must search the pages of your website to find your
buttons so you can edit their details.
NOT E : To change product options for saved payment buttons, copy the code that PayPal
newly generates and paste it onto the pages of your website to replace the code that
you pasted there previously.
 You can track inventory and profit and loss for the items that your buttons sell.
your PayPal account. Your PayPal account holds a maximum of 1,000 saved buttons.


4

Tracking Inventory and Profit and Loss for Automatic Billing Buttons
Tracking Inventory
until sold.

Adding HTML Variables to Automatic Billing Buttons
you understand HTML programming and the advanced HTML variables supported by your
payment button, enter them in the button creation tool before the button code is generated.

Generating Code for Automatic Billing Buttons and Email Payment Links
When you create payment buttons with tools on the PayPal website, PayPal generates HTML
code for them. Then, you copy and paste the HTML code onto the pages of your website.
payment links to add payment button functionality to your email messages. Your web editing
tool or your service provider might not let you paste HTML code onto your webpages. If they
do not, try pasting the URL code for email payment links onto your webpages instead.

Protecting HTML Code for Automatic Billing Buttons
When you create payment buttons on the PayPal website, PayPal lets you protect the HTML
code that it generates by encrypting part of it. Protecting the HTML code of your payment
buttons helps protect against malicious tampering and fraudulent payments.


4


Step 1 – Specifying Basic Features of Your Automatic Billing Button

You must have a PayPal Business account to create and use Automatic Billing buttons. In
addition, you must be approved for PayPal Payment Standard Enhanced Recurring Payments.
For more information, contact your PayPal representative.
For more information, see “Billing Your Customer Automatically” on page 197.
of the following:



4

4. In the Choose a button type dropdown menu, select “Automatic Billing.”
5. From the Currency dropdown menu, select the currency for automatic billing plans that
buyers set up when they click your Automatic Billing button.
If you customize the text of your button by changing the country elsewhere in the Step 1
section, make sure here to select a currency to match.
With Automatic Billing buttons, buyers agree to pay you automatically when you bill them,
up to a limit that they choose. You set the parameters for the limits they choose.
Select one of the following check boxes:
– Let my customers choose their own maximum payment limits
In the Minimum payment limit field, enter the lowest maximum billing limit that you
want customers to choose. Customers cannot check out with a lower maximum than the
amount you enter here.
which you will bill customers. The description appears above the text box where they
choose the monthly maximum. For example, you might enter: Regular house cleaning.
Prior to checkout, buyers enter monthly maximums in a text box above the button.


4

– I’ll set the payment limits
For Option 1, enter the lowest maximum payment amount you want buyers to choose.
Add successively higher maximums for the remaining options.
which you will bill customers. The description appears above the dropdown menu
where they choose the monthly maximum. For example, you might enter: Regular
house cleaning.
Before checkout, buyers select the monthly maximum payment from a dropdown menu
with the options that you set.

Click the Done button to keep your choices.
7. Click the Customize text or appearance link and do one of the following (optional).
section to match.


4

8. Choose between your secure merchant account ID and your primary email address.


Follow the instructions for “Copying and Pasting the HTML Code for Your Automatic
Billing Button” on page 210.
– If you do not want to save your button in your PayPal account, click the Step 2 bar.
Follow the instructions for “Step 2 – Tracking Inventory for Your Automatic Billing
Follow the instructions for “Step 3 – Adding Advanced Features to Your Automatic


4

Step 2 – Tracking Inventory for Your Automatic Billing Button

your item.

until sold.
For more information, see Tracking Inventory and Profit and Loss for Automatic Billing
Buttons.
– Clear the Add you button to My saved buttons checkbox to not save the important
item.
For more information, see Securing Your PayPal Payments Standard Buttons.
For more information, see Saving Automatic Billing Buttons in Your PayPal Account.


4

– By Option – Select this radio button if you want to track profit and loss by the product
options that you set up during Step 1 of the button creation tool. If you set up product
options with prices, PayPal sets the radio button automatically and you cannot change it.
sold.


4

you specified.
Follow the instructions for Copying and Pasting the Automatic Billing Code.
Follow the instructions for Step 3 – Adding Advanced Features to Your Automatic
Billing Button.
Follow the instructions for Step 1 – Specifying Basic Features of Your Automatic
Billing Button.

Step 3 – Adding Advanced Features to Your Automatic Billing Button
1. Can your customer add special instructions in a message to you?
– No – Select this radio button if you do not want to prompt buyers to add special
instructions to you during checkout.


4

– Yes – Select this radio button to prompt buyers to add special instructions to you during
checkout.
(Optional) In the Name of message box field, enter text to Display above the text box
where buyers enter their special instructions. For example, you might enter, “Add
special handling instructions.”
during checkout.
Network..

by PayPal Payments Standard payment buttons, enter them here. Select the checkbox, and
automatically.


4

page 407.
Follow the instructions for “Copying and Pasting the HTML Code for Your Automatic
Follow the instructions for “Step 1 – Specifying Basic Features of Your Automatic
Billing Button” on page 202, beginning with Step 5.
the Step 2 bar.
Follow the instructions for “Step 2 – Tracking Inventory for Your Automatic Billing

Copying and Pasting the Automatic Billing Code
website.
and messages. In addition, your web editing tool or your service provider might not let you
paste HTML code onto your webpages. If they do not, try pasting the URL code for email
payment links onto your webpages instead.
Copy and paste the code that PayPal generates onto your webpages and into your email, even
if you save the button in your PayPal account.
Copying and Pasting the HTML Code for Your Automatic Billing Button



4


code.


Copying and Pasting the URL Code for Your Automatic Billing Email Payment
Link



4
Sample HTML Code for Automatic Billing Buttons


Avoiding Problems with Pasted Automatic Billing Code
After you paste the code onto your webpage or into your email, check that it matches exactly
following reasons:
pasting URLs and display text. Make sure that you paste the generated code into a field that

The following sample HTML code demonstrates various features of Automatic Billing
buttons:
 “Sample HTML Code for a Basic Automatic Billing Button” on page 212
 “Sample HTML Code for Choosing Limits with Automatic Billing Buttons” on page 214

Sample HTML Code for a Basic Automatic Billing Button
The sample code below illustrates a basic Automatic Billing button, with these features:
 A text box above the button for buyers to enter a maximum billing limit
 A minimum billing limit of $240 USD, set by using the min_amount HTML variable
 The item name and description “Regular House Cleaning” above the button
 Buyer’s address required during checkout


4



<input type="hidden" name="business" value="your-secure-merchant-ID">


<input type="hidden" name="cmd" value="_xclick-auto-billing">


<input type="hidden" name="item_name" value="Regular House Cleaning">
<input type="hidden" name="max_text" value="Regular House Cleaning">
<input type="hidden" name="set_customer_limit" value="max_limit_own">
<input type="hidden" name="min_amount" value="240.00">


<table>
<tr><td><strong>Regular House Cleaning</strong></td></tr>
<tr><td>Enter the maximum amount you want to
pay each month.</td></tr>
<tr><td>$ <input type="text"
name="max_amount" value=""> USD</td></tr>


<tr><td>You will pay at least $240.00 USD.</td></tr>
</table>


<table>
<tr><td align=center><i>Sign up for</i></td></tr>
<tr><td><input type="image" border="0" name="submit"
src="https://www.paypal.com/en_US/i/btn/btn_auto_billing_LG.gif"
alt="PayPal - The safer, easier way to pay online!"></td></tr>
</table>
src="https://www.stage2sc4078.qa.paypal.com/en_US/i/scr/pixel.gif"

</form>
The preceding sample code produces the following result on your webpage:

4

Sample HTML Code for Choosing Limits with Automatic Billing Buttons
The sample URL code below illustrates an Automatic Billing button with these features:
 A dropdown menu for buyers to choose a maximum billing limit, from choices $240 USD,
$300 USD, and $450 USD
 The item name and description “Regular House Cleaning” above the button
 The buyer’s address required during checkout




<input type="hidden" name="cmd" value="_xclick-auto-billing">


<input type="hidden" name="item_name" value="Regular House Cleaning">
<input type="hidden" name="set_customer_limit"
value="max_limit_defined">


<input type="hidden" name="option_select0" value="240">
<input type="hidden" name="option_amount0" value="240">

4

<table>
<tr>
<td align=center><input type="hidden" name="on0"
value="Regular house cleaning">
<strong>Regular House Cleaning</strong></td></tr>
<tr>
<td align=center>Select the maximum amount you want
to pay each month.</td></tr>
<tr>
<td align=center>$ <select name="os0">
<option value="240"> 240</option>
</select> USD</td></tr>


src="https://www.paypal.com/en_US/i/btn/btn_auto_billing_LG.gif"
</table>

</form>

4


5 Recurring Payments –
Installment Plan Buttons

Use Installment Plan buttons to let buyers pay in full or sign up to pay in installments, without
interest. You can offer installment plans that collect the first installment on checkout, with up
to 3 additional installments. Or, you can set up installment plans that defer the first installment,
with up to 4 installments sometime later. All payments must be collected within one year of
checkout.

You can create Installment Plan buttons that you add to your website by using a tool on the
PayPal website, or you can write the HTML code for Installment Plan buttons manually.
 “Getting Started with Installment Plan Buttons” on page 217
 “The Checkout Experience with Installment Plan Buttons” on page 220
 “Managing Installment Plans” on page 226
 “Creating Advanced Installment Plan Buttons on the PayPal Website” on page 228
 “Sample HTML Code for Installment Plan Buttons” on page 241

representative.

Getting Started with Installment Plan Buttons
The easiest way to add an Installment Plan button to your website is by using the button
creation tool on the PayPal website. As soon as you add the button, buyers can begin signing
up for installment plans with up to 4 installments, without interest.

representative.


Recurring Payments – Installment Plan Buttons
5

The following instructions create a basic Installment Plan button that lets buyers pay in 4
installments, starting at checkout.
5. In the Choose a button type dropdown menu, select “Installment Plan.”
With Installment Plan buttons, you can offer buyers one or more plan options with a single
button. For any plan option, the first payment can be collected at checkout or deferred. Plan
options can have up to 4 payments of equal or varying amounts.
After buyers agree to a plan option during checkout, PayPal makes the payments
automatically on the schedule you set. All payments must be made within one year of
checkout. You can include tax and shipping in the total amount, but do not include interest.
Select one of the following radio buttons to set up an installment plan for your button.
– In the Amount field, enter the full amount that PayPal collects at checkout for your item.
The total payment on other plan options must be the same amount.
– Offer equal installments at regular intervals
In the Bill Every dropdown menus, set the interval between payments. For example,
you might select “1” and “month(s).”
Under the Start Payments heading, select the At Checkout option to collect the first
payment at checkout. Or, select the After option, then select how long to defer the first
payment. For example, you might select “3” and “month(s).” In the Amount field enter
the amount for the payments. In the Cycles dropdown menu, select the number of
payments, up to 4.


5

– Offer variable installments at irregular intervals
In the Frequency of payments dropdown menu, select “days,” “weeks,” or “months.”
In row 1, enter the amount PayPal collects at checkout. In rows 2-4, enter amounts for
the remaining payments and select how long after checkout PayPal collects them.
Click Done to keep your choices. If you want to offer more plan options with your button,
click Create another Installment Plan.
code.



5
The Checkout Experience with Installment Plan Buttons

T h e C h e c k o u t E x p e r i e n c e w i t h I n s ta l l m e n t P l a n B u t t o n s

Read the following topics to learn more about the checkout experience:
 “Enhancing the Checkout Experience with Installment Plan Buttons” on page 225

The basic checkout experience with Installment Plan buttons begins on your website when a
buyer is ready to sign up.


5


In this example, Sarah begins on Andy’s Discount Appliances website. She wants an electric
oven, but she can’t afford to pay in full. Sarah selects the “No Payments for 30 Days” radio
button, and then she clicks the Installment Plan button to check out.



5


In this case, Sarah does not have a PayPal account. She enters her billing information. She also
enters her contact information – email address and home phone number– so that PayPal can
send her a PayPal payment notification and contact her if necessary to complete the
transaction. Then, she clicks the Continue button.
billing information page to sign up. The page changes to let them log in to PayPal.


5


billing plan before they complete their agreements.


5


In this case, Sarah reviews the details of her installment plan. Then, she clicks the Agree and
Pay button to complete her signup.


5

PayPal displays a payment confirmation page to let buyers know that they signed up
successfully.

Buyers View and Print Their Installment Plan Confirmations

In this case, Sarah prints the confirmation page for her records.

Enhancing the Checkout Experience with Installment Plan Buttons
PayPal Payments Standard lets you enhance the basic checkout experience in the following
ways:
 “Filling Out the Checkout Pages With Billing Addresses” on page 195
experience.


5
Managing Installment Plans

The basic checkout experience ends on a PayPal webpage. Use one of the following
techniques to enhance the basic checkout experience so that it ends on your website:
 Return URL – Let buyers return to a page on your website by clicking a link or button on
the PayPal payment confirmation page.
To learn more, “HTML Variables for Displaying PayPal Checkout Pages” on page 434.
 Auto Return – Have PayPal return buyers to a page on your website automatically.
Filling Out the Checkout Pages With Billing Addresses
The basic checkout experience has forms for filling out billing and shipping addresses. PayPal
lets you pass in these addresses when you initiate checkout processes.
Enhance the checkout experience by filling out the billing and shipping addresses for the
buyer, if you gather that information from buyers on your website. Use the shipping address
and billing address HTML form variables to pass the information that you have. PayPal
displays the forms during checkout with the fields filled out automatically. Buyers are more
likely to complete their payments when there is less data for them to re-enter.
To learn more, see “Filling Out FORMs Automatically with HTML Variables” on page 411.
To learn which HTML variables to use, see “HTML Variables for Filling Out PayPal

PayPal offers tools and features to help manage your installment plans.
 “Using the Recurring Payments Dashboard to Track Installment Plans” on page 226
 “Using Recent Activity to Track Installment Plan Payments” on page 227

Using the Recurring Payments Dashboard to Track Installment Plans

PayPal displays Installment Plans in the Recurring payments dashboard, soon after buyers
complete checkout.


5


Result:

Using Recent Activity to Track Installment Plan Payments

PayPal displays Installment Plans in your recent activity, soon after buyers complete checkout.
In addition, your recent activity shows payments that PayPal makes automatically under the
terms of plans.


5
Creating Advanced Installment Plan Buttons on the PayPal Website


Result:
From the My recent activity list, do any of the following:
 See new plans and new automatic payments that were made under the terms of plans.
 Manage a specific plan by clicking the Details link in the row for the plan.

Creating Advanced Installment Plan Buttons on the PayPal
Website
 “Basic Steps in the Button Creation Tool for Installment Plan Buttons” on page 229
 “Saving Installment Plan Buttons in Your PayPal Account” on page 230
 “Tracking Inventory and Profit and Loss for Installment Plan Buttons” on page 230
 “Adding HTML Variables to Installment Plan Buttons” on page 231
 “Generating Code for Installment Plan Buttons and Email Payment Links” on page 231
 “Protecting HTML Code for Installment Plan Buttons” on page 231
 “Step 1 – Specifying Basic Features of Your Installment Plan Button” on page 231
 “Step 2 – Tracking Inventory for Your Installment Plan Button” on page 235
 “Step 3 – Adding Advanced Features to Your Installment Plan Button” on page 237


5

 “Copying and Pasting the Installment Plan Code” on page 239
 “Avoiding Problems with Pasted Installment Plan Code” on page 241

Basic Steps in the Button Creation Tool for Installment Plan Buttons
information that PayPal uses to track inventory and to track profit and loss on the item.
the advanced HTML variables supported by PayPal Payments Standard, you can enter
them here.
bar to expand it.



5

Saving Installment Plan Buttons in Your PayPal Account
The button creation tool saves payment buttons in your PayPal account, by default. The tool
saves your button and generates the code when you click the Create Button button.
Make sure you copy and paste the generated code onto your webpages, regardless of whether
you save your button at PayPal. The generated code is shorter for saved buttons. PayPal keeps
most of the information about your button in your account instead of placing it in the code that
you add to your website.
 Your payment buttons are more secure. The generated code that you add to your website
contains no information that can be tampered with to produce fraudulent payments.
 You can edit the details and options of your payment buttons from a central location in
your PayPal account. Otherwise, you must search the pages of your website to find your
buttons so you can edit their details.
NOT E : To change product options for saved payment buttons, copy the code that PayPal
newly generates and paste it onto the pages of your website to replace the code that
you pasted there previously.
 You can track inventory and profit and loss for the items that your buttons sell.
your PayPal account. Your PayPal account holds a maximum of 1,000 saved buttons.

Tracking Inventory and Profit and Loss for Installment Plan Buttons
Tracking Inventory
until sold.


5

Adding HTML Variables to Installment Plan Buttons
you understand HTML programming and the advanced HTML variables supported by your
payment button, enter them in the button creation tool before the button code is generated.

Generating Code for Installment Plan Buttons and Email Payment Links
When you create payment buttons with tools on the PayPal website, PayPal generates HTML
code for them. Then, you copy and paste the HTML code onto the pages of your website.
payment links to add payment button functionality to your email messages. Your web editing
tool or your service provider might not let you paste HTML code onto your webpages. If they
do not, try pasting the URL code for email payment links onto your webpages instead.

Protecting HTML Code for Installment Plan Buttons
When you create payment buttons on the PayPal website, PayPal lets you protect the HTML
code that it generates by encrypting part of it. Protecting the HTML code of your payment
buttons helps protect against malicious tampering and fraudulent payments.


Step 1 – Specifying Basic Features of Your Installment Plan Button

You must have a PayPal Business account to create and use Installment Plan buttons. In
addition, you must be approved for Website Payment Standard Enhanced Recurring
Payments. For more information, contact your PayPal representative.
of the following:


5



4. In the Choose a button type dropdown menu, select “Installment Plan.”
5. From the Currency dropdown menu, select the currency for installment plans that buyers
set up when they click your Installment button.
If you customize the text of your button by changing the country elsewhere in the Step 1
section, make sure here to select a currency to match.
With Installment Plan buttons, you can offer buyers one or more plan options with a single
button. For any plan option, the first payment can be collected at checkout or deferred. Plan
options can have up to 4 payments of equal or varying amounts.
After buyers agree to a plan option during checkout, PayPal makes the payments
automatically on the schedule you set. All payments must be made within one year of
checkout. You can include tax and shipping in the total amount, but do not include interest.
Select one of the following radio buttons to set up an installment plan for your button.


5

– Pay in full
Select this option to let buyers pay in full. Generally, select this option if you want to
offer more than one plan option with your button.
In the Amount field, enter the full amount that PayPal collects at checkout for your
item. The total payment on other plan options must be the same amount.
(Optional) In the Description field, enter a short description of the plan option. For
example, you might enter: Pay in full. If you set up plan options with your button,
buyers choose this plan by selecting a radio button with this descrption.
– Offer equal installments at regular intervals
Select this option to offer buyers payments at regular intervals. PayPal can collect the
first payment at checkout or at a later time. The first payment can have a different
amount than the other payments.
In the Bill Every dropdown menus, set the interval between payments. For example,
you might select “1” and “month(s).”
Under the Start Payments heading, select the At Checkout option to collect the first
payment at checkout. Or, select the After option, then select how long to defer the first
payment. For example, you might select “3” and “month(s).” In the Amount field enter
the amount for the payments. In the Cycles dropdown menu, select the number of
payments, up to 4.
example, you might enter: Pay in 4 equal installments. If you set up multiple plan
options with your button, buyers choose this plan by selecting a radio button with this
descrption.
– Offer variable installments at irregular intervals
Select this option to offer buyers installments at irregular intervals, with different
amounts for each installment. PayPal always collects the first payment at checkout. The
remaining payments can have their own intervals and amounts.
In the Frequency of payments dropdown menu, select “days,” “weeks,” or “months.”
In row 1, enter the amount PayPal collects at checkout. In rows 2-4, enter amounts for
the remaining payments and select how long after checkout PayPal collects them.
example, you might enter: Pay in 4 Installments. If you set up plan options with your
button, buyers choose this plan by selecting a radio button with this descrption.
Click Done to preserve your choices. If you want to offer more plan options with your
button, click Create another Installment Plan.
7. Click the Customize text or appearance link and do one of the following (optional).
section to match.


5

8. Choose between your secure merchant account ID and your primary email address.


Follow the instructions for “Copying and Pasting the Installment Plan Code” on
page 239.
to save your button in your PayPal account, click the Step 2 bar.
Follow the instructions for “Step 2 – Tracking Inventory for Your Installment Plan


5

Follow the instructions for “Step 3 – Adding Advanced Features to Your Installment
Plan Button” on page 237.

Step 2 – Tracking Inventory for Your Installment Plan Button

your item.

until sold.
For more information, see “Tracking Inventory and Profit and Loss for Installment Plan
– Clear the Add you button to My saved buttons checkbox to not save the important
item.
page 337.
For more information, see “Saving Installment Plan Buttons in Your PayPal Account”
on page 230.


5

that you set up during Step 1 of the button creation tool. If you set up product options
with prices, the radio button is selected automatically and cannot be changed.
sold.


5

you specified.

page 239.
Follow the instructions for “Step 3 – Adding Advanced Features to Your Installment
Follow the instructions for “Step 1 – Specifying Basic Features of Your Installment

Step 3 – Adding Advanced Features to Your Installment Plan Button
1. Can your customer add special instructions in a message to you?
– No – Select this radio button if you do not want to prompt buyers to add special
instructions to you during checkout.


5

– Yes – Select this radio button to prompt buyers to add special instructions to you during
checkout.
(Optional) In the Name of message box field, enter text to Display above the text box
where buyers enter their special instructions. For example, you might enter, “Add
special handling instructions.”
during checkout.
Network..

by PayPal Payments Standard payment buttons, enter them here. Select the checkbox, and
automatically.


5

page 407.
page 239.
Follow the instructions for Step 1 – Specifying Basic Features of Your Installment Plan
Button .
the Step 2 bar.
Follow the instructions for “Step 2 – Tracking Inventory for Your Installment Plan

Copying and Pasting the Installment Plan Code
website.
and messages. In addition, your web editing tool or your service provider might not let you
paste HTML code onto your webpages. If they do not, try pasting the URL code for email
payment links onto your webpages instead.
Copy and paste the code that PayPal generates onto your webpages and into your email, even
if you save the button in your PayPal account.
Copying and Pasting the HTML Code for Your Installment Plan Button



5


code.


Copying and Pasting the URL Code for Your Installment Plan Email Payment
Link



5
Sample HTML Code for Installment Plan Buttons


Avoiding Problems with Pasted Installment Plan Code
After you paste the code onto your webpage or into your email, check that it matches exactly
following reasons:
pasting URLs and display text. Make sure that you paste the generated code into a field that

The following sample HTML code demonstrates various features of Installment Plan buttons:
 “Sample HTML Code for a Basic Installment Plan Button” on page 241
 “Sample HTML Code for an Installment Button with 2 Plan Options” on page 243

Sample HTML Code for a Basic Installment Plan Button
The sample code below illustrates a basic Installment Plan button, with these features:
 4 Payments of $75.00 USD each, beginning at checkout
 Payment periods of one month each
 The description “Pay in 4 installments” above the button
 Details of the plan above the button
 The total payment – $300.00 USD – above the button


5




<input type="hidden" name="cmd" value="_xclick-payment-plan">


<input type="hidden" name="item_name" value="Electric Oven">
<<input type="hidden" name="disp_tot" value="Y">



<input type="hidden" name="option_select0" value="option_0">
<input type="hidden" name="option_select0_name"
value="Pay in 4 installments">
<input type="hidden" name="option_select0_type" value="E">
<input type="hidden" name="option_select0_a0" value="75.00">
<input type="hidden" name="option_select0_p0" value="1">
<input type="hidden" name="option_select0_t0" value="M">
<input type="hidden" name="option_select0_n0" value="4">


<table>
<tr>
<td><input type="hidden" name="on0" value="plan"></td></tr>
<tr>
<td><input type="hidden" name="os0" value ="option_0"></td>
<td><b>Electic Oven</b></td></tr>
<tr>
<td></td>
<td>Number of payments: 4</td></tr>
<tr>
<td></td>
<td>Start payments at checkout</td></tr>
<tr>
<td></td>
<td>
<!-- a 2 column table for due and amount -- >
<table>
<tr>
<th align="left">Due*</th><th align="right">Amount</th></tr>
<tr>
<td colspan="2"><hr /></td></tr>
<tr>

5

<td>At checkout</td>
<td align="right">$75.00 USD</td></tr>
<tr>
<td>Every 1 month (x 3)</td>
<tr>
<tr>
<td colspan="2"
align="right"><b>Total $300.00 USD</b></td></tr>
</table></td></tr>
<tr>
<td colspan="3"><i>* We calculate payments from the
date of checkout.</i></td></tr>
</table>


<table>
<tr>
<td align=center><i>Sign up for</i></td></tr>
<tr>
<td><input type="image" border="0" name="submit"
src="https://www.paypal.com/en_US/i/btn/btn_installment_plan_LG.gif"
</table>
src="https://www.paypal.com/en_US/i/scr/pixel.gif">

</form>

Sample HTML Code for an Installment Button with 2 Plan Options
The sample code below illustrates an Installment Plan button with these features:
 Two plan options – “Pay in Full” and “No Payments for 30 Days”
 For plan option “Pay in Full,” the total payment at checkout, amount $300 USD
 For plan option “No Payments for 30 Days:Payment:”
– First payment 1 month after checkout, amount $150 USD
– Second payment 2 months after checkout, amount $50 USD
– Third payment 3 months after checkout, amount $50 USD
– Fourth payment 4 months after checkout, amount $50 USD
 The description “No Payments for 30 Days” above the button
 Details of the plan above the button
 The total payment – $300.00 USD – above the button

5




<input type="hidden" name="cmd" value="_xclick-payment-plan">


<input type="hidden" name="item_name" value="Electric Oven">
<input type="hidden" name="disp_tot" value="Y">




value="Pay In Full">
<input type="hidden" name="option_select0_type" value="F">
<input type="hidden" name="option_select0_t0" value="D">

value="No Payment for 30 Days">
<input type="hidden" name="option_select1_type" value="E">


<table>
<tr>
<td><input type="hidden" name="on0" value="plans"></td></tr>

5

<tr>
<td><input type="radio" name="os0" value ="option_0"
checked="checked"></td>
<td><strong>Pay In Full</strong></td></tr>
<tr>
<td></td>
<td>Amount at checkout $300.00 USD</td></tr>

<tr>
<td><input type="radio" name="os0" value ="option_1"></td>
<td><strong>No Payments for 30 Days</strong></td></tr>
<tr>
<tr>
<td></td>
<td>Number of payments: 4</td></tr>
<tr>
<td></td>
<td>Start payments after 1 month</td></tr>
<tr>
<td></td>
<td>
<table>
<tr>
<th align="left">Due*</th>
<th align="right">Amount</th></tr>
<tr>
<tr>
<td>First Payment</td>
<tr>
<td>Every 1 month (x 3)</td>
<tr>
<tr>
<td colspan="2"
align="right"><b>Total   
$300.00 USD</b></td></tr>
</table></td></tr>
<tr>
<td colspan="3"><i>* We calculate payments from the
date of checkout.</i></td></tr>
</table>

5

<table>
src="https://www.paypal.com/en_US/i/btn/btn_installment_plan_LG.gif"
</table>

</form>
The preceding sample code produces the following result on your webpage:


6 The PayPal Shopping Cart – Add
to Cart and View Cart Buttons

With the PayPal Shopping Cart, you can let buyers select multiple items on your website and
pay for them with a single payment. Buyers click Add to Cart buttons to add items to their
PayPal Shopping Carts, and they click View Cart buttons to review the items in their carts
before they check out and make their payments.

You can create Add to Cart buttons that you add to your website by using a tool on the PayPal
website, or you can write the HTML code for Add to Cart buttons manually. You can create
Read the following topics to learn more about the PayPal Shopping Cart:
 “Getting Started With The PayPal Shopping Cart” on page 247
 “The Checkout Experience With the PayPal Shopping Cart” on page 255
 “Managing PayPal Shopping Cart Transactions” on page 264
 “Advanced Features of Add to Cart Buttons” on page 266
 “Creating Advanced PayPal Shopping Cart Buttons on the PayPal Website” on page 267
 “Sample HTML Code for Add to Cart Buttons” on page 285
 “Sample HTML Code for a View Cart Button” on page 300
 “Creating PayPal Shopping Cart Buttons with JavaScript Disabled” on page 303

Getting Started With The PayPal Shopping Cart
The easiest way to add the PayPal shopping cart to your website is to create Add to Cart and
View Cart buttons by using a tool on the PayPal website. As soon as you add the buttons, you
can begin accepting payments on your website.


The PayPal Shopping Cart – Add to Cart and View Cart Buttons
6

Do the following to add the PayPal Shopping Cart to your website:
 “Getting Started With Add To Cart Buttons” on page 248
 “Getting Started With View Cart Buttons” on page 251

Getting Started With Add To Cart Buttons
Follow one of these procedures to get started creating your own Add to Cart buttons:
 “Using the Button Creation Tool for a Basic Add to Cart Button” on page 248
 “Creating Add to Cart Buttons Before You Create Your PayPal Account” on page 249
Using the Button Creation Tool for a Basic Add to Cart Button
To use the button creation tool for a basic Add to Cart button:
5. In the Choose a button type dropdown menu, select “Shopping cart.”


6

code.
– or –

– or –
Creating Add to Cart Buttons Before You Create Your PayPal Account
You can create basic Add to Cart buttons, add them to your website, and begin accepting
payments before you sign up for your PayPal account. Read the following topics to learn more
about creating Add to Cart buttons before you create your PayPal account.
 “Creating a Basic Add to Cart Button Without a PayPal Account” on page 249
 “Limitations of Add to Cart Buttons Created Without a PayPal Account” on page 250

Creating a Basic Add to Cart Button Without a PayPal Account.


6

– Email address to receive payments – Enter the email address that you will use when
you sign up for your PayPal account.
code.


Limitations of Add to Cart Buttons Created Without a PayPal Account. Consider the
following limitations of payment buttons that you create and add to your website before you
 You cannot claim the payments that people authorize during checkout. PayPal collects and
 Buyers must have a PayPal account to pay you.
– Tracking inventory or profit and loss
in your browser.

Unclaimed Payments From Buttons Created Without a PayPal Account. For buttons
that you create without a PayPal account, payments that buyers authorize are held as
unclaimed by PayPal until you sign up. PayPal holds your unclaimed payments under the
email address that you specify when you create the buttons. Make sure to use the same email
address when you sign up for your account. Otherwise PayPal cannot transfer your unclaimed
payments to your PayPal account balance.


6

In their PayPal accounts, buyers see unclaimed payments that they made to you from Add to
Cart buttons that you created without a PayPal account. Such unclaimed payments are
displayed in their recent account activity and in their transaction history. Until you finish
signing up for your PayPal account, buyers can cancel your unclaimed payments and recover
their funds.


Getting Started With View Cart Buttons
You need to create only one View Cart button, regardless of the number of Add to Cart buttons
that you create and add to your website. View Cart buttons on your website let buyers view
their shopping carts and the items in them. From there they can proceed to checkout.
Follow one of these procedures to get started creating your own View Cart buttons:
 “Using the Button Creation Tool for a View Cart Button” on page 251
 “Creating View Cart Buttons Before You Create Your PayPal Account” on page 253
Using the Button Creation Tool for a View Cart Button
Each time you create an Add to Cart button, PayPal gives you a chance to create a View Cart
button. You can use the generated HTML code for any of these View Cart buttons – the code
is identical. Paste the same HTML button code onto your webpages for as many View Cart
buttons as you need.
To use the button creation tool for a View Cart button:


6

3. Under the Selling Preferences heading, click the Create new button link.
4. In the Accept payments for dropdown menu, select “Shopping cart.”
– Item name – Enter any name.
– Price – Enter any price.

The Step 2 – Track inventory, profit and loss (optional) section of the tool expands to
fill the page.
9. Click the Create a View Cart button link.
10.Click the Create button button.
The You’ve Created Your Button page opens.
code.
12.Copy the text that you selected to the clipboard, by:
– or –


6

– or –
Creating View Cart Buttons Before You Create Your PayPal Account
You can create View Cart buttons before you create your PayPal account and add them to your
website. However, to begin accepting payments, you must add some Add to Cart buttons, as
well.
in your browser.
button. You can use the generated HTML code for any of these View Cart buttons – the code
is identical. Paste the same HTML button code onto your webpages for as many View Cart
buttons as you need.
To create a View Cart button without a PayPal account:
1. Visit the PayPal website at https://www.paypal.com.
3. Under the Need to accept credit cards? heading, click the On your website link.
The Choose a payment solution page opens.
4. Under the PayPal Payments Standard heading, click the Learn more link.
The PayPal PayPal Payments Standard: Overview page opens.
5. Under the Sell multiple items heading, click the Create payment button link.
6. In the Accept payments for dropdown menu, select “Products” or “Services”.
7. Select the Yes; create an “Add to Cart” button radio button.
8. Enter the payment details of an item.


6

The PayPal account required for this button type message box appears.
10.Click the close icon in the upper right corner of the message box to proceed.

11. Click the Create a View Cart button link.
12.Click the Create button button.
The PayPal account required for this button type message box appears.
13.Click the close icon in the upper right corner of the message box to proceed.



6
The Checkout Experience With the PayPal Shopping Cart

14.Click the Select Code button on the Websites tab to select all of the generated HTML
code.
– or –

– or –

This section demonstrates the PayPal checkout experience for people who click Add to Cart
and View Cart buttons on your website. The following diagram illustrates the steps.


6

The Checkout Experience with Add to Cart and View Cart Buttons

Read these topics to better understand the checkout experience with Add to Cart and View
Cart buttons:
 “Begin – Buyers Add Your Items to the PayPal Shopping Cart” on page 257


6

 “1 – Buyers Enter Their Billing Information or They Log In To PayPal” on page 258
 “End – Buyers Receive Payment Authorization Notices by Email” on page 262
 “Enhancing the Checkout Experience With Add to Cart Buttons” on page 262

Begin – Buyers Add Your Items to the PayPal Shopping Cart
The basic checkout experience with the PayPal Shopping Cart begins when someone on your
website adds your items to the cart and then views it to check out.

Buyers Add Your Items to the PayPal Shopping Cart

In this example, Steve begins on Kin’s Kards website, looking for birthday cards. Steve clicks
the Add to Cart buttons under two cards that he wants. Then, he clicks the View Cart button
to review his selections.
PayPal displays a shopping cart page, which lets buyers review their selections, specify
quantities, and remove items before proceeding to check out. If you set up shipping rates in


6

your account profile, a shipping calculator displays at the bottom of the cart. When the buyers
enter their zip codes, the shipping calculator determines the shipping amount and adds it to the
total. If your account has sales tax associated with that zip code, the calculator also determines
the tax amount and adds it to the total. If the buyer changes the zip code, the calculator uses the
new zip code to recalculate the shipping and tax amounts.

Buyers Review Their Selections in the PayPal Shopping Cart

In this case, Steve is satisfied with his selections and the transaction amount. He clicks the
Proceed to Checkout button.

1 – Buyers Enter Their Billing Information or They Log In To PayPal


6

Buyers Enter Their Billing Information or Log In to PayPal

For the PayPal Shopping Cart, the PayPal billing information/log-in page shows transaction
details on the left, such as the item names and the transaction total.
If buyers are satisfied with the details, they do one of the following to select a payment
method:
 Have a PayPal account? – Buyers click this link, enter their PayPal credentials, and click
the Log in button.
 Don’t have a PayPal account?– Buyers enter their billing information. They also enter
their contact information – email address and home phone number– so that PayPal can send
their PayPal transaction receipts and can contact them if necessary to complete the
transaction. Then, they click the Review Order and Continue button.
If your website gathers information about your buyer, you can define HTML code to
prepopulate (prefill) the corresponding billing information fields. In this case, the buyers


6

see a collapsed version of the billing information section. For example, if you prefilled the
billing address, the address information displays on the page without the entry fields. Each
prefilled section of information is followed by a change link to let the buyers modify the
information, if necessary.
For more information about prepopulation, see “Filling Out FORMs Automatically with
HTML Variables” on page 411.
In this case, Steve is satisfied with the total transaction amount of $14.28 USD. He enters his
billing and contact information, and then clicks the Review Order and Continue button.

2 – Buyers Confirm Their Transaction Details Before Paying
PayPal displays a transaction confirmation page to let buyers confirm the details before they


In this case, Steve reviews the transaction details and clicks the Pay Now button to complete
the transaction and make his payment.


6

3 – Buyers View and Print Their PayPal Payment Confirmations
PayPal displays a payment confirmation page after buyers pay to let them know that they have
completed their transactions and authorized their payments successfully.

Buyers View Their Payment Confirmations

 View the PayPal transaction ID to reconcile their payments.
 Click the Print receipt link to print receipts for their records.


6


In this case, Steve prints the PayPal payment receipt for his records.

End – Buyers Receive Payment Authorization Notices by Email
PayPal sends buyers a payment authorization notice by email to confirm the transaction that
they made with the merchant.
In this case, PayPal sends Steve an email message notifying him of his transaction with Kin’s
Kards and his authorization for payment of $14.28 USD.

Enhancing the Checkout Experience With Add to Cart Buttons
your buyers:
 Calculating Tax and Shipping Amounts
 Prepopulating the Checkout Pages With Billing and Shipping Addresses
 Returning Buyers to Your Website After They Check Out


6

Calculating Tax and Shipping Amounts
The basic checkout experience handles tax and shipping, if you provide the information.You
can enhance the checkout experience by specifying tax and shipping rates in your account
profile. PayPal calculates the charges automatically for each transaction. In addition, you can
specify tax and shipping charges individually for items in the payment buttons that you create.
 “Automatic Calculation of Sales Tax” on page 363
 “Automatic Calculation of Shipping Charges (U.S. Merchants Only)” on page 368
 “Automatic Calculation of Shipping Charges (non-U.S. Merchants Only)” on page 384
your button.
Prepopulating the Checkout Pages With Billing and Shipping Addresses
The basic checkout experience has forms for filling in billing and shipping information. You
can enhance the checkout experience by prepopulating the forms with information that you
have on your website about the buyer.
The basic checkout experience leaves buyers on the PayPal website after they check out. Use
one of the following techniques to enhance the checkout experience so that buyers return to
your website instead of the PayPal website.
 Return URL – Let buyers return to a page on your website if they click a return link or
To learn more, see Step 4 of “Page 2 – Adding More Details to the PayPal Shopping Cart
page 434.


6
Managing PayPal Shopping Cart Transactions

Auto Return on. With Auto Return on, PayPal redirects buyers to your
the transaction information that you need to let buyers print receipts from
your website.

Read the following topics to learn how PayPal helps you manage PayPal Shopping Cart
transactions:
 “Using Email Notices to Track PayPal Shopping Cart Transactions” on page 264
 “Using Recent Activity to Track PayPal Shopping Cart Transactions” on page 265
 “Using Transaction History to Track PayPal Shopping Cart Transactions” on page 265
 “Using Downloadable History Logs to Track PayPal Shopping Cart Transactions” on
page 265
 “Using Instant Payment Notification to Track PayPal Shopping Cart Transactions” on
page 266

Using Email Notices to Track PayPal Shopping Cart Transactions
organization who handles order processing or accounting. Add the additional email address to
your account profile. Then, use that email address as the one to receive payments when you
use the button creation tool on the PayPal website to create your Add to Cart buttons. Specify
the alternate email address as the value for the business HTML variable when you write the
HTML code yourself for your Add to Cart buttons.


6

For more information, see Step 4 in the instructions for “Page 2 – Adding More Details to the
PayPal Shopping Cart Button” on page 309, or “HTML Variables for PayPal Payments
Standard” on page 417.”

Using Recent Activity to Track PayPal Shopping Cart Transactions
PayPal displays PayPal Shopping Cart transactions in your recent activity, soon after buyers
complete them by clicking Add to Cart buttons and checking out on your website.

Using Recent Activity to Track PayPal Shopping Cart Transactions


Using Transaction History to Track PayPal Shopping Cart Transactions
PayPal lets you search for PayPal Shopping Cart transactions on the History page. The status
of payments found there can be:
 Completed – Transactions were successful, and funds were credited to your account
 Cleared – Payments cleared senders’ accounts, and funds were credited to your account
 Uncleared – Payments have not cleared sender’s accounts, and funds were not credited

Using Downloadable History Logs to Track PayPal Shopping Cart
Transactions
PayPal lets you download your PayPal Shopping Cart transactions to your computer from the
History page. You can specify a date range for the transactions and the file format of the
download file.


6
Advanced Features of Add to Cart Buttons


Using Instant Payment Notification to Track PayPal Shopping Cart
Transactions
PayPal lets your web server receive messages about PayPal Shopping Cart transactions and
payment activity on your account. If you activate Instant Payment Notification, PayPal sends
messages when:
notify_url” on page 415 and the Merchant Setup and Administration Guide.

Advanced Features of Add to Cart Buttons
Read the following topics to learn about these advanced features of Add to Cart buttons:
 “Offering Product Options With Add to Cart Buttons” on page 266
 “Offering Discounts With Add to Cart Buttons” on page 267

Offering Product Options With Add to Cart Buttons
Prompt buyers for product options, such as size or color. You can prompt buyers for their
option selections with dropdown menus or with text boxes. PayPal limits you to 7 product
options on a single payment button. Up to 5 options can prompt for selections with dropdown
menus, and up to 2 options can prompt for selections with text boxes.

With Add to Cart buttons, you can offer a product option that has separate prices for each
selection by using 1 of the 5 allowable dropdown menus.
Specifying Product Options With Add to Cart Buttons
Do one of the following to create Add to Cart buttons that offer product options:


6
Creating Advanced PayPal Shopping Cart Buttons on the PayPal Website

 Specify the product options when you create Add to Cart buttons by using the creation tool
on the PayPal website.
See Step 7 of “Step 1 – Specifying Basic Features of Your Add to Cart Button” on
page 271.
See “Sample Code for an Add to Cart Button With Product Options” on page 286.

Offering Discounts With Add to Cart Buttons
PayPal allows you to offer a discount for an item. You can offer item discounts either as an
amount or a percentage.
 Set a discount amount that applies to single or multiple quantities of the item. You can set a
discount for the first item and a different discount for the additional quantity, and you can
limit the total quantity to which the discount applies.
 Set a discount percentage that applies to single or multiple quantities of the item. You can
set a discount for the first item and a different discount for the additional quantity, and you
can limit the total quantity to which the discount applies.
When you set a discount amount or percentage, you can limit the number of items to which the
discount applies. Any applicable tax calculations occur after subtracting the discount.
information.
Specifying item discounts
Do one of the following to create Add to Cart buttons that specify discounts:
 Specify the discount amounts or percentages when you create your Add to Cart buttons by
using the creation tool on the PayPal website.
See Step 5 of “Step 3 – Adding Advanced Features to Your Add to Cart Button” on
page 279.
See “Sample HTML Code for Add to Cart Buttons with Discounts” on page 296.

Creating Advanced PayPal Shopping Cart Buttons on the
PayPal Website
Read the following topics to learn more about creating Add to Cart buttons on the PayPal
website:
 “The Basic Steps for Using the Tool With Add to Cart Buttons” on page 268
 “Saving Add to Cart Buttons in Your PayPal Account” on page 269


6

 “Tracking Inventory and Tracking Profit and Loss” on page 270
 “Adding Advanced Features to Add to Cart Buttons With HTML Variables” on page 270
 “Pricing Items in Multiple Currencies” on page 270
 “Working with View Cart Buttons” on page 271
 “Step 1 – Specifying Basic Features of Your Add to Cart Button” on page 271
 “Step 2 – Tracking Inventory With Your Add to Cart Button” on page 275
 “Step 3 – Adding Advanced Features to Your Add to Cart Button” on page 279
 “Copying and Pasting the Add to Cart Code” on page 281
 “Using the Button Creation Tool for a View Cart Button” on page 283

The Basic Steps for Using the Tool With Add to Cart Buttons
The button creation tool for Add to Cart buttons is a single webpage with three sections:
the details of your Add to Cart button. You can specify product options that buyers can
choose, and you can specify item-specific charges for shipping and tax.
information that PayPal uses to track inventory and to track your profit and loss on the
item.
advanced features of Add to Cart buttons. If you are familiar with HTML programming
and the advanced HTML variables supported by PayPal Payments Standard buttons, you
can enter them here.
bar to expand it.


6


Saving Add to Cart Buttons in Your PayPal Account
information about your button in your account instead of placing it in the code that you add to
your website.
NOT E : If you change product options, you must copy and paste the code newly generated
by PayPal to replace the code that you pasted previously.


6

Tracking Inventory and Tracking Profit and Loss
PayPal can track inventory and can track profit and loss for items that you sell with Add to
Cart buttons if you save them in your PayPal account. You can track inventory and profit and
loss for the item itself or by its product options.
If you track inventory, PayPal helps you avoid oversold situations. PayPal sends you an alert
by email when your inventory on hand falls to or below the alert level you specify. You have
the option to let oversold transactions go through or to warn buyers and prevent them from
buying more than your quantity on hand.
If you track profit and loss, PayPal helps you understand the profitability of your items. You
enter the cost of your item, including the price that you pay to acquire the item, as well as other
activity costs that you incur, such as warehousing, quality control, and administrative
overhead. PayPal then provides profit and loss reports based on the volume of sales.
Use the Step 2 section of the button creation tool to specify the information that PayPal uses to
track inventory and to track profit and loss. You can have a maximum of 1,000 saved buttons
in your PayPal account.

Adding Advanced Features to Add to Cart Buttons With HTML Variables
before the button code is generated.
For more information, see Step 5 of “Step 3 – Adding Advanced Features to Your Add to Cart

Pricing Items in Multiple Currencies
All items that buyers add to carts must be priced in the same currency. The first item that
buyers add to an empty cart determines the currency for all items in the shopping cart. The cart
uses the currency that you selected for your Add to Cart buttons when you created them.
After a buyer adds the first item to a shopping cart, the buyer cannot add items priced in other
currencies. To change the currency of a shopping cart, a buyer 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 buyers choose the currency
for viewing your catalog and display prices on your website only in the currency that the buyer
selected.


6

Working with View Cart Buttons
You need to create only one View Cart button, regardless of the number of Add to Cart buttons
that you create and add to your website. View Cart buttons on your website let buyers view
their shopping carts and the items in them. From there they can proceed to checkout.
button. Paste the same HTML button code onto your webpages for as many View Cart buttons
as you need.
The HTML button code that PayPal generates for View Cart buttons does not require
protection, because the code does not contain any payment information. You can use the
generated HTML code for any View Cart buttons that you create – the code is identical.

When you create Add to Cart buttons with tools on the PayPal website, PayPal generates
HTML code for website payment buttons. Then, you copy and paste the HTML code onto the
pages of your website.
payment links to add Add to Cart functionality to your email messages. If your web editing
tool or your service provider does not allow you to paste HTML code onto your webpages,
you may be able to paste the URL code for email payment links onto your webpages instead.

When you create Add to Cart code with tools on the PayPal website, PayPal lets your protect
the HTML button code that it generates by encrypting part of it. Protecting the HTML code of

For more information, see “Securing Your PayPal Payments Standard Buttons” on page 337.”

Step 1 – Specifying Basic Features of Your Add to Cart Button
To begin using the button creation tool for Add to Cart buttons:


6

button link.

– Item ID – (optional) Enter the inventory ID or tracking number of your item, if you
assign such IDs to your products.
If you want to set up your item so that PayPal tracks inventory levels, enter a value that
is unique among all the items that you sell and want PayPal to track. For more
information, see “Step 2 – Tracking Inventory With Your Add to Cart Button” on
page 275.
If you want to add product options with different prices for each option that buyers can
select, do not enter a price here. For more information, see Step 8 below.


6

– Currency – Select the currency in which you priced the item; the dropdown menu
If you want to customize the country and language of the button, make sure that you
select an appropriate currency here. For more information, see Step 9 below.
8. Customize your button with product options (optional).
Do any of the following:
menu of product options, with a separate price for each option.
Enter a name for the dropdown menu, such as “Color”. For each menu option, enter a
name, such as “Red”, “Blue”, or “Green”, and the price you want buyers to pay. Select
the currency for your prices from the dropdown menu. You can add a maximum of 10
priced options to the menu.
an option, clear the menu option name and price, and then click the Done button.
– Add dropdown menu without prices – Select this checkbox to add a dropdown menu
of product options, without separate prices.
Enter a name for the dropdown menu, such as “Size”. For each menu option, enter a
name, such as “Small”, “Medium”, or “Large”.
an option, clear the menu option name and click the Done button.
Click the Add another dropdown menu link to open a set of fields for another
dropdown menu of options without prices. You can add a maximum of 4 dropdown
menus, with a maximum of 10 options per menu.
– Add text field – Select this checkbox to add a text box in which buyers can enter option
information.
Enter a name for the text box, such as “Enter the text you want engraved”.
Click the Done button to preview the text field in the Buyer’s View pane.
Click the Edit link to change the name of the text field.
Click the Delete link to remove the text box from your button.
Click the Add another text box link to open a field for the name of another text box.
You can add a maximum of 2 boxes.
For more information, see“Offering Product Options With Add to Cart Buttons” on
page 266 .
Click the Customize appearance link and select one of the following:


6

If you change the country, ensure the currency that you selected in Step 7 above is
appropriate.
10.Add shipping charges and tax rates to your item (optional).
You can add shipping charges and tax rates for your item here. They override the tax and
shipping rates that PayPal calculates automatically based on rates that you specify in your
account profile.
– Shipping – Enter a specific amount to charge for shipping this item.
The currency for the amount is the same as the currency for the item. Enter zero (0.00)
for items that do not incur shipping charges. The amount you enter here overrides the
automatic calculation of shipping charges on the item.
NOT E :Before you can accept payments from Add to Cart buttons with specific
shipping costs entered here, you must enable the override of shipping methods
in the Shipping Calculations section of your account profile. You can create
your button successfully, but you cannot accept payments from your button
until you enable shipping cost overrides. Ensure that you enable shipping cost
overrides for all the shipping methods that you set up for your account. For
more information, see “Automatic Calculation of Shipping Charges (U.S.
Merchants Only)” on page 368 or “Automatic Calculation of Shipping Charges
(non-U.S. Merchants Only)” on page 384.
– Tax – Enter a percentage to calculate the tax on this item, regardless of quantity.
The currency for the calculated tax will be the same as the currency for the item. Enter
zero (0.000) for non-taxable items to override automatic sales tax calculation on the
item.
of your webpages.


6


PayPal account than by use of your merchant ID. Your email address is

Follow the instructions for “Copying and Pasting the Add to Cart Code” on page 281.
– Click the Step 2 bar if you want PayPal to track inventory levels for your item or if you
do not want to save your button in your PayPal account.
Follow the instructions for “Step 2 – Tracking Inventory With Your Add to Cart
Follow the instructions for “Step 3 – Adding Advanced Features to Your Add to Cart

Step 2 – Tracking Inventory With Your Add to Cart Button
details of your button in your PayPal account and to provide inventory tracking information
for your item.
For more information, see “Tracking Inventory and Tracking Profit and Loss” on page 270.
1. Select the Save button at PayPal checkbox to save your button in your PayPal account
and to enable your ability to track inventory for your item and to track profit and loss.


6

2. Select the Track inventory checkbox to enable entering information that PayPal uses to
track inventory for your item. Then, do one of the following:
options selected by buyers.
you specified during “Step 1 – Specifying Basic Features of Your Add to Cart Button”
on page 271. If you set up product options with prices, the button creation tool
automatically selects this radio button.
Under the Can customers buy an item when it is sold out? heading, do one of the
following:
– Yes – Select this radio button to let buyers checkout and authorize their payments, even
when inventory tracking shows that your item would become oversold. Buyers are not
after they complete their transactions.
– No – Select this radio button to prevent buyers from checking out and authorizing their
payments when inventory tracking shows that your item would become oversold. In the
text box, enter the URL of a page on your website where you want PayPal to send buyers
of out of stock items.
If there are some items in stock, but not enough to fulfill a buyer’s request, PayPal
proposes the amount currently available.


6

Buyers can click the Update button to accept the proposed quantity, adjust the quantity
to a lower number, or click the Remove link to proceed with checkout.
If there are no items in stock, PayPal lets buyers know that the item is completely sold
out.


6

PayPal drops sold-out items from the transaction if buyers proceed with checkout.
3. Select the Track profit and loss checkbox to enable entering information that PayPal uses
to track profit and loss for your item. You do not have to track inventory to track profit and
loss. If you track inventory, you can track profit and loss only in the same way – either by
item or by option.
that you specified during “Step 1 – Specifying Basic Features of Your Add to Cart
Button” on page 271. If you set up product options with prices, the button creation tool
automatically selects this radio button and you cannot chnage it.
Enter the cost to you of your item or for each product option. Include the price that you pay
to acquire the item, as well as other activity costs that you incur, such as warehousing,
quality control, and administrative overhead.


6

Follow the instructions for “Step 3 – Adding Advanced Features to Your Add to Cart
Follow the instructions for “Step 1 – Specifying Basic Features of Your Add to Cart

Step 3 – Adding Advanced Features to Your Add to Cart Button
1. Can your buyers add special instructions in a message to you (optional)?
– Yes – Select this radio button to let buyers add special instructions to you during
checkout. In the Name of message box text box, enter the text that you want displayed
for the text box in which buyers enter their special instructions; the default value is “Add
special instructions to the merchant”.


6

2. Do you need your buyers’ shipping addresses (optional)?
during checkout.
Select this option for items that do not require shipping, such as digital goods that buyers
download, or if the item is a service that does not require on-site delivery.
3. Take buyers to a specific webpage (URL) after checkout cancellation (optional)?
website where you want buyers to return if they cancel their checkouts before completing
their transactions.
4. Take buyers to a specific webpage (URL) after successful checkout (optional)?
website where you want buyers to return after they complete their checkouts successfully.
NOT E : If you have a special webpage for buyers who return to your website after checking
Network..


6

the checkbox, and then enter the variables in the text box below it.
For example, if you want to handle purchases as orders rather than as final sales, use the
HTML variable paymentaction with the value order. If you were to include the
variable in HTML code that you write manually, you would use the standard HTML
format:

<input type="hidden" name="paymentaction" value="order">
paymentaction=order
Do not enclose values in quotes, even if value contain spaces. PayPal surrounds the value
page 407.”
Follow the instructions for “Step 1 – Specifying Basic Features of Your Add to Cart
– Scroll to the top of the page and click the Step 2 bar if you want to adjust information
that PayPal uses to track inventory levels or if you do not want to save your button in
Follow the instructions for “Step 2 – Tracking Inventory With Your Add to Cart

Copying and Pasting the Add to Cart Code
code page. The page contains tabs with Add to Cart code for specific situations:
website.
paste HTML code.


6

Copying and Pasting the HTML Code for the Add to Cart Button
HTML code for your Add to Cart payment button.
If in “Step 2 – Tracking Inventory With Your Add to Cart Button” on page 275 you specified
that you do not want to save your button in your Paypal account, PayPal protects the generated
HTML button code with encryption. Protected HTML code helps secure your buttons against
malicious tampering and fraudulent payments.
You can the expose the code of your payment button by clicking the Remove code protection
edit the code later to change the item price. If you remove code protection, you must use other
methods that PayPal recommends to secure your payment button. Click the Protect code link
to restore the button protection that you removed.

To copy and paste the HTML code for your Add to Cart payment button:
code.
– or –

– or –
Copying and Pasting the Code for the Add to Cart Email Payment Link
code for your Add to Cart email payment link.


6

NOT E : PayPal cannot protect the URL 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 “Securing Your PayPal Payments Standard
To copy and paste the URL code for your Add to Cart email payment link:
– or –
– or –

Using the Button Creation Tool for a View Cart Button
button. Paste the same HTML button code onto your webpages for as many View Cart buttons
as you need.


6

The Step 2 – Track inventory, profit and loss (optional) section of the tool expands to
fill the page.
10.Click the Create a View Cart button link.
11. Click the Create button button.
The You’ve Created Your Button page opens.
12.Click the Select Code button on the Websites tab to select all of the generated HTML
code.
– or –

– or –


6
Sample HTML Code for Add to Cart Buttons

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:
 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.
 Your HTML editing tool might change some characters in the pasted code.

The sample HTML code in this section demonstrates various features of Add to Cart buttons:
 “Sample HTML Code for a Basic Add to Cart Button” on page 285
 “Sample HTML Code for Add to Cart Buttons With Product Options” on page 286
 “Sample HTML Code for Add to Cart Buttons that Open the Shopping Cart in the
Merchant Window” on page 290
 “Sample HTML Code for Add to Cart Buttons that Continue Shopping on the Current
Merchant Webpage” on page 293
 “Sample HTML Code for Add to Cart Buttons with Discounts” on page 296
To protect against malicious users tampering with the HTML code for your Add to Cart
buttons and submitting fraudulent payments, see “Securing Your PayPal Payments Standard


Sample HTML Code for a Basic Add to Cart Button
The sample HTML code below illustrates a basic Add to Cart button with these features:
 An item named “Birthday - Cake and Candle”.
 The buyer’s PayPal Shopping Cart opens in a separate browser window or tab.


6

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

<input type="hidden" name="business" value="kin@kinskards.com">


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

<input type="hidden" name="item_name"
value="Birthday - Cake and Candle">

src="https://www.paypal.com/en_US/i/btn/btn_cart_LG.gif"
</form>

Sample HTML Code for Add to Cart Buttons With Product Options
When you add production options to your Add to Cart buttons with HTML code that you write
yourself, you can have a maximum of 10 product options, each with their own sets of choices.
The options can be either dropdown menus or text boxes. Only one of the dropdown menu
options can have options with prices.
Read the following topics for sample code that illustrates various ways to add product options
to Add to Cart buttons.
 “Sample Code for an Add to Cart Button With Product Options” on page 286
 “Sample Code for an Add to Cart Button With Product Options With Prices” on page 287
 “Sample Code for an Add to Cart Button With Product Options as a Text Box” on page 289
For more information, see “Offering Product Options With Add to Cart Buttons” on page 266.
Sample Code for an Add to Cart Button With Product Options
The sample code below illustrates a basic Add to Cart button with a dropdown menu of
product options.

6

method="post">





<input type="hidden" name="on0" value="Color">Color scheme <br />
<select name="os0">
<option
value="Select a color scheme">-- Select a color scheme --
<option value="Blue">Blue</option>
<option value="Pink">Pink</option>
<option value="Yellow">Yellow</option>
</select> <br />

</form>
The sample code above produces the following result on your webpage.

Sample Code for an Add to Cart Button With Product Options With Prices
The sample code below illustrates a basic Add to Cart button with a dropdown menu of
product options that have separate prices for each option. Only one of the dropdown menus in
the set product options that your Add to Cart button offers can have prices.

6

Product options with prices specify the prices in two places:
 The dropdown menu displays the prices for each option – buyers see the prices they pay for
each option.
 A list of hidden HTML variables repeats the prices for each option – PayPal uses these
prices to charge buyers for the options they choose.
Dropdown menus with option prices use the following variables:
 currency_code – sets the currency for option prices
 item_index – identifies which dropdown menu of product option has prices
 option_select* and option_amount* – repeats the prices for each option
NOT E : You cannot specify item IDs for production options with prices to have PayPal track
inventory for your item. PayPal can track inventory by product option only for buttons
that you save in your PayPal account.

method="post">





<input type="hidden" name="on0" value="Color">Color scheme <br />
<select name="os0">
<option
value="Select a color scheme">
-- Select a color scheme --</option>
<option value="Blue">Blue</option>
<option value="Pink">Pink</option>
<option value="Yellow">Yellow</option>
</select> <br />


<input type="hidden" name="on1" value="Size">Size <br />
<select name="os1">
<option
value="Select a size">-- Select a size --</option>
<option value="2x4">2 x 4 - $3.95 USD</option>

6

</select> <br />

<input type="hidden" name="option_select0" value="2x4">

</form>

Sample Code for an Add to Cart Button With Product Options as a Text Box
The sample code below illustrates a basic Add to Cart button with a text box for entering
product options.

method="post">

6



</form>


Sample HTML Code for Add to Cart Buttons that Open the Shopping Cart in
the Merchant Window
By default, when buyers click Add to Cart buttons, the PayPal Shopping Cart opens in a
separate browser window.


6

Opening the PayPal Shopping Cart in the Same Browser Window

You can change the shopping experience for you buyers by opening the PayPal Shopping Cart
in the same browser window that displays your website.


6

Opening the PayPal Shopping Cart in the Same Browser Window

Use the target attribute in the form element to control whether the PayPal Shopping Cart
opens in a separate browser window or opens in the same browser window that displays your
website.


6

Values for “Target” That Open the PayPal Shopping Cart

Target expression Where the PayPal Shopping Cart Opens
target="paypal" The PayPal Shopping cart opens in a browser window
or browser tab that is separate from the browser window
or tab that displays the merchant website.
target="_self" The PayPal Shopping cart opens in the browser window
or browser tab that displays the merchant website.

The sample HTML code below for an Add to Cart button illustrates how to open the PayPal
Shopping Cart in the browser window that displays the merchant website.

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




</form>
See also “Sample HTML Code for a View Cart Button That Opens the Shopping Cart in the
Merchant Window” on page 301.

Sample HTML Code for Add to Cart Buttons that Continue Shopping on the
Current Merchant Webpage
When buyers click Add to Cart buttons, the PayPal Shopping Cart page opens. Buyers can see
the items in their carts, and they can begin checking out. In addition, buyers can click the
Continue Shopping button to return to your website and add more items to their carts.


6

If your website has many product pages, browsers may have difficulty returning buyers to the
same product pages that they leave when they click your Add to Cart buttons. Returning
buyers to a different page, such as the home page of your website, degrades the shopping
experience for buyers who want to add more items to their carts before checking out.
Use the shopping_url variable to specify which page PayPal returns buyers to when they
click the Continue Shopping button. You can set the value of the shopping_url variable if
you know the URL for the webpage where the button appears. In the code below, the merchant
wants to ensure that buyers who click an Add to Cart button for a birthday card return to the
product page for birthday cards when they want to continue shopping.

method="post">



value="Birthday Card - Cake and Candle">

6

<input type="hidden" name="shopping_url"
value="http://www.kinskards.com/birthday_cards.html">

</form>
With a more advanced coding technique, you can add JavaScript functions to your product
pages that get the current URL for the webpage from the browser and uses it as the value of
shopping_url. Use this coding technique to make your button code more portable when you
copy and paste buttons from webpage to webpage.

...
<script type="text/javascript">

</script>
...

method="post">



value="Birthday Card - Cake and Candle">

6


onclick=getContinueShoppingURL(this.form)
</form>
See also “Sample HTML Code for View Cart Buttons that Continue Shopping on the Current
Merchant Webpage” on page 302.

Sample HTML Code for Add to Cart Buttons with Discounts
The sample HTML code in this section demonstrates how to specify discounts:
 “Sample Code for Add to Cart Buttons with a Flat Discount Amount” on page 296
 “Sample Code for Add to Cart Buttons with Multiple Discount Amounts” on page 297
 “Sample Code for Add to Cart Buttons with a Discount Percentage” on page 298
 “Sample Code for Add to Cart Buttons with Multiple Discount Percentages” on page 298
 “Sample Code for Add to Cart Buttons with a Buy One, Get One Free Discount” on
page 299
Sample Code for Add to Cart Buttons with a Flat Discount Amount
 A $2.00 discount applies to the item.

method="post">





6




</form>

Sample Code for Add to Cart Buttons with Multiple Discount Amounts
 A $0.15 discount applies on the first item; $0.20 on the next 4 items.

method="post">

6

<input type="hidden" name="discount_amount2" value="0.20">

</form>

Sample Code for Add to Cart Buttons with a Discount Percentage
The sample HTML code below illustrates a basic Add to Cart button that applies a 10%
discount. This discount applies only to the first item regardless of the quantity purchased.

method="post">






</form>

Sample Code for Add to Cart Buttons with Multiple Discount Percentages
The sample HTML code below illustrates a basic Add to Cart button that charges the normal
price for the first item and applies a 10% discount for the next 9 items.

6

method="post">





</form>

Sample Code for Add to Cart Buttons with a Buy One, Get One Free Discount
The following HTML code uses the discount percentage variables to offer a “Buy one, get one
free” discount. To receive the discount, the buyer must purchase two of the item; the second
one is free (100% discount).
If the buyer purchases only one of the item, it is the full price. If the buyer purchases more than
two, the second one is free and any additional items are full price.

method="post">





6
Sample HTML Code for View Cart Buttons



</form>

The sample HTML code in this section demonstrates various features of View Cart buttons:
 “Sample HTML Code for a View Cart Button” on page 300
 “Sample HTML Code for a View Cart Button That Opens the Shopping Cart in the
Merchant Window” on page 301
 “Sample HTML Code for View Cart Buttons that Continue Shopping on the Current
Merchant Webpage” on page 302

Sample HTML Code for a View Cart Button
View Cart buttons contain no payment information, so you do not need to take on precautions
on securing them.
The value for the business variable must match a confirmed email address on file with your
PayPal account, and it must match the value that you used for the business variables on your
Add to Cart buttons.


6

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 of your website wherever you want buyers to click to view the
contents of their PayPal Shopping Carts and begin the checkout process.

Sample HTML Code for a View Cart Button That Opens the Shopping Cart
in the Merchant Window
By default, when buyers click View Cart buttons, the PayPal Shopping Cart opens in a
separate browser window.You can simplify the shopping experience for you buyers by
opening the PayPal Shopping Cart in the same browser window that displays the pages of your
website.
The sample HTML code below for a View Cart button illustrates how to open the PayPal
Shopping Cart in the same browser window as the merchant website.

6

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



</form>
For more information, see “Sample HTML Code for Add to Cart Buttons that Open the
Shopping Cart in the Merchant Window” on page 290.

Sample HTML Code for View Cart Buttons that Continue Shopping on the
Current Merchant Webpage
When buyers click View Cart buttons, the PayPal Shopping Cart page opens. Buyers can see
the items in their carts, and they can begin checking out. In addition, buyers can click the
Continue Shopping button to return to your website and add more items to their carts.

If your website has many product pages, browsers may have difficulty returning buyers to the
same product pages that they leave when they click your View Cart buttons. Returning buyers
to a different page, such as the home page of your website, degrades the shopping experience
for buyers who want to add more items to their carts before checking out.


6
Creating PayPal Shopping Cart Buttons with JavaScript Disabled

Use the shopping_url variable to let PayPal control which page buyers return to when they
click the Continue Shopping button.

method="post">



<!-- Continue shopping on the current webpage of the merchant site. --
>

</form>
For more information, see “Sample HTML Code for Add to Cart Buttons that Continue
Shopping on the Current Merchant Webpage” on page 293.

Creating PayPal Shopping Cart Buttons with JavaScript
Disabled
 “Getting Started with Add to Cart Buttons With JavaScript Disabled” on page 304
 “Getting Started with View Cart Buttons With JavaScript Disabled” on page 305
 “Creating Advanced Shopping Cart Buttons With JavaScript Disabled” on page 306
 “Limitations When Creating Shopping Cart Buttons With JavaScript Disabled” on
page 314

6

Getting Started with Add to Cart Buttons With JavaScript Disabled
4. Click the Add to Cart link.

The PayPal Shopping Cart page opens.
– Item name/service – Enter the name of your item or service.
– Price – Enter a fixed price of your item.
– 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.
The Add a shopping cart to your site page displays the generated code.
7. Click the “Add to Cart” button code text box to select all of the generated HTML code.



6


Getting Started with View Cart Buttons With JavaScript Disabled
4. Click the Add to Cart link.

– Item name/service – Enter a name.
– Price – Enter a price.
7. Click the “View Cart” button code text box to select all of the generated HTML code.


6



Creating Advanced Shopping Cart Buttons With JavaScript Disabled
The button creation tool for Add to Cart buttons and View Cart buttons on the PayPal website
requires JavaScript. If JavaScript is disabled in your browser, PayPal automatically offers you
an alternative button creation tool that does not require JavaScript.

IM PORT AN T : The button creation tool for PayPal Shopping Cart buttons with JavaScript
disabled 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 “Securing Your PayPal Payments Standard Buttons” on page 337.” View
Cart buttons do not require encryption.
Read the following topics to learn how to create Add to Cart and View Cart buttons with
JavaScript disabled.
 “The Pages in the Button Creation Tool for Add to Cart” on page 306
 “Page 1 – Specifying the Basic Features of the Add to Cart Button” on page 307
 “Page 2 – Adding More Details to the PayPal Shopping Cart Button” on page 309
 “Copying and Pasting PayPal Shopping Cart Code With JavaScript Disabled” on page 313
NOT E : The alternative tool lets you create Add to Cart buttons on the PayPal website, but it
does not allow you to save your buttons in your PayPal account.
The Pages in the Button Creation Tool for Add to Cart
The button creation tool for Add to Cart and View Cart buttons with JavaScript disabled has
three pages:
 PayPal Shopping Cart – the initial page to specify the required and most often used
optional features
 PayPal Shopping Cart – Page 2 – an optional page to specify additional, advanced
features, including the button image for View Cart buttons
 Add a shopping cart to your site – the final page that has the generated code for your
payment button


6

Page 1 – Specifying the Basic Features of the Add to Cart Button
To create HTML code for an Add to Cart button and a View Cart button using a tool on the
PayPal website with JavaScript disabled:
4. Under the Create button without JavaScript enabled heading, click the Add to Cart
link.

– 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 buyers at the time of payment, and it is displayed in
the transaction details that both merchants and buyers 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 270.
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.
– 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.


6

6. Choose a button style for your Add to Cart button.
hosted by PayPal.

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


6

– 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 363.
9. If you have additional details to specify for your button, such as option fields or a custom
payment page style that has your own logo and colors, click the Add More Options button
and follow the instructions for “Page 2 – Adding More Details to the PayPal Shopping Cart
– or –
If you entered all the details and options for your button, go to “Copying and Pasting
PayPal Shopping Cart Code With JavaScript Disabled” on page 313.
Page 2 – 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 with JavaScript disabled.
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.
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.
hosted by PayPal.


6

– or –
NOT 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 buyers to click to view their shopping cart and begin the checkout
process.
Use these settings to give buyers a visually seamless payment experience by customizing
– Primary Page Style (display only) – The payment pages that your buyers see are
– 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 buyers check out and pay from the PayPal Shopping Cart.
buyers see.
4. Customize your buyer’s experience.
Use these settings to give buyers a payment experience that is easy to navigate.


6

– 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 Payment Data Transfer on or off
for all your payment buttons.
want buyers redirected to if they cancel their payments at any point in the PayPal
Shopping Cart checkout experience. If you do not enter a URL, buyers see a PayPal
webpage instead of your webpage. Only this payment button uses the URL that you
enter.


6

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 your products do not require shipping,
such as digital goods that buyers download, or if your items are services that do not require
on-site delivery.
6. 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.
label to prompt buyers 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.
(Optional) In the Email Address dropdown menu, select the email address through which
email address of the person in your organization who handles order fulfillment or
accounting. All payments are deposited to your PayPal account balance, regardless of
which email addresses receive particular payments. Only confirmed email addresses can be
used to receive payments.


6

Add to Cart Button” on page 307, beginning with Step 5.
– or –
PayPal Shopping Cart Code With JavaScript Disabled” on page 313.
Copying and Pasting PayPal Shopping Cart Code With JavaScript Disabled
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:
 An Add to Cart button, which is used for the item you want to sell.
 A View Cart button, which takes buyers to a webpage hosted by PayPal. This page lists the
items that buyers added to their carts and allows them to check out and pay.

Copying and Pasting the HMTL Code for the Add to Cart Button With JavaScript
Disabled.
1. Click the “Add to Cart” button code text box to select all of the generated HTML code.
– or –
– or –

Copying and Pasting the HTML Code for the View Cart Button With JavaScript
Disabled. You need to create only one View Cart button, regardless of the number of Add to
Cart buttons that you create and add to your website. View Cart buttons on your website let
buyers view their shopping carts and the items in them. From there they can proceed to
checkout.
1. Scroll down the Add a shopping cart to your site page to the View Cart Button section.
2. Click the “View Cart” button code text box to select all of the generated HTML code.


6

– or –
4. Open the webpage where you want the button.
– or –

Creating More Add to Cart Buttons With JavaScript Disabled. 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 “Page 1 – Specifying the Basic
Features of the Add to Cart Button” on page 307, beginning with Step 5. The pages of the
button creation tool retain the options that you specified previously.

Limitations When Creating Shopping Cart Buttons With JavaScript
Disabled
The alternative tool that works with JavaScript disabled lets you create Add to Cart and
View Cart buttons on the PayPal website. However, the following features are not supported
by the alternative tool:
 Product options with separate pricing for Add to Cart buttons
 Language choices for buttons images
To use any of the above features when creating payment buttons on the PayPal website, enable
JavaScript in your browser.

website require thatyou enable JavaScript in your browser.
 “Enabling JavaScript in FireFox” on page 316


6

3. Select the Trusted sites icon in the box of Web content zones.



6

Enabling JavaScript in FireFox


7 Third-Party Shopping Carts – The
Cart Upload Command

Third-party shopping carts integrate PayPal Payments Standard on behalf of PayPal
merchants. Third-party carts use the Cart Upload command to pass the contents of shopping
carts to PayPal for checkout and payment processing.
NOT E : If you are not a shopping cart developer, you can add a PayPal Shopping Cart to your
site that is hosted by PayPal.
Read the following topics to learn more about third-party shopping carts:
 “The Checkout Experience With the Cart Upload Command” on page 317
 “Implementing the Cart Upload Command” on page 322
 “Implementing the Instant Update API With the Cart Upload Command” on page 326

The Checkout Experience With the Cart Upload Command
The PayPal checkout experience with the Cart Upload command begins on a merchant's
shopping cart page, when someone clicks the check-out button. Alternatively, it begins when
someone selects PayPal on the merchant’s payment methods page.
The example below shows how a third-party shopping cart works with PayPal and PayPal
Payments Standard. The example merchant has the following account profile settings:
 PayPal Account Optional is turned on – The buyer 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 356.
 Shipping Calculations have been set up – PayPal calculates the shipping charges
automatically and adds them to the order.
 Auto Return is turned off – Buyers must click a Return to Merchant button to redirect
their browsers to the merchant website after completing their payments with PayPal.

What Buyers See With Third-Party Shopping Carts
Steve is shopping for photos on the Designer Fotos website. He selects several photos for
purchase by clicking the Add to Cart button underneath each one.


Third-Party Shopping Carts – The Cart Upload Command
7

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 Steve clicks an Add to Cart button. In addition,
Steve can click the View Cart link at any time to review the items already in the cart and to
begin the PayPal PayPal Payments Standard checkout experience.

Third-Party Shopping Cart – View Shopping Cart


7

After selecting the items he wants to buy and specifying their quantities, Steve clicks the
Proceed to Checkout button.
Steve’s browser is redirected to the PayPal website. Buyers 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.

Third-Party Shopping Cart – PayPal Payment Log-in Page

NOT E : If your website gathers information about your buyer, you can define HTML code to
prepopulate (prefill) the corresponding billing information fields. The buyers will see
a collapsed version of the billing information section. For example, if you prefilled the
billing address, the address information displays on the page without the entry fields.
Each prefilled section of information is followed by a change link to let the buyers
modify the information, if necessary.
For more information about prepopulation, see “Filling Out FORMs Automatically
with HTML Variables” on page 411.
Steve does not have a PayPal account, so he clicks Don’t have a PayPal account? to enter his
payment and billing information on the payment login page. He clicks the Agree and
Continue button. A review page displays the details of his payment.


7

Third-Party Shopping Cart – PayPal Payment Review Page

Designer Fotos has set up Shipping Calculations in the account profile, so PayPal calculates
shipping costs automatically and adds them to the order.
Steve clicks the Pay Now button to complete the payment. In response, the browser takes
Steve to a payment confirmation page.


7

Third-PartyShopping Cart – PayPal Payment Confirmation Page

Steve can:
 Click Print Receipt to view and print a PayPal payment receipt.
 Click Go to PayPal account overview to view his account.
 Click Link your bank account to your PayPal account now to add a bank account to his
PayPal account.
Steve clicks Print Receipt to get a copy for his records.


7
Implementing the Cart Upload Command

Third-PartyShopping Cart – PayPal Payment Receipt

PayPal sends Steve an email notice of his payment to Designer Fotos.
PayPal also sends Designer Fotos an email notice of Steve’s payment.
NOT E : Designer Fotos (the user seller@designerfotos.com) can also see the payment in the
PayPal account history.

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 you can use the Cart
Upload command to integrate PayPal Payments Standard with your third-party cart.

Required Third-Party Shopping Cart Variables
Your HTML code requires at least the following hidden HTML variables. For a complete list
of variables, see HTML Variables for PayPal Payments Standard.


7

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 PayPal
Payments Standard:
 Pass the details of the individual items.
 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 buyers’ and 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 in Technical HTML Variables.
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 quantity_2; the third item with variables like
item_name_3, amount_3, and quantity_3; and so on.

IM PORT AN T : Sequentially increment the _x value by 1 to have PayPal recognize each item.
Skipping one or more numbers in the sequence causes PayPal to ignore
items.. For example, if you skip from item #1 to item #3 without defining an
item #2, PayPal ignores the third item.


7

The minimum required HTML for your post to PayPal looks similar to the following.

HTML for Passing Individual Item Detail to PayPal

<input type="hidden" name="business" value="seller@dezignerfotos.com">
<input type="hidden" name="item_name_1" value="Item Name 1">
<input type="hidden" name="amount_1" value="1.00">
<input type="hidden" name="shipping_1" value="1.75">
<input type="hidden" name="item_name_2" value="Item Name 2">
<input type="hidden" name="shipping_2" value="2.50">
<input type="submit" value="PayPal">
</form>

Setting Currency in the Cart
PayPal interprets all monetary variables (amount_x, shipping_x, shipping2_x,
handling_x, tax_x, and tax_cart) 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 you do not post a
currency_code variable, 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 Profile-Based Shipping Charges by Weight on Individual Items
Use the weight_x and weight_unit variables to specify item weights if the merchant uses
weight-based shipping rates. 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="weight_unit" value="kgs">
Use the quantity_x variable if the merchant uses quantity-based shipping rates. 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">
For information on how merchants set up wieght-based shipping rates, see the “Automatic
Calculation of Shipping Charges (U.S. Merchants Only)” on page 368.


7

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 Weight for the Entire Cart
Use the weight_cart and weight_unit variables to specify the total weight of the cart, if
the merchant uses weight-based shipping rates. The weight_cart variable overrides any per-
item weights specified with weight_x.

Setting Discounts for the Cart
Use the discount variables to specify discount amount or percentages.
 Use discount_amount_cart to charge a single discount amount for the entire cart.
 Use discount_amount_x to set a discount amount associated with item x.
 Use discount_rate_cart to charge a single discount percentage for the entire cart.
 Use discount_rate_x to set a discount percentage associated with item x.
information.
Default Tax and Discount Processing
Item-specific discounts apply before tax calculation for items in the third-party cart. Discounts
and tax apply to each item based on the discounts and tax rate specified. However, your buyer
sees only a total discount amount for the cart and one entry for any applicable sales tax.
Setting Consolidated Discount Amounts
Consolidated discounts apply to the entire cart. PayPal calculates the tax on the total of all
items after applying the consolidated discount value. Your buyer sees a total discount amount
for the cart and one entry for any applicable sales tax.
When you use consolidated discount amounts, you should specify a consolidated tax value in
tax_cart. If you do not specify a tax value and your profile specifies a tax rate, PayPal
applies your profile tax rate after applying the consolidated discount value.
PayPal ignores consolidated discount amounts if your third-party cart contains any item with
an individual tax amount or rate specified using tax_x or tax_rate_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.


7
Implementing the Instant Update API With the Cart Upload Command

NOT E : One drawback with passing aggregate cart information is that buyers do not see the
individual items in their order on the PayPal payment pages.
The following HTML is identical to the example in “Passing Individual Item Details to
PayPal” on page 323, except here the example aggregates the individual item amounts and
item names into a single amount and a single item.

HTML for Aggregate Cart Detail to PayPal

<input type="hidden" name="business" value="seller@designerfotos.com">
<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 Securing Your PayPal Payments Standard Buttons.

Implementing the Instant Update API With the Cart Upload
Command
The Instant Update API is a callback-style API that lets you update PayPal in real time with
shipping, insurance, and tax amounts when buyers change their shipping address on the
PayPal Review Your Payment page.
Read these topics to learn more about implementing the Instant Update API:
 “About the Instant Update API and the Cart Upload Command” on page 326
 “Best Practices for Implementing Instant Update” on page 329
 “Other Considerations for Implementing Instant Update” on page 330
 “Setting Up the Callback for Instant Update” on page 332
 “Responding to the Callback for Instant Update” on page 333

About the Instant Update API and the Cart Upload Command
The Instant Update API is a server call to your callback server that instantly updates PayPal
pages and enhances the Express Checkout experience on the Review your information page.


7

Here is how the Instant Update API works:
1. When a buyer logs in to PayPal, the PayPal server calls your callback server with the
buyer’s default shipping address, which is stored in the PayPal system.
2. Your callback server responds with the shipping options available for that address, along
with any insurance options and tax adjustments on the order.
3. PayPal displays this information on the Review your information page so buyers can
choose from the options.
How Instant Update Works With the Cart Upload Command
The figure below shows how the Instant Update callback works in the Cart Upload checkout
experience.

How Instant Update Works in the Cart Upload Checkout Experience

The checkout experience proceeds from left to right. Numbered events in the illustration above
are described below.
1. The checkout experience begins when a buyer clicks the checkout button on the Shopping
Cart page of your third-party cart.
In the HTML code of the checkout button, provide the URL where PayPal can call your
callback server, as well as fallback tax, shipping and insurance amounts. If you or your
carrier base shipping rates on shipment size, include the shippping dimension HTML
variables on individual items in the cart.
2. The buyer is redirected to PayPal to enter billing information or to log in to PayPal.


7

3. Before displaying the PayPal Review page, PayPal sends the buyer’s shipping address to
your callback server.
Every time the buyer changes the shipping address, PayPal calls your callback server.
4. Your callback server calculates tax, shipping, and insurance, based on the address in the
callback request.
Calculate the amounts in your own code, or request the shipping and insurance amounts
from your preferred carrier. If the address in the request is outside of the areas where you
ship, respond with NO_SHIPPING_OPTION_DETAILS set to 1.
5. PayPal updates the Review Your Payment page to show the options and rates that you sent
back in the callback response from your callback server.
6. The buyer makes final selections and clicks the Pay button.
7. PayPal displays a confirmation page, from which the buyer can click a link to print a
receipt.
Implementing Instant Update With the Cart Upload Command
You need a callback server to respond to Instant Update requests from PayPal. Also, you need
to add Instant Update HTML variables to your Cart Upload command to set up the checkout
for Instant Update.
1. Set up a secure server as your Instant Update callback server to accept Instant Update
requests from PayPal.
2. Develop you callback server to process Instant Update requests and respond with tax,
shipping, and insurance amounts.
3. Modify the HTML code of your Cart Upload commands by adding Instant Update HTML
variables:
– The URL of your callback server and the timeout duration
– Fallback tax, shipping options, and an insurance amount. You must specify at least 1
shipping option
– Dimensions for all individual items, if you base shipping rates on shipping dimensions
4. Eliminate your shipping options page.
5. Test your implementation of the callback and your fallback options.

The Review Your Payment Page After Implementing Instant Update

After you integrate the Instant Update API, you can display the shipping options, related
insurance options, and the tax amount. You control what to display, which is instantly updated
on the page.
The shipping options, related insurance options, and the tax amount appear on the page, as
follows:


7

PayPal Review Your Payment Page With Shipping Options, Insurance, and Tax

Best Practices for Implementing Instant Update
PayPal recommends its list of best practices as a checklist for completing your implementation
of the Instant Update API.
 Meet the pre-requisites – Provide individual item details instead of aggregate order
amounts to take advantage of the Instant Update API.
 Streamline the checkout experience – Eliminate the shipping options page in your
standard checkout experience.
 Use the default callback timeout – Use the recommended 3-second callback response
timeout.


7

 Follow PayPal-defined semantics and syntax – Adhere to well-formed variable names
and syntax rules in the callback response to PayPal. If errors occur in the response, PayPal
uses the fallback options.
 Ensure a consistent and good buyer experience – When fallback shipping options are
used, you should honor the rates to ensure a consistent and good buyer experience.
 Localize shipping options – Return localized shipping options, based on the buyer’s
country and locale, which PayPal sends in the callback request.

Other Considerations for Implementing Instant Update
When you implement the callback, you must consider callback response errors, .timeouts, and
shipping options.

Callback Response Errors
If there are any callback response errors, PayPal responds by displaying the fallback options
on the PayPal Review Your Payment page. To obtain the richer set of options available
through the callback, exercise care in the syntax and values you specify and test the callback
integration.
Minimum and Maximum Shipping Options
You can specify up to 10 shipping options for the fallback options in the HTML code for the
Cart Upload command and for the detailed options based on shipping address in the callback
response. You must specify at least 1 shipping option.
Callback Timeouts
If the callback does not return within the timeout period, PayPal displays the fallback shipping
options you specified in the HTML code for the Cart Upload command in the drop-down
menu on the PayPal Review Your Payment page.
The PayPal Review your information page in the figure below shows 2 shipping options
from which the buyer can choose if the callback times out. An amount of $1.00 is offered for
insurance:


7

Example PayPal Review Page When Callback Times Out

You Do Not Ship to the Buyer’s Shipping Address
If you do not ship to the buyer’s shipping address that PayPal sends in the callback request, set
NO_SHIPPING_OPTION_DETAILS to 1 in the callback response.
The sample code below illustrates the callback response when you do not ship to the buyer’s
address.
METHOD=CallbackResponse
NO_SHIPPING_OPTION_DETAILS =1
When your callback server sends the previous response, the Review your information page has
these features:
 A message at the top of the page indicates that your business does not ship to this location.
 The shipping and handling section and the insurance section are dimmed.
 The buyer can change the shipping address.


7

 A new callback request is sent if the buyer changes the shipping address.

Example PayPal Review Page When You Do Not Ship to the Buyer’s Address

Setting Up the Callback for Instant Update
To set up the callback, establish a connection with PayPal by providing the location where
PayPal calls your callback server, along with your shipping options.
There are two sides to setting up the Instant Update callback:
 Establishing your Instant Update callback server
 Passing Instant Update callback information to PayPal
Establishing Your Instant Update Callback Server
To start, you must build and operate a secure, reliable, and fast callback server that computes
shipping options, corresponding insurance options, and tax, based on your business rules. To
verify that callback requests originate from PayPal.
The HTTP protocol to specify in your callback URL depends on the integration environment
you are using:
 The callback URL must start with HTTPS for production integration.
 The callback URL must start with HTTP or HTTPS for PayPal Sandbox integration.
Passing Instant Update Callback Information to PayPal
You pass Instant Update callback information in the HTML code of the Cart Upload
command. The Instant Update HTML variables let you specify the URL of you callback server
and the fallback values for shipping, insurance, and tax amounts.
To set up the Cart Upload command for Instant Update during the checkout experience, use at
a minimum the following Instant Update HTML variables:
 callback_url – the URL of your callback server
 callback_timeout – always use the value 3, unless instructed otherwise by PayPal


7

 fallback_shipping_option_x – one or more sets of shipping option variables.
You must include 1 instance of this variable, with its index (x) set to 0. If you include just 1
instance, you must include fallback_shipping_option_is_default_x with its
index (x) set to 0 and its value set to 1.
The sample code below illustrates a basic setup for the Instant Update callback, which you
include in the HTML Form variables for the Cart Upload command.

...

<input type="hidden" name="callback_url" value="your_callback_server_URL">
<input type="hidden" name="callback_timeout" value="3">
<input type="hidden" name="callback_version" value="61">
<input type="hidden" name="fallback_shipping_option_name_0" value="Option
1">
<input type="hidden" name="fallback_shipping_option_amount_0" value="1">
<input type="hidden" name="fallback_shipping_option_is_default_0"
value="1">
<input type="hidden" name="fallback_shipping_option_name_1" value="Option
2">
<input type="hidden" name="fallback_shipping_option_amount_1" value="3">
<input type="hidden" name="fallback_shipping_option_is_default_1"
value="0">
<input type="hidden" name="fallback_insurance_option_offered" value="0">
...

Responding to the Callback for Instant Update
PayPal sends your callback server an Instant Update request whenever buyers enter billing
information or log in to PayPal to make payments. Your callback server calculates shipping
options and rates and sends them back to PayPal, in Name-Value pair (NVP) format.
PayPal sends Instant Update callback requests to the location that you specified with the
callback_url HTML variable. The fields in the callback request include:
 Individual item details that you included in the Cart Upload command.
 Shipping address of the buyer.
Using the information in the callback request, calculate the rates and options yourself or send
the information in an API call to your carrier to perform the calculations for you. Then send
the shipping options, insurance amounts, and taxes to PayPal in the callback response.
The Callback Request for Instant Update With the Cart Upload Comand
Callback requests specify the shipping addresses that buyers want to use when they are about
to complete a payment. Also, callback requests include individual item details for the
payments that buyers want to complete.

7

The sample code below illustrates an Instant Update callback request, with these features:
 2 individual item details, which can be used to calculate taxes
 Weight information with one line item, which can be used to calculate shipping charges
 A shipping address

METHOD=CallbackRequest
&CALLBACKVERSION=57.0
&CURRENCYCODE=USD
&LOCALECODE=en_US
&L_NAME0=10% Decaf Kona Blend Coffee
&L_NUMBER0=623083
&L_DESC0=Size: 8-oz
&L_AMT0=9.95
&L_QTY0=2
&L_NAME1=Coffee Filter bags
&L_NUMBER1=6230
&L_DESC1=Size: Two 24-piece boxes
&L_AMT1=39.70
&L_QTY1=2
&L_ITEMWEIGHTUNIT1=lbs
&L_ITEMWEIGHTVALUE1=0.5
&SHIPTOSTREET=1 Main St
&SHIPTOCITY=San Jose
&SHIPTOSTATE=CA
&SHIPTOCOUNTRY=US
&SHIPTOZIP=95131
&SHIPTOSTREET2

The Callback Response for Instant Update With the Cart Upload Command
Callback responses let you specify one or more shipping options, with unique shipping,
insurance, and tax amounts. Your callback server calculates the amounts based on shipping
addresses that buyers provide during the PayPal checkout experience.
The sample code below illustrates an Instant Update callback response, with these features:
 Shipping insurance, with a different amount for each shipping option
 3 shipping methods, with different shipping amounts
 Taxes, with different amounts for each shipping method
 The UPS Expedited shipping method is the default method


7

METHOD=CallbackResponse
&OFFERINSURANCEOPTION=true
&L_SHIPPINGOPTIONNAME0=UPS Air
&L_SHIPPINGOPTIONLABEL0=UPS Next Day Air Freight
&L_SHIPPINGOPTIONAMOUNT0=20.00
&L_TAXAMT0=2.20
&L_INSURANCEAMOUNT0=1.51
&L_SHIPPINGOPTIONISDEFAULT0=false
&L_SHIPPINGOPTIONNAME1=UPS Expedited
&L_SHIPPINGOPTIONLABEL1=UPS Express 2 Days
&L_TAXAMT1=2.00
&L_SHIPPINGOPTIONISDEFAULT1=true
&L_SHIPPINGOPTIONNAME2=UPS Ground
&L_SHIPPINGOPTIONLABEL2=UPS Ground 2 to 7 Days
&L_TAXAMT2=1.99
&L_SHIPPINGOPTIONISDEFAULT2=false
The sample code above produces the following result on the PayPal Review Your Payment
page:


7


8 Securing Your PayPal Payments
Standard Buttons

Unprotected and non-encrypted buttons that are not saved in your PayPal account are in plain
text in the source view of your webpages. The HTML button code for your payment buttons
can be viewed by anyone. A malicious third party could copy a page, change button HTML
variables such as price, and make fraudulent payments.

on securing PayPal Payment Standard buttons.
PayPal provides the following strategies for securing PayPal Payments Standard buttons. Use
one or more of the following security strategies to prevent and/or detect tampering with your
buttons:

Strategy for Securing Buttons See
Create protected buttons by using button creation tools “Creating Protected Payment Buttons on the PayPal
on the PayPal website. Website” on page 338
Save payments buttons that you create on the PayPal “Saving Payment Buttons in Your PayPal Account” on
website in your PayPal account. page 340
Manually check the item amounts in each payment “Reconciling Payments Manually Through Transaction
through the transaction history in your PayPal account History” on page 341
before shipping.
N O TE : You are required to reconcile your payments,
especially if you have unprotected or non-
encrypted buttons.
Automatically check the item amounts in each payment “Reconciling Payments Through Instant Payment
through Instant Payment Notification before shipping. Notification” on page 342
N O TE : You are required to reconcile your payments,
especially if you have unprotected or non-
encrypted buttons.
Edit your PayPal account profile to enable Encrypted “Protecting Payment Buttons by Using Encrypted
Website Payments, and use a script and open-source Website Payments” on page 342
libraries from OpenSSL to encrypt your buttons
dynamically when rendering your webpages.
You must be comfortable programming in scripts like
PHP and ASP to use Encrypted Website Payments.
Edit your PayPal account profile to block unprotected “Blocking Unprotected and Non-encrypted Website
and non-encrypted buttons to add extra security to your Payments” on page 348
protected, saved, and encrypted buttons.


Securing Your PayPal Payments Standard Buttons
8
Creating Protected Payment Buttons on the PayPal Website

Read the following topics to learn about creating protected payment buttons:
 “How Protected Payment Buttons Help Prevent Fraudulent Payments” on page 338
 “Using the Button Creation Tool to Create a Protected Payment Button” on page 338
 “Creating a Protected Payment Button with JavaScript Disabled” on page 339

How Protected Payment Buttons Help Prevent Fraudulent Payments
Protected payment buttons help secure your payments because the HTML button code that
PayPal generates and that you paste onto your webpages is encrypted. HTML button code that
is protected with encryption cannot be altered by malicious third parties to create fraudulent
payments.
You can protect the HTML button code that PayPal generates for any kind of payment button:
 Buy Now buttons
 Add to Cart buttons
 Buy Gift Certificate buttons
 Subscribe buttons
 Automatic Billing buttons
 Installment Plan buttons
 Donate buttons
NOT E : PayPal cannot protect HTML button code for Add to Cart buttons with JavaScript
disabled in your browser. In such cases, use an alternative strategy to secure your
buttons. See “Reconciling Payments Manually Through Transaction History” on
page 341, and “Reconciling Payments Through Instant Payment Notification” on
page 342.

Using the Button Creation Tool to Create a Protected Payment Button


8

5. In the Choose a button type menu, select the kind of button you want to create and
protect.
6. Enter details about your button.
7. Click the Step 2 bar to expand that section of the button creation tool.
NOT E : If you save your buttons at PayPal, you do not need to protect them. The code that
you add to your website for buttons that you save contain no information that can
be fraudulently altered by malicious third parites to submit fraudulent payments.
– Click the Create Button button to generate the protected HTML code.
– Click the Step 3 bar to customize your button with advanced features. Then click the
Create Button button.
10.Click the text box to select the generated, protected, HTML code, and then paste it onto the
pages of your website.

Update the profile settings on your PayPal account to block non-encrypted website payments,
as described in “Blocking Unprotected and Non-encrypted Website Payments” on page 348.

Creating a Protected Payment Button with JavaScript Disabled


8
Saving Payment Buttons in Your PayPal Account

5. Under the Create button without JavaScript enabled heading, click an appropriate link:
– Buy Now
– Add to Cart
– Donate
– Subscribe
– Gift Certificate
NOT E : You cannot create Automatic Billing or Installment Plan buttons with JavaScript
6. Enter details about your button, and then choose a button image.
7. In the Security Settings section, select the Yes radio button to protect your button with
encryption. This is the default setting.
– Click the Create Button Now button to generate the encrypted HTML code.
– Click the Add More Options button to enter optional details about your button, and then
click the Create Button Now button.
NOT E : Some settings on the Add More Options page require that you change Security
Settings to No. In such cases, you must use an alternative strategy to secure your
buttons. See “Reconciling Payments Manually Through Transaction History” on
page 341, and “Reconciling Payments Through Instant Payment Notification” on
page 342.
9. Click the HTML code for Websites text box to select all of the generated, protected,
HTML code, then paste it onto the pages of your website.

Update the profile settings on your PayPal account to block unprotected website payments, as
described in “Blocking Unprotected and Non-encrypted Website Payments” on page 348.

Saving Payment Buttons in Your PayPal Account
Saving your buttons in your PayPal account helps secure against fraudulent payments because
the HTML button code that PayPal generates and that you paste onto your webpages does not
contain pricing information. PayPal holds pricing information in your PayPal account, so
malicious third parties cannot alter it and submit fraudulent payments.
You can save any kind of payment button in your PayPal Premiere or Business account:
 Buy Now buttons


8
Reconciling Payments Manually Through Transaction History

 Donate buttons
NOT E : You cannot save payment buttons in your PayPal account with JavaScript disabled in
your browser or if you have a PayPal Personal account. In such cases, use an
alternative strategy to secure your buttons. See “Reconciling Payments Manually
Through Transaction History” on page 341, and “Reconciling Payments Through
Instant Payment Notification” on page 342.
5. In the Choose a button type menu, select the kind of button you want to create and
protect.
6. Enter the details for your button, using the Step 1, Step 2, and Step 3 sections of the tool.
Make sure you select the Save button at PayPal checkbox at the top of the Step 2 section.
It is selected by default.
7. Click the Create Button button to save the details of your payment button in your PayPal
account and to generate the small portion of code that you copy and paste onto your
webpages.

Update the profile settings on your PayPal account to block non-encrypted website payments,
as described in “Blocking Unprotected and Non-encrypted Website Payments” on page 348.

Reconciling Payments Manually Through Transaction History
If you process a small number of transactions, reconcile your payments manually through your
transaction history and the reporting tools provided by PayPal. You are required to reconcile
your payments, especially if you have unprotected or non-encrypted buttons.


8
Reconciling Payments Through Instant Payment Notification

To reconcile payments manually through your transaction history:
1. Log in to your PayPal Premier account or Business account.
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.
6. For each payment that was found, verify that the item amounts match the amounts that you
charge.
For detailed instructions on using the History subtab, see the Merchant Setup and Administration
Guide.

Reconciling Payments Through Instant Payment Notification
If you process a large number of transactions, reconcile your payments automatically through
Instant Payment Notification by verifying that the item amounts match the amounts that you
charge. You are required to reconcile your payments, especially if you have unprotected or
non-encrypted buttons.
With Instant Payment Notification, PayPal posts a message to your server when someone pays
you. You specify the URL through which you receive Instant Payment Notification messages
in your PayPal account. Instant Payment Notification messages are text files that include
payment details, such as the name of the payer and the amounts charged for each item.
To learn more about Instant Payment Notification, see the Instant Payment Notification Guide.

Protecting Payment Buttons by Using Encrypted Website
Payments
Read the following topics to learn about protecting payment buttons by using Encrypted
Website Payments:
 “How Encrypted Website Payments Helps Prevent Fraudulent Payments” on page 343
 “Public Key Encryption Used by Encrypted Website Payments” on page 343
 “Setting Up Certificates Before Using Encrypted Website Payments” on page 344
 “Using Encrypted Website Payments to Protect Your Payment Buttons” on page 346


8
Protecting Payment Buttons by Using Encrypted Website Payments

How Encrypted Website Payments Helps Prevent Fraudulent Payments
Using Encrypted Website Payments helps secure payment buttons that you generate or write
manually. Encrypted Website Payments protects the HTML button code that contains pricing
information by encrypting it. HTML button code that you protect by using Encrypted Website
Payments cannot be altered by malicious third parties to create fraudulent payments.
Encrypted Website Payments relies on standard public key encryption for protection. With
public and private keys, you can dynamically generate HTML code for payment buttons and
encrypt the payment details before displaying the buttons on your website. The below table
illustrates the sequence of actions that occur with payment buttons protected by using
Encrypted Website Payments.
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.
N O TE : Do this action only once, when you
first integrate PayPal Payments
Standard with your 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 Click the published PayPal Check the authenticity of the data by
for the payment button to the website. payment button. using the website’s public key, which
was previously uploaded to PayPal.
Decrypt the protected button code by
using the PayPal private key.
Redirect the payer’s browser to the
appropriate PayPal checkout
experience, as specified in the HTML
variables of the decrypted button
code.

Public Key Encryption Used by Encrypted Website Payments
Encrypted Website Payments uses public key encryption, or asymmetric cryptography, which
provides security and convenience by allowing senders and receivers of encrypted
communication to exchange public keys to unlock each others messages. The fundamental
aspects of public key encryption are:


8

 Public keys – Public keys are created by receivers and are given to senders before they
encrypt and send information. Public certificates comprise a public key and identity
information, such as the originator of the key and an expiry date. Public certificates can be
signed by certificate authorities, who guarantee that public certificates and their public
keys belong to the named entities.
You and PayPal exchange each others’ public certificates.
 Private keys – Private keys are created by receivers are kept to themselves.
You create a private key and keep it in your system. PayPal keeps its private key on its
system.
 The encryption process – Senders use their private keys and receivers’ public keys to
encrypt information before sending it. Receivers use their private keys and senders’ public
keys to decrypt information after receiving it. This encryption process also uses digital
signatures in public certificates to verify the sender of the information.
You use your private key and PayPal’s public key to encrypt your HTML button code.
PayPal uses its private key and your public key to decrypt button code after people click
your payment buttons.

Setting Up Certificates Before Using Encrypted Website Payments
Do the following before you use Encrypted Website Payments to protect your payment
buttons:
 Generate your private key.
 Generate your public certificate.
 Upload your public certificate to your PayPal account.
 Download the PayPal public certificate from the PayPal website.
PayPal uses only X.509 public certificates, not public keys. A public key can be used for
decryption but contains no information identifying who provided the key. A public certificate
includes a public key along with information about the key, such as when the key expires and
who owns the key. PayPal accepts public certificates in OpenSSL PEM format from any
established certificate authority, such as VeriSign.
You can generate your own private key and public certificate using open source software such
as OpenSSL (https://www.openssl.org), which is detailed in the following section.
Generating 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


8

Generating 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 Your PayPal Account
To upload your public certificate to your PayPal account:
1. Log in to your PayPal Business or Premier account.
3. In the Selling 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.
NOT E : The file you upload must be in PEM format.
6. Click the Add button.
After your public certificate uploads successfully, it appears in the Your Public
Certificates section of the Website Payment Certificates page.

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 software provided by PayPal.
Downloading the PayPal Public Certificate From the PayPal Website
To download the PayPal public certificate:
3. In the Seller Preferences column, click the Encrypted Payment Settings link.


8

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

IM PORT AN T : If you remove your public certificate, its associated certificate ID is no longer
valid for encrypting buttons, and any buttons that you generated or wrote
manually for your website that use the ID will not function correctly.
To remove one or more of your public certificates:
3. In the Seller Preferences column, click the Encrypted Payment Settings link.
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.

Using Encrypted Website Payments to Protect Your Payment Buttons
Encrypted Website Payments includes Java and Microsoft Windows software to protect the
payment buttons that you generate or write manually. Download the software from the
following location after logging in to PayPal: 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 PayPal Payments Standard variables and values for each encrypted
button that you want to generate. Each variable and value must be on a separate line, as in
the following example.
NOT E : The cert_id variable identifies the public certificate you uploaded to PayPal
website.

cert_id=Z24MFU6DSHBXQ


8

cmd=_xclick
business=sales@company.com
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 software using the appropriate syntax, as shown in the Command Line
Syntax for PayPal Encrypted Website Payments Software table.
Command Line Syntax for PayPal Encrypted Website Payments Software

Software Command Line
Java
java ButtonEncryption CertFile PKCS12File PPCertFile Password InputFile
OutputFile [Sandbox]

Microsoft
Windows PPEncrypt CertFile PrivKeyFile PPCertFile InputFile OutputFile [Sandbox]

where:
Arguments for Running Encrypted Website Payments Software

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 that lets you test payment buttons in the PayPal
Sandbox that you protected with Encrypted Website Payments

3. Copy the encrypted code to your website.


8
Blocking Unprotected and Non-encrypted Website Payments

Blocking Unprotected and Non-encrypted Website Payments
For extra security of your protected and encrypted buttons, update your PayPal account profile
to block unprotected and non-encrypted payments.
To block payments from unprotected and non-encrypted PayPal 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.
6. Scroll to the bottom of the page, and click the Save button.


9 Using Your PayPal Account
Profile

Use your PayPal account profile settings to control how PayPal Payments Standard works for
people who pay you and how it works to let you accept the payments that they make. Your
PayPal account profile contains the account information, financial information, and selling
preferences for your organization.
Many of the selling preferences that you can set in your account profile have equivalent
HTML variables to let you control the behavior of individual transactions. After you enable
settings in your account profile, you can include HTML variables with a transaction to take
advantage of those settings.
Read the following topics to learn about special profile tasks that interact with developer-
written code:
 Co-Branding the PayPal Checkout Pages
 Tailoring the Checkout Experience
 Automatic Calculation of Sales Tax
 Automatic Calculation of Shipping Charges (U.S. Merchants Only)
 Language Encoding Your Data
NOT E : For information about administrative tasks that you can perform from your PayPal
account, such as adding users, setting up custom page styles, and managing multiple
currency balances, see the Merchant Setup and Administration Guide.

Co-Branding the PayPal Checkout Pages
Custom payment pages let you tailor the PayPal checkout pages presented to payers to match
the style of your website. Custom payment pages work with all PayPal Payments Standard
buttons. You can add up to three custom page styles. You can add or edit custom payment
pages in your PayPal account profile or use HTML variables to set the custom pages for
individual transactions.
For step-by-step instructions on using your account profile to add or edit custom payment
pages, see the Merchant Setup and Administration Guide.
For more information about the HTML variables, see “HTML Variables for Displaying
PayPal Checkout Pages” on page 434.


Using Your PayPal Account Profile
9
Tailoring the Checkout Experience

Overriding Page Styles On Individual Payment Buttons
Your primary page style is applied to all your checkout pages unless you specify otherwise.
You can override this behavior by specifying custom page style variables in the HTML code
of your payment buttons.
To change the page style for a button that you created already, replace the value of the
page_style variable with the page style name you want to use. The next time that someone
clicks the payment button, the checkout pages appear in the new style.

Overriding Co-Branding Options on Individual Payment Buttons
You can specify variables in the HTML code of payment buttons to override specific co-
branding options. These customizing of payment page variables override page styles set in
your account profile or set with the page_style variable. The customizing of payment page
variables takes precedence in the following order:
Order of Page Style Variables

Custom Option Description
1 Customizing of Payment Page Variables on See “HTML Variables for Displaying PayPal
Individual Buttons Checkout Pages” on page 434.
2 Page Style Variable on Individual Buttons With the page_style variable, you can specify a
page style on individual payment buttons that
overrides any page styles set in your account profile.
3 Primary Page Style in Account Profile You can create and set the primary style in your
account profile.
4 Default PayPal Page Style in Account Profile The default page style used when an alternative is not
selected and designated as primary.

Read the following topics to learn how to tailor the checkout experience for people who pay
you with PayPal Payments Standard:
 “Auto Return” on page 351
 “Getting Contact Telephone Numbers” on page 354
 “PayPal Account Optional” on page 356


9

Auto Return
With Auto Return for PayPal Payments Standard, you can avoid making people click a button
to return to your website after they complete their payments with PayPal. Auto Return applies
to all PayPal Payments Standards payment buttons, including Buy Now, Shopping Cart,
Subscription, Gift Certificate, and Donate buttons.
Auto Return shortens the checkout flow and immediately brings your buyers back to your
website upon payment completion. To set up Auto Return, you need to turn it on and enter the
return URL that will be used to redirect your buyers back to your site.
NOT E : If you have turned on Auto Return and have chosen to turn on PayPal Account
Optional for new users, a new user will not be automatically directed back to your
website, but will be given the option to return.
The Return URL will be applied to all of your Auto Return payments unless otherwise
specified within the button or link for that Website Payment. You may specify a different
Return URL by changing it in your profile settings; otherwise, you may add or edit the HTML
(variable: return) associated with a button or link. In this case, the Return URL that is
associated with the button or link will override what was specified in the profile settings.
As specified in the PayPal User Agreement, you must provide verbiage on the page displayed
by the Return URL that
 Helps the buyer understand that the payment has been made and that the transaction has
been completed.
 Explains that payment transaction details will be emailed to the buyer.
What Payers See with Auto Return On
With Auto Return on, instead of having to click a button on the payment confirmation page,
payers see an alternative payment confirmation page for a few seconds before PayPal returns
them automatically to your website.


9

Momentary Payment Confirmation with Auto Return On

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


9

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.
NOT E : PayPal checks the Return URL that you enter. If the URL is not properly formatted
or cannot be validated, PayPal will not activate Auto Return.
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 URL 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">

NOT E : To receive transaction-related data from PayPal, you must turn Payment Data Transfer
on. To learn more, see the Payment Data Transfer page on Developer Central.


9

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.
NOT E : You can use Auto Return with Subscriptions, which is a separate feature from
Subscriptions Password Management. For more information, see “Recurring
Payments – Subscribe Buttons” on page 113.

Getting Contact Telephone Numbers
PayPal always collects contact telephone numbers from payers for each transaction that they
complete with PayPal. PayPal collects telephone numbers to help confirm the identity of the
payer and to contact the payer if necessary to complete the transaction.
Contact Telephone Number is a feature of PayPal Payments Standard that lets you obtain the
contact telephone numbers that PayPal collects from people who pay you. Contact Telephone
Number is off by default.
You can turn Contact Telephone Number on in one of two ways:
 On (Optional Field) – During checkout PayPal gives people the option of sharing their
contact telephones numbers with you.

Merchants Allow People to Share Their Telephone Numbers During Checkout

 On (Required Field) – During checkout PayPal informs people that their contact
telephone numbers will be shared with you because you require it.


9

Merchants Require People To Share Their Telephone Numbers During Checkout

When people share their contact telephone numbers with you, PayPal includes their shared
numbers in the transaction details section of payment authorization notices sent by email.
Also, PayPal displays the shared numbers in the Transaction Details page for transactions in
which contact telephone numbers were shared. These actions inform you and payers that
contact telephone numbers were shared as part of the transaction.

IM PORT AN T : In accordance with the PayPal user agreement, you may use contact telephone
numbers only to communicate with the payer about the related transaction.
You may not use them for unsolicited communication.
Turning Contact Telephone Number On
To turn Contact Telephone Number on:
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) – PayPal lets payers share their telephone numbers with you, as an
option.
– On (Required Field) – PayPal informs payers that their telephone numbers will be
shared with you because you require it.
– Off (Recommended) – PayPal does not share payers’ telephone numbers with you.
6. Scroll to the bottom of the page and click the Save button.


9

PayPal Account Optional
With PayPal Account Optional turned on, people can pay by credit card without signing up for
PayPal accounts. They are offered the chance to sign up for a PayPal account by using the
address and credit card from the completed transaction, but they are not required to. PayPal
Account Optional is turned on by default for new PayPal Premiere and Business accounts.
With PayPal Account Optional turned off, people without PayPal accounts must sign up for a
PayPal account. They can pay by credit card, but they must agree to sign up for a PayPal
account before completing their transactions and making their payments.
NOT E : Only Premiere or Business accounts have PayPal Account Optional in their account
profiles. With Personal accounts, the checkout experience is as if PayPal Account
Optional were turned off.
The Checkout Experience With Account Optional Turned Off
This topic demonstrates the PayPal checkout experience for PayPal Payments Standard when
PayPal Account Optional is turned off. The following diagram illustrates the steps.


9

Checkout Experience with PayPal Account Optional Turned Off


9

Read these topics to better understand the checkout experience when PayPal Account Optional
is turned off:
 “Begin – Buyers are Ready to Purchase on Your Website” on page 358
 “1 – Buyers Enter Their Billing Information or They Log In to PayPal” on page 358
 “End – PayPal Sends Email Notices to Buyers” on page 362

Begin – Buyers are Ready to Purchase on Your Website. The checkout experience with
PayPal Account Optional turned off begins when someone on your website is ready to
purchase.

Buyers Begin on Your Website When They are Ready to Make a Purchase

In this example, Bob begins on the Designer Fotos website and decides to buy a photo of an
orchid. He clicks the Buy Now button to pay.

1 – Buyers Enter Their Billing Information or They Log In to PayPal. PayPal displays a
billing information/log-in page, which lets buyers enter their billing information and
passwords for new PayPal accounts or log in to PayPal.


9

Buyers Enter Their Billing Information or Log In to PayPal

In this case, Bob does not have a PayPal account. He enters his billing information and a
password for his new PayPal account. Then, he clicks the Agree and Create Account button.


9

2 – Buyers Confirm Their Transaction Details Before Paying. PayPal displays a
transaction confirmation page to let buyers confirm the details before they complete their
transactions and authorize their payments.
If the buyers signed up for PayPal accounts to pay for their orders, Paypal displays an account
confirmation message at the top of the page. The confirmation message lets buyers know that
they have successfully created their PayPal accounts.


In this case, Bob sees a message confirming his new PayPal account. He reviews the
transaction details and clicks the Pay Now button to complete the transaction and make his
payment.

3 – Buyers View and Print Their PayPal Payment Confirmations. PayPal displays a
payment confirmation page after buyers pay to let them know that they have completed their
transactions and authorized their payments successfully.


9

Buyers View Their Payment Confirmation

 View the PayPal transaction ID to reconcile their payments.
 Click Go to PayPal account overview to see their account information.
 Click the Print Receipt link to print receipts for their records.


9


In this case, Bob prints the PayPal payment receipt for his records.

End – PayPal Sends Email Notices to Buyers. PayPal sends buyers account signup
notices by email to confirm the accoutnst they created.
PayPal also sends buyers a payment authorization notice by email to confirm the transaction
that they made with the merchant.
Turning PayPal Account Optional Off
PayPal Account Optional is available on PayPal Premiere and Business accounts only. It is
turned 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.


9
Automatic Calculation of Sales Tax

4. Scroll down to the PayPal Account Optional section of the page.

5. Select the Off radio button to turn PayPal Account optional off.

You can have PayPal calculate sales tax (also called value-added tax or VAT) automatically.
PayPal calculates sales taxes based on rates that you specify in your account profile. You can
set up tax rates as follows:
 Domestic (U.S.-only) tax rates by state or zip code
 Canadian tax rates by province
 International sales tax rates by country or jurisdiction
Read these topics to learn more about automatic calculation of sales tax:
 “Displaying the Sales Tax that PayPal Calculates During Checkout” on page 363
 “Accessing Your Sales Tax Rates in Your Account Profile” on page 364
 “Setting Up Domestic Sales Tax Rates” on page 365
 “Setting Up International Sales Tax Rates” on page 367
 “Resolving Overlapping Sales Tax Rates” on page 367
 “Editing or Deleting Sales Tax Rates” on page 368
 “Overriding Sales Tax Calculations on Individual Transactions” on page 368

Displaying the Sales Tax that PayPal Calculates During Checkout
After you set up sales tax rates in your account profile, PayPal calculates the tax for purchase
transactions automatically. Buyers see the tax as a separate item during checkout, based on the
shipping addresses that they provide.


9

Buyers See Sales Taxes Before They Pay

If buyers change their shipping addresses, PayPal calculates the tax again and displays the new
amount.

Accessing Your Sales Tax Rates in Your Account Profile
To view or modify your sales tax rates in your account profile:
2. Click the Profile subtab of the My Account tab.
3. In the Selling Preferences column, click the Sales Tax link.


9

Sales Tax Rates in Your Account Profile

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.


9

5. Click the Continue button to add the new rate and return to the Sales Tax page (“Sales Tax
Rates in Your Account Profile” on page 365).
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.

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.


9

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.
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:
 For Canada, sales tax rates can be for one or more provinces.
 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 (“Sales Tax
Rates in Your Account Profile” on page 365).
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 “Three
Domestic Sales Tax Rates” on page 368, all three of the domestic sales tax rates apply to a
buyer in zip code 94044.


9
Automatic Calculation of Shipping Charges (U.S. Merchants Only)

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

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.

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 324 and “Setting the Tax for the Entire Cart” on page 325.

Automatic Calculation of Shipping Charges (U.S. Merchants
Only)
You can have PayPal calculate shipping charges automatically. PayPal calculates shipping
charges based on rates that you specify in your account profile. You can set up shipping rates
as follows:
 Domestic (U.S.-only) shipping rates for regions defined by state or zip code
 International shipping rates for regions define by country or jurisdiction
Within shipping regions, you can specify rates for different shipping methods, such as
standard and express delivery.
Read these topics to learn more about automatic calculation of sales tax:


9

 “Displaying the Sales Tax that PayPal Calculates During Checkout” on page 363
 “Shipping Regions” on page 372
 “Shipping Methods” on page 373
 “Shipping Rate Bases” on page 373
 “Shipping Rates and Currencies” on page 374
 “Adding Shipping Rates for the First Time” on page 374
 “Adding Shipping Methods by Using a Wizard” on page 375
 “Viewing, Editing, and Adding Shipping Rates” on page 378
 “Deleting Shipping Methods” on page 381
 “Examples of Rate Bases and Shipping Calculations” on page 381
 “Overriding Shipping Calculations on Individual Transactions” on page 383
 “Editing the Configuration Settings of an Existing Shipping Method” on page 379

Displaying the Shipping Charges that PayPal Calculates During Checkout
After you set up shipping rates in your account profile, PayPal calculates the shipping charges
for purchase transactions automatically. PayPal prompts buyers to enter their shipping
destinations on the first checkout page.

PayPal Prompts Buyers for Shipping Destinations


9

Buyers click the calculate total order amount link to enter information about their shipping
destinations.

Buyers Enter Shipping Destinations to Calculate Shipping Charges

Buyers enter information about their shipping destinations, and then they click the Update
button.


9

Buyers See Shipping Charges Before They Pay

PayPal calculates the shipping charges using the least expensive shipping method that you set
up for the destination.


9

Buyers Select Their Preferred Shipping Methods

PayPal lets buyers select their preferred shipping methods after they enter their billing
information or log in to PayPal. If buyers change their shipping addresses or select a different
shipping method, PayPal calculates the shipping charges again and displays the new amount.

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
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:
 You ship only domestically or both domestically and internationally
 You want one set of rates for all U.S. domestic shipments, or you want rates for different
domestic regions, such as western and eastern states
 You want one set of rates for all international shipments, or you want rates for different
international regions, such as Europe and Asia


9

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,” “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:
 Total order amount
 Total order weight
 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
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 381

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.


9

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

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:


9

3. In the Selling Preferences column, click the Set Up Shipping Calculations link.
This Shipping Calculations page appears, as shown below.

Shipping Calculations Setup Page

From the Shipping Calculations setup page, you can start a domestic or an international
shipping wizard.

Adding Shipping Methods by 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:
 Click the Start button from the Shipping Calculations setup page, as shown in “Shipping
Calculations Setup Page” on page 375.
 Click the Add Another Shipping Method link from the Shipping Calculations review
page, as shown in Shipping Calculations Review Page (U.S. Merchants Only).
The steps in domestic and international shipping wizards are the same.


9

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.


9

2. Configuring the Shipping Methods Within the Region of a Shipping Wizard. Select a name
and delivery time frame, specify 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.
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 of
your shipping regions. In addition, you select the currency in which you want to price the
shipping rates within the region.
NOT E : You can 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 374.
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 Use the shipping fee... checkbox to permit individual transactions to override automatic
calculation of shipping charges. For more information, see “Overriding Sales Tax Calculations
on Individual Transactions” on page 368.
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.


9

Viewing, Editing, and Adding Shipping Rates
After you set up some shipping regions, methods, and rates, PayPal tailors the page sequence
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:
3. In the Selling Preferences column, click the Shipping Calculations link.
The Shipping Calculations review page appears, as shown below.

Shipping Calculations Review Page (U.S. Merchants Only)


9

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.
– Editing the Configuration Settings of an Existing Shipping Method. Select the checkbox
next to the shipping method and click the Edit button.
– Deleting Shipping Methods. Select the checkboxes next to the shipping methods and
click the Delete button.
– Adding Shipping Methods by 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:
The Shipping Calculations review page appears.
4. Click the View button.
The View Domestic Shipping Method page or the View International Shipping Method
page appears.
5. 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:


9

4. Click the Edit button.
The Edit Domestic Shipping Method page or the Edit International Shipping Method
page appears.
5. Change any of the following settings:
Shipping Method Settings

Setting Action
Status Select whether the shipping method is actively used to calculate shipping
charges. Allowable values:
 Active – the shipping method is available for buyers to choose
 Inactive – the shipping method is hidden from buyers

Currency and Region Displays the domestic regions or foreign countries currently selected for the
shipping region. To select different regions or countries, click the Change link.
Use the shipping fee in the Select whether the shipping rates can be overridden by individual transactions if
transaction instead of my the information is passed to PayPal with HTML variables in the transaction.
claculator’s settings Allowable values:
 Yes
 No

I MP O R TAN T : Changing the 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.
Select Delivery Time (Optional) From the dropdown menu, select a delivery time.
Based On Select the rate basis for the shipping method. Allowable values:
 By Amount – based on the total amount of the order
 By Weight – based on the total weight of items in the order
 By Quantity – based on total quantity of items in the order

For more information, see “Examples of Rate Bases and Shipping Calculations”
on page 381
Shipping Rates Reconfigure the rows in the rate table to change the shipping rates that PayPal
uses to calculate shipping charges when buyers select the shipping method. You
can set shipping rates as fixed amounts or as percentages.
N OT E : Changes that you make to active shipping methods become effective
after a momentary delay.

6. Click the Save Changes button.


9

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

IM PORT AN T : After you delete a shipping method, it cannot be recovered for use in future
shipping calculations.
To delete one or more shipping methods:
4. Click the Delete button.
5. 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:
 “Calculating Shipping Charges Based on Amount of Purchase” on page 381
 “Calculating Shipping Charges Based on Weight of Shipment” on page 382
 “Calculating Shipping Charges Based on Quantity of Items Shipped” on page 382
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.


9

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.

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%).
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.

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.


9

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:
 Enable overrides of your shipping rates; overrides are enabled for new shipping methods
by default.
 Set special shipping rates for individual items with special HTML variables of Buy Now,
Donation, Add to Cart, and View Cart buttons.
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:
 Editing any shipping method and changing the Override shipping methods per
transaction.setting.
 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


9
Automatic Calculation of Shipping Charges (non-U.S. Merchants Only)

IM PORT AN 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.
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:
3. In the Selling Preferences column, click the Postage Calculations link.
The Postage Calculations page appears, as shown below.


9

Shipping Calculations Page (non-U.S. Merchants Only)


9

Examples of Cost Methods and Shipping Calculations
The following examples demonstrate how different cost methods are applied when calculating
shipping charges.
Calculating Shipping Charges with the Flat Amount Cost Method
When you choose Flat Amount as the cost method for shipping rates, PayPal expresses the
costs for each price range as fixed amounts.

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.
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:
 Enable overrides of your shipping rates for individual transactions; overrides are disabled
by default.
 Set the special shipping rates for individual items or entire transactions with special HTML
variables of Buy Now, Add to Cart, and View Cart buttons.
For more information, see “HTML Variables for PayPal Payments Standard” on page 417.


9
Language Encoding Your Data

Enabling the Override of Shipping Rates on Individual Transactions
To enable overrides of shipping rates:
3. In the Selling Preferences column, click the Postage Calculations link.
The Postage Calculations page appears
4. Click the checkbox labeled Click here to allow transaction-based postage values to
override the profile postage settings listed above (if profile settings are enabled).
5. 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
exchange data with 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. 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.

IM PORT AN T : If your language encoding preferences do not match the language and
encoding that your website uses, your data cannot be exchanged with PayPal.
In some cases, particularly in Asian countries or with certain operating
systems, the default language and/or encoding chosen by PayPal may not
match those used by your website.
Use your PayPal account profile to set:
 Your website’s language – Set the character set used on your website, such as Western
European, Japanese, or Russian.
 Encoding – Set the character encoding used on your website, such as UTF-8, EUC-JP, or
KOI8-R.
NOT E : For a complete list of supported character encodings, see ““Setting the Character
Set – charset” on page 409.
For step-by-step instructions on changing these settings in your account profile, see the
Merchant Setup and Administration Guide.


9


10 Using Authorization & Capture

PayPal Authorization & Capture is a settlement solution that provides increased flexibility in
obtaining payments from 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 (such as taxes, shipping, or item
availability) that occur after the buyers place the initial order. 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:
 Capture or void authorizations on the PayPal website (www.paypal.com).
 Use the Authorization & Capture API in programming code.

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


Using Authorization & Capture
10
Basic Authorization & Capture Scenarios

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, funds may 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 the PayPal Products
Supporting Authorization & Capture table.
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.
NOT E : You must 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.
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.

Capturing A Single Authorization
If you have authorized a transaction, you need to capture the funds in order to receive
payment.


10

NOT E : PayPal recommends that you capture payments within three days of the original
authorization.
To initiate a capture:
The History page appears.
3. Find the payment transaction you want to capture and click the Capture button associated
with the transaction.
The Capture Funds page appears.

4. Review the information, enter the amount to capture, and then click the Capture Funds
button.
The funds are transferred to your account.


10

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:
3. Click the Capture button associated with any transaction.
The Capture Funds page appears.

4. Click the Batch Capture link that is located in the introductory paragraph.

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


10

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

7. 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.
NOT E : Voiding an authorization cancels the entire open amount.
You can initiate a void in the following cases:
 The authorization is pending
 The authorized amount was captured at less than 100%
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.
NOT 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.


10

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.

Capture From 4 - 29 Days
1. Your buyer orders a DVD player from your website.
paymentaction=authorization.
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.

Transaction Details – Reauthorization, Final Capture


10

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

Transaction Details – Partial Capture, Reauthorization, Refund

Lower Capture Amount
1. Your buyer orders a laser printer and a USB cable from your website.


10

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.
Your Transaction Details shows the following:

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.


10

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.

Transaction Details – Expired Authorization

Void
1. Your buyer orders a stereo system from your website.


10

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.

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.
NOT E : The reauthorization scenario is similar to the Reattempted Capture scenario, as
detailed above.


10
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 3-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 3-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 3-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.

IM PORT AN T : 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.


10


11 Issuing Refunds

When you issue a refund, PayPal sends the gross amount of the refund 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” on page 401
 “Refunding After 60 Days” on page 403

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. If you refund a pending eCheck payment, PayPal does not charge
transaction fees because the pending payment is canceled.
To issue a refund within 60 days:
3. Find the payment transaction you want to refund.
4. Click the Details link for the transaction.
The Transaction Details page appears.
5. Scroll down to the Refunds section and click the Issue Refund link.

The Issue Refund Page appears.
6. Enter the refund amount and click the Continue button.


Issuing Refunds
11
Refunding Within 60 Days of Payment

The Review and process refund page appears.
7. Confirm the refund amount and click the Issue Refund button.


Issuing Refunds
11
Refunding After 60 Days

When you issue a refund after 60 days, PayPal does not credit your original transaction fee for
receiving the payment to your account.
To issue a refund after 60 days:
2. Click the Send Money tab.
The Send Money page appears.
3. Enter the email address for the buyer who will receive the refund, the amount and currency
type of the refund, and the type of transaction.
4. Click the Continue button.
The Send Money page displays confirmation information.
5. Review the information and enter an optional message to your buyer. Click the Send
Money button to complete the refund.


Issuing Refunds
11


12 Testing Payment Buttons in the
PayPal Sandbox

The PayPal Sandbox can be used to test the following functionality:
 Buy Now buttons – Test single-item payments.
For more information, see Chapter 1, “Single-Item Payments – Buy Now Buttons.”
 Subscribe buttons – Test recurring payments.
For more information, see Chapter 3, “Recurring Payments – Subscribe Buttons.”
 Donate buttons – Test contribution payments.
For more information, see Chapter 2, “Contribution Payments – Donate Buttons.”
 Shopping Cart buttons – Test multiple-item payments in a single purchase transaction.
For more information, see Chapter 6, “The PayPal Shopping Cart – Add to Cart and View
Cart Buttons.”
 Refunds – Test the refunding of money paid by PayPal members.
For more information, see Chapter 11, “Issuing Refunds.”
 Payment Data Transfer – Test your identity token, return URL, and Payment Data
Transfer settings.
To learn more, see the Payment Data Transfer page on Developer Central.
 Instant Payment Notification – Test Instant Payment Notification messages for payments
and reversals.
Instant Payment Notification messages in the Sandbox environment include the special
ipn_test variable, set to the value 1. This variable lets your code differentiate between
Instant Payment Notification messages in the Sandbox and Instant Payment Notification
messages from the live PayPal website. Use the ipn_test variable to develop scripts that
work in both situations.

IM PORT AN T : Instant Payment Notification messages that come from the Sandbox cannot
be verified against the live PayPal website, and Instant Payment
Notification messages that come from the live PayPal website cannot be
verified against the Sandbox.
For more information about implementing Instant Payment Notification, see the Instant
Payment Notification Guide.
 Simulated transactions – Test scenarios, such as successful and failed eChecks.
To test in the Sandbox, create a Developer Central account. Then create multiple PayPal
test accounts for buyers and merchants so that you can simulate different scenarios.

IM PORT AN T : The Sandbox does not process real money.
For more information, see the Sandbox User Guide.


Testing Payment Buttons in the PayPal Sandbox
12


13 HTML Form Basics for PayPal
Payments Standard

This chapter describes in technical terms the basic functionality of PayPal Payments Standard
and its use of HTML Forms. Use the information in this chapter as a guide to writing the
HTML code yourself for PayPal 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 PayPal 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 Donate, the Subscribe, or the PayPal Shopping Cart checkout
experience and various other PayPal features.

Form Attributes – ACTION and METHOD
The FORM tag includes two required attributes, action and method, which always look like
this:

<FORM action="https://www.paypal.com/cgi-bin/webscr" method="post">

IM PORT AN T : Do not change these values. These attributes are required for all payment
buttons and the Cart Upload command.

Hidden Input Variables
HTML input variables in a PayPal PayPal 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
PayPal Payments Standard,” and the allowedValue is any of the values detailed for those
variables.


HTML Form Basics for PayPal Payments Standard
13
Specifying the Kind of Payment Button – cmd

Sp e c i f y i n g t h e K i n d o f P a y m e n t B u t t o n – c m d
The cmd variable is always required in a FORM. Its value determines which PayPal Payments
Standard checkout experience you are using to obtain payment.
Allowable Values for the cmd HTML Variable

Value of cmd Description
_xclick The button that the person clicked was a Buy Now button.
_cart For shopping cart purchases. The following variables specify the kind
of shopping cart button that the person clicked:
 add – Add to Cart buttons for the PayPal Shopping Cart
 display – View Cart buttons for the PayPal Shopping Cart
 upload – The Cart Upload command for third-party carts

_oe-gift-certificate The button that the person clicked was a Buy Gift Certificate button.
_xclick-subscriptions The button that the person clicked was a Subscribe button.
_xclick-auto-billing The button that the person clicked was an Automatic Billing button.
_xclick-payment-plan The button that the person clicked was an Installment Plan button.
_donations The button that the person clicked was a Donate button.
_s-xclick The button that the person clicked was protected from tampering by
using encryption, or the button was saved in the merchant’s PayPal
account. PayPal determines which kind of button was clicked by
decoding the encrypted code or by looking up the saved button in the
merchant’s account.

The input tag looks like one of the following:
 Buy Now buttons – <INPUT TYPE="hidden" name="cmd" value="_xclick">
 Shopping cart buttons – <INPUT TYPE="hidden" name="cmd" value="_cart">
 Buy Gift Certificate buttons – <INPUT TYPE="hidden" name="cmd" value="_oe-
gift-certificate">
 Subscribe buttons – <INPUT TYPE="hidden" name="cmd" value="_xclick-
subscriptions">
 Automatic Billing buttons – <INPUT TYPE="hidden" name="cmd"
value="_xclick-auto-billing">
 Installment Plan buttons – <INPUT TYPE="hidden" name="cmd"
value="_xclick-payment-plan">
 Donate buttons – <INPUT TYPE="hidden" name="cmd" value="_donations">

IM PORT AN T : These INPUT tags are required exactly as shown above. Do not alter them.


13
Variations on Basic Variables

This section highlights a few ways to use PayPal Payments Standard FORM variables.
The HTML variables interact in various ways. Sometimes their effect is cumulative,
sometimes they can cancel each other out, and 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 PayPal Payments Standard” and Appendix B, “Address
Handling (U.S. Merchants Only).”

Record Keeping with Passthrough Variables
Some variables are exclusively for your own use, such as order management. PayPal returns
the values that you send through Instant Payment Notification exactly as you sent them. For
this reason, they are called passthrough variables. Their values are not recorded or used by
PayPal.
The following are passthrough variables:
 custom
 item_number or item_number_x
 invoice

Setting the Character Set – charset
Use the charset HTML variable to specify the character set and character encoding for the
billing information/log-in page on the PayPal website. In addition, this variable sets the same
values for information that you send to PayPal in your HTML button code.
For example, the following INPUT tag sets the encoding to UTF-8:
<INPUT TYPE="hidden" name="charset" value="utf-8">


13

Character Sets and Encoding Schemes Supported by PayPal

Big5 ISO-2022-JP ISO-8859-8 UTF-16BE US-ASCII windows-1258
(Traditional ISO-2022-KR ISO-8859-9 UTF-16LE windows-1250 windows-874
Chinese in ISO-8859-1 ISO-8859-13 UTF16_Platfor windows-1251 (Thai)
Taiwan) (Western mEndian windows-949
ISO-8859-15 windows-1252
EUC-JP European UTF16_Opposit (Korean)
KOI8-R windows-1253
EUC-KR Languages) (Cyrillic) eEndian x-mac-greek
windows-1254
EUC-TW ISO-8859-2 Shift_JIS UTF-32 x-mac-turkish
windows-1255
gb2312 ISO-8859-3 UTF-7 UTF-32BE x-mac-
windows-1256
(Simplified ISO-8859-4 UTF-32LE centraleurroman
UTF-8 windows-1257
Chinese) ISO-8859-5 x-mac-cyrillic
UTF-16 UTF32_Platfor
gbk ISO-8859-6 mEndian ebcdic-cp-us
HZ-GB-2312 ISO-8859-7 UTF32_Opposit ibm-1047
(Traditional eEndian
Chinese in Hong
Kong)
ibm-862
(Hebrew 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.
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">
For allowable values in currency_code, see Appendix D, “Currencies Supported by
PayPal.”
NOT E : If the currency_code variable is not included, the currency defaults to USD.


13
Using HTML Variables With Saved Payment Buttons

Using HTML Variables With Saved Payment Buttons
When you create payment buttons on the PayPal website and save them in your PayPal
account, PayPal generates HTML code for the saved button. You must add this generated code
to your website. Otherwise, buyers have nothing to click on.
Most features of the button, such as item name and amount, are saved with the button in the
PayPal account. Therefore, PayPal generates much simpler code for saved buttons than for
other buttons, as the following example shows.



<input type="hidden" name="cmd" value="_s-xclick">


<input type="hidden" name="hosted_button_id" value="221">



</form>

IM PORT AN T : Do not write HTML button code for saved payment buttons yourself. The
value for the hosted_button_id variable is generated solely by PayPal.
Results are unpredictable if you use your own value.
You should not write HTML button code for saved buttons. Always use the code that PayPal
generates. However, you can enhance the generated code for saved buttons by adding hidden
HTML variables that do not affect the transaction amount. For example, you can enhance
saved buttons with automatic fill-out variables, as described in “Filling Out FORMs
Automatically with HTML Variables” on page 411.

Filling Out FORMs Automatically with HTML Variables
With PayPal Account Optional turned on in your Account Profile, you can accept payments
from buyers without PayPal accounts. However, checking out by paying with PayPal is often
faster for buyers because they do not re-enter information that is stored by them on PayPal. For
repeat buyers, it is to your advantage to encourage them to sign up for PayPal accounts.

13

Billing Information Page without Buyer Information Filled Out Automatically

When you initiate a checkout process, you can fill out the Billing Information page
automatically by including special HTML input variables. When you pass these variables in
your button code, with the buyer’s name, billing address, and contact information, PayPal fills
out the page automatically and displays a simpler version.


13

Billing Information Page Filled Out Automatically with the Buyer’s Name, Address, and
Other Contact Information

The automatically filled-out form displays Change links to let buyers change billing or
contact information, if necessary.
Filling out the Billing Information page automattically with buyers’ names, billing addresses,
and contact information streamlines the checkout experience, reduces buyer friction, and helps
improve the conversion of shopping carts to completed purchases.
For information about the variables to use, see “HTML Variables for Filling Out PayPal
To learn how filling out addresses automatically affects the way PayPal handles billing and
shipping addresses during checkout, see Appendix B, “Address Handling (U.S. Merchants
Only).”


13
Overriding Addresses Stored With PayPal

Sample HTML Code for Filling Out FORMs Automatically for Buyers
The following sample HTML code shows a payment button with variables for automatically
filling out PayPal forms for the buyer. Your website generates the field entries dynamically
from information that your website gathers about the buyer. The variables and their values are
included in the URL to which buyers are sent when they click the payment button.

<input type="hidden" name="item_name" value="hat">
<input type="hidden" name="item_number" value="123">
<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">
<input type="hidden" name="city" value="Berwyn">
<input type="hidden" name="state" value="PA">
<input type="hidden" name="zip" value="19312">
<input type="hidden" name="night_phone_a" value="610">
<input type="hidden" name="night_phone_b" value="555">
<input type="hidden" name="night_phone_c" value="1234">
<input type="hidden" name="email" value="jdoe@zyzzyu.com">
</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 Filling Out PayPal Checkout Pages Automatically.”
The payer is shown the passed-in address but cannot edit it. No address is shown if the address
is invalid, 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
billing and shipping addresses, see Appendix B, “Address Handling (U.S. Merchants Only).”


13
Instant Payment Notification – notify_url

Sample HTML Code for Overriding Addresses Stored With PayPal
The following sample HTML code shows the address_override variable in conjunction
with variables for overriding a buyer’s address that is stored with PayPal.

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">


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

13

How IPN Works – Three General Steps

1. A payment or a refund triggers IPN. This payment can be via PayPal 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.
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 Instant Payment Notification 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 Instant Payment Notification Guide.


A HTML Variables for PayPal
Payments Standard

This appendix provides reference information for all HTML variables supported by any kind
of PayPal Payments Standard payment button:
 Buy Now buttons
 Donate buttons
Reference information for HTML variables supported by the Cart Upload command are also
provided.
Read the following topics to learn about the kinds of HTML variables that you can use:
 “Technical HTML Variables” on page 418
 “HTML Variables for Individual Items” on page 420
 “HTML Variables for Payment Transactions” on page 426
 “HTML Variables for Shopping Carts” on page 427
 “HTML Variables for Recurring Payments Buttons” on page 429
 “HTML Variables for Filling Out PayPal Checkout Pages Automatically” on page 439
 “HTML Variables for the Instant Update API” on page 441


HTML Variables for PayPal Payments Standard
A
Technical HTML Variables

Te c h n i c a l H T M L Va r i a b l e s
Technical HTML variables control how PayPal responds technically when people click
PayPal Payments Standard payment buttons or when third-party or custom carts initiate
payment processing with the Cart Upload command. They also control how your buttons
interact with special PayPal features.
Allowable Values for the cmd HTML Variable

Value of cmd Description
_xclick The button that the person clicked was a Buy Now button.
_cart For shopping cart purchases. The following variables specify the kind
of shopping cart button that the person clicked:
 add – Add to Cart buttons for the PayPal Shopping Cart
 display – View Cart buttons for the PayPal Shopping Cart
 upload – The Cart Upload command for third-party carts

_oe-gift-certificate The button that the person clicked was a Buy Gift Certificate button.
_xclick-subscriptions The button that the person clicked was a Subscribe button.
_xclick-auto-billing The button that the person clicked was an Automatic Billing button.
_xclick-payment-plan The button that the person clicked was an Installment Plan button.
_donations The button that the person clicked was a Donate button.
_s-xclick The button that the person clicked was protected from tampering by
using encryption, or the button was saved in the merchant’s PayPal
account. PayPal determines which kind of button was clicked by
decoding the encrypted code or by looking up the saved button in the
merchant’s account.

HTML Variables for Special PayPal Features

Required
or Character
Name Optional Description Length
notify_url Optional The URL to which PayPal posts information about the 255
payment, in the form of Instant Payment Notification
messages.
hosted_button_i See Required for buttons that have been saved in PayPal See
d description. accounts; otherwise, not allowed. description.
The identifier of a button that was saved in a merchant’s
PayPal account. PayPal assigns the value when payment
buttons are first created and saved in merchants’ PayPal
accounts.
NOT E : A merchant’s PayPal account can have a maximum
of 1,000 saved payment buttons.


A
Technical HTML Variables

Required
or Character
bn Optional An identifier of the source that built the code for the button
that the buyer clicked, sometimes known as the build
notation. Specify a value using the following format:
<Company>_<Service>_<Product>_<Country>
Substitute <Service> with an appropriate value from the
following list:
 BuyNow
 AddToCart
 Donate
 Subscribe
 AutomaticBilling
 InstallmentPlan
 BuyGiftCertifcate
 ShoppingCart

Substitute <Product> with WPS always for PayPal
Payments Standard payment buttons and for the PayPal
Payments Standard Cart Upload command.
Substitute <Country> with an appropriate two-letter
country code from codes defined by the ISO 3166-1
standard.
For example, a Buy Now button on your website that you
coded yourself might have the following line of code:
bn="DesignerFotos_BuyNow_WPS_US"
NOT E : HTML button code that you create on the PayPal
website includes bn variables with valid values
generated by PayPal.


A
HTML Variables for Individual Items

H T M L Va r i a b l e s f o r I n d i v i d u a l I t e m s
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 Donate
buttons.

Required
or Character
amount See The price or amount of the product, service, or contribution,
description. not including shipping, handling, or tax. If this variable is
omitted from Buy Now or Donate buttons, buyers enter their
own amount at the time of payment.
 Required for Add to Cart buttons
 Optional for Buy Now and Donate buttons
 Not used with Subscribe or Buy Gift Certificate buttons

discount_amount Optional Discount amount associated with an item.
It must be less than the selling price of the item. If you
specify discount_amount and discount_amount2 is not
defined, then this flat amount is applied regardless of the
quantity of items purchased.
Valid only for Buy Now and Add to Cart buttons.
discount_amount Optional Discount amount associated with each additional quantity of
2 the item.
It must be equal to or less than the selling price of the item. A
discount_amount must also be specified as greater than or
equal to 0 for discount_amount2 to take effect.
discount_rate Optional Discount rate (percentage) associated with an item.
It must be set to a value less than 100. If you do not set
discount_rate2, the value in discount_rate applies
only to the first item regardless of the quantity of items
purchased.
discount_rate2 Optional Discount rate (percentage) associated with each additional
quantity of the item.
It must be equal to or less 100. A discount_rate must
also be specified as greater than or equal to 0 for
discount_rate2 to take effect.


A

Required
or Character
discount_num Optional Number of additional quantities of the item to which the
discount applies.
Applicable when you use discount_amount2 or
discount_rate2. Use this variable to specify an upper limit on
the number of discounted items.
item_name See Description of item. If this variable is omitted, buyers enter 127
description. their own name during checkout.
 Optional for Buy Now, Donate, Subscribe, Automatic
Billing, Installment Plan, and Add to Cart buttons
 Not used with Buy Gift Certificate buttons

item_number See Pass-through variable for you to track product or service 127
description. purchased or the contribution made. The value you specify is
passed back to you upon payment completion. This variable
is required if you want PayPal to track inventory or track
profit and loss for the item the button sells.
quantity Optional Number of items. If profile-based shipping rates are
configured with a basis of quantity, the sum of quantity
values is used to calculate the shipping charges for the
payment. PayPal appends a sequence number to identify
uniquely the item in the PayPal Shopping Cart, for example,
quantity1, quantity2, and so on.
NOT E : The value for quantity must be a positive integer.
Null, zero, or negative numbers are not allowed.
shipping Optional The cost of shipping this item. If you specify shipping and
shipping2 is not defined, this flat amount is charged
regardless of the quantity of items purchased.
This shipping variable is valid only for Buy Now and Add
to Cart buttons.
Default – If profile-based shipping rates are configured,
buyers are charged an amount according to the shipping
methods they choose.
shipping2 Optional The cost of shipping each additional unit of this item. If this
variable is omitted and profile-based shipping rates are
configured, buyers are charged an amount according to the
shipping methods they choose.
This shipping variable is valid only for Buy Now and Add
to Cart buttons.


A

Required
or Character
tax Optional Transaction-based tax override variable. Set this variable to a
flat tax amount to apply to the payment regardless of the
buyer’s location. This value overrides any tax settings set in
your account profile. Valid only for Buy Now and Add to
Cart buttons. Default – Profile tax settings, if any, apply.
tax_rate Optional Transaction-based tax override variable. Set this variable to a 6
percentage that applies to the amount multiplied by the
quantity selected during checkout. This value overrides any
tax settings set in your account profile. Allowable values are
numbers 0.001 through 100. Valid only for Buy Now and
Add to Cart buttons. Default – Profile tax settings, if any,
apply.
undefined_ Optional 1 – allows buyers to specify the quantity. 1
quantity  Optional for Buy Now buttons
 Not used with other buttons

weight Optional Weight of items. If profile-based shipping rates are
configured with a basis of weight, the sum of weight values
is used to calculate the shipping charges for the payment.
Allowable values are decimals numbers, with 2 significant
digits to the right of the decimal point.
weight_unit Optional The unit of measure if weight is specified.
Allowable values are:
 lbs
 kgs

The default is lbs.
on0 Optional First option field name and label. The os0 variable contains 64
the corresponding value for this option field. For example, if
on0 is size, os0 could be large.
 Optional for Buy Now, Add to Cart, Subscribe,
Automatic Billing, and Installment Plan buttons
 Not used with Donate or Buy Gift Certificate buttons

on1 Optional Second option field name and label. The os1 variable 64
contains the corresponding value for this option field. For
example, if on1 is color then os1 could be blue.
You can specify a maximum of 7 option field names (6 with
Subscribe buttons) by incrementing the option name index
(on0 through on6).


A

Required
or Character
os0 Optional Option selection of the buyer for the first option field, on0. If See
the option field is a dropdown menu or a set of radio buttons, description.
each allowable value should be no more than 64 characters.
If buyers enter this value in a text field, there is a 200-
character limit.
NOT E : The option field on0 must also be defined. For
example, it could be size.
For priced options, include the price and currency symbol in
the text of the option selections, as the following sample
code shows:

<option value="small">small - $10.00</option>
Add a corresponding option_select0 and
option_amount0 variable for each priced option. Priced
options are supported only for Buy Now and Add to Cart
buttons. Only one dropdown menu option selection can have
priced options.

os1 Optional Option selection of the buyer for the second option field, 64 or 200
on1. If the option field is a dropdown menu or a set of radio See
buttons, each allowable value should be no more than 64 description.
characters. If buyers enter this value in a text field, there is a
200-character limit.
You can specify a maximum of 7 option selections (6 with
Subscribe buttons) by incrementing the option selection
index (os0 through os6). You can implement up to 5 option
selections as dropdown menus and up to 2 option selections
as test boxes.
NOT E : A corresponding option field (on0 through on6)
must be defined.


A

Required
or Character
option_index See The cardinal number of the option field, on0 through on9,
description. that has product options with different prices for each option.
Include option_index if the option field with prices is not
on0.

Default – 0
option_select0 Optional For priced options, the value of the first option selection of 64
the on0 dropdown menu. The values must match exactly, as
the following sample code shows:

<option value="small">small - $10.00</option>
...
<input type="hidden" name="option_select0"
value="small">
option_amount0 Optional For priced options, the amount that you want to charge for 64
the first option selection of the on0 dropdown menu. Use
only numeric values; the currency is taken from the
currency_code variable. For example:

<option value="small">small - $10.00...
<input type="hidden"
name="option_amount0"</option> value="10.00">


A

Required
or Character
option_select1 Optional For priced options, the value of the second option selection 64
of the on0 dropdown menu. For example:

...
<option value="medium">small -
$10.00</option>...
<input type="hidden" name="option_select"
value="medium">
You can specify a maximum of 10 option selections by
incrementing the option selection index (option_select0
through option_select9).
NOT E : A corresponding option selection in os0 must also
be set.
option_amount1 Optional For priced options, the amount that you want to charge for 64
the second option selection of the on0 dropdown menu. For
example:

...
<option value="small">medium - $15.00</option>
...
<input type="hidden" name="option_amount1"
value="15.00">
You can specify a maximum of 10 option amounts by
incrementing the option amount index (option_amount0
through option_amount9).
NOT E : A corresponding option selection in os0 must also
be set.


A
HTML Variables for Payment Transactions

H T M L Va r i a b l e s f o r P a y m e n t Tra n s a c t i o n s
HTML variables for payment transactions provide information about entire payments,
regardless of the individual items involved with the payment. You can use these variables with
Add to Cart buttons and the Cart Upload command.
HTML Variables for Payment Transactions

Required
or Character
address_ Optional 1 – The address specified with automatic fill-in variables 1
override overrides the PayPal member’s stored address. Buyers see
the addresses that you pass in, but they cannot edit them.
PayPal does not show addresses if they are invalid or
omitted.
For more information, see the “HTML Variables for Filling
Out PayPal Checkout Pages Automatically” on page 439.
currency_code Optional The currency of the payment. The default is USD. 3
For allowable values, see “Currencies Supported by PayPal”
on page 459.
custom Optional Pass-through variable for your own tracking purposes, which 256
buyers do not see.
Default – No variable is passed back to you.
handling Optional Handling charges. This variable is not quantity-specific. The
same handling cost applies, regardless of the number of
items on the order.
Default – No handling charges are included.
invoice Optional Pass-through variable you can use to identify your invoice 127
number for this purchase.
Default – No variable is passed back to you.
tax_cart Optional Cart-wide tax, overriding any individual item tax_x value
weight_cart Optional If profile-based shipping rates are configured with a basis of
weight, PayPal uses this value to calculate the shipping
charges for the payment. This value overrides the weight
values of individual items.
Allowable values are decimals numbers, with 2 significant
digits to the right of the decimal point.
weight_unit Optional The unit of measure if weight_cart is specified.
 lbs
 kgs

The default value is lbs.


A
HTML Variables for Shopping Carts

HTML variables for shopping carts can be used with Add to Cart buttons, as well as with
third-party shopping carts or custom carts that initiate payment processing with the Cart
Upload command.

Required
or Character
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_x Required The amount associated with item x. To pass an aggregate
amount for the entire cart, use amount_1.
Applies only to the Cart Upload command.
business Required Your PayPal ID or an email address associated with your
PayPal account. Email addresses must be confirmed.
discount_amount Optional Single discount amount charged cart-wide.
_cart It must be less than the selling price of all items combined in
the cart. This variable overrides any individual item
discount_amount_x values, if present.
discount_amount Optional The discount amount associated with item x.
_x It must be less than the selling price of the associated item.
This amount is added to any other item discounts in the cart.
discount_rate_c Optional Single discount rate (percentage) to be charged cart-wide.
art It must be set to a value less than 100. The variable overrides
any individual item discount_rate_x values, if present.
discount_rate_x Optional The discount rate associated with item x.
It must be set to a value less than 100. The variable takes into
account all quantities of item x.


A

Required
or Character
display See Display the contents of the PayPal Shopping Cart to the 1
description. 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_ cart Optional Single handling fee charged cart-wide. If handling_cart
is used in multiple Add to Cart buttons, the
handling_cart value of the first item is used.
item_name_x Required The name associated with item x. To pass an aggregate name
for the entire cart, use item_name_1.
paymentaction Optional Indicates whether the payment is a final sale or an
authorization for a final sale, to be captured later.
 sale
 authorization
 order

The default value is sale. Set the value to authorization
to place a hold on the PayPal account for the authorized
amount. Set the value to order to authorize the payment
without placing a hold on the PayPal account.
IM PORT AN T : If you set paymentaction to order, use
the Authorization & Capture API to
authorize and capture the payment
payments. The Merchant Services on the
PayPal website let you capture payments
only for authorizations, not for orders.
shopping_url Optional The URL of the page on the merchant website that buyers go
to when they click the Continue Shopping button on the
PayPal Shopping Cart page.
For more information, see “Sample HTML Code for Add to
Cart Buttons that Continue Shopping on the Current
Merchant Webpage” on page 293.


A
HTML Variables for Recurring Payments Buttons

Required
or Character
upload See Upload the contents of a third-party shopping cart or a 1
description custom shopping cart.
This variable must be set as follows:

upload="1"
The alternatives are the add="1" variable and the
display="1" variables, which are used with the PayPal
Shopping Cart.

Recurring Payments buttons are:
HTML variables for recurring payments buttons set terms for different kinds of PayPal
automatic payment plans.
Subscribe Button HTML Variables

Required
or Character
business Required Your PayPal ID or an email address associated with your
PayPal account. Email addresses must be confirmed.
item_name Optional Description of item being sold. If you are collecting 127
aggregate payments, the value can be a summary of all items
purchased, a tracking number, or a generic term such as
“subscription.” If this variable is omitted, buyers see a field
in which they can enter the item name.
currency_code Optional The currency of prices for trial periods and the subscription. 3
The default is USD.
For allowable values, see “Currencies Supported by PayPal”
on page 459.
a1 Optional Trial period 1 price. For a free trial period, specify 0.
p1 See Trial period 1 duration. Required if you specify a1. Specify 2
description. an integer value in the allowable range for the units of
duration that you specify with t1.


A

Required
or Character
t1 See Trial period 1 units of duration. Required if you specify a1. 1
description. Allowable values are:
 D – for days; allowable range for p2 is 1 to 90
 W – for weeks; allowable range for p2 is 1 to 52
 M – for months; allowable range for p2 is 1 to 24
 Y – for years; allowable range for p2 is 1 to 5

a2 Optional Trial period 2 price. Can be specified only if you also specify
a1.
p2 See Trial period 2 duration. Required if you specify a2. Specify 2
description. an integer value in the allowable range for the units of
duration that you specify with t2.
t2

Pp website paymentsstandard_integrationguide

Pp website paymentsstandard_integrationguide

More Related Content

Similar to Pp website paymentsstandard_integrationguide (20)

Pp website paymentsstandard_integrationguide