Download PayPal as a Payment Option: Standard Checkout Integration Guide

PayPal as a Payment
Option: Standard Checkout
Integration Guide
For Professional Use Only
Currently only available in English.
A usage Professional Uniquement
Disponible en Anglais uniquement pour l'instant.
Last Updated: May 2005
PayPal as a Payment Option: Standard Checkout Integration Guide
© 2006 PayPal Inc. All rights reserved. PayPal and the PayPal logo are registered trademarks of PayPal,
Inc. Designated trademarks and brands are the property of their respective owners.
PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United
Kingdom as an electronic money institution. PayPal FSA Register Number: 226056.
Notice of Non-Liability
PayPal, Inc. and the authors assume no liability for errors or omissions, or for damages, resulting from
the use of this Manual or the information contained in this Manual.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 15
PayPal-Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 2
PayPal Payments Overview . . . . . . . . . . . . . . . . . 17
PayPal Account Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Buy Nowand Donations Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Custom Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Calculating Shipping, Handling, and Tax. . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Contact Telephone Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Back-end Integration Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Instant Payment Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Payment Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Payment Receiving Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Multi-User Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Subscriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Payment Flow Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Chapter 3
Getting Started . . . . . . . . . . . . . . . . . . . . . . . 23
Account Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Account Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Financial Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Selling Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Payment Receiving Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Blocking Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 4
Account Optional . . . . . . . . . . . . . . . . . . . . . . 31
Payment Option: Standard Checkout Integration Guide
May 2005
3
Contents
Turning PayPal Account Optional On or Off . . . . . . . . . . . . . . . . . . . . . . . . . 31
Your Customer’s Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 5
Creating Buy NowButtons . . . . . . . . . . . . . . . . . . 39
How Buy Now and Donations Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
What You See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Buy Now and Donations Button Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Creating a Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Creating a Donations Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
How You Get Your Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Downloadable Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Instant Payment Notification (IPN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 6
Adding PayPal to Your Third-party Shopping Cart . . . . . 55
Passing the Aggregate Shopping Cart Amount to PayPal . . . . . . . . . . . . . . . . . . 55
Passing Individual Items to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 7
Encrypted Website Payments . . . . . . . . . . . . . . . . 57
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Prerequisites to Using EWP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Keys and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Creating Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Uploading Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Downloading PayPal's Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . 60
Removing Your Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Allowing Only Encrypted Website Payments . . . . . . . . . . . . . . . . . . . . . . 60
Creating Encrypted Website Payment Button Code with the PayPal SDK . . . . . . . . . 61
Chapter 8
Custom Payment Pages . . . . . . . . . . . . . . . . . . . 63
Examples of Custom Payment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
4
May 2005
Payment Option: Standard Checkout Integration Guide
Contents
Adding a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Editing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Previewing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Making a Page Style Primary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Removing a Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Overriding Page Style Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Background Colors and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Chapter 9
Calculating Shipping, Handling, and Tax . . . . . . . . . . 73
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Sales or Value Added Tax Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Overriding Tax Setting Per Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 73
Shipping Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Flat Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Percentage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Overriding Your Shipping Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Chapter 10
Creating Customer Contact Telephone . . . . . . . . . . . 77
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
What You See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
What Your Customer Sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Notifications You Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Chapter 11
Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . 81
How Auto Return Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Setting Up Auto Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Subscription Password Management and Auto Return . . . . . . . . . . . . . . . . . . . 86
Chapter 12
Using Multiple Currencies . . . . . . . . . . . . . . . . . . 87
Receiving Money. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Accepting Payments
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Managing Currency Balances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Chapter 13
Language Encoding for Your Data . . . . . . . . . . . . . . 91
Payment Option: Standard Checkout Integration Guide
May 2005
5
Contents
Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Changing Your Language Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Your Default Language Encoding at PayPal Signup. . . . . . . . . . . . . . . . . . . 91
Navigating Your Profile: Language Encoding . . . . . . . . . . . . . . . . . . . . . . 92
Changing Your Website Language . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
More Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Setting Language in Website Payments: charset . . . . . . . . . . . . . . . . . . . . . . 96
Chapter 14
Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Website Payments, PDT, and IPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Your PayPal Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Testing Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 15
Processing Refunds
. . . . . . . . . . . . . . . . . . . 103
Refunding Within 60 Days of Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Refunding After 60 Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Sending Partial Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Chapter 16
Security . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Notification Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Button Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Multi-User Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Using Secure Socket Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
SSL Certificate Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Appendix A Country Codes
. . . . . . . . . . . . . . . . . . . . . . 109
ISO 3166 Standard Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
6
May 2005
Payment Option: Standard Checkout Integration Guide
Contents
Payment Option: Standard Checkout Integration Guide
May 2005
7
Contents
8
May 2005
Payment Option: Standard Checkout Integration Guide
List of Tables
Table 1.1
PayPal-Supported Currencies, Currency Codes, and Maximum Transaction
Amounts 16
Table 1.2
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table 7.1
How Encrypted Website Payments Work . . . . . . . . . . . . . . . . . 57
Table 8.1
Order of Customization Variables . . . . . . . . . . . . . . . . . . . . . 70
Table 13.1
Character Sets and Encodings Supported by PayPal . . . . . . . . . . . 96
Table A.1
ISO 3166 Two-Character Country Codes. . . . . . . . . . . . . . . . . .109
Payment Option: Standard Checkout Integration Guide
May 2005
9
List of Tables
10
May 2005
Payment Option: Standard Checkout Integration Guide
List of Figures
Figure 2.1
PayPal Payment Flows
Figure 3.1
Business Account Signup . . . . . . . . . . . . . . . . . . 23
Figure 3.2
Confirming Your Email Address
Figure 3.3
Merchant Profile Page . . . . . . . . . . . . . . . . . . . . 25
Figure 3.4
Payment Receiving Preferences . . . . . . . . . . . . . . . 27
Figure 8.1
Payment Page in Standard PayPal Page Style . . . . . . . . . 63
Figure 8.2
Payment Page with Custom Style: Header Image and Header Border
64
Figure 8.3
Payment Page with Custom Style: Header Image, Image Border,
and Background Color 65
Figure 8.4
Editing Page Style Settings . . . . . . . . . . . . . . . . . 68
Figure 8.5
Example of Unallowed Background Color . . . . . . . . . . . 71
Figure 8.6
Example of Allowable Background Color
Figure 13.1
Profile Seller Preferences for Language Encoding . . . . . . . 92
Figure 13.2
Language Encoding Settings: Basic Choices
Figure 13.3
Website Language Preference . . . . . . . . . . . . . . . . 94
Figure 13.4
More Language Encoding Options . . . . . . . . . . . . . . 95
Payment Option: Standard Checkout Integration Guide
. . . . . . . . . . . . . . . . . . . 22
May 2005
. . . . . . . . . . . . . . . 24
. . . . . . . . . . . 72
. . . . . . . . . 93
11
List of Figures
12
May 2005
Payment Option: Standard Checkout Integration Guide
Preface
This Document
This document, the PayPal as a Payment Option: Standard Checkout Integration Guide,
which describes how to use and integrate PayPal features for merchants, replaces the PayPal
Merchant User Manual and Integration Guide, issued in February, 2005.
Intended Audience
This document is written for merchants whose websites use PayPal features to obtain
payments from PayPal members.
Notational Conventions
This document uses typefaces to identify the characteristics of text. These typefaces and the
characteristics they imply are described below:
Typeface
How Used
serif italics
A document title.
A term being discussed or defined.
For example: A file is a readable or writable stream of characters …
Boolean values (not keywords).
For example: The function returns true if it encounters an error.
monospaced
Pathnames or file names that appear in body text frames.
Code-related names that appear in body text frames. Such names are used for
functions, callbacks, arguments, data structures, and fields.
For example: AbstractResponseType is the SOAP response type definition on
which all PayPal API response methods are based.
Components of Internet protocol requests and responses, such as HTTPS and
FORM variables.
For example: The PayPal system uses a method=POST request to return IPN
status variables related to subscriptions, such as txn_type.
Serif bold
User interface names, such as window names or menu selections.
For example: On the Profile page, click Email to confirm your email address.
Payment Option: Standard Checkout Integration Guide
May 2005
13
Preface
Typeface
How Used
San-serif
oblique
Placeholders used in the context of a format or programming standard or formal
descriptions of PayPal system syntax. Placeholders indicate values or names that
the reader should provide.
Example: For example, amount is the variable for a single-item shopping cart, but
amount_X is the name of the variable for a multi-item shopping cart. amount_3
is the item amount for the third item in a multiple-item shopping cart.
To convey additional information, this document may also apply color and underlining to words or
phrases that use the typefaces described above. Such use is described below:
Text attribute
How Used
xxxxxx
Hypertext link to a page in the current document or to another document in the set.
xxxxxx
Hypertext link to a URL or that initiates a web action, such as sending mail.
Documentation Problems
If you discover any errors in or have any problems with this documentation, please e-mail us
by following the instructions below. Describe the error or problem as completely as possible
and give us the document title, the date of the document (located at the foot of every page),
and the page number or page range.
To contact Customer Service about documentation problems:
1. Go to https://www.paypal.com/.
2. Click Help in the upper left corner of the page.
3. Click Contact Us in the lower left of the page.
4. Chose Help by Email.
5. Complete the form.
To contact Developer Technical Support about documentation problems:
1. Log in to your account at https://developer.paypal.com/ by entering your email address and
password in the Member Log In box
2. Click Help Center at the bottom of the box on the right side of the page.
3. Click Email PayPal Technical Support.
4. Complete the form.
14
May 2005
Payment Option: Standard Checkout Integration Guide
1
Introduction
The PayPal as a Payment Option: Standard Checkout Integration Guide provides information
about the majority of PayPal's features, and instructions for using these features to meet your
online payment needs.
Use the Payment Option: Standard Checkout Integration Guide to:
z
Quickly and easily set up e-commerce functionality with PayPal. For example, learn how
to integrate PayPal into your website in minutes with Buy Now buttons.
z
Learn more advanced techniques and tools to get the most out of the PayPal products. For
example, set up Instant Payment Notification to integrate PayPal payments with your
business's back-end operations.
z
Understand what your buyers see when they pay with PayPal. For example, review what it
means for a new buyer to optionally create a PayPal account using the PayPal Account
Optional feature.
z
View various product flows to better visualize your end product.
z
Review recommended solutions and best practices.
The PayPal as a Payment Option: Standard Checkout Integration Guide includes information
about, and instructions for using, the following features:
z
Buy Now Buttons
z
Donations Buttons
z
PayPal Account Optional
z
Custom Payment Pages
z
Instant Payment Notification
z
Payment Data Transfer
z
Multi-User Access
z
Shipping, Handling, and Tax
z
Auto Return
Payment Option: Standard Checkout Integration Guide
May 2005
15
1
Introduction
PayPal-Supported Currencies
PayPal-Supported Currencies
The following currencies are supported by PayPal.
TABLE 1.1
PayPal-Supported Currencies, Currency Codes, and Maximum
Transaction Amounts
Code
Currency
Maximum Transaction
Amount
AUD
Australian Dollar
12,500 AUD
CAD
Canadian Dollar
12,500 CAD
EUR
Euro
8,000 EUR
GBP
Pound Sterling
5,500 GBP
JPY
Japanese Yen
1,000,000 JPY
USD
U.S. Dollar
10,000 USD
Additional Information
The following table lists URLs you can consult for more information about PayPal.
N O T E : In
most cases, you must log in to PayPal to see this additional information.
TABLE 1.2
16
Additional Information
Information
URL
Fees
https://www.paypal.com/fees
Online Security
https://www.paypal.com/security
User Agreement and
Policies
https://www.paypal.com/cgibin/webscr?cmd=p/gen/ua/ua-outside
Online Help
https://www.paypal.com/fees/help
Customer Service
https://www.paypal.com/wf
May 2005
Payment Option: Standard Checkout Integration Guide
2
PayPal Payments Overview
This section provides a brief overview of each of the products described in this manual.
PayPal Account Optional
With PayPal Account Optional turned on, your customers who are new to PayPal can make
credit card and debit card payments without signing up for a PayPal account. This setting is
available from your Profile, and is available to Premier and Business accounts.
PayPal Account Optional is turned on by default for all U.S. Premier and Business accounts.
This means that your customers who already have PayPal accounts will go through the same
Website Payments experience to which they’re accustomed.
Your new customers, or existing customers who are new to PayPal, will go through a checkout
that doesn’t require PayPal signup; however, they will have that option available after
completing the payment. Whether customers sign up for a PayPal account or not, you can set
your Buy Now, Donations, and Shopping Cart buttons to return them to your website, and you
will still receive the same notification emails as in the current checkout flow.
For more information about PayPal Account Optional, see Chapter 4, “Account Optional.”
Buy Nowand Donations Buttons
PayPal makes it easy to accept donations and payments for single items through your website.
The Buy Now and Donations Buttons feature can be implemented in minutes, giving you easy
access to business from PayPal’s millions of members, and any other buyer on the web.
Because using Buy Now and Donations buttons to send and receive payments is secure, both
you and your customers remain protected. PayPal automatically encrypts your confidential
information using the Secure Sockets Layer (SSL) protocol with an encryption key length of
128 bits (the highest level commercially available). Your customers will not need to share
their private financial information (e.g. credit card or bank account numbers) during the
transaction, so they can complete payment while retaining security. However, using button
encryption does impose some limitations, and therefore PayPal offers both encrypted and
unencrypted button options.
The flexibility of our Buy Now buttons keeps your website working for you. You can accept
payments from current PayPal members as well as people who have just signed up for our
service, and you won’t lose your customers after they have made a purchase—the payment
process lets you return buyers to your website, not lose them to ours.
Benefits of Buy Now and Donations Buttons include:
Payment Option: Standard Checkout Integration Guide
May 2005
17
2
PayPal Payments Overview
Custom Payment Pages
z
Easy to implement — no CGI scripting necessary.
z
No up-front costs — you’ll have the same low fee schedule used as when you receive other
PayPal payments.
z
Sell with ease — PayPal maintains detailed transaction records on the PayPal website.
z
Improve buyer experience — with customizable buttons and secure payments, happy
customers become repeat customers.
For more information about Buy Now and Donations Buttons, see Chapter 5, “Creating Buy
NowButtons.”
Custom Payment Pages
With our Custom Payment Pages feature, you can tailor PayPal's payment pages to the style of
your website for a truly seamless payment experience. Make PayPal's payment flow yours
with custom page colors and your own images. Custom Payment Pages can be used with all
PayPal Website Payment buttons, including Buy Now, Donations, and Subscriptions.
For more information about Custom Payment Page, see Chapter 8, “Custom Payment Pages.”
Calculating Shipping, Handling, and Tax
You can set up your PayPal account to automatically calculate and charge shipping and sales
(or value added) tax, as well as specify a different tax rate for each of the 50 U.S. states and
any of the countries listed. In addition, you can charge shipping costs as a fixed rate based on
the amount of the total purchase, or as a percentage of the purchase price. You also have the
option to assign shipping amounts to individual products.
For more information about shipping and tax, see Chapter 9, “Calculating Shipping, Handling,
and Tax.”
Contact Telephone Number
The Customer Contact Information Telephone field provides merchants with a contact
telephone number for their buyer. In accordance with our User Agreement, merchants may
only use this Contact Telephone Number to communicate with buyers about the related
purchase. This number may not be used for unsolicited commercial messages.
18
May 2005
Payment Option: Standard Checkout Integration Guide
PayPal Payments Overview
Auto Return
2
Auto Return
Auto Return for Website Payments allows merchants to eliminate the Payment Receipt page in
the Website Payments flow and automatically return or redirect buyers to their website upon
payment completion.
For more information about Auto Return, see Chapter 11, “Auto Return.”
Back-end Integration Methods
There are two back-end integration methods: Instant Payment Notification and Payment Data
Transfer.
Instant Payment Notification
PayPal’s Instant Payment Notification (IPN) allows you to integrate PayPal payments with
your website's back-end operations:
z
Customize your website's response to customer purchases in real-time.
z
Track customers through the notification's pass through variables.
z
Automate your fulfillment operations.
z
Store transaction information in your own database.
IPN provides immediate notification and confirmation of PayPal payments you receive. After
you activate IPN, you receive an IPN when a payment is first received that displays the status
of the payment: Completed or Pending. If the payment status was Pending, you will receive
another IPN when the payment clears, fails, or is denied.
IPN can be integrated with each of the PayPal Website Payments solutions — Buy Now
Buttons, PayPal Shopping Cart, Subscriptions and Recurring Payments, and Donations — and
with regular PayPal Send Money and Mass Payment. It lets you focus on selling, not on
manually tracking your orders.
For more information about IPN, see the Order Management Integration Guide.
Payment Data Transfer
Payment Data Transfer (PDT) provides merchants with the ability to display transaction
details to buyers who are redirected back to their website upon payment completion.
For more information about PDT, see the Order Management Integration Guide.
Payment Option: Standard Checkout Integration Guide
May 2005
19
2
PayPal Payments Overview
Payment Receiving Preferences
Payment Receiving Preferences
Once you have set up your PayPal account, you’re ready to receive payments. Your Payment
Receiving Preferences let you manage the types of payments you receive.
For more information about Payment Receiving Preferences, see “Payment Receiving
Preferences” on page 27.
Refunds
You can automatically send a refund to your buyer with 60 days after receiving payment.
For more information about sending refunds, see Chapter 15, “Processing Refunds.”
Multi-User Access
PayPal’s Multi-User Access feature allows you to set up multiple logins and access levels.
Your employees only have access to the parts of your PayPal account that they need to
complete their jobs, letting you run your business smoothly and securely.
For more information about Multi-User Access, see “Multi-User Access” on page 106.
Reports
PayPal’s Reporting Tools provide you with the information you need to effectively measure
and manage your business:
z
Analyze your revenue sources to better understand your customers’ buying behavior.
z
Automate time-consuming bookkeeping tasks.
z
Accurately settle and reconcile transactions.
For more information about PayPal's Reporting Tools, see https://www.paypal.com/us/cgibin/webscr?cmd=p/xcl/rec/reports-intro-outside.
Subscriptions
PayPal Subscriptions and Recurring Payments is a service with which you can accept
recurring payments for your service.
When you set up Subscriptions, you can offer your subscribers a trial period, special
introductory rates, and a regular rate. Your subscribers will be billed automatically according
20
May 2005
Payment Option: Standard Checkout Integration Guide
PayPal Payments Overview
Subscriptions
2
to the terms you dictate, removing the hassle of keeping track of which payments you have and
have not received.
For more information about PayPal Subscriptions and Recurring Payments, see the PayPal
Subscriptions manual, which is available on the PayPal website.
Payment Option: Standard Checkout Integration Guide
May 2005
21
2
PayPal Payments Overview
Payment Flow Overview
Payment Flow Overview
The following diagram represents an overview of the PayPal payment flows.
FIGURE 2.1 PayPal Payment Flows
22
May 2005
Payment Option: Standard Checkout Integration Guide
3
Getting Started
You can start accepting payments with PayPal in 5 easy steps:
Step 1 - Sign Up: Go to https://www.paypal.com/ and click the Sign Up link in the upper righthand corner of the page. Click the Business link to sign up for a Business account, as shown in
the following diagram. Be sure to remember the email address and password you choose; in
the future, you will use them to login to your PayPal account.
FIGURE 3.1 Business Account Signup
Step 2 - Confirm Email Address: After completing the two-page signup, PayPal will send
you an email to confirm your email address. Open your email and click the link in the email
we sent you. You will be taken to a PayPal page and asked to enter your password, as shown in
the following diagram. Once you have successfully entered your password, your email address
will be confirmed.
IMPO RTANT: PayPal
representatives will never ask you for your password, and will never
ask you to enter your password or financial information in an email or send
such information in an email. If you believe someone has learned your
password, please change it immediately and contact PayPal customer service
as soon as possible.
Payment Option: Standard Checkout Integration Guide
May 2005
23
3
Getting Started
Account Profile
FIGURE 3.2 Confirming Your Email Address
Step 3 - Add Bank Account: You must add a bank account In order for PayPal to add funds
to it. Log in to your PayPal account and click the Profile subtab of the My Account tab. Click
the Bank Accounts link in the Financial Information column. After you add your bank
account, it becomes your Primary bank account and default payment method. If you decide to
add additional bank accounts to your PayPal account, you can change any of them to be your
primary account.
Step 4 - Add Credit Card (optional): Log in to your PayPal account and click the Profile
subtab of the My Account tab, as shown in the following diagram. Click the Credit Cards
link in the Financial Information column. On the Credit Cards page, click the Add button.
The credit card you add will become your primary credit card, meaning it is the default credit
card used on your PayPal account. If you decide to add additional credit cards to your PayPal
account, you can select any of them as your primary card.
Step 5 - Start Receiving Payments: Now that you’ve set up everything in your PayPal
account, you’re ready to start receiving payments.
Account Profile
The PayPal account Profile consolidates all of the different settings and preferences for your
account. You can use your Profile to manage all of the information in your PayPal account. To
24
May 2005
Payment Option: Standard Checkout Integration Guide
Getting Started
Account Profile
3
go to your Profile, log in to your PayPal account and click the Profile subtab of the My
Account tab, as shown in the following diagram.
Your Profile is organized in three sections for managing your account information, as shown
in the following diagram.
FIGURE 3.3 Merchant Profile Page
Account Information
Use the Account Information column to perform basic account maintenance, including
updating your password, adding and confirming email addresses, and managing your business
information.
Financial Information
Use the Financial Information column to organize and maintain all of the financial
instruments associated with your PayPal account, including adding credit cards and bank
accounts, maintaining your Multiple Currency Balances, and viewing your Monthly Account
Statements.
Payment Option: Standard Checkout Integration Guide
May 2005
25
3
Getting Started
Account Profile
Selling Preferences
Use the Selling Preferences column to organize the way you sell with your PayPal account,
including editing your Payment Receiving Preferences, tax, and shipping.
26
May 2005
Payment Option: Standard Checkout Integration Guide
Getting Started
Payment Receiving Preferences
3
Payment Receiving Preferences
Once you have set up your PayPal account, you’re ready to start receiving payments. Your
Payment Receiving Preferences let you manage the types of payments you receive:
z
Block payments from U.S. users that do not have a confirmed address.
z
Block payments sent to you in a currency you do not hold.
z
Block payments from users with non-U.S. PayPal accounts.
z
Block payments from users who initiate payments from the Pay Anyone subtab.
z
Block payments funded by credit cards when the sender has a bank account.
z
Block payments funded by eCheck for PayPal Website Payments and Smart Logo
payments.
To edit your Payment Receiving Preferences:
z
Log in to your PayPal account.
z
Click the Profile subtab of the My Account tab.
z
Click the Payment Receiving Preferences link in the Selling Preferences column. The
Payment Receiving Preferences page opens, as shown in the following diagram.
FIGURE 3.4 Payment Receiving Preferences
Payment Option: Standard Checkout Integration Guide
May 2005
27
3
Getting Started
Payment Receiving Preferences
Blocking Payments
Blocking Payments From U.S. Users Without a Confirmed Address
This preference allows you to better manage your risk by filtering payments where the buyer
chooses not to share his Confirmed Address with you. PayPal provides Confirmed Addresses
to help you make informed decisions when shipping goods. To be eligible for PayPal's Seller
Protection Policy, and to help reduce your risk of dealing with fraudulent buyers, ship to a
buyer’s Confirmed Address.
There are three choices for this preference:
z
Yes: All payments from U.S. buyers without a Confirmed Address will be blocked. All
U.S. buyers will be required to provide a Confirmed Address in order to pay you.
z
No: All payments will be accepted. To maximize your sales, select No.
z
Ask Me: You can choose whether to accept or deny payment without a Confirmed Address
on a case-by-case basis. This option allows you the flexibility to decide whether you want
to take on the risk of not having the buyer’s Confirmed Address for each transaction. If you
accept the payment, it becomes a completed transaction. If you deny a particular payment,
the sender of the payment will be notified that the payment has been denied and will be
credited with the payment amount. PayPal does not charge fees for denied payments.
Blocking Payments in a Currency You Do Not Hold
When you receive a payment in a currency you do not hold, PayPal will prompt you to open a
balance for that currency, convert it to your primary balance, or deny the payment. Payments
in currencies for which you hold a balance will automatically be applied to the correct balance,
and you will see a summary of each currency balance in your Account Overview page.
There are three choices for this preference:
z
Yes: Accepts the payment regardless of the currency in which the payment is made.
z
No, accept them and convert them to U.S. Dollars: Accepts the payment but
automatically converts to U.S. Dollars.
z
Ask Me: You can choose to accept or deny, transaction-by-transaction, a payment in a
currency you do not currently hold. If you accept the payment, it becomes a completed
transaction. If you deny a particular payment, the sender of the payment will be notified
that the payment has been denied and will be credited with the payment amount. PayPal
does not charge fees for denied payments.
Blocking Payments From Users With Non-U.S. PayPal Accounts
Since many international addresses cannot be confirmed, you may choose to block payments
from users with non-U.S. PayPal accounts in order to qualify for the Seller Protection Policy
(SPP).
Blocking Payments Initiated From the Pay Anyone Subtab
This preference allows you to choose whether or not to receive payments initiated via the Pay
Anyone subtab of the Send Money tab on the PayPal website.
If you choose to block these payments, you will accept only payments initiated via PayPal’s
Buy Now Buttons, Donations, Subscriptions and Recurring Payments, Winning Buyer
28
May 2005
Payment Option: Standard Checkout Integration Guide
Getting Started
Payment Receiving Preferences
3
Notification, Mass Payments, Money Requests, Post-Sale Manager Invoices, Smart Logos, or
eBay Checkout Payments. Selecting this option may help you manage your account, because
all of the PayPal payments you receive will be attached to a specific item or transaction that
you previously defined.
If you choose not to block these payments, you will accept all payments, including those
initiated via the Pay Anyone subtab of the Send Money tab.
Blocking Payments Funded By Credit Cards When Sender Has a Bank Account
This preference allows you to force customers to pay you with a bank account or PayPal funds
if they are able to do so. However, if they cannot pay you using a bank account or PayPal
funds, they will still have the option to pay with a credit card.
This preference can also help to reduce your risk of chargebacks. Verified users are users who
have confirmed their bank accounts with PayPal, or have been otherwise verified by PayPal.
Because most Verified members have the option of paying with their bank accounts (via
eCheck or Instant Transfer), choosing this preference will not prevent any users from being
able to send you money. When they pay you with PayPal’s Instant Transfer, you receive the
payment instantly, just as when they pay with a credit card. Users who have not confirmed
their bank accounts with PayPal can still send you money funded by credit cards.
Blocking Payments Funded By eChecks
This preference allows you to block eCheck payments. Because eCheck payments take three
to four business days to clear, you may not want to accept them for your Instant Purchase and
Buy Now buttons.
If you choose to block these payments, you will not receive eCheck payments through PayPal
Website Payments and Auction Logos. Users who attempt to pay via eCheck will be prompted
to add a credit card to their account before completing the transaction.
If you choose not to block these payments, you will receive eCheck payments through PayPal
Website Payments or Auction Logos. eCheck payments will be listed as ‘Pending’ and will not
be credited to your PayPal Account for three to four business days.
Adding the Credit Card Statement Name
This preference allows you to specify the name that appears on your customers’ credit card
statements. When a buyer pays you by credit card, your Credit Card Statement Name appears
with the word PAYPAL* next to the charge on the statement (for example,
PAYPAL*MYCCNAME). The Credit Card Statement Name can be up to 11 English or German
characters in length, including spaces, and cannot contain special characters (e.g. &, #, _, etc).
This name is converted to all capital letters and may be truncated by some credit card
processors.
The Credit Card Statement Name should accurately reflect your business or legal name.
Payment Option: Standard Checkout Integration Guide
May 2005
29
3
30
Getting Started
Payment Receiving Preferences
May 2005
Payment Option: Standard Checkout Integration Guide
4
Account Optional
With PayPal Account Optional turned on, your customers who are new to PayPal can make
credit card payments without signing up for a PayPal account. This setting is available in the
Profile of Premier and Business accounts.
PayPal Account Optional is turned on by default for all U.S. Premier and Business accounts.
Your customers who already have PayPal accounts will go through the same Website
Payments experience to which they’re accustomed, which is shown in the “How It Works”
section of the Creating Buy Now and Donations Buttons section of this manual.
Your new customers (or existing customers who are new to PayPal) will go through a checkout
that doesn’t require PayPal signup, but they will have that option available after completing
the payment. Whether customers sign up for a PayPal account or not, you can set your Buy
Now, Donations, and Shopping Cart Buttons to return them to your website, and you will still
receive the same notification emails as in the current checkout flow.
Turning PayPal Account Optional On or Off
1. Log in to your PayPal account at https://www.paypal.com.
2. Click the Profile subtab.
3. Click the Website Payment Preferences link in the Selling Preferences column.
4. Scroll down to the PayPal Account Optional section of the page.
5. Select On to turn PayPal Account optional on, or Off to turn it off and continue using the
existing Website Payments flow for all of your customers.
6. Click Save to save your preference.
The setting you choose for PayPal Account Optional affects all of your existing and new Buy
Now, Donations, and Shopping Cart buttons for customers who are new to PayPal. Your
customers who already have PayPal accounts will see no change in their checkout
experience—they will log in as usual at the time of payment and complete the transaction from
within the PayPal account.
Payment Option: Standard Checkout Integration Guide
May 2005
31
4
Account Optional
Your Customer’s Experience
Your Customer ’s Experie n c e
If you turn PayPal Account Optional off, the customer is required to sign up for a PayPal
account to complete the payment and then returns to your website.
If you have PayPal Account Optional turned on, the checkout experience for a customer who
doesn’t currently have a PayPal account does not require the PayPal account signup to
complete the transaction, thus shortening the time and effort necessary on the customer’s part.
What Your Customer Sees
Step 1: Bob goes to Alice’s website and clicks Buy Now.
Step 2: Bob is taken to a PayPal Payment Details page which shows the details of the payment
he is about to make. He is prompted to log in to his PayPal account, but he is not already a
PayPal member, so he clicks Continue Checkout.
Step 3: Bob is prompted to enter the shipping information for his purchase, and to let Alice
know if the shipping address he has entered is the same as the billing address on his credit
32
May 2005
Payment Option: Standard Checkout Integration Guide
Account Optional
Your Customer’s Experience
4
card. If it is, he clicks Yes. Bob is then taken to the Billing Information page, as shown in Step
4, where the Billing and Shipping Address information has been prepopulated; however, Bob
will still need to enter his credit card information, email, phone, and security measure code.
N O T E : If your Payment Receiving Preferences are set to accept payments onlyfrom customers
with Confirmed addresses, then the buyer will skip over this Shipping Information
screen and go directly to Billing Information in Step 4.
Payment Option: Standard Checkout Integration Guide
May 2005
33
4
Account Optional
Your Customer’s Experience
Step 4: Bob is prompted to fill in his billing information for the credit card he wishes to use for
the purchase. The items will be shipped to the shipping address he has provided.
34
May 2005
Payment Option: Standard Checkout Integration Guide
Account Optional
Your Customer’s Experience
4
Step 5: Bob is taken to a review page containing the details of his purchase. Because Alice has
activated Profile-based Shipping for all of her transactions, the Shipping amount for this
purchase ($2.00) is automatically added to Bob’s purchase. He clicks Complete Checkout to
complete his purchase.
information about setting Shipping preferences, see Chapter 9, “Calculating
Shipping, Handling, and Tax.”
N O T E : For more
Payment Option: Standard Checkout Integration Guide
May 2005
35
4
Account Optional
Your Customer’s Experience
Step 6: Bob is taken to a payment completion page where he sees his Receipt ID for this
transaction, and Alice's customer service contact information. He can use both to contact Alice
with any questions about his purchase.
If Bob clicks Save My Info, he will be taken to a page where he can enter the rest of the
information needed to create a PayPal account (see Step 7). The information Bob has already
entered to complete the transaction is carried forward.
If he clicks Continue, he will be redirected to either Alice’s site or to PayPal, depending on
how she has set her return preferences for the button.
36
May 2005
Payment Option: Standard Checkout Integration Guide
Account Optional
Your Customer’s Experience
4
card. If it is, he clicks Yes. Bob is then taken to the Billing Information page, as shown in Step
4, where the Billing and Shipping Address information has been prepopulated; however, Bob
will still need to enter his credit card information, email, phone, and security measure code.
N O T E : If your Payment Receiving Preferences are set to accept payments onlyfrom customers
with Confirmed addresses, then the buyer will skip over this Shipping Information
screen and go directly to Billing Information in Step 4.
Payment Option: Standard Checkout Integration Guide
May 2005
33
Account Optional
Your Customer’s Experience
4
Step 7: If Bob clicked Save My Info, he is taken to a page where he can complete signing up
for a PayPal account. Once he has filled in the fields, he clicks Save Information to create the
account.
Step 8: Bob sees a page that confirms the creation of his account.
If he clicks Continue, he will be redirected to either Alice’s website or to PayPal, depending
on how she has set her return preferences for the button.
Payment Option: Standard Checkout Integration Guide
May 2005
37
4
Account Optional
Your Customer’s Experience
Step 9: Bob receives an email receipt for this transaction that confirms his payment and
includes a copy of the payment details.
38
May 2005
Payment Option: Standard Checkout Integration Guide
5
Creating Buy NowButtons
PayPal makes it easy to accept payments for single items through your website. Buy Now and
Donations buttons can be implemented in minutes, giving you easy access to business and
donors from PayPal’s millions of members, and any other buyer on the web.
Because using Buy Now and Donations Buttons to send and receive payments is secure, both
you and your customers remain protected. PayPal automatically encrypts your confidential
information using the Secure Sockets Layer (SSL) protocol with an encryption key length of
128 bits (the highest level commercially available). Your customers will not need to share
their private financial information (e.g. credit card or bank account numbers) during the
transaction, so they can complete payment while retaining security.
The flexibility of our Buy Now and Donations Buttons keep your website working for you.
You can accept payments from current PayPal members as well as people who have just
signed up for our service, and you won’t lose your customers after they make a purchase or
donation—the payment process lets you return buyers to your website, not lose them to ours.
Other benefits of Buy Now and Donations Buttons include:
z
Easy to implement—no CGI scripting necessary.
z
No up-front costs—you’ll have the same low fee schedule used as when you receive other
PayPal payments.
z
Sell with ease—PayPal maintains detailed transaction records on our website.
z
Improve buyer experience— customizable buttons and secure payments make happy,
repeat customers.
How Buy Now and Donations Work
Bob, who is new to PayPal, is going to make a purchase or a donation on Alice's Used Books
website. Depending on the PayPal Account Optional setting Alice has chosen in the Website
Payments Preferences of her Profile, Bob's purchasing experience may differ from what is
shown here.
The following example depicts the flow that occurs when PayPal Account Optional is turned
off, and the user must create a PayPal account to complete the transaction. For more
information about the PayPal Account Optional setting, see Chapter 4, “Account Optional.”
Payment Option: Standard Checkout Integration Guide
May 2005
39
5
Creating Buy NowButtons
How Buy Now and Donations Work
What Your Customer Sees
Step 1: Bob goes to Alice’s website and clicks Buy Now or Donations.
Step 2: Bob is taken to a PayPal Payment Details page which shows the details of the
payment he is about to make.
Step 3: Bob is prompted to log in to his PayPal account; however, he is not already a PayPal
member. So next to If you have never paid through PayPal, he clicks Click Here, as shown
in the following diagram.
40
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
How Buy Now and Donations Work
5
Step 4: To pay for his purchase, Bob is prompted to add a credit card, email address, and
password, which creates his new PayPal account.
Payment Option: Standard Checkout Integration Guide
May 2005
41
5
Creating Buy NowButtons
How Buy Now and Donations Work
Step 5: Bob is taken to a Payment Details page that contains the details of his purchaseor
donation. Bob clicks Pay to complete his purchaseor donation, as shown in the following
diagram. For donations, Bob would choose a shipping address before clicking Pay so Alice
can send him a tax receipt.
The Shipping amount for this purchase, $2.00, is automatically added to Bob’s purchase
because Alice has activated Profile-based Shipping for all of her transactions. To learn more
about automatically calculating shipping for all of your transactions, see Chapter 9,
“Calculating Shipping, Handling, and Tax.”
42
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
How Buy Now and Donations Work
5
Step 6: Bob is taken to a payment completion page where he sees the details of his transaction.
He is also given Alice’s customer service email address. He clicks the Continue link and is
returned to a page on Alice’s website, which she specified when she created her payment
button.
With Auto Return for Website Payments, Bob is redirected back to Alice’s website
immediately after clicking Pay on the Payment Confirmation page.
The Payment Completion page can be merchant-hosted if the merchant has turned on Auto
Return. To learn more about Auto Return, see Chapter 11, “Auto Return.”
Payment Option: Standard Checkout Integration Guide
May 2005
43
5
Creating Buy NowButtons
How Buy Now and Donations Work
Step 7: Bob receives an email receipt for this transaction that confirms his payment and
includes a copy of his payment details.
What You See
Step 8: Alice receives an email notification of Bob’s payment.
44
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
Buy Now and Donations Button Factory
5
Step 9: Alice logs in to her PayPal account to check the payment Bob has sent.
Step 10: The funds from Bob’s payment are now reflected in Alice’s PayPal account balance.
She ships the book to Bob.
N O T E : For more
information about PayPal’s fees, please click the Fees link at the bottom of
any PayPal web page, or visit https://www.paypal.com/fees.
Buy Now and Donations Button Factory
One Buy Now button can be used to sell a single Mozart CD for $15 or, if you choose, it can
allow your customer to purchase multiple copies of the same CD at once. If, however, you
would like to sell a Mozart CD and a Beethoven CD, you will need to create separate Buy
Now Buttons for each item.
Donations buttons can be used to collect a pre-determined amount, (i.e. donations of $50), or
you can allow your donors to choose the amounts of their donations.
Use the following steps to create your Buy Now and Donations buttons.
Getting Started
1. Log in to your PayPal account at https://www.paypal.com.
2. Click the Merchant Tools tab.
3. Click the Buy Now Buttons or Donations link under the Website Payments heading to
open the Button Factory.
Payment Option: Standard Checkout Integration Guide
May 2005
45
5
Creating Buy NowButtons
Buy Now and Donations Button Factory
Creating a Buy Now Button
Step 1: Enter the details for your item (all fields are optional):
– Item Name/Service: Enter the name of the item or service you wish to sell. If you do not
enter anything in this field, your customers will be able to complete it at the time of
purchase. PayPal recommends entering an item name to make it easier for you to ship the
order.
– Item ID/Number: If you have an ID or tracking number for your item, enter it here. This
field will not be displayed to your customers at the time of payment, but they will see it
in their transaction details on the PayPal website.
– Item Price: Enter the price of the item you wish to sell. If you do not enter anything in
this field, your customers will complete it. PayPal recommends entering an Item Price to
make it easier for you to collect the correct amount.
– Currency: Choose the currency in which you would like this payment to be
denominated. This field will default to the currency of your primary balance.
Step 2: Choose a payment button to put on your website.
If you are going to receive payments from your website, choose the image for the button you
would like your customers to click to make their purchase. To display your own image, enter
the URL of the image’s location in the URL field.
N O T E : PayPal
recommends that you enter an image URL only if the image is stored on a
secure (https) server. Otherwise, your customer’s web browser will display a message
that the payment page contains insecure items.
If you are creating an email link, skip to Step 4.
Step 3: Security Settings
PayPal offers the option to encrypt your button's HTML code. Encryption ensures that an
item's price and other details cannot be altered by a third party, thus increasing the security of
your transactions. Select Yes to encrypt your code, or No to leave it editable.
N O T E : PayPal
highly recommends encrypting your button code; however, doing so has three
limitations:
1. Encrypted button HTML is not editable. If you want tp modify your button code manually,
select No for this option.
2. You will not be able to encrypt your button if it has dynamically-generated code from the
Add More Options page, such as drop-down Options fields (see step 5). If you need
Option fields for your products, select No to turn encryption off.
3. If you choose to encrypt your button, you will not be able to create an email link.
If you do not have additional details to add to your button (such as sales tax, shipping, or your
logo), click Create Button Now and go to Step 11. Otherwise, click Add More Options.
46
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
Buy Now and Donations Button Factory
5
Step 4: Shipping and Sales Tax
– Shipping Cost Calculation: If you have already specified shipping rates in your Profile,
they will be listed here. To learn more about charging for shipping, see Chapter 9,
“Calculating Shipping, Handling, and Tax.”
– Sales or Value Added Tax Calculation: If you have already specified your tax rate from
your Profile, it will be listed here. For more information about charging for tax, see
Chapter 9, “Calculating Shipping, Handling, and Tax.”
Step 5: Add Option fields to your button
Let your customers specify information about their purchases by creating an option field. You
can use Option fields to specify things like color, size, or gift-wrapping. These options you
allow customers to choose options must not change the price of an item, but let you collect
additional information from your customer without extra email communication. Each Buy
Now Button can have up to two option fields, and you canuse a drop-down menu or text box to
collect the information.
Unfortunately, Option fields and button encryption cannot be used if you are creating an email
hyperlink. If you would still like to send out Buy Now links in emails, you may try either
sending an HTML email, providing a link to the Buy Now Button (with Option fields) on your
website, or asking your user to include the optional information in the Note field.
– Option Field Type: Choose the type of option field: drop-down menu or text box. If you
choose drop-down menu, you must enter the different choices. If you choose text box,
your customers enter their choice.
– Option Name: Enter the name of your option. There is a 60-character limit for the
Option Name field.
– Drop-Down Menu Choices: If you are using a drop-down menu, enter your menu
choices. There is a 30-character limit per choice, with a maximum of 10 choices. Use a
carriage return (press ENTER) to separate each choice.
Step 6: Customize your payment pages
– Custom Payment Page Style: Give your customers a seamless payment experience by
customizing PayPal's payment pages to match the style of your website. If you have
already added Custom Payment Page Styles in your Profile, they will be listed here.
Choose the page style you would like to appear when your customer clicks your Buy
Now button. To learn more about creating page styles, see Chapter 8, “Custom Payment
Pages.”
Step 7: Customize Your Buyer Experience
– Successful Payment URL: Enter the URL for the page to which you want your
customer redirected after he has completed his payment. Unless you have enabled Auto
Return, after customers complete their payments they see a payment completion page.
From this page, they click Continue and return to the Successful Payment URL you have
specified. If you do not enter a Successful Payment URL, customers who click this link
are taken to a PayPal web page.
– Cancel Payment URL: Enter the URL where you would like to send your customers if
they cancel their payments at any point in the Buy Now payment flow. If you do not enter
a Cancel Payment URL, customers who click this link are taken to a PayPal web page.
Payment Option: Standard Checkout Integration Guide
May 2005
47
5
Creating Buy NowButtons
Buy Now and Donations Button Factory
Step 8: Miscellaneous Options
– Quantity: If you would like to let your customers purchase more than one item or
service, choose Yes. They will be prompted to enter the quantity of the item they want
to buy. If you choose No, the quantity will be set to 1 and your customers will be able to
purchase only one item per payment.
– Shipping Address: If you would like your customers to be prompted to provide a
shipping address, choose Yes. If you choose No, for items such as digital goods, your
customers will not be asked to provide a shipping address.
Step 9: Collect additional information from your customers
– Note: Select Yes if you would like your customers to be able to include a note to you
with their payment. If you select No, your customers cannot include a note.
– Note Title: If you are allowing your customers to include a note with their payments,
you may choose a title for the note field. By including a title, you can prompt your buyers
to enter specific information, such as User ID or special instructions. There is a 40character limit on your note field title. If you do not enter a title, your customers will see
Special Instructions (optional) as the note field title.
Step 10: Choose an email address to receive payment
If you have added more than one confirmed email address to your PayPal account, you can
specify the address at which you would like to receive your email payment notifications when
your customers pay you.
Step 11: Copy and paste the HTML code
When you have finished filling out the Buy Now Button Factory form, click Create Button
Now.
If your customers will be making purchases through your website: Copy the code from the
HTML for Websites text box by highlighting all of the text and pressing Ctrl+C, or by
highlighting all of the text, right-clicking your mouse, and selecting Copy.
In your website files, open the code for the web page from which you wish to collect payment.
Paste the code you just copied into your web page file wherever you would like the image to
appear, typically next to the description of the item or service, by either pressing Ctrl+V or by
right-clicking on your mouse and selecting the Paste option.
N O T E : HTML
Tips: Please ensure that the HTML code on your web page exactly matches
the code you copied from PayPal. Some HTML editors may add, delete, or change
some characters in your code. If this is the case, please change the code on your web
page to exactly match the code you copied You can copy the code into a new Notepad
document, reselect all of the code, copy, then paste it into your web editor.
Please be sure that when you paste the HTML code for your button, you are pasting
this information into a field that accepts HTML code. If you paste this code into a
standard text field, the code will be posted to your web page as standard text.
For more tips on placing your payment on your web page, please refer to the Help
section of your web page editor.
48
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
Buy Now and Donations Button Factory
5
If you will be sending your customers the payment link via email: Copy the code from the
Link for Emails text box by highlighting all of the text and pressing Ctrl+C, or by
highlighting all of the text, right-clicking on your mouse, and choosing Copy.
Open the email you wish to send.
Paste the code you just copied into your email by either pressing Ctrl+V or by right-clicking
on your mouse and selecting the Paste option.
When your customers receive the email, the code will appear as a link. Clicking the link will
take them to your PayPal payments page.
N O T E : If
you enable button encryption, you will not be able to create an email link.
Creating a Donations Button
Step 1: Enter the details for your donations.
N O T E : All
fields are optional.
– Donation Name/Service: Enter the reason for payment or the name of your
organization/charity here. If you do not enter anything in this field, your donors can
complete this field.
– Donation ID/Number: You may use this field to differentiate payments (e.g. to enter a
campaign name). This field will not be displayed to your donors at the time of payment,
but they will see it in their transaction details on the PayPal website.
– Donation Amount: If you would like to collect a pre-determined amount, you can enter
it in the Donation Amount field. If you would like your donors to choose their donation
amounts, do not enter a price in this field. Users will be prompted to enter a donation
amount when they make payment.
– Currency: Choose the currency in which you would like this payment to be
denominated. This field will default to the currency of your primary balance.
Step 2: Choose a Donations button to put on your website
Choose the image for the button you would like your donors to click to make their payment.
To display your own image, enter the URL of the image’s location in the URL field.
If you are also creating an email link, continue to Step 8. If you have no further details to add
to your Donations button, click Create Button Now. Otherwise, click Add More Options.
IMPO RTANT: If
you are creating an email link, be sure to click No for the encrypt button
option.
Step 3: Customize Your Payment Pages
– Custom Payment Page Style: Give your donors a seamless payment experience by
customizing PayPal's payment pages to match the style of your website. If you have
already added Custom Payment Page Styles in your Profile, they will be listed here.
Choose the page style you would like to appear when your donor clicks your Donate
button. To learn more about creating page styles, Chapter 8, “Custom Payment Pages.”
Step 4: Customize Your Donors’ Experience
Payment Option: Standard Checkout Integration Guide
May 2005
49
5
Creating Buy NowButtons
Buy Now and Donations Button Factory
– Successful Payment URL: Enter the URL where you would like to send your donors
after they have completed payment. Once donors complete their payments, they see a
payment confirmation page. From this page, they click Click to Continue and return to
the successful payment URL you have specified. If you do not enter a successful
payment URL, donors who click this link are taken to a PayPal web page.
– Cancel Payment URL: Enter the URL where you would like to send your donors if they
cancel a payment at any point in the Donations payment flow. If you do not enter a cancel
payment URL, donors who click this link will be taken to a PayPal web page.
Step 5: Miscellaneous
– Shipping Address: If you would like to prompt customers to provide a shipping address,
choose Yes. If you choose No, donors are not asked to provide a shipping address.
Step 6: Collect additional information from your customers
– Note Title: If you are allowing your donors to include a note with their payment, you
may choose a title for the note field. By including a title, you can prompt your buyers to
enter specific information, such as a User I, or special instructions. There is a 40character limit on your note field title. If you do not enter a title, donors see ‘Special
Instructions (optional)’ as the note field title.
N O T E : Select
Yes if you would like your donors to be able to include a note to you with
their payment. If you select No, your donors cannot include a note.
Step 7: Choose an email address to receive payment
If you have added more than one confirmed email address to your PayPal account, you can
specify the address at which you would like to receive your email payment notifications when
your donors pay you.
Step 8: Copy and Paste the Donations code
When you have finished filling out the Donations Button Factory form, click Create Button
Now.
If your donors will be donating through your website:
1. Copy the code from the HTML for Websites text box by highlighting all of the text and
pressing Ctrl+C, or by highlighting all of the text, right-clicking your mouse, and clicking
Copy.
2. In your website files, open the code for the web page from which you wish to collect
payment.
3. Paste the code you just copied into your web page file wherever you would like the image
to appear (typically, next to the description of the donation service) by pressing Ctrl+V, or
right-clicking on your mouse and selecting Paste.
If you will be sending your donors the Donations link via email:
How You Get Your Money
After your customer makes a payment:
50
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
Notifications You Receive
5
1. You will receive an email notification of the payment.
2. Your customer will receive an email receipt for the payment.
3. Your PayPal account will reflect the payment (you can view this information from your
account history or download it as part of your history transaction log).
For more information about payment-related notifications, see “Notifications You Receive” on
page 51 and the Order Management Integration Guide.
Notifications You Receive
You can be notified of payments in these four ways: email, history transaction log,
downloadable history transaction log, and (if you have activated it) Instant Payment
Notification (IPN).
Email
You receive an email notification in the following cases:
z
Successful Payment
z
Pending Payment
z
Cancelled Payment
If you do not want to receive payment notifications via email:
1. Click the Profile subtab of the My Account tab.
2. Click the Notifications under the Account Information heading.
3. Find the Payment Notifications heading and clear the I receive PayPal Website
Payments and Instant Purchase checkbox.
4. Click Save.
History
Your transaction history log (“History”) contains information about your payments. Each
payment will have one of these options as its status:
z
Completed: The transaction was successful and the money was credited to your account.
z
Cleared: The eCheck payment has cleared the sender’s account and has been credited to
your account.
z
Uncleared: The eCheck payment has not cleared the sender’s account yet.
Payment Option: Standard Checkout Integration Guide
May 2005
51
5
Creating Buy NowButtons
Notifications You Receive
Downloadable Logs
Log in to your PayPal account, go to the History subtab of the My Account tab and choose
the Download My History link in the Reporting Tools menu. You have two ways of
selecting data:
1. Click the Custom Date Range radio button and enter the dates of the entries you want to
download. Choose the type of file you would like to download (Comma delimited, Tab
delimited, Quicken, or QuickBooks), and click Download History.
2. Click the Last Download to Present radio button to see all payments since you last
downloaded your history.
The downloaded file containx a record of all payments that match your criteria.
Instant Payment Notification (IPN)
If you have Instant Payment Notification activated, you will receive an IPN when a payment is
first sent, which will state the status of the payment: Completed or Pending. If the payment
was Pending, you will receive another IPN when the payment clears, fails, or is denied.
To learn more about IPN, see the Order Management Integration Guide.
52
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Buy NowButtons
Notifications You Receive
Payment Option: Standard Checkout Integration Guide
May 2005
5
53
5
54
Creating Buy NowButtons
Notifications You Receive
May 2005
Payment Option: Standard Checkout Integration Guide
6
Adding PayPal to Your Thirdparty Shopping Cart
Some web developers want to integrate PayPal payment processing with their own third-party
shopping cart instead of the standard PayPal Shopping Cart. The instructions and variables in
this chapter allow your buyers to pay with PayPal when they are ready to check out after
adding all of their items to your third-party shopping cart.
There are two ways to integrate your third-party shopping cart with the PayPal payment flow.
The first is to pass the aggregate amount of the total Cart payment rather than the individual
items. The second is to pass details of the items that have been selected to PayPal, instead of
an aggregated amount for the entire Cart.
N O T E : Posting
the necessary variables to PayPal as described in the following instructions
will probably require you to implement some scripting on your website.
Passing the Aggregate Shopping Cart Amount to PayPal
If you wish, you can aggregate your entire shopping cart and pass the total amount with
PayPal’s Buy Now code. In other words, you will need to post a single name for the entire cart
and the total price of the cart’s contents as though it were a purchase of a single item.
One drawback of this method is that your buyers will not be able to see the individual items in
their carts. In addition, you cannot change our variable names, nor can you add your own
variable names.
Passing Individual Items to PayPal
If your third-party shopping cart can be configured to pass individual items to PayPal,
information about the items will be included in the buyer’s and seller’s History transactions
and notifications. To include information about the items, you will post HTML form elements
to a new version of PayPal’s Shopping Cart flow. This process is much like the one described
in Passing Aggregate Shopping Cart Amount to PayPal, with the following exceptions:
1. Set the cmd variable to _cart.
2. Replace this required HTML line:
<input type="hidden" name="cmd" value="_xclick">
with
<input type="hidden" name="cmd" value="_cart">
3. Add the upload variable:
Payment Option: Standard Checkout Integration Guide
May 2005
55
6
Adding PayPal to Your Third-party Shopping Cart
Passing the Aggregate Shopping Cart Amount to PayPal
<input type="hidden" name="upload" value="1">
4. Define item details.
For each of the following item-specific parameters, define a new set of values that
correspond to each item that was purchased with your third-party cart. Append _x to the
variable name, where x is the item number, starting with 1 and increasing by one for each
item that is added.
5. Repeat for each item included in cart.
Include a set of required variables and any optional variables from the table above for each
item included in your buyer’s cart. The first item included in the cart should be defined
with parameters ending in _1, such as item_name_1, amount_1, and so on. Similarly, the
second item should be denoted with variables like item_name_2, amount_2, and so on.
IMPO RTANT: The _x values must increment by
one continuously in order to be recognized.
If you skip from item #1 to item #3 without defining an item #2, the third item
will be ignored.
To specify currency: All monetary variables (amount_x, shipping_x, shipping2_x,
handling_x, tax_x, and tax_cart) are interpreted in the currency designated by the
currency_code variable posted with the payment. Because currency_code is not itemspecific, there is no need to append _x to the currency_code variable name. If no
currency_code variable is posted, all monetary values default to U.S. Dollars.
To specify cart-wide tax: Use the tax_cart variable to specify a tax amount that applies to
the entire purchase, rather than to individual items. The tax_cart variable overrides any peritem tax amount specified with tax_x.
For a complete list of variables, see the Passing Individual Items to PayPal section of
Appendix A in this manual.
56
May 2005
Payment Option: Standard Checkout Integration Guide
7
Encrypted Website Payments
To add security to online payments, merchants can create Encrypted Website Payment (EWP)
button code using standard public-key encryption. With public and private keys, merchants
can dynamically encrypt payment information before it is sent to PayPal.
N O T E : The
PayPal Software Development Kit includes commands to create private keys and
public certificates for EWP and to generate EWP code. For more information, see the
PayPal SDK Guide.
How It Works
Encrypted Website Payments works in the following way.
TABLE 7.1
How Encrypted Website Payments Work
Merchant...
Buyer...
PayPal...
Clicks “Pay” button, which
posts the signed, encrypted
FORM data to PayPal’s
URL
Checks the authenticity of the data by
using the merchant’s uploaded public
key
Creates HTML name/value pairs that
represent the parameters of the
HTML FORM to post to PayPal when
a customer clicks a button on his
website
Encrypts those button parameters
with PayPal’s public key
Signs the encrypted data with his own
private key
Publishes the signed, encrypted
FORM to his website with a “Pay”
button
Decrypts the data with PayPal’s
private key
Directs the buyer’s browser to the
PayPal payment flow specified in the
button parameters
Payment Option: Standard Checkout Integration Guide
May 2005
57
7
Encrypted Website Payments
Prerequisites to Using EWP
Prerequisites to Using EWP
Before you can use Encrypted Website Payments, you must:
z
Generate a private key
z
Generate a public certificate
z
Upload your public certificate to the PayPal website at https://www.paypal.com/us/cgibin/webscr?cmd=_profile-website-cert
z
Download PayPal's public certificate from https://www.paypal.com/us/cgibin/webscr?cmd=_profile-website-cert
Keys and Certificates
This section describes how to create your private and public keys for EWP, upload your public
key to PayPal, and download a copy of PayPal’s public key.
Public-Key Encryption Background
Public-key encryption (asymmetric encryption) improves security and convenience by
allowing senders and receivers to have separate public and private encryption keys:
z
The public key: The public key is the portion of an asymmetric cryptographic key that
receivers give senders who want to send information. Information is encrypted using the
receiver's public key so only the receiver can decrypt it. The receiver can use the sender’s
public key to decrypt information that was encrypted with the sender's private key. This
encryption process is used with digital signatures, which are signed using the sender's
private key and later decrypted with the sender’s public key by the receiver to verify the
origin of information.
z
The private key: The private key is the portion of an asymmetric cryptographic key the
receiver keeps secret and is not sent to anyone. It is used by the receiver to decrypt
information encrypted by senders. Private keys are also used to create digital signatures,
which prove the authenticity of a sender.
z
The public certificate: The public certificate consists of the the public key and identity
information, such as a person's name, all of which could be signed by a certificate authority
(CA). The CA guarantees that the public key belongs to the named entity.
Creating Your Public Certificate
For EWP, PayPal requires that you upload your public certificate to its website, so that the
authenticity of the encrypted code can be verified.
PayPal accepts only X.509 public certificates, not public keys. The difference between a key
and a certificate is that a certificate includes the public key along with information about the
key, such as when the key expires and who the key belongs to. PayPal accepts public
58
May 2005
Payment Option: Standard Checkout Integration Guide
Encrypted Website Payments
Keys and Certificates
7
certificates in OpenSSL PEM format from any established certificate authority, such as
Verisign.
You can also create your own private key and public certificate using open source software
such as OpenSSL (http://www.openssl.org), which is detailed in the following section.
N O T E : The
PayPal Software Development Kit includes commands to create private keys and
public certificates for EWP.
Creating Your Private Key with OpenSSL
Using the openssl program, enter the following command to create your private key. The
command generates a 1024-bit RSA private key. The private key is stored in the file myprvkey.pem:
openssl genrsa -out my-prvkey.pem 1024
Creating Your Public Certificate Using OpenSSL
To create 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 mypubcert.pem
Uploading Your Public Certificate
To upload your public certificates to the PayPal website:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. Click the Encrypted Payment Settings link from the right-handed menu.
4. Click Add.
5. Click Browse and select the public certificate you want to upload.
The public certificate must be in PEM format.
If your public certificate is successfully uploaded, it will appear on the next screen under Your
Public Certificates.
Payment Option: Standard Checkout Integration Guide
May 2005
59
7
Encrypted Website Payments
Keys and Certificates
After you have successfully uploaded your certificate, PayPal assigns a corresponding
certificate ID. Store the certificate ID in a safe place; you need it to make Encrypted Website
Payments.
Downloading PayPal's Public Certificate
To download PayPal's public certificate:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. Click the Encrypted Payment Settings link from the right-hand menu.
4. Click the Download button under the PayPal Public Certificate section.
Removing Your Public Certificate
N O T E : If
you remove your public certificate, the certificate ID associated with it will not be
valid to encrypt buttons and any buttons generated by your website with that certificate
ID will not function correctly.
To remove one or more of your public certificates:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. Click the Encrypted Payment Settings link from the right-hand menu.
4. Select one of the listed certificates, and click Remove.
5. On the next screen, click Remove again to remove the selected public certificate.
Allowing Only Encrypted Website Payments
To prevent someone from creating a “spoof” version of your Website Payment Buttons, you
can block unencrypted website payments.
1. To allow only Encrypted Website Payments:
60
May 2005
Payment Option: Standard Checkout Integration Guide
Encrypted Website Payments
Creating Encrypted Website Payment Button Code with the PayPal SDK
7
2. Log in to your Business or Premier PayPal account.
3. Click the Profile subtab.
4. Click the Website Payment Preferences link from the right-hand menu.
5. Select On next to Block Non-encrypted Website Payments.
Creating Encrypted Website Payment Button Code with the
PayPal SDK
The general process for creating EWP code is as follows:
1. Create HTML name/value pairs that represent the parameters of the HTML FORM to post
to PayPal when a customer clicks a button on your website to buy your goods or service.
2. Encrypt those button parameters with PayPal’s public key.
3. Sign the encrypted data with your private key.
4. Publish the signed, encrypted FORM to your website with the “PayPal” button.
The PayPal Software Development Kit (SDK) includes the console thathas commands to
simplify the creation of Encrypted Website Payments button code. It also has program
methods for Java and Microsoft .NET to encrypt button code.
For more information, see the “Generating EWP Code with the Console” chapter in the
PayPal SDK Guide.
Payment Option: Standard Checkout Integration Guide
May 2005
61
7
62
Encrypted Website Payments
Creating Encrypted Website Payment Button Code with the PayPal SDK
May 2005
Payment Option: Standard Checkout Integration Guide
8
Custom Payment Pages
With our Custom Payment Pages feature, you can tailor PayPal's payment pages to the style of
your website for a truly seamless payment experience. Make PayPal's payment flow yours
with custom page colors and your own images. Custom Payment Pages can be used with all
PayPal Website Payment buttons, including Buy NowDonations, and Subscriptions. It is also
compatible with the PayPal Account Optional feature and will apply your choices to the pages
in that payment flow.
Examples of Custom Payment Pages
The pictures in this section demonstrate the types of customization you can add to your PayPal
Website Payment buttons.
Figure 8.1, “Payment Page in Standard PayPal Page Style,” shows a payment page without
any customization.
FIGURE 8.1 Payment Page in Standard PayPal Page Style
Payment Option: Standard Checkout Integration Guide
May 2005
63
8
Custom Payment Pages
Examples of Custom Payment Pages
Figure 8.2, “Payment Page with Custom Style: Header Image and Header Border,” shows a
custom header image and header border color.
FIGURE 8.2 Payment Page with Custom Style: Header Image and Header Border
64
May 2005
Payment Option: Standard Checkout Integration Guide
Custom Payment Pages
Getting Started
8
Figure 8.3, “Payment Page with Custom Style: Header Image, Image Border, and Background
Color,” shows a custom header image, header border color, and page background color.
FIGURE 8.3 Payment Page with Custom Style: Header Image, Image Border, and
Background Color
Getting Started
1. Log in to your PayPal account at https://www.paypal.com
2. Click the Profile sub-tab.
3. Click the Custom Payment Pages link under the Selling Preferences heading to get to the
Custom Payment Page Styles page.
4. From this page, you can add, edit, preview, and remove page styles, as well as make any
page style your primary style.
Payment Option: Standard Checkout Integration Guide
May 2005
65
8
Custom Payment Pages
Adding a Page Style
Adding a Page Style
You can add up to three page styles. To add a page style:
1. Begin at the Custom Payment Page Styles page.
2. Click Add.
3. Enter your page style preferences:.
– Page Style Name (required)
Enter a name up to 30 characters in length. The name can contain letters, numbers, and
underscores but no other symbols or spaces. The Page Style Name will be used to refer
to the page style within your PayPal account and in the HTML code for your PayPal
Website Payment buttons.
– Header Image URL (optional)
Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high;
larger images will be reduced to this size. The image must be in a valid graphics format
such as .gif, .jpg, .png, and .swf. The image will appear at the top left of the payment
page.
N O T E : PayPal
recommends that you enter an image URL only if the image is stored on a
secure (https) server. Otherwise, your customer’s web browser displays a message
that the payment page contains insecure items.
– Header Background Color (optional)
Enter the background color for the header using HTML hex code. The color code must
be six digits long and should not contain the # symbol. If the Header Image URL is
present, then the header will be a 750 pixel wide by 90 pixel high space at the top of the
payment page. If the Header Image URL is not present, the header height will be reduced
to 45 pixels.
– Header Border Color (optional)
Enter the border color for the header using HTML hex code. The color code must be six
digits long and should not contain the # symbol. The header border is a two-pixel
perimeter around the header space.
– Background Color (optional)
Enter the background color for the payment page using HTML hex code. The color code
must be six digits long and should not contain the # symbol.
4. Click Preview to preview your page style, or click Save to save it.
The next time you create a button, you have the option to apply a page style to the payment
pages associated with it. To do so, click Add More Options on the button creation page, and
select a page style from the Custom Payment Page Style menu.
N O T E : The
settings described here can also be specified with HTML <FORM> input variables
passed through at a transaction level.
66
May 2005
Payment Option: Standard Checkout Integration Guide
Custom Payment Pages
Editing a Page Style
8
Editing a Page Style
To edit a page style:
1. Begin at the Custom Payment Page Styles page. For more information, see “Getting
Started” on page 65.
2. Click the radio button next to the page style you wish to edit.
3. Click Edit.
4. Keep or modify your page style preferences:
– Page Style Name (required)
Enter a name up to 30 characters in length. The name can contain letters, numbers,
underscores but no other symbols or spaces. The Page Style Name will be used to refer
to the page style within your PayPal account and in the HTML code for your PayPal
Website Payment buttons.
– Header Image URL (optional)
Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high;
larger images will be reduced to this size. The image must be in a valid graphics format
such as .gif, .jpg, .png, or .swf. The image will appear at the top left of the payment page.
N O T E : PayPal
recommends that you enter an image URL only if the image is stored on a
secure (https) server. Otherwise, your customer's web browser will display a message
that the payment page contains insecure items.
– Header Background Color (optional)
Enter the background color for the header using HTML hex code. The color code must
be six digits long and should not contain the # symbol. If the Header Image URL is
present, then the header will be a 750 pixel wide by 90 pixel high space at the top of the
payment page. If the Header Image URL is not present, the header height will be reduced
to 45 pixels.
– Header Border Color (optional)
Enter the border color for the header using HTML hex code. The color code must be six
digits long and should not contain the # symbol. The header border is a 2 pixel perimeter
around the header space.
– Background Color (optional)
Enter the background color for the payment page using HTML hex code. The color code
must be six digits long and should not contain the # symbol.
5. Click Preview to preview your page style, or click Save to save it.
Payment Option: Standard Checkout Integration Guide
May 2005
67
8
Custom Payment Pages
Editing a Page Style
FIGURE 8.4 Editing Page Style Settings
68
May 2005
Payment Option: Standard Checkout Integration Guide
Custom Payment Pages
Previewing a Page Style
8
P r e v i e w i n g a P a g e St y l e
To preview a page style:
1. Begin at the Custom Payment Page Styles page. For more information, see “Getting
Started” on page 65.
2. Click the radio button next to the page style you wish to preview.
3. Click Preview.
Making a Page Style Primary
When you make a page style Primary, it is applied to all of your payment pages unless you
specify otherwise. To learn how to apply a page style other than your Primary style, Chapter 8,
“Custom Payment Pages.”
N O T E : If
you do not designate a page style as Primary, the default PayPal page style is used.
To make a page style Primary:
1. Begin at the Custom Payment Page Styles page.
For more information, see “Getting Started” on page 65.
2. Click the radio button next to the page style you wish to make your Primary style.
3. Click Make Primary.
4. Click Make Primary to confirm your choice.
Removing a Page Style
When you remove a page style, the payment pages to which the style applies will no longer be
customized with those specifications. Instead, your Primary page style will be applied to those
pages. If you remove your Primary page style, the PayPal page style will become Primary.
To remove a page style:
1. Begin at the Custom Payment Page Styles page.
For more information, see “Getting Started” on page 65.
2. Click the radio button next to the page style you wish to remove.
3. Click Remove.
4. Click Remove to confirm your choice.
Payment Option: Standard Checkout Integration Guide
May 2005
69
8
Custom Payment Pages
Overriding Page Style Settings
Overriding Page Style Settings
Your Primary page style will automatically be applied to all of your payment pages unless you
specify otherwise.
To apply a page style other than your Primary style, select a different one when creating your
button. Just click Add More Options on the button creation page, and select a page style from
the Custom Payment Page Style menu.
To change the page style for a button you have already created, you can modify the button's
HTML code, replacing the value of the page_style variable with the Page Style Name of the
style you wish to apply. The next time the button is clicked, its payment pages will appear in
the new style.
When Custom Payment Page variables are passed at a transaction-level, they override any
page styles set in profile settings or page_settings. Customization variables are applied
in the following order:
TABLE 8.1
70
Order of Customization Variables
Custom Option
Description
2
Primary Page Style at a
Transaction level
A valid page style can be passed through at a Transaction level
that overrides any page styles set in profile settings or
page_settings.
3
Primary Page Style in
Profile
You can create and select the primary style in profile settings.
4
Default PayPal Page
Style in Profile
The default page style used when an alternative is not selected
and designated as primary.
May 2005
Payment Option: Standard Checkout Integration Guide
Custom Payment Pages
Background Colors and Error Messages
8
Background Colors and Error Messages
PayPal’s error message system highlights errors in red. PayPal does not allow certain
background colors that make these error messages unreadable.
The background color of the following payment page is not allowed. The color makes the
fields the customer must complete difficult to read.
FIGURE 8.5 Example of Unallowed Background Color
Payment Option: Standard Checkout Integration Guide
May 2005
71
8
Custom Payment Pages
Background Colors and Error Messages
The background color of the following payment page is allowed. Unlike in the previous
example, the fields displayed in red are easy to read.
FIGURE 8.6 Example of Allowable Background Color
To verify that your background color is allowed, enter its hex code into the Background Color
field on the Custom Payment Pages page under the Profile subtab of the My Account tab
and click Preview. The background color is allowed if you are able to preview the payment
page with your chosen background color. If you receive an error message about the
background color, the color is not allowed and you must choose a different color.
If a conflicting background color is passed through, it will be considered invalid and PayPal
will automatically default your background color to white.
Font Colors
PayPal dynamically changes font colors from black to white, depending on the background
color. To confirm that these font changes comply with your font color selections, you should
test your color settings on PayPal.
Image Storage
PayPal recommends that you store your images on secure (https) servers. If your images are
not stored on secure servers, your customers may be shown a browser warning indicating that
you have insecure items on your page.
72
May 2005
Payment Option: Standard Checkout Integration Guide
9
Calculating Shipping, Handling,
and Tax
You can set up your PayPal account to automatically calculate and charge shipping and sales
tax (also called “value added tax”).
Getting Started
To view or modify your sales tax and shipping charges:
1. Log in to your PayPal account at https://www.paypal.com.
2. Click the Profile subtab of the My Account tab.
3. Click the Sales Tax or the Shipping Calculation link in the Selling Preferences column.
Sales or Value Added Tax Collection
You can charge your customers tax by choosing a Country (such as, United Kingdom) or State
(such as, California) from the Country and U.S. State drop-down menus, and entering your
Tax Rate for that state in the Tax Rate field. All your customers who reside in the country or
state you select are automatically charged the tax rate you choose. You can specify a different
tax rate for each U.S. state and any of the listed countries.
There are radio buttons that allow you to apply tax to an item only, or to an item and any
shipping and handling costs, as you desire.
Click Save to save your changes.
N O T E : If you are entering the rate for a U.S. state, ensure that the Country drop-down menu is
set to United States.
Overriding Tax Setting Per Transaction
The tax variable is an optional transaction-based tax override variable with which you can set
a flat tax amount on a single transaction regardless of the buyer’s location.
Payment Option: Standard Checkout Integration Guide
May 2005
73
9
Calculating Shipping, Handling, and Tax
Shipping Calculation
Shipping Calculation
Determine whether you would like to charge your customers for shipping as a flat amount or a
percentage of the total purchase amount.
Flat Amount
A flat amount is charged based on the subtotal of a purchase. Here’s an example.
EXAMPLE 9.1 Flat Amount Shipping Calculation
Your flat amount settings are:
$0.00 through $49.99 = $3.00
$50.00+ = $6.00
– If your customer’s subtotal is $36.50, your customer is charged $3.00 for shipping,
making the total purchase $39.50.
– If your customer’s subtotal is $66.50, your customer is charged $6.00 for shipping,
making the total purchase $72.50.
Choose the Flat Amount radio button (with the $ by it), and enter a flat amount for each dollar
amount increment. Click Save to save your changes.
Percentage
A percentage is charged based on the subtotal of a purchase. Here’s an example.
EXAMPLE 9.2 Percentage Shipping Calculation
Your percentage settings are:
$0.00 through $49.99 = 5%
$50.00+ = 4%
– If your customer’s subtotal is $36.50, your customer is charged 5% x $36.50 = $1.83 for
shipping, making the total purchase $38.33.
– If your customer’s subtotal is $66.50, your customer is charged 4% x $66.50 = $2.66 for
shipping, making the total purchase $69.16.
Choose the Percentage radio button (with the % by it), and enter a percentage for each dollar
amount increment. Click Save to save your changes.
Overriding Your Shipping Calculation
In some cases, you might want to set a special shipping rate for an item (for example, if the
item is especially heavy and costs more to ship or if it is a service which does not require
shipping charges). To charge a different shipping amount for an item, include the shipping
74
May 2005
Payment Option: Standard Checkout Integration Guide
Calculating Shipping, Handling, and Tax
Shipping Calculation
9
cost in the HTML for that Buy Now button using the shipping, shipping2, and
handling_cart variables.
Payment Option: Standard Checkout Integration Guide
May 2005
75
9
76
Calculating Shipping, Handling, and Tax
Shipping Calculation
May 2005
Payment Option: Standard Checkout Integration Guide
10
Creating Customer Contact
Telephone
The Customer Contact Information Telephone is an option that provides you with a contact
telephone number for your buyer. When you activate this option, your customers are asked to
include a Contact Telephone Number with their payment information. PayPal will share this
number with you.
IMPO RTANT: In
accordance with PayPal’s User Agreement, you may use this Contact
Telephone Number only to communicate with the buyer about the related
purchase. You may not use this number for unsolicited commercial messages.
How It Works
When you enter your payment preferences on the Website Payment Preferences page, you will
have the opportunity to request a Contact Telephone Number from your buyer.
You can choose to make the Contact Telephone Number optional or required, or turn it off
altogether. “Off” is the recommended default option because buyers value their privacy and
prefer to keep unsolicited communications to a minimum.
What You See
Step 1:
You can select the option you want to use to activate the Contact Telephone Number feature.
If you do not want to request a contact telephone number from your buyer, select the Off radio
button. You will see the following on the Website Payment Preferences page:
Payment Option: Standard Checkout Integration Guide
May 2005
77
10
Creating Customer Contact Telephone
Getting Started
Step 2: On the Transaction Details page, you will see the buyer’s contact telephone number:
What Your Customer Sees
Step 3: When you require the buyer’s contact telephone number, your buyer will see the
information below:
Getting Started
Use the following instructions to activate the Customer Contact Information Telephone
option:
1. Log in to your PayPal account at https://www.paypal.com.
2. Click the My Account tab.
3. Click the Profile link.
4. Click the Website Payment Preferences link.
5. Select the option you prefer: On (Optional Field), On (Required Field), or Off
(Recommended).
6. Complete the rest of the selections on the page.
7. Click Save.
78
May 2005
Payment Option: Standard Checkout Integration Guide
Creating Customer Contact Telephone
Notifications You Receive
10
Notifications You Receive
You receive an email notification when a buyer makes a purchase.
Payment Option: Standard Checkout Integration Guide
May 2005
79
10
80
Creating Customer Contact Telephone
Notifications You Receive
May 2005
Payment Option: Standard Checkout Integration Guide
11
Auto Return
With Auto Return for Website Payments, merchants can eliminate the “Done” page in the
Website Payments flow and automatically return or redirect buyers to their website upon
payment completion. By decreasing the Website Payments purchasing process by 1/3 and
automatically bringing buyers back to their website, merchants provide their buyers with a
quicker, more seamless, and continuous purchasing experience.
Merchants with premier or business accounts can enable Auto Return by turning it on,
specifying the URL to redirect the buyer upon payment completion, and agreeing to the terms
that require that the merchant provide “payment done” messaging on the page assigned to the
return URL.
Auto Return applies to all PayPal Website Payments, including Buy NowDonations, and
Subscriptions.
How Auto Return Works
This example shows the Auto Return flow with Custom Payment Pages, but without the
PayPal Account Optional feature.
Bob is going to purchase a widget from the Widget Warehouse.
Step 1: Bob goes to the Widget Warehouse website, finds the widget he wants, and clicks Buy
Now.
Payment Option: Standard Checkout Integration Guide
May 2005
81
11
Auto Return
How Auto Return Works
Step 2: Bob is taken to a PayPal Payment Details page which displays the details of the
payment he is about to make.
Step 3: Bob enters his PayPal account information into the PayPal Login fields. (These pages
are not included in this example.)
N O T E : At
this point, buyers that do not have a PayPal account click the If you have never
paid through PayPal, Click Here button. The Payment Details page then displays
credit card, email, password, and security fields that can be used to create a new PayPal
account. After buyers create a new account, they click Continue to proceed to the next
step in the payment process.
82
May 2005
Payment Option: Standard Checkout Integration Guide
Auto Return
How Auto Return Works
11
Step 4: Bob is then taken to a confirmation page that displays the details of his selection,
information about how his automatic payments will be funded, and his shipping information.
He clicks Pay to complete payment.
Step 5: A payment confirmation page appears that informs Bob that his payment is complete
and that he is being automatically redirected back to the Widget Warehouse sebsite. The page
also displays a success URL that the user can click manually if the redirect fails.
Payment Option: Standard Checkout Integration Guide
May 2005
83
11
Auto Return
How Auto Return Works
Step 6: The Widget Warehouse’s “Thank You” page appears, again informing Bob that his
transaction is complete and that a receipt for the purchase has been emailed to him. The page
also displays a link to PayPal that Bob can use to view details of the transaction if necessary,
as well as links that he can use to continue shopping.
Step 7: Bob receives an email receipt for this transaction that confirms the purchase and
includes a copy of the payment details, the Widget Warehouse's business information, and his
confirmed shipping address.
84
May 2005
Payment Option: Standard Checkout Integration Guide
Auto Return
Setting Up Auto Return
11
Setting Up Auto Return
To set up Auto Return:
1. Log in to your PayPal account at https://www.paypal.com.
2. Click the Profile subtab.
3. Click the Website Payment Preferences link under the Selling Preferences column on
the right.
4. Under Auto Return for Website Payments, click the On radio button to enable Auto
Return.
Payment Option: Standard Checkout Integration Guide
May 2005
85
11
Auto Return
Subscription Password Management and Auto Return
5. Enter the Return URL to which you want your buyers redirected upon payment completion
in the Return URL field.
You Return URL must meet the following requirements:
– Per the user agreement, you must provide content on the page displayed by the Return
URL that helps the buyer understand that the payment has been made and that the
transaction has been completed.
– You must provide content on the page displayed by the Return URL that explains that
payment transaction details will be emailed to the buyer.
– Your Return URL must specify a server that is available and be properly formatted.
N O T E : If
the Return URL that you supply is not valid, PayPal displays the standard
Payment Done page upon payment completion.
6. Click Save.
Subscription Password Management and Auto Return
If you use or plan to use Subscriptions Password Management, you must make sure that Auto
Return is turned off in order to display the PayPal-generated username and password to the
buyer.
N O T E : You
can use Auto Return with Subscriptions, which is a separate feature from
Subscription Password Management. For more information about Subscriptions, see
the Subscriptions and Recurring Payments Manual, which is available on the PayPal
website.
86
May 2005
Payment Option: Standard Checkout Integration Guide
12
Using Multiple Currencies
PayPal’s Multiple Currencies feature gives you the ability to buy and sell globally. Use your
current PayPal account to make or accept payments any of the PayPal-supported currencies.
Buyers:
z
Pay for purchases in your selected currency.
z
Payment is automatically converted to your desired currency.
z
No need to hold a balance in another currency to send a payment.
Sellers:
z
Accept payments directly in your selected currency.
z
Manage multiple currency payments using your current PayPal account.
z
Hold one currency balance and still accept payments in multiple currencies.
Receiving Money
Receive payments in any of the currencies listed in Table 1.1, “PayPal-Supported Currencies,
Currency Codes, and Maximum Transaction Amounts” on page 16.
Premier and Business account holders have additional flexibility for managing Multiple
Currencies payments.
Accepting Payments
You choose which currencies to accept and how you would like to accept them. When a buyer
sends a payment in a currency you hold, the funds will automatically appear in your account in
the balance of the given currency. When a buyer sends a payment in a currency you do not
hold, you will be asked to Accept or Deny the payment:
z
Accept the payment and open a new currency balance.
z
Accept the payment and convert it to your primary currency.
z
Block the payment.
Payment Option: Standard Checkout Integration Guide
May 2005
87
12
Using Multiple Currencies
Receiving Money
You can also set up your Payment Receiving Preferences to indicate how you would like to
handle incoming currency payments.
Receiving fees are assessed in the currency in which the funds were sent. Payments converted
to your primary currency are converted at a competitive exchange rate.
To learn more about receiving money in multiple currencies, see the Multiple Currencies
FAQs in the PayPal online Help Center.
If you use Instant Payment Notification (IPN), see Table A.8, “IPN Variables with Each
Subscription Event” on page 52 for more information about Multiple Currencies variables.
88
May 2005
Payment Option: Standard Checkout Integration Guide
Using Multiple Currencies
Managing Currency Balances
12
Managing Currency Balances
You can manage your currency balances in the Currency Balances section of your Profile:
z
Select your primary currency
z
Open or close a currency balance
z
Transfer funds between currency balances
Funds transferred from one currency balance to another will be transferred at a competitive
exchange rate. To learn more about managing currency balances, see the Multiple Currencies
FAQs in our Help Center.
Payment Option: Standard Checkout Integration Guide
May 2005
89
12
90
Using Multiple Currencies
Managing Currency Balances
May 2005
Payment Option: Standard Checkout Integration Guide
13
Language Encoding for Your Data
This chapter tells you how you can set your Profile preferences to indicate the language and
character encoding that your website uses.
Background Information
Websites that use PayPal in different parts of the world work with different languages. Human
languages are represented in computing by the terms character set and character encoding.
A character set is a computer representation of all the individual possible letterforms or word
symbols of a language. For instance, ASCII (or American Standard Code for Information
Interchange) is a common character set that has been used for decades to represent the
letterforms, numbers, punctuation, and symbols of American English. Another example of a
character set is Big 5, which is one of the most widely implemented Chinese character sets.
Character encoding, on the other hand, refers to how a particular character set is represented
internally in data processing; that is, how the individual characters are actually stored and
operated on. There many different kinds of character encodings. For example, an encoding
might allow 7, 8, or 16 computer bits for a single character.
PayPal refers to these two terms together as language encoding.
Changing Your Language Encoding
This section describes the default character encoding PayPal assumes for you and how you can
change that setting.
With your Language Encoding preferences, you can precisely control the encoding of the
data that PayPal should expect from your website’s use of any PayPal website payment button,
such as Buy Now or Website Payments, and the encoding of the data that your website expects
to receive back from PayPal
Your Default Language Encoding at PayPal Signup
When you sign up for a new business account with PayPal, the PayPal system determines your
character set and its encoding based on your country of origin, as specified by you during
signup. For example, if your postal address indicates France, by default your Selling
Preferences language encoding is set to a Western language character set.
Payment Option: Standard Checkout Integration Guide
May 2005
91
13
Language Encoding for Your Data
Changing Your Language Encoding
Navigating Your Profile: Language Encoding
To see or change the default language encoding for your PayPal Business account, log in to
your account and click the Profile tab.
Click Language Encoding at the bottom Selling Preferences column, as shown in the
following diagram.
FIGURE 13.1Profile Seller Preferences for Language Encoding
92
May 2005
Payment Option: Standard Checkout Integration Guide
Language Encoding for Your Data
Changing Your Language Encoding
13
Changing Your Website Language
The Language Encoding page displays the setting for your website’s language, as shown in
the following illustration. With the Your website’s language drop-down menu, you change
the setting.
FIGURE 13.2Language Encoding Settings: Basic Choices
Payment Option: Standard Checkout Integration Guide
May 2005
93
13
Language Encoding for Your Data
Changing Your Language Encoding
To change the language of data PayPal should expect from your website, click the Your
website’s language drop-down menu and select a different language, as shown in the
illustration Figure 13.3, “Website Language Preference.”
FIGURE 13.3Website Language Preference
Click Save to save your selection or Cancel to to leave the setting unchanged.
94
May 2005
Payment Option: Standard Checkout Integration Guide
Language Encoding for Your Data
Changing Your Language Encoding
13
More Encoding Options
If you know and want to specify the exact standard name of your website’s character
encoding, click More Options on the Language Encoding page to open the More Encoding
Options page shown in “More Language Encoding Options” on page 95.
The More Encoding Options page allows you to specify the character encoding PayPal
should expect from your website and the encoding of data PayPal sends to your website.
FIGURE 13.4More Language Encoding Options
The encoding selection in the Encoding drop-down menu is based on the country of origin
you specified at signup.
To change the encoding selection, click the Encoding drop-down menu and select one of the
available encodings. For a complete list of supported encodings, see “Table 13.1, “Character
Sets and Encodings Supported by PayPal” on page 96.
For data that PayPal should send to you, you have the option to specify the same or a different
encoding. To use the same encoding as your website, click the Yes radio button. To use a
Payment Option: Standard Checkout Integration Guide
May 2005
95
13
Language Encoding for Your Data
Setting Language in Website Payments: charset
different encoding, click the No, use radio button and select the desired encoding from the
associated drop-down menu.
TABLE 13.1 Character Sets and Encodings Supported by PayPal
Big5 (Traditional
Chinese in Taiwan)
EUC-JP
EUC-KR
EUC-TW
gb2312 (Simplified
Chinese)
gbk
HZ-GB-2312
(Traditional Chinese
in Hong Kong)
ibm-862 (Hebrew
with European
characters)
ISO-2022-CN
ISO-2022-JP
ISO-2022-KR
ISO-8859-1
(Western
European
Languages)
ISO-8859-2
ISO-8859-3
ISO-8859-4
ISO-8859-5
ISO-8859-6
ISO-8859-7
ISO-8859-8
ISO-8859-9
ISO-8859-13
ISO-8859-15
KOI8-R
(Cyrillic)
Shift_JIS
UTF-7
UTF-8
UTF-16
UTF-16BE
UTF-16LE
UTF16_Platform
Endian
UTF16_Opposit
eEndian
UTF-32
UTF-32BE
UTF-32LE
UTF32_Platform
Endian
UTF32_Opposit
eEndian
US-ASCII
windows-1250
windows-1251
windows-1252
windows-1253
windows-1254
windows-1255
windows-1256
windows-1257
windows-1258
windows-874 (Thai)
windows-949
(Korean)
x-mac-greek
x-mac-turkish
x-maccentraleurroman
x-mac-cyrillic
ebcdic-cp-us
ibm-1047
Setting Language in Website Payments: charset
In the HTML for your PayPal website payment buttons, such as for Buy Now, Website
Payments, Website Payments Express, you can use the charset HTML variable to specify
the character set or character encoding of the data you collect in your website forms and send
to PayPal. PayPal sends data to you in the same character set or encoding you specify with the
charset variable. For a complete list of the allowable values for the charset variable , see
Table 13.1, “Character Sets and Encodings Supported by PayPal.”
96
May 2005
Payment Option: Standard Checkout Integration Guide
14
Testing
Website Payments, PDT, and IPN
The PayPal Sandbox can be used to test the following functionality.
IMPO RTANT: The
Sandbox does not process real money.
z
Web Payments: Use the Sandbox to test accepting PayPal as a payment mechanism on a
website. For more information, see the PayPal website and online help center.
z
Subscriptions: Use the Sandbox for creating and publishing test/prototype web pages and
other content to which only paying members will have access. For more information, see
the PayPal Subscriptions and Recurring Payments Integration Guide, available on the
PayPal website.
z
Refunds: A PayPal user providing a refund of money paid by another participant in a
transaction.
z
Instant Payment Notifications (IPNs): Use the Sandbox to test such IPNs as payments
and reversals. For more information on implementing IPNs to the PayPal website, see the
Order Management Integration Guide.
In the Sandbox environment, an additional variable (ipn_test) is sent with IPNs, with a
value of 1 (one). The purpose of this variable is to provide clear differentiation between test
and real IPNs. It also allows developers to modify existing scripts so they are easily able to
work with either live or Sandbox IPNs.
IMPO RTANT: IPNs
coming from the Sandbox cannot be verified against the live PayPal
website, and IPNs coming from the live website cannot be verified against the
Sandbox.
z
Payment Data Transfer (PDTs): Use the Sandbox to test using your identity token, return
URL, and PDT settings.
For more information about implementing PDT, see the Order Management Integration
Guide.
z
Simulated transactions: Test difficult scenarios like successful and failed eChecks.
In order to test feature functionality in the Sandbox, you must first create a Developer Central
account. This account will allow you to create multiple PayPal accounts, such as Seller and
multiple Buyer accounts, to simulate different scenarios (unconfirmed, verified, international,
and so on).
Payment Option: Standard Checkout Integration Guide
May 2005
97
14
Testing
Your PayPal Button
Your PayPal Button
Now that you have the HTML code in your website or in your email, you should test it. Click
the link in the email or click the button on your web page. A PayPal-hosted payment page
should appear with payment details you specified.
Because PayPal saves user information in a browser cookie, you will see your own PayPal
username. Your customers will not see your username:
z
If your customer is already a PayPal member, he will see his PayPal username here.
z
If your customer is not yet a PayPal member, he will see a signup page. To view this from
your computer, click the link that says something like “If you are not Bob Smith, Click
Here.”
After testing in the Sandbox, PayPal recommends testing your button implementation with the
live PayPal system. Here’s an easy way to do it:
1. Sign up for a Personal PayPal account if you don’t already have one, and add a credit card
to the account. This will be your “buyer” account.
N O T E : According
to the PayPal User Agreement, you may have both one Personal and one
Premier/Business account. Please do not set up any additional PayPal accounts, as this
may result in your account access being limited.
2. Make sure that your Business/Premier account is Verified. This is your “seller” account.
3. Go to your web browser and click the button you created. Use the login and password for
your buyer account to purchase the item. You can use penny, $.01, transactions and still
refund the entire amount.
4. Check the results of your button test by looking at the emails received by both accounts and
by viewing the History page for each account.
5. Log in to your seller account and refund the payment. To refund a payment, go to the
Transaction Details page and click the Refund Payment link at the bottom of the page.
The refund reverses the entire payment, including transaction fees. You have 60 days to
refund the payment.
This testing method is free of charge and lets you complete the entire process yourself. You
can also have friends or trusted clients buy test items, then refund them, if you would prefer
not to open a second PayPal account.
98
May 2005
Payment Option: Standard Checkout Integration Guide
Testing
Your PayPal Button
14
Testing Tips
You might find the following testing tips useful when testing your buttons.
Testing Tip 1
PayPal recommends starting with one of PayPal’s code samples available at
https://www.paypal.com/ipn under the Code Samples section. There are code samples for the
following development environments.
z
ASP/VBScript
z
ColdFusion
z
ava/JSP
z
PERL
z
PHP
Testing Tip 2
In your Website Payments button HTML code, add or modify the return and rm variables
as follows, replacing the URL with the URL for your website:
<input type=”hidden” name=”return” value=”http://www.mysite.com/ipn.cgi”>
<input type=”hidden” name=”rm” value=”2”>
Then, with your buyer account, click the Website Payments button and complete the
transaction. Once you get to the PayPal Payment Complete page, you can use your browser's
View Source function to view the values of the posted IPN variables at the bottom of the code.
Testing Tip 3
You can put debugging print statements into your IPN script. PayPal recommends creating a
debugging mode of your script that you can turn on and off by adding or removing variable
comments. Set the return variable in your Website Payments button HTML code to point
to your IPN URL. When you complete the payment, the output of your script’s print
statements will be sent to your browser.
Payment Option: Standard Checkout Integration Guide
May 2005
99
14
100
Testing
Your PayPal Button
May 2005
Payment Option: Standard Checkout Integration Guide
and IPN
If you
have
enabled IPN, you will automatically receive notification when the eCheck
clears or fails. For more information about IPN, see the Order Management
Integration Guide.
Payment Option: Standard Checkout Integration Guide
May 2005
101
102
May 2005
Payment Option: Standard Checkout Integration Guide
15
Processing Refunds
You can send a refund to your buyer for 60 days after receiving payment by using the refund
link on the Transaction Details page.
N O T E : Fees
assessed by Business or Premier Account receiving payments can be reimbursed
only if the refund link on the Transaction Details page is used.
If it has been more than 60 days since you received the payment, you should send the refund
using Send Money.
Refunding Within 60 Days of Payment
To send a refund within 60 days of receiving payment:
1. Log in to your PayPal account.
2. Click the History subtab.
3. Find the payment you would like to refund.
4. Click Details to open the Transaction Details page.
5. Click the Refund Payment link on the Transaction Details page.
6. Enter the refund amount and click Submit.
7. Confirm the refund amount and click Submit.
Refunding After 60 Days
To send a refund 60 or more days after receiving payment:
1. Log in to your PayPal account.
2. Click the Send Money tab.
3. Enter the required information.
4. Click Continue.
5. Review the information on the confirmation page and click Send Money to complete your
transaction.
The original transaction fee will be credited back to you when you perform a refund. If you
perform a partial refund, a portion of the transaction fee will be credited back to you.
Payment Option: Standard Checkout Integration Guide
May 2005
103
Processing Refunds
Sending Partial Refunds
Sending Partial Refunds
You can send a partial refund to your buyer for 60 days after receiving payment by using the
refund link on the Transaction Details page. The partial refund will be deducted from your
PayPal account balance or sent to the buyer in the form of an eCheck.
N O T E : If
the buyer denies your partial refund offer, you can offer another refund. Only one
partial refund is allowed.
To send a partial refund:
1. Log in to your PayPal account.
2. Click the History subtab.
3. Find the payment you would like to refund.
4. Click Details to open the Transaction Details page.
5. Click the Refund Payment link on the Transaction Details page
6. Enter the partial refund amount and click Submit.
7. Confirm the partial refund amount and click Process Refund.
104
May 2005
Payment Option: Standard Checkout Integration Guide
16
Security
Notification Validation
Notification validation is the process you use to validate your IPN data. For more information
about Notification Validation, see the Order Management Integration Guide.
Button Encryption
If you choose Button Encryption in the Button Factory, which is the default value, your
website payments will be secure, thus both you and your customers remain protected. PayPal
automatically encrypts your confidential information using the Secure Sockets Layer (SSL)
protocol with an encryption key length of 128 bits (the highest level commercially available).
N O T E : PayPal
highly recommends encrypting your button code; however, doing so has three
limitations:
1. Encrypted button HTML is not editable. If you want tp modify your button code manually,
select No for this option.
2. You will not be able to encrypt your button if it has dynamically-generated code from the
Add More Options page, such as drop-down Options fields (see step 5). If you need
Option fields for your products, select No to turn encryption off.
3. If you choose to encrypt your button, you will not be able to create an email link.
Payment Option: Standard Checkout Integration Guide
May 2005
105
16
Security
Multi-User Access
Multi-User Access
PayPal’s Multi-User Access feature allows you to set up multiple logins and give others
different levels of access to your PayPal account, so your employees have access onlyto the
parts of your Paypal account that they need to complete their jobs. For example, use MultiUser Access to provide your customer service representatives with their own login with
limited permissions, so that they only have the ability to view balances and perform refunds,
but not the ability to edit profiles, send money, withdraw funds, and so on.
Using the Multi-User Access feature, you can give your employees access to any combination
of the following PayPal Account features:
106
z
Send Money
z
Mass Payments- U.S. Accounts only
z
Request Money
z
Add Funds
z
Refunds
z
BillPay-U.S. Accounts only
z
Withdraw Funds
z
Cancel Payments
z
View Balance
z
View Profile
z
Edit Profile
z
Settlement File
z
Scheduled Downloads Log
z
API Activation and Authorization
May 2005
Payment Option: Standard Checkout Integration Guide
Security
Multi-User Access
16
Getting Started
To use Multi-User Access:
1. Log in to your PayPal Business account.
2. Go to your Profile and click the Multi-User Access link.
3. Specify your Administrative Contact email address, which is the email address that will
receive notifications about your account activity.
4. Add up to nine separate logins to your account. For each login, select a User ID and
password, and specify what account privileges the user has permission to access (e.g.
Refunds, Send and Request Money).
You might want to establish a separate username and password for each employee who
accesses your PayPal account, and grant each user the minimum access necessary. If an
employee forgets or loses a password, you can always log in and reset it.
N O T E : Remember
to revoke privileges of any employee that leaves the company.
5. You can create additional logins, edit an existing user’s privileges, or delete a login at
anytime from your Profile.
Payment Option: Standard Checkout Integration Guide
May 2005
107
16
Security
Using Secure Socket Layer (SSL)
Using Secure Socket Layer (SSL)
If you have contracted with a third-party hosting provider to operate your website, PayPal
recommends contacting your provider to find out if you already have SSL capabilities or if
you need to have SSL installed. Most hosting providers can activate SSL for your hosting
account.
If you run your own web server, you will need to acquire and install your own SSL
certificates.
The following information and resources are useful for implementing SSL.
General Information
z
Installing on Apache and Microsoft IIS web servers: http://www.thawte.com/guides
z
Windows Server 2003:
http://www.microsoft.com/resources/documentation/windowsserv/2003/all/deployguide/enus/iisdg_mea_nfmd.asp
z
Apache: http://www.apache-ssl.org and http://modssl.org
SSL Certificate Providers
108
z
Verisign: http://www.verisign.com
z
GeoTrust: http://www.geotrust.com
May 2005
Payment Option: Standard Checkout Integration Guide
A
Country Codes
ISO 3166 Standard Country Codes
PayPal relies on two-character country codes defined by International Standards Organization
(ISO) 3166.
TABLE A.1
ISO 3166 Two-Character Country Codes
Country
Code
Anguilla
AI
Argentina
AR
Australia
AU
Austria
AT
Belgium
BE
Brazil
BR
Canada
CA
Chile
CL
China
CN
Costa Rica
CR
Denmark
DK
Dominican Republic
DO
Ecuador
EC
Finland
FI
France
FR
Germany
DE
Greece
GR
Hong Kong
HK
Iceland
IS
India
IN
Ireland
IE
June 2005
109
A
Country Codes
ISO 3166 Standard Country Codes
TABLE A.1
110
ISO 3166 Two-Character Country Codes
Country
Code
Israel
IL
Italy
IT
Jamaica
JM
Japan
JP
Luxembourg
LU
Malaysia
MY
Mexico
MX
Monaco
MC
Netherlands
NL
New Zealand
NZ
Norway
NO
Portugal
PT
Singapore
SG
South Korea
KR
Spain
ES
Sweden
SE
Switzerland
CH
Thailand
TH
Taiwan
TW
Turkey
TR
United Kingdom
GB
United States
US
Uruguay
UY
Venezuela
VE
June 2005