PFP ExpressCheckout PP

Express Checkout for
Payflow Pro
For Professional Use Only

Currently only available in English.
A usage Professional Uniquement

Disponible en Anglais uniquement pour l’instant.
Last updated: April 2009

Express Checkout for Payflow Pro
Document Number: 200042.en_US-200904
© 2009 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard
Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349.
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How to Contact Customer Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Document History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1 Express Checkout Processing Flow . . . . . . . . . . . . . 9

What Is Express Checkout? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
How Express Checkout Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Express Checkout Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Express Checkout ACTION Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Express Checkout Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Express Checkout Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . 12
Set Express Checkout (ACTION=S) . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Redirecting the Customer to PayPal Example. . . . . . . . . . . . . . . . . . . . . . 13
Get Express Checkout Details (ACTION=G) . . . . . . . . . . . . . . . . . . . . . . 14
Redirecting the Customer to Your Website Example . . . . . . . . . . . . . . . . . . 15
Do Express Checkout Payment (ACTION=D) . . . . . . . . . . . . . . . . . . . . . . 15
Other Express Checkout Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Obtaining the Buyer’s Telephone Number During Checkout . . . . . . . . . . . . . . 16
Pending Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2 Express Checkout Recurring Payments . . . . . . . . . . . 19

Creating Multiple Billing Agreement Descriptions . . . . . . . . . . . . . . . . . . . . . . 19
Creating a Single Billing Agreement Description. . . . . . . . . . . . . . . . . . . . . . . 20
Example of Creating a Billing Agreement Description . . . . . . . . . . . . . . . . . . . . 20
Chapter 3 PayPal Button Placement and Page Designs . . . . . . . . 23

HTML for PayPal Button Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Design Variation: Eliminating Your Order Review Page . . . . . . . . . . . . . . . . . . . 25
Payment Method Page Layout Recommendations . . . . . . . . . . . . . . . . . . . . . 26
Express Checkout for Payflow Pro 3

Contents
Chapter 4 Express Checkout Transaction Types . . . . . . . . . . . . 27

Honor Period and Authorization Period . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Payment Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Sale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Do Reauthorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Do Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Delayed Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Complete Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Partial Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Chapter 5 Transaction Responses . . . . . . . . . . . . . . . . . . . 35

Response Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 36
Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Normalized Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
PayPal Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
PNREF Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
PNREF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
RESULT Values for Transaction Declines or Errors . . . . . . . . . . . . . . . . . . . 39
Chapter 6 Express Checkout Testing . . . . . . . . . . . . . . . . . 45

Testing Your Integration Using the Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . 45
Create A Business Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Create a Payflow Test Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Link Your Payflow Pro Account to the Sandbox . . . . . . . . . . . . . . . . . . . . . 46
Testing Your Integration Using the PayPal Simulator . . . . . . . . . . . . . . . . . . . . 47
Appendix A Express Checkout Parameter Reference . . . . . . . . . . 49

Connection Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
User Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Express Checkout Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . 51
4 Express Checkout for Payflow Pro

Contents
Set Express Checkout Request Parameter Descriptions . . . . . . . . . . . . . . . . 51

Set Express Checkout Response Parameter Descriptions . . . . . . . . . . . . . . . 57
Get Express Checkout Details Request Parameter Descriptions . . . . . . . . . . . . 58
Get Express Checkout Details Response Parameter Descriptions . . . . . . . . . . . 58
Do Express Checkout Payment Request Parameter Descriptions . . . . . . . . . . . 62
Do Express Checkout Payment Response Parameter Descriptions . . . . . . . . . . 66
Do Authorization Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Do Reauthorization Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . 68
Void Parameter Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Credit Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Delayed Capture Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Appendix B Currency Codes . . . . . . . . . . . . . . . . . . . . . . . 73
Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . . 75
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Contents

Preface
Intended Audience
This guide assumes that its readers:
z Are experienced web or application developers
z Have a background in payments services
z Are developing payment services applications that are integrating Express Checkout to
process transactions to be sent over the Payflow gateway
Related Documentation
For additional information on Payflow documentation and the Payflow SDK, go to
http://www.paypal.com/developer, select Documentation from the Library tab, and click the
Payflow Pro link.
How to Contact Customer Support

For problems with transaction processing or your connection to the server, contact Customer
Support by opening a ticket on the under Contact Support tab at http://www.paypal.com/mts.
Document History
TABLE 1.1 Document history
Date Description
April 2009 Added creating billing agreements for setting up Recurring Payments
through Express Checkout.
Added order line-item details parameters.
Updated with PHONENUM parameter in Set Express Checkout
request.

Document History

1 Express Checkout Processing
Flow
This chapter describes Express Checkout processing:

z What Is Express Checkout?
z How Express Checkout Works
z Express Checkout Flow
z Express Checkout Sale Transaction Example
z Other Express Checkout Concepts
What Is Express Checkout?

Express Checkout is PayPal’s method of payment. It offers your customers an easy, convenient
checkout experience by letting them use shipping and billing information stored securely at
PayPal to check out, so they don’t have to re-enter it on your website.
Like other Payflow transactions, Express Checkout transaction requests send data as name-
value pair parameters, and include this basic set of required parameters:
z Connection parameters
z User parameters
z Transaction type (TRXTYPE) such as Sale (TRXTYPE=S), Authorization (TRXTYPE=A), or
Order (TRXTYPE=0)
z Tender type, which is always PayPal (TENDER=P)
How Express Checkout Works

The figure below summarizes the Express Checkout flow.

Express Checkout Processing Flow
1
How Express Checkout Works
FIGURE 1.1 Express Checkout flow
The figure shows a typical set of web pages representing your merchant website. The PayPal
logo is used by the customer to choose PayPal as their method of payment. Express Checkout
gives you the flexibility to place the PayPal logo at the start of checkout and later on your
billing page with other payment options.
The web page layout may differ somewhat from your own web design, but the integration
points at which the Express Checkout calls are made and customer redirection to PayPal and
back to your website are important to understand. The events that take place at each number in
the figure are described below:

1
Express Checkout Flow
1. On your website, your customer clicks the PayPal button to check out. This customer
action triggers the call to the Set Express Checkout request.
2. The server responds to the request by returning a token or string value to your website. In
the previous figure, the token is represented by an orange “donut.” The token keeps track of
your customer throughout the checkout process.
3. You direct your customer to the PayPal site, where they log in, select a funding source, and
confirm contact and shipping information. Express Checkout includes parameters that you
can use to customize the PayPal pages so they match characteristics of your own website.
For example, you can provide your own logo and colors.
4. When your customer clicks the “Continue” button, PayPal sends them back to your site at
the return URL you specified in the Set Express Checkout request. The token is appended
to the URL to identify the customer.
5. Optionally you can send the Get Express Checkout Details request to obtain details about
your customer such as the customer’s telephone number and shipping address. You send
the token to identify the customer. The server returns the requested information.
6. When your customer clicks the “Pay” button, you send the Do Express Checkout Payment
request to perform the actual payment transaction.
7. The server returns the transaction result.
Express Checkout Flow

Through a set of name-value pair parameters, you provide Express Checkout transaction data
to the server. The server responds with RESULT and RESPMSG values, along with other
response parameter data about the transaction.
Unlike most Payflow Pro transactions, which consist of a single request call, Express
Checkout is a three-step process where the second step is optional:
1. Set Express Checkout sets up the data about the transaction at hand such as a Sale and
controls what is displayed to the customer on the PayPal site when the customer chooses
PayPal at checkout.
2. Get Express Checkout Details is an optional request enabling you to obtain this information
for display on your own website.
3. Do Express Checkout Payment performs the actual money transfer.
This guide refers to this request sequence and the resulting customer experience as the Express
Checkout flow.

1
Express Checkout Sale Transaction Example
Express Checkout ACTION Values

To identify each request in the Express Checkout flow, you pass the appropriate ACTION
parameter. The table below shows the value of ACTION for each Express Checkout request.
TABLE 1.1 ACTION values for Express Checkout
Request ACTION value

Set Express Checkout ACTION=S
Get Express Checkout Details ACTION=G
Do Express Checkout Payment ACTION=D
Express Checkout Token

The TOKEN value returned in the response to Set Express Checkout associates the customer
with this particular Express Checkout flow. You pass it back to the server in these Express
Checkout requests:
z In the HTTP request to redirect the customer’s browser to the PayPal web site
z In the Get Express Checkout Details request to obtain the customer’s hipping information
z In the Do Express Checkout Payment request to carry out the transaction

This section describes the Express Checkout flow in greater detail using a Sale transaction as
the example. See Appendix A, “Express Checkout Parameter Reference,” for detailed
descriptions of all required and optional Express Checkout transaction parameters.
z Set Express Checkout (ACTION=S)
z Redirecting the Customer to PayPal Example
z Get Express Checkout Details (ACTION=G)
z Redirecting the Customer to Your Website Example
z Do Express Checkout Payment (ACTION=D)
Set Express Checkout (ACTION=S)

The Set Express Checkout request passes the transaction details from your website to PayPal
when a customer chooses to pay with PayPal.
Set Express Checkout requires that you pass data for the following parameters.
z ACTION
z AMT

1
z RETURNURL
z CANCELURL
This is an example Set Express Checkout request parameter string for a Sale transaction:
"TRXTYPE=S
&ACTION=S
AMT=35.00
&CANCELURL=http://www.order_page.com
&CUSTOM=TRVV14459
&EMAIL=buyer_name@abc.com
&PARTNER=partner
&PWD=password
&RETURNURL=http://www.confirmation_page.com
&TENDER=P
&USER=user
&VENDOR=vendor"
N O T E : It
is strongly recommended that RETURNURL be the URL of the final review page on
your website where the customer confirms the order and payment. Likewise,
CANCELURL should be the URL of the original page on your website where the
customer initially chose to use PayPal.
This is a response to the request.
RESULT=0&RESPMSG=Approved&TOKEN=EC-17C76533PL706494P
RESULT and RESPONSE values are returned with all transactions. In a successful response, the
value of RESULT is 0. For details on the set of response parameters generally passed back in
transactions, see Chapter 5, “Transaction Responses.” The TOKEN value returned associates
this customer with this particular Express Checkout flow.
Redirecting the Customer to PayPal Example

After your buyer clicks the PayPal button and you submit the Set Express Checkout request,
you will want to automatically direct your customer to the PayPal website. The redirect URL
for this is:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=<TOKEN>
TOKEN is the value returned in the Set Express Checkout response.
N O T E : ExpressCheckout has a variation on this redirect URL (called useraction) that allows
you to bypass the call to Get Express Checkout Details and to change the text of the
button displayed on the PayPal website from “Continue” to “Pay.” For more
information, see “Design Variation: Eliminating Your Order Review Page” on page 25.
PayPal recommends that you use the HTTPS response 302 “Object Moved” with your URL as
the value of the Location header in the HTTPS response. Alternately, you can generate a web
page for your buyer that includes a META REFRESH tag in the header. An example is shown
below. Remember to replace <TOKEN> with the token value that you received in the Set
Express Checkout response.

1
The following example uses the META REFRESH tag.

<html>
<head>
<META HTTP-EQUIV="Refresh"CONTENT="0;URL=https://www.paypal.com/cgi-
bin/webscr?cmd=_express-checkout&token=<TOKEN>">
</head>
<body>


<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_express-
checkout&token=<TOKEN>"Click here if you are not redirected to PayPal within 5
seconds.</a>
</body>
</html>
Get Express Checkout Details (ACTION=G)

The Get Express Checkout Details request enables you to retrieve the customer’s billing
information, such as the shipping address and email address. If you use Get Express Checkout
Details, you need to pass data for these parameters.
z ACTION
z TOKEN
The following is an example Get Express Checkout Details request parameter string:
"TRXTYPE=S
&VENDOR=vendor
&USER=user
&PWD=pwd
&TENDER=P
&PARTNER=partner
&ACTION=G
&TOKEN=EC-17C76533PL706494P"
The following is the Get Express Checkout Details response.

1
RESULT=0
&RESPMSG=Approved
&AVSADDR=Y
&TOKEN=EC-17C76533PL706494P
&PAYERID=FHY4JXY7CV9PG
&EMAIL=buyer_name@aol.com
&PAYERSTATUS=verified
&CUSTOM=TRVV14459
&FIRSTNAME=Chris
&LASTNAME=Alexander
&BUSINESS=Monroe Creek Regional Interiors
&SHIPTOSTREET=5262 Green Street #8
&SHIPTOCITY=San Jose
&SHIPTOSTATE=CA
&SHIPTOZIP=95148
&SHIPTOCOUNTRY=US
Redirecting the Customer to Your Website Example

PayPal redirects the customer back to your website at the location you specified in the
RETURNURL parameter to Get Express Checkout request. To the URL string, PayPal appends
the TOKEN and PAYERID name-value pairs, as shown below:
http://[RETURNURL]/?token=<TOKEN>&PayerID=<PAYERID>
You need to pass the PAYERID in the Do Express Checkout Payment request.
Do Express Checkout Payment (ACTION=D)

The Do Express Checkout Payment request performs the actual money transfer of the Sale
transaction.
Do Express Checkout Payment request requires that you pass data for these parameters.
z ACTION
z TOKEN
z PAYERID
z AMT
The following is an example Do Express Checkout Payment request parameter string:

1
Other Express Checkout Concepts
"TRXTYPE=S
&VENDOR=vendor
&USER=user
&PWD=pwd
&TENDER=P
PARTNER=partner
&ACTION=D
&AMT=35.00"
The following is an example response:
RESULT=0
&PNREF=EFHP0CDBF5C7
&RESPMSG=Approved
&AVSADDR=Y
&PPREF=2P599077L3553652G
&PAYMENTTYPE=instantonly
The response returns a 12-character PNREF (Payflow Transaction ID) that is used to identify
this transaction in PayPal Manager reports.

The following topics are related to processing Express Checkout transactions.
z Obtaining the Buyer’s Telephone Number During Checkout
z Pending Responses
Obtaining the Buyer’s Telephone Number During Checkout

You have three options regarding the buyer’s contact telephone number. You can choose to:
z Not request the contact telephone number (default)
z Request the contact telephone number as an optional field
z Require that the buyer enter their contact telephone number to proceed.
To choose how you want to handle the buyer’s contact telephone number:
1. Log in to your PayPal account.
2. From the Profile tab, click Website Payments Preferences.
3. Choose from the three options for handling the contact telephone number at the bottom of
the page.

1
If you choose to require the buyer provide a telephone number, a telephone number displays in
the Contact Information on the PayPal Review page during checkout. Help text tells the buyer
how to change the number displayed to their own number.
Pending Responses
If the Do Express Checkout Payment PENDINGREASON response is a value other than none or
completed, the payment is pending. Typically, this means the customer has paid with an
eCheck. In such a case, funds are not guaranteed, and you should not ship or deliver items or
services until the payment has successfully completed.
N O T E : PayPal
recommends that you block eChecks as a payment method if you are unable to
handle pending state payments.
To find out the status of a pending payment, you can:
z Submit an Inquiry transaction.
z Check the status using PayPal Manager. See PayPal Manager online help for details.

1

2 Express Checkout Recurring
Payments
This chapter describes how to bill the buyer’s PayPal account on a recurring basis. As a
prerequisite, you need to set up a billing agreement description.
z Creating Multiple Billing Agreement Descriptions
z Creating a Single Billing Agreement Description
z Example of Creating a Billing Agreement Description
Creating Multiple Billing Agreement Descriptions

To set up multiple recurring payments billing agreement descriptions, pass the following
parameter information in the Set Express Checkout request.
TABLE 2.1 Set Express Checkout fields for recurring payments
Parameter Notes
L_BILLINGTYPEn Type of billing agreement. For recurring payments, the

value must be RecurringPayments. One
L_BILLINGTYPEn must correspond to each
L_BILLINGAGREEMENTDESCRIPTIONn in the Set
Express Checkout request.
L_BILLINGAGREEMENTDESCRIPTIONn Description of goods or services. You can pass up to a

maximum of ten different billing agreement description
strings, each of which can be used later to create a
unique recurring payments profile.
N O T E : You must pass the same L_BILLINGAGREEMENTDESCRIPTIONn string later in the

call to create a recurring payments profile for that billing agreement description. See
the Website Payments Pro Payflow Edition - Recurring Payments Developer’s Guide
for details on creating and managing recurring payments profiles.
The Set Express Checkout response returns a TOKEN that can be passed in subsequent requests
to Get Express Checkout Details and Do Express Checkout Payment in the Express Checkout
flow, as described in “Express Checkout Processing Flow” on page 9.
You can also pass the TOKEN returned as a parameter in the request to create a recurring
payments profile, along with the following parameters:
z One of the L_BILLINGAGREEMENTDESCRIPTIONn strings
z TENDER type P to identify the recurring payments as billing a PayPal account

Express Checkout Recurring Payments
2
Creating a Single Billing Agreement Description
Thereafter, you can bill the buyer’s PayPal account on a regular basis as well as mix recurring
payments with one-time purchases the buyer makes in the Express Checkout flow. The
advantage of passing L_BILLINGAGREEMENTDESCRIPTIONn strings is that you can use the
same TOKEN with each of the other L_BILLINGAGREEMENTDESCRIPTIONn strings passed to
Set Express Checkout to create up to ten different recurring payments profiles.
Creating a Single Billing Agreement Description

To create a single billing agreement description, you can pass the following parameters in the
call to Set Express Checkout.
TABLE 2.2 Set Express Checkout fields for recurring payments
Parameter Notes
BILLINGTYPE Type of billing agreement. For recurring payments, the

value must be RecurringPayments.
BA_DESC String value describing the merchandise or services.
Pass the Set Express Checkout response TOKEN along with the BA_DESC string and TENDER
type P in the request to create a single recurring payments profile.
Example of Creating a Billing Agreement Description

The following Set Express Checkout example returns a TOKEN that can be used to create two
recurring payments profiles.
See Website Payments Pro Payflow Edition Recurring Payments Developer’s Guide for an
example of how to create a recurring payments profile for the PayPal account. The TOKEN
returned (EC-5FA74536B1724550T) can be used to create a profile for each of the billing
agreement descriptions, below.

2
Set Express Checkout Request

"TRXTYPE=A
&USER=mytest01
&TENDER=P
&PARTNER=partner
&VENDOR=mytest01
&PWD=pwd
&ACTION=S
&AMT=10.00
&RETURNURL=http://...
&CANCELURL=http://...
&CURRENCY=USD
&L_BillingType0=RecurringPayments
&L_BillingAgreementDescription0=Time magazine
&L_BillingType1=RecurringPayments
&L_BillingAgreementDescription1=Newsweek magazine
&FIRSTNAME=J
&LASTNAME=Smith
&SHIPTOCITY=San Jose
&SHIPTOCOUNTRY=USA US
&SHIPTOFIRSTNAME=J
&SHIPTOLASTNAME=Smith
&SHIPTOSTATE=CA
&SHIPTOSTREET=1 Main St
&SHIPTOZIP=95131
&paymenttype=any"
Set Express Checkout Response
RESULT=0
&RESPMSG=Approved
&TOKEN=EC-5FA74536B1724550T
&CORRELATIONID=e8f1f97944872

2

3 PayPal Button Placement and
Page Designs
When you offer PayPal Express Checkout to your customers, PayPal recommends that you
display it in two forms for your customers’ best buying experience:
z PayPal as a checkout choice on your shopping cart page
z PayPal as a payment method
Table 3.1 summarizes these guidelines.
TABLE 3.1 PayPal Button Placement Guidelines
PayPal Button
Graphic Placement Requirements
At the beginning of checkout Align the PayPal Checkout button on your

as a checkout choice shopping cart page with any other checkout
buttons
At the end of checkout as a Place the PayPal Acceptance mark:

payment method option z On your Payment Billing page
z On your home page, along with credit
card logos, if applicable
PayPal button graphics and placement topics below include:

z HTML for PayPal Button Graphics
z Design Variation: Eliminating Your Order Review Page
z Payment Method Page Layout Recommendations
HTML for PayPal Button Graphics

You can get HTML for the Express Checkout button and PayPal Acceptance Mark from the
following location: https://www.paypal.com/express-checkout-buttons
Rather than storing the button graphics on your own server, reference the PayPal image paths
on the PayPal website. This ensures that you are always displaying the most up-to-date logos.

PayPal Button Placement and Page Designs
3
Examples of Button Placement
Examples of Button Placement

Below are two examples of proper PayPal button graphic placement within the context of web
pages.
Figure 3.1 places the PayPal button graphic as a checkout choice.
FIGURE 3.1 PayPal as a Checkout Choice

3
Design Variation: Eliminating Your Order Review Page
Figure 3.2 places the PayPal mark as a payment method with other payment methods.
FIGURE 3.2 PayPal Mark as a Payment Method
Design Variation: Eliminating Your Order Review Page

You can make checkout appear to complete on the PayPal website rather than on your own
and, therefore, eliminate the need for an order review page on your site. (Of course, when the
customer returns from PayPal, you still call the Do Express Checkout Payment request to
complete the transaction.) In this situation, you would want the button text on PayPal to appear
as “Pay” rather than “Continue.”
You control the button text through the value of the useraction variable. You set this
variable on the PayPal URL to which you redirect the buyer after calling Set Express
Checkout.
Values and resulting button text are described below:

3
Payment Method Page Layout Recommendations
z If you do not set useraction or you set useraction continue, PayPal displays the
button text “Continue Checkout.”
z If you set useraction to commit, PayPal displays the button text “Pay.”
To display the “Pay” button text, for example, append &useraction=commit to the redirect
URL string as shown below where tokenvalue is the token value returned in the Set Express
Checkout response.
"https://www.paypal.com/cgi-bin/webscr?cmd=_express-
checkout&token=tokenvalue&useraction=commit"
Payment Method Page Layout Recommendations

When you display the PayPal Acceptance mark with other payment methods, you have several
designs to choose from:
z As a radio button
z As horizontal field options
z In a dropdown list
IMPO RTANT: Do not preselect any payment method. Allow the customer to make a choice
without any default.
The figures below illustrate each of these layouts.
FIGURE 3.3 As a Radio Button
FIGURE 3.4 As Horizontal Field Options
FIGURE 3.5 In a Dropdown List

4 Express Checkout Transaction
Types
The Payflow gateway supports transaction types (TRXTYPE) for obtaining payment during the
Express Checkout flow as well as for managing the capture of payments after the Express
Checkout flow.
z Honor Period and Authorization Period
z Payment Transaction Types
z Sale
z Authorization
z Order
z Do Reauthorization
z Do Authorization
z Delayed Capture
z Void
z Credit
Honor Period and Authorization Period

Your business may not be able to provide immediate fulfillment of a product or service. An
item, for example, may not be immediately available to ship because it is temporarily out of
stock. Under these circumstances, you can have the buyer approve of placing a 29-day hold or
authorization period on their balance for the amount of the authorization to ensure funds are
available for capture.
After a successful authorization, PayPal honors the authorized funds for a three-day honor
period. You can extend the honor period once with a Do Reauthorization or multiple times
with a Do Authorization.
Payment Transaction Types

During the Express Checkout flow, the following transaction types are supported:
z Sale (TRXTYPE=S)
z Authorization (TRXTYPE=A)
z Order (TRXTYPE=O)

Express Checkout Transaction Types
4
Sale
After the Express Checkout flow, you can manage the capture of payment using the following
transaction types:
z Do Reauthorization (TRXTYPE=A)
z Do Authorization (TRXTYPE=A)
z Delayed Capture (TRXTYPE=D)
z Void (TRXTYPE=V)
z Credit (TRXTYPE=C)
Sale
A Sale transaction charges the specified amount against the account, and marks the transaction
for immediate fund transfer.
Use a Sale transaction when you can fulfill an order immediately and you know the final
amount of the payment at the time you send the Do Express Checkout Payment Details
request. A Sale is appropriate, for example, if you have the items in stock for immediate
shipment.
To set up a Sale, set these parameters in the Set Express Checkout, Get Express Checkout
Details, and Do Express Checkout Payment requests:
z Set Express Checkout request: TRXTYPE=S, ACTION=S
z Get Express Checkout Details request (optional): TRXTYPE=S, ACTION=G
z Do Express Checkout Payment request: TRXTYPE=S, ACTION=D
After you send the Do Express Checkout Payment request for a Sale transaction, which returns
a RESULT value of 0 (success), the payment is complete and no further action is necessary.
You cannot capture a further payment or void any part of the payment.
For a detailed example of a Sale transaction, see Express Checkout Sale Transaction Example.
Authorization
An Authorization transaction represents an agreement to pay. It places the buyer’s funds on
hold for a three-day honor period is valid for 29 days. It does not transfer funds.
If your business does not provide immediate fulfillment of products or services, an
Authorization enables you to capture funds with a Delayed Capture transaction when back-
ordered merchandise, for example, does become available. You can capture up to the
authorized amount specified in the original Authorization transaction.
If you are still not able to complete the Authorization and Delayed Capture within the 29-day
period, you can perform a one-time extension of the Authorization using a Do
Reauthorization. Merchants get around these limitations by choosing to perform an Order

4
Order
transaction instead of an Authorization. Orders provide greater flexibility with fewer time
constraints when handling products or services that not immediately available.
An Authorization uses the same parameters as a Sale transaction except that TRXTYPE is A.
See Express Checkout Sale Transaction Example for details.
To set up an Authorization, set these parameters in the Set Express Checkout, Get Express
Checkout Details, and Do Express Checkout Payment requests:
z Set Express Checkout request: TRXTYPE=A, ACTION=S
z Get Express Checkout Details request (optional): TRXTYPE=A, ACTION=G
z Do Express Checkout Payment request: TRXTYPE=A, ACTION=D
Note the value of PNREF in the Do Express Checkout Payment response, for example:
RESULT=0
&PNREF=EFHP0CDBF5C7
&RESPMSG=Approved
&PPREF=2P599077L3553652G
To capture authorized funds, you use the PNREF to reference the original Authorization
transaction. See Delayed Capture for details.
Order
An Order transaction represents an agreement to pay one or more authorized amounts up to
the specified total over a maximum of 29 days.
Orders provide you with greater flexibility in delivering merchandise than Authorizations. You
should use an Order when a Sale or an Authorization with a single Do Reauthorization do not
meet your needs. Situations in which Orders are appropriate include the handling of the
following:
z Back orders, in which you send available merchandise immediately and the remaining
merchandise, as it is available
z Split orders, in which you send merchandise in more than one shipment—perhaps to
different addresses—and you want to collect a payment for each shipment
z Drop shipments, or shipments from other vendors, for which you accept the payment
To create multiple authorizations of the Order over the 29-day period, use the Do
Authorization transaction. Each Do Authorization places the buyer’s funds on hold for up
to three days. If the three-day honor period or the valid authorization period expires, simply
create another Do Authorization.
To set up an Order,
1. Set TRXTYPE=O in the Set Express Checkout, Get Express Checkout Details, and Do
Express Checkout Payment requests in your Express Checkout flow.

4
Do Reauthorization
– Set Express Checkout request: TRXTYPE=O, ACTION=S

– Get Express Checkout Details request (optional): TRXTYPE=O, ACTION=G
– Do Express Checkout Payment request: TRXTYPE=O, ACTION=D
2. Note the value of PNREF in the Do Express Checkout Payment response, for example:
RESULT=0
&PNREF=EFHP0CDBF5C7
&RESPMSG=Approved
&PPREF=2P599077L3553652G
To capture an Order, you must first authorize it.
1. To authorize the Order, set ORIGID=PNREF (PNREF value returned in original Order
response) and TRXTYPE=A in a Do Authorization transaction request, for example:
"TRXTYPE=A
&TENDER=P
&PARTNER=partner
&USER=user
&VENDOR=vendor
&PWD=pwd
&ORIGID=EFHP0CDBF5C7"
This is the Do Authorization response:
RESULT=0
&PNREF=EFHP0CDCG6C8
&RESPMSG=Approved
&PPREF=3Q600078M3553652G
2. To capture the Do Authorization, set ORIGID=PNREF (PNREF returned in the Do

Authorization response) and TRXTYPE=D, for example:
"TRXTYPE=Dcg&TENDER=P&PARTNER=partner&USER=user&VENDOR=vendor&PWD=pwd&OR
IGID=EFHP0CDBF6C8"
Do Reauthorization
To reauthorize an Authorization for an additional three-day honor period, you can use a Do
Reauthorization transaction. A Do Reauthorization can be used at most once during the 29-day
authorization period.
To set up a Do Reauthorization, you must pass the following parameters in the request string:
z Set ORIGID=PNREF (PNREF returned in the original Authorization response)
z Set TRXTYPE=A
z Set DoReauthorization=1
This is an example Do Reauthorization request string with required parameters:

4
Do Authorization
"TRXTYPE=A
&TENDER=P
&PARTNER=partner
&USER=user
&VENDOR=vendor
&PWD=pwd
&ORIGID=EFHP0CDBF5C7
&DOREAUTHORIZATION=1"
Do Authorization
A Do Authorization transaction represents an agreement to pay and places the buyer’s funds
from the original Order transaction on hold for up to three days. It does not transfer funds.
N O T E : You
can only use Do Authorization if the original transaction in the Express Checkout
flow is an Order. You cannot use Do Reauthorization against a Do Authorization.
To set up a Do Authorization, you must pass the following parameters in the request string:
z Set ORIGID=PNREF (PNREF value returned in the original Order transaction response
only)
N O T E : Do
not pass the PPREF returned from the original Order transaction in place of the
PNREF.
z Set TRXTYPE=A
In this example, the PNREF returned in the original Order response is EFHP0CDBF7D9. This is
the Do Authorization request string:
"TRXTYPE=A
&TENDER=P
&PARTNER=partner
&USER=user
&VENDOR=vendor
&PWD=pwd
&ORIGID=EFHP0CDBF7D9"
Delayed Capture
A Delayed Capture transaction captures authorized funds and transfers them to PayPal. Once a
capture is approved, you will see the funds in your PayPal account.
You can capture up to the amount specified in the original Authorization.

4
Delayed Capture
Complete Capture
To set up a capture of the total amount in the original Authorization, you must pass the
following parameters in the Delayed Capture request string:
z Set ORIGID=PNREF (PNREF value returned in the original Authorization, Do
Authorization, or Do Reauthorization transaction response)
z Set TRXTYPE=D
This is an example Delayed Capture request string with required parameters.
"TRXTYPE=D
&TENDER=P
&PARTNER=partner
&USER=user
&VENDOR=vendor
&PWD=pwd
Partial Capture
To set up a partial capture of authorized funds, pass the following parameters in the Delayed
Capture request string:
z Set ORIGID=PNREF (PNREF value returned in the original Authorization, Do
Authorization, or Do Reauthorization transaction response)
z Set TRXTYPE=D
z Set the value for AMT
z Set CAPTURECOMPLETE=N to perform a partial capture; set CAPTURECOMPLETE=Y to void
any remaining amount of the original authorized transaction
This example is based on an initial Authorization for $100. You charge $66 for the first partial
shipment using a Delayed Capture transaction. You charge the $34 for the final part of the
shipment using a second Delayed Capture transaction.
1. Capture the authorized funds for a partial shipment of $66.
"TRXTYPE=D
&TENDER=C
&PWD=SuperUserPassword
&PARTNER=PayPal
VENDOR=SuperMerchant
USER=SuperMerchant
&CAPTURECOMPLETE=N
&ORIGID=EFHP0D426A51
&AMT=66.00"
2. Once you have shipped the remainder of the merchandise, capture the $34 balance.
TRXTYPE=D&TENDER=C&PWD=SuperUserPassword&PARTNER=PayPal&VENDOR=SuperMerc
hant&USER=SuperMerchant&CAPTURECOMPLETE=Y&ORIGID=EFHP0D426A51&AMT=34.00

4
Void
Void
A Void transaction voids any of the following transaction types:
z Order
z Authorizations (Authorization, Do Authorization, or Do Reauthorization)
N O T E : You can use a Void transaction only on transactions that have not yet settled. To refund
a customer’s money for a settled transaction, you must use a Credit transaction.
If you void an unsettled transaction, the full authorized amount of the original transaction
becomes void and can no longer be captured.
N O T E : As part of its internal process, PayPal makes reasonable effort to process authorization
reversals for void transactions for debit and credit cards. However, there is no
guarantee authorization reversal requests will be honored.
To set up a Void transaction, you must pass the following parameters in the request string:
z Set ORIGID=PNREF (PNREF value returned in the response to the original Authorization or
Order)
z Set TRXTYPE=V
This is an example Void transaction request string with the required parameters set.
"TRXTYPE=V
&TENDER=P
&PARTNER=partner
&USER=user
&VENDOR=vendor
&PWD=pwd
Credit
A Credit transaction refunds the buyer for a settled transaction. Credit transactions are
permitted only against existing Sale and Delayed Capture transactions.
To set up a Credit transaction request, you must pass the following parameters in the request
string:
z Set ORIGID=PNREF (PNREF value returned in the response to the original Sale or Delayed
Capture)
z Set TRXTYPE=C
z Set the value for AMT if the amount of the credit differs from the original Sale or Delayed
Capture transaction
This is an example Credit request string with the required parameters set:

4
Credit
"TRXTYPE=C
&TENDER=P
PARTNER=partner
VENDOR=vendor
&USER=user
&PWD=password
&ORIGID=EFHP0D426A62
&AMT=45.00"
Say, for example, a buyer purchases merchandise from a particular merchant using the buyer’s
PayPal account. The merchant can send a Memo Post Sale (above transaction) to Paymentech
so Paymentech can include that Sale information in the merchant’s Paymentech account. The
advantage to the merchant is that the merchant can view PayPal Sale activities in their
Paymentech reports.
The merchant uses a Memo Post Credit to send the buyer’s Credit transaction information to
Paymentech so the merchant can see the buyer’s Credit information in their Paymentech
reports.

5 Transaction Responses
Transaction response parameters indicate the status of the transaction and return requested
information.
z Response Parameters
z Address Verification Service Responses From PayPal
z Card Security Code Results
z PNREF Value
z RESULT Values and RESPMSG Text
Response Parameters
When a transaction finishes, the server returns a response string made up of name-value pairs.
For example, this is a response to a Sale transaction request:
RESULT=0
&PNREF=EFHP0D426A53
&RESPMSG=APPROVED
&AUTHCODE=25TEST
&AVSADDR=Y
&AVSZIP=N
&CVV2MATCH=Y
&PPREF=68W3371331353001F
&CORRELATIONID=2dc60e253495e
Express Checkout transaction responses include the response parameters described below as
well as parameters returned by the specific transaction type (TRXTYPE) and ACTION.
TABLE 5.1 General response parameters
Parameter Description
RESULT The outcome of the attempted transaction. A result of 0 (zero) indicates the
transaction was approved. Any other number indicates a decline or error.
N O T E : The PayPal processor may also return a warning message in the
RESPMSG string when RESULT=0. For more information on corrective
actions, see the PayPal developer documentation on Developer Central.
Limitations: Numeric.
PNREF Payflow Transaction ID, a unique 12-character alphanumeric string that
identifies the transaction.

Transaction Responses
5
Address Verification Service Responses From PayPal
TABLE 5.1 General response parameters
PPREF Unique PayPal transaction ID of the payment.
If the request ACTION was A (Authorization), you should store the value of
PPREF if you need to research a specific transaction with PayPal.
Limitations: 17-character string.
RESPMSG The response message returned with the transaction result. Exact wording varies.
Sometimes a colon appears after the initial RESPMSG followed by more detailed
information.
N O T E : The PayPal processor may also return a warning message in the
RESPMSG string when RESULT=0. For more information on corrective
actions, see the PayPal developer documentation on Developer Central.
Limitations: Alphanumeric.
CORRELATIONID Value used for tracking.
Limitations: 13-character alphanumeric string.
Address Verification Service Responses From PayPal

The table below compares the detailed response returned by the PayPal processor for address
verification to the normalized response value (Y, N, or X) returned in the AVSADDR and AVSZIP
response parameters. If you want to obtain the PayPal processor value, set the VERBOSITY
parameter to MEDIUM. With this setting, the processor value is returned in the PROCAVS
response parameter.
TABLE 5.2 Address Verification Service response value mapping
PayPal
Processor
Address
Verification
Service Code Meaning AVSADDR AVSZIP
A Address Y N
B International “A” Y N
C International “N” N N
D International “X” Y Y
E Not allowed for MOTO (Internet/Phone) transactions X X
F UK-specific “X” Y Y
G Global Unavailable X X
I International Unavailable X X

5
Card Security Code Results
TABLE 5.2 Address Verification Service response value mapping
PayPal
Processor
Address
Verification
Service Code Meaning AVSADDR AVSZIP
N No N N
P Postal (International “Z”) N Y
R Retry X X
S Service not Supported X X
U Unavailable X X
W Whole Zip N Y
X Exact Match Y Y
Y Yes Y Y
Z Zip N Y
All other X X
Card Security Code Results

The CVV2MATCH parameter returns Y, N, or X.
The CVV2MATCH parameter returns Y, N, X, or a processor-specific response.
Normalized Results
If you submit the transaction request parameter for card security code (that is, the CVV2
parameter), the cardholder’s bank returns a normalized Yes/No response in the CVV2MATCH
response parameter, as described in the table below.
TABLE 5.3 CVV2MATCH response values
CVV2MATCH Value Description

Y The submitted value matches the data on file for the card
N The submitted value does not match the data on file for the card.
X The cardholder’s bank does not support this service.

5
PNREF Value
PayPal Card Security Code Results

The table below shows the detailed results returned by the PayPal processor for card security
codes. If you want to obtain the PayPal processor value, set the VERBOSITY parameter to
MEDIUM. The processor value is returned in the PROCCVV2 response parameter.
TABLE 5.4 Card security code response code mapping
PayPal Processor CVV2

Code PayPal Processor Code Description PROCVV2MATCH
M Match Y
N No Match N
P Not Processed X
S Service Not Supported X
U Unavailable X
X No Response X
All other X
PNREF Value
The PNREF is a unique transaction identification number issued by PayPal that identifies the
transaction for billing, reporting, and transaction data purposes. The PNREF value appears in
the Transaction ID column in PayPal Manager reports.
z The PNREF value is used as the ORIGID value (original transaction ID) in Delayed Capture
transactions (TRXTYPE=D), Credits (TRXTYPE=C), Inquiries (TRXTYPE=I), and Voids
(TRXTYPE=V).
z The PNREF value is used as the ORIGID value (original transaction ID) value in reference
transactions for Authorization (TRXTYPE=A) and Sale (TRXTYPE=S).
N O T E : The PNREF is also referred to as the Transaction ID in PayPal Manager.
PNREF Format
The PNREF is a 12-character string of printable characters, for example:
z VADE0B248932
z ACRAF23DB3C4
N O T E : Printable
characters also include symbols other than letters and numbers such as the
question mark (?). A PNREF typically contains letters and numbers only.
The PNREF in a transaction response tells you that your transaction is connecting to PayPal.

5
RESULT Values and RESPMSG Text

The RESULT parameter and value is the first name-value pair returned in the response string.
The value of RESULT indicates the overall status of the transaction attempt:
z A value of 0 (zero) indicates that no errors occurred and the transaction was approved.
z A value less than zero indicates that a communication error occurred. In this case, no
transaction is attempted.
z A value greater than zero indicates a decline or error (except in the case of RESULT 104.
See the table below).
The response message (RESPMSG) provides a brief description for decline or error results.
RESULT Values for Transaction Declines or Errors

For non-zero RESULT values, the response string includes a RESPMSG name-value pair. The
exact wording of the RESPMSG (shown in bold) may vary. Sometimes a colon appears after the
initial RESPMSG followed by more detailed information.
When interpreting RESULT values for the PayPal processor, note the following:
z When RESULT=0, warning information may be returned that is useful to the request
application. See the PayPal API documentation on Developer Central for detailed
information on corrective actions.
z When RESULT=104, you must log in to the PayPal website to determine if the transaction
actually went through. If the transaction does not appear in the History section, you should
retry it.
TABLE 5.5 Payflow Transaction RESULT Values and RESPMSG Text
RESULT RESPMSG and Explanation
0 Approved
1 User authentication failed. Error is caused by one or more of the following:

z Login information is incorrect. Verify that USER, VENDOR, PARTNER, and
PASSWORD have been entered correctly. VENDOR is your merchant ID and USER
is the same as VENDOR unless you created a Payflow Pro user. All fields are case
sensitive.
z Invalid Processor information entered. Contact merchant bank to verify.
z "Allowed IP Address" security feature implemented. The transaction is coming
from an unknown IP address. See PayPal Manager online help for details on
how to use Manager to update the allowed IP addresses.
z You are using a test (not active) account to submit a transaction to the live
PayPal servers. Change the host address from the test server URL to the live
server URL

5
2 Invalid tender type. Your merchant bank account does not support the following
credit card type that was submitted.
3 Invalid transaction type. Transaction type is not appropriate for this transaction.
For example, you cannot credit an authorization-only transaction
4 Invalid amount format. Use the format: “#####.##” Do not include currency
symbols or commas.
5 Invalid merchant information. Processor does not recognize your merchant

account information. Contact your bank account acquirer to resolve this problem.
6 Invalid or unsupported currency code
7 Field format error. Invalid information entered. See RESPMSG
8 Not a transaction server
9 Too many parameters or invalid stream
10 Too many line items
11 Client time-out waiting for response
12 Declined. Check the credit card number, expiration date, and transaction
information to make sure they were entered correctly. If this does not resolve the
problem, have the customer call their card issuing bank to resolve.
13 Referral. Transaction cannot be approved electronically but can be approved with a

verbal authorization. Contact your merchant bank to obtain an authorization and
submit a manual Voice Authorization transaction.
19 Original transaction ID not found. The transaction ID you entered for this
transaction is not valid. See RESPMSG
20 Cannot find the customer reference number
22 Invalid ABA number
23 Invalid account number. Check credit card number and re-submit.
24 Invalid expiration date. Check and re-submit.
25 Invalid Host Mapping. Error is caused by one or more of the following:

z You are trying to process a tender type such as Discover Card, but you are not
set up with your merchant bank to accept this card type.
z You are trying to process an Express Checkout transaction when your account is
not set up to do so. Contact your account holder to have Express Checkout
added to your account.

5
26 Invalid vendor account. Login information is incorrect. Verify that USER,

VENDOR, PARTNER, and PASSWORD have been entered correctly. VENDOR is
your merchant ID and USER is the same as VENDOR unless you created a Payflow
Pro user. All fields are case sensitive.
27 Insufficient partner permissions
28 Insufficient user permissions
29 Invalid XML document. This could be caused by an unrecognized XML tag or a

bad XML format that cannot be parsed by the system.
30 Duplicate transaction
31 Error in adding the recurring profile
32 Error in modifying the recurring profile
33 Error in canceling the recurring profile
34 Error in forcing the recurring profile
35 Error in reactivating the recurring profile
36 OLTP Transaction failed
37 Invalid recurring profile ID
50 Insufficient funds available in account
51 Exceeds per transaction limit
99 General error. See RESPMSG.
100 Transaction type not supported by host
101 Time-out value too small
102 Processor not available
103 Error reading response from host
104 Timeout waiting for processor response. Try your transaction again.
105 Credit error. Make sure you have not already credited this transaction, or that this
transaction ID is for a creditable transaction. (For example, you cannot credit an
authorization.)
106 Host not available
107 Duplicate suppression time-out

5
108 Void error. See RESPMSG. Make sure the transaction ID entered has not already
been voided. If not, then look at the Transaction Detail screen for this transaction to
see if it has settled. (The Batch field is set to a number greater than zero if the
transaction has been settled). If the transaction has already settled, your only
recourse is a reversal (credit a payment or submit a payment for a credit)
109 Time-out waiting for host response
110 Referenced auth (against order) Error
111 Capture error. Either an attempt to capture a transaction that is not an

authorization transaction type, or an attempt to capture an authorization transaction
that has already been captured.
112 Failed AVS check. Address and ZIP code do not match. An authorization may still
exist on the cardholder’s account.
113 Merchant sale total will exceed the sales cap with current transaction. ACH
transactions only.
114 Card Security Code (CSC) Mismatch. An authorization may still exist on the
cardholder’s account.
115 System busy, try again later
116 VPS Internal error. Failed to lock terminal number
117 Failed merchant rule check. One or more of the following three failures occurred:
An attempt was made to submit a transaction that failed to meet the security
settings specified on the PayPal Manager Security Settings page. If the transaction
exceeded the Maximum Amount security setting, then no values are returned for
AVS or CSC.
AVS validation failed. The AVS return value should appear in the RESPMSG.
CSC validation failed. The CSC return value should appear in the RESPMSG
118 Invalid keywords found in string fields
120 Attempt to reference a failed transaction
121 Not enabled for feature
122 Merchant sale total will exceed the credit cap with current transaction. ACH
transactions only.
125 Fraud Protection Services Filter — Declined by filters

5
126 Fraud Protection Services Filter — Flagged for review by filters

I M P O R T A N T : RESULT value 126 indicates that a transaction triggered a fraud
filter. This is not an error, but a notice that the transaction is in a
review status. The transaction has been authorized but requires you
to review and to manually accept the transaction before it will be
allowed to settle.
RESULT value 126 is intended to give you an idea of the kind of transaction that is
considered suspicious to enable you to evaluate whether you can benefit from using
the Fraud Protection Services.
To eliminate RESULT 126, turn the filters off.
For more information, see the fraud documentation for your payments solution.
127 Fraud Protection Services Filter — Not processed by filters
128 Fraud Protection Services Filter — Declined by merchant after being flagged
for review by filters
132 Card has not been submitted for update
133 Data mismatch in HTTP retry request
150 Issuing bank timed out
151 Issuing bank unavailable
200 Reauth error
201 Order error
600 Cybercash Batch Error
601 Cybercash Query Error
1000 Generic host error. This is a generic message returned by your credit card
processor. The RESPMSG will contain more information describing the error.
1001 Buyer Authentication Service unavailable
1002 Buyer Authentication Service — Transaction timeout
1003 Buyer Authentication Service — Invalid client version
1004 Buyer Authentication Service — Invalid timeout value
1014 Buyer Authentication Service — Merchant is not enrolled for Buyer

Authentication Service (3-D Secure)

5
1016 Buyer Authentication Service — 3-D Secure error response received. Instead of
receiving a PARes response to a Validate Authentication transaction, an error
response was received.
1017 Buyer Authentication Service — 3-D Secure error response is invalid. An error
response is received and the response is not well formed for a Validate
Authentication transaction.
1021 Buyer Authentication Service — Invalid card type
1022 Buyer Authentication Service — Invalid or missing currency code
1023 Buyer Authentication Service — merchant status for 3D secure is invalid
1041 Buyer Authentication Service — Validate Authentication failed: missing or

invalid PARES
1042 Buyer Authentication Service — Validate Authentication failed: PARES

format is invalid
1043 Buyer Authentication Service — Validate Authentication failed: Cannot find

successful Verify Enrollment
1044 Buyer Authentication Service — Validate Authentication failed: Signature

validation failed for PARES
1045 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid amount in PARES

or invalid acquirer in PARES

or invalid Merchant ID in PARES

or invalid card number in PARES

or invalid currency code in PARES

or invalid XID in PARES

or invalid order date in PARES
1052 Buyer Authentication Service — Validate Authentication failed: This PARES

was already validated for a previous Validate Authentication transaction

6 Express Checkout Testing
You can set up the testing of your integration using two methods.
z Testing Your Integration Using the Sandbox
z Testing Your Integration Using the PayPal Simulator
Testing Your Integration Using the Sandbox

To set up the testing of your integration using the Sandbox:
z Create A Business Account
z Create a Payflow Test Account
z Link Your Payflow Pro Account to the Sandbox
Create A Business Account

If you do not already have a Payflow account, follow the procedure below to create one. If
your account is already set up, proceed to “Create a Payflow Test Account” on page 46
1. Sign up for a Payflow Pro test account. Go to the following URL and click Continue:
https://registration.paypal.com/productSelectionInit.do
2. Either log in with your existing PayPal account or create a new account by clicking Sign
Up.
3. PayPal Manager account information:
– Merchant Login: (Enter all lowercase characters, for example, yourcompanynametest.)
– Password: (The password is case sensitive. Choose a password you can remember. If
you enter it incorrectly too many times, you will be locked out.)
4. Complete the information in the Business Information section.
5. Complete the information in the Business Owner Contact Information section, and click
Continue.
6. On the Internet Merchant Account application, click Save and Exit.
7. To test your login, go to https://manager.paypal.com/ and enter the following:
– Partner Name: PayPal
– Merchant login: yourcompanynametest

Express Checkout Testing
6
Testing Your Integration Using the Sandbox
– Password: (your password)

Your account should show the following status message: Your account is currently in TEST
status. You can run only test transactions.
8. Click Log Out.
Create a Payflow Test Account

To create Payflow test account, follow the procedure below:
1. If you have an existing Sandbox account, log in to the Sandbox. Otherwise, click Sign Up
Now and create a Sandbox Seller account.
2. Once you are logged into the PayPal Sandbox Test environment, click Test Accounts.
3. Click Create Test Account.
4. For Country, select United States. For Account Type, select Seller.
5. Note the Seller’s login email address and password.
6. Click Show Advanced Options.
7. Add a balance of 500 to the Seller account.
Link Your Payflow Pro Account to the Sandbox

To link your Payflow Pro account to the Sandbox, follow the procedure below:
1. Click the Contact Support tab.
2. Enter the Subject as: Link Payflow Pro to Sandbox
3. Provide the following:
– Your Payflow Pro Merchant account login email address and password
– The login email address and password of the Seller account you created in the Sandbox
Test Environment
4. Submit the ticket.
Your Merchant ID and Sandbox Seller account will be linked within 72 hours, allowing you to
redirect Express Checkout transactions through the Sandbox environment. Be sure to:
z Send all test transaction requests as POSTs to the Payflow host address: https://pilot-
payflowpro.paypal.com
z Send Express Checkout redirects to: https://www.sandbox.paypal.com/cgi-
bin/webscr?cmd=_express-checkout&token=<ec-token>
NOTE: You must be logged into the Sandbox before redirecting.

6
Testing Your Integration Using the PayPal Simulator
You should also create a Buyer account in the Sandbox to make test Express Checkout
purchases against your Seller account. Be sure to add a positive balance to the Buyer account
at the time of creation.

To test your integration using the simulator, direct all test transactions to the Payflow host
address for testing: https://pilot-payflowpro.paypal.com
Transactions are processed through PayPal’s simulated payment network, enabling you to test
the configuration and operation of your application or storefront—with no money changing
hands.
N O T E : You
must activate your account and configure your application for live transactions in
PayPal Manager before accepting real orders.

6

A Express Checkout Parameter
Reference
This reference describes all parameters that can be used with the Express Checkout payment
solution.
z “Connection Parameter Descriptions” on page 49
z “User Parameter Descriptions” on page 50
z “Express Checkout Parameter Descriptions” on page 51
z “Do Reauthorization Parameter Descriptions” on page 68
z “Do Authorization Parameter Descriptions” on page 67
z “Void Parameter Descriptions” on page 69
z “Credit Parameter Descriptions” on page 70
z “Delayed Capture Parameter Descriptions” on page 71
Connection Parameter Descriptions

Pass the connection parameters in the format and syntax required by the Payflow gateway and
programming language that you are using. See your integration documentation for details.
TABLE A.1 Connection request parameters
HOSTADDRESS (Required) Payflow host name
HOSTPORT (Required) Use port 443.
PARMLIST (Required) List of parameters that specify the payment information for the
transaction. The quotation marks “ ” at the beginning and end are required.
The following is an example:
"TRXTYPE=S&TENDER=C&PARTNER=Partner&VENDOR=vendor&USER=user&
PWD=password&ACCT=5555555555554444&EXPDATE=0308&AMT=123.00"
The content of the PARMLIST varies by the type of transaction being
processed. For example, a Void transaction requires a different set of
parameters than a Sale.
PROXYADDRESS (Optional) Proxy server address. Use the PROXY parameters for servers
behind a firewall. Your network administrator can provide the values.
PROXYPORT (Optional) Proxy server port.
PROXYLOGON (Optional) Proxy server logon ID.
Express Checkout for Payflow Pro Reference Transactions 49

Express Checkout Parameter Reference
User Parameter Descriptions
TABLE A.1 Connection request parameters
PROXYPASSWORD (Optional) Proxy server logon password.
User Parameter Descriptions

All Payflow transaction requests require the user parameters described below.
TABLE A.2 User request parameters
USER (Required) If you set up one or more additional users on the account, this
value is the ID of the user authorized to process transactions. If, however,
you have not set up additional users on the account, USER has the same
value as VENDOR.
Limitations: 64 alphanumeric, case-sensitive characters.Limitations: 64
alphanumeric, case-sensitive characters.
VENDOR (Required) Your merchant login ID that you created when you registered
for the account.
Limitations: 64 alphanumeric, case-sensitive characters.Limitations: 64
alphanumeric, case-sensitive characters.
PARTNER (Required) The ID provided to you by the authorized PayPal Reseller who
registered you for the Payflow Pro service.
Limitations: 12 alphanumeric, case-sensitive characters.
PWD (Required) The password that you defined while registering for the
account.
Limitations: Six- to thirty-two alphanumeric, case-sensitive characters.
50 Express Checkout for Payflow Pro Reference Transactions

Express Checkout Parameter Descriptions
Set Express Checkout Request Parameter Descriptions
TABLE A.3 Set Express Checkout request parameters
TRXTYPE (Required) How you want to obtain payment:

z A indicates that this payment is an Authorization subject to settlement
with the Delayed Capture request
z O indicates that this payment is an Order subject to settlement with the
Delayed Capture request
z S indicates that this is a final Sale for which you are requesting
payment
N O T E : You cannot set this value to S in the Set Express Checkout request
and then change this value to A on the final Do Express Checkout
Payment request.
Limitations: One alpha character.
TENDER (Required) The tender type (method of payment). It is always P.

ACTION (Required) Is S to indicate this is a Set Express Checkout request.

AMT (Required) Amount (US Dollars) U.S. based currency.

N O T E : You must set CURRENCY set to one of the currency codes for any
of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any currency. Nine numeric
characers plus decimal (.) character. No currency symbol. Specify the
exact amount to the cent using a decimal point—use 34.00, not 34. Do not
include comma separators—use 1199.95 not 1,199.95.
Nine numeric characters plus decimal.
CURRENCY (Required) One of the supported currency codes. See “Currency Codes”
on page 73.”
RETURNURL (Required) URL to which the customer’s browser is returned after

choosing to pay.
Limitations: Character string with no maximum length.
CANCELURL (Required) URL to which the customer is returned if the customer cancels
the order.
Limitations: Character string with no maximum length.

TOKEN (Optional) Include this parameter to modify an existing Sale or

Authorization request. The value is returned in a previous Set Express
Checkout response.
L_BILLINGTYPEn (Optional) Describes the billing type for a PayPal account. The possible
values are:
z RecurringPayments
Use this value to use the TOKEN returned by the Set Express Checkout
response as a parameter in a request to create a Recurring Payments
profile. See Website Payments Pro Payflow Edition - Recurring
Payments Developer’s Guide for details.
Each L_BILLINGTYPEn must have a corresponding description string
(L_BILLINGAGREEMENTDESCRIPTIONn), where n is a value from 0 to 9.
N O T E : If you pass L_BILLINGTYPEn and BILLINGTYPE, the
BILLINGTYPE parameter will be ignored.
Character length and limitations: A string. n is a value in the range 0-9.
L_BILLINGAGREEMEN (Optional) Describes the billing type for a PayPal account. See
TDESCRIPTIONn L_BILLINGTYPEn.
BILLINGTYPE (Optional) Describes the billing type for a PayPal account. If

BILLINGTYPE is specified, BA_DESC also must be specified. See
L_BILLINGTYPEn.
The possible values are:
z RecurringPayments
Use this value to use the TOKEN returned by the Set Express Checkout
response as a parameter in a request to create a Recurring Payments
profile. See Website Payments Pro Payflow Edition - Recurring
Payments Developer’s Guide for details.
BA_DESC (Optional) Describes the billing agreement for a PayPal account. If

BA_DESC is specified, BILLINGTYPE also must be specified.
BA_CUSTOM (Optional) Custom annotation field for your exclusive use with billing
agreements.
Limitations: 255-character string
L_NAMEn (Optional) Line-item name.

Character length and limitations: 36 alphanumeric characters.

L_DESCn (Optional) Line-item description for each different item purchased such as
hiking boots or cooking utensils.
N O T E : You can view line item information in the Transaction Details
report in your PayPal merchant account.
L_COSTn (Required if L_QTYn is supplied) Cost of the line item. The line-item unit
price can be a positive or a negative value but not 0.
N O T E : You must set CURRENCY to one of the three-character currency
codes for any of the supported PayPal currencies. See CURRENCY
in this table for details.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use 1199.95
not 1,199.95.
L_TAXAMTn (Optional) Line-item tax amount.

not 1,199.95.
L_QTYn (Required if L_COSTn is supplied) Line-item unit quantity.

Limitations: 10-character integer.
ITEMAMT (Required if L_COSTn is specified) Sum of cost of all items in this order.
not 1,199.95.
TAXAMT (Required if L_TAXAMTn is specified) Sum of tax for all items in this
order.
not 1,199.95.
FREIGHTAMT (Optional) Total shipping cost for this order.

codes for any of the supported PayPal currencies.
not 1,199.95.

HANDLINGAMT (Optional) Total handling cost for this order.

not 1,199.95.
DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a
positive amount.
not 1,199.95.
INSURANCEAMT (Optional) Total shipping insurance cost for this order.

not 1,199.95.
ALLOWNOTE (Optional) Is 1 or 0 (default). If 1, the buyer may enter a note in the

Express Checkout flow to be returned by the responses to Get Express
Checkout Details and Do Express Checkout Payment.
Limitations: Numeric.
MAXAMT (Optional) The expected maximum total amount of the complete order,
including shipping and tax charges.
not 1,199.95.
ORDERDESC (Optional) Description of items the customer is purchasing.

CUSTOM (Optional) Free-form field for your own use such as a tracking number or
other value you want PayPal to return in the Get Express Checkout Details
response.
INVNUM (Optional) Merchant invoice number. If you do not provide an invoice

number, the transaction ID (PNREF) will be submitted.
Limitations: Nine-character alphanumeric string.

PHONENUM Account holder’s telephone number.

Limitations: 20-character string. The field mask is:
xxx-xxx-xxxx (US numbers)
+xxxxxxxxxxx (international numbers)
REQBILLINGADDRESS (Optional) Is 1 or 0. The value 1 indicates that you require that the
customer’s shipping address on file with PayPal be a confirmed address.
Setting this element overrides the setting you have specified in your
Merchant Account Profile.
Limitations: One character.
REQCONFIRMSHIPPIN (Optional) Is 1 or 0. The value 1 indicates that you require that the
G customer’s shipping address on file with PayPal be a confirmed address.
Setting this element overrides the setting you have specified in your
Merchant Account Profile
Limitations: One character.
NOSHIPPING (Optional) Is 1 or 0. The value 1 indicates that on the PayPal pages, no

shipping address fields should be displayed whatsoever.
Limitations: Four-character string.
ADDROVERRIDE (Optional) Is 1 or 0. The value 1 indicates that the PayPal pages should
display the shipping address set by you in the shipping address (SHIPTO*
parameters) passed to this Set Express Checkout request, not the shipping
address on file with PayPal for this customer.
Limitations: Four-character string.
LOCALECODE (Optional) Locale of pages displayed by PayPal during Express Checkout

Limitations: Two-character string.
AT
AU
BE
CA
CH
CN
DE
ES
FR
GB
IT
JP
NL
PL
US

PAGESTYLE (Optional) Sets the Custom Payment Page Style for payment pages
associated with this button/link. PageStyle corresponds to the HTML
variable page_style for customizing payment pages
The value is the same as the Page Style Name you chose when adding or
editing the page style from the Profile subtab of the My Account tab of
your PayPal account.
Limitations: 30-character alpha string.
HDRIMG (Optional) A URL for the image you want to appear at the top left of the
payment page. The image has a maximum size of 750 pixels wide by 90
pixels high. PayPal recommends that you provide an image that is stored
on a secure (https) server.
HDRBORDERCOLOR (Optional) Sets the border color around the header of the payment page.
The border is a two-pixel perimeter around the header space, which is 750
pixels wide by 90 pixels high.
Limitations: Six-character HTML hexadecimal color code in ASCII.
HDRBACKCOLOR (Optional) Sets the background color for the header of the payment page.
PAYFLOWCOLOR (Optional) Sets the background color for the payment page.
EMAIL (Optional) Email address of the customer as entered during checkout.

PayPal uses this to pre-fill the PayPal membership sign-up portion of the
PayPal login page.
SHIPTOFIRSTNAME (Optional) Ship-to first name.

SHIPTOLASTNAME (Optional) Ship-to last name.

SHIPTOSTREET (Optional) Ship-to street address.

SHIPTOSTREET2 (Optional) Extended Ship-to street address. Example: Bldg. 6, Mail Stop
3.
SHIPTOCITY (Optional) Ship-to city.

SHIPTOSTATE (Optional) Ship-to state.


SHIPTOZIP (Optional) Ship-to postal code.

SHIPTOCOUNTRY (Optional) Ship-to country.

Limitations: Two-character country code.
SHIPTOPHONENUM (Optional) Ship-to telephone number.

Limitations: 21 characters.
Set Express Checkout Response Parameter Descriptions
TABLE A.4 Set Express Checkout response parameters
TOKEN A time-stamped value by which you identify to PayPal that you are
processing this payment with Express Checkout.
The token expires after three hours.
If you set TOKEN in the Set Express Checkout request, the value of TOKEN
in the response is identical to the value in the request.
BAID The billing agreement ID.

RESULT Response value for the request.
RESPMSG Response message in case if any error occurs.

Get Express Checkout Details Request Parameter Descriptions
TABLE A.5 Get Express Checkout Details request parameters

payment
Payment request.

ACTION (Required) Is G to indicate this is a Get Express Checkout Details request.

TOKEN (Optional) Include this parameter to modify an existing Sale or

Authorization request. The value is returned in a previous Set Express
Checkout response.
Get Express Checkout Details Response Parameter Descriptions
TABLE A.6 Get Express Checkout Details response parameters
TOKEN The value returned by Set Express Checkout response.

EMAIL Email address of the customer as entered during checkout.

PAYERID Unique PayPal customer account identification number.


PAYERSTATUS Status of customer. Values are:

verified
unverified
DISCOUNT Shipping discount for this order. Specify the discount as a positive
amount.
not 1,199.95.
INSURANCEAMT Total shipping insurance cost for this order.

not 1,199.95.
NOTE Is 0 (default) or 1. If ALLOWNOTE is set to 1 in the Set Express Checkout

request, NOTE will contain the text entered by the buyer in the Express
Checkout flow.
ADJUSTMENTAMT A discount or gift certificate offered by PayPal to the buyer. This amount
will be represented by a negative amount. If the buyer has a negative
PayPal account balance, PayPal adds the negative balance to the
transaction amount, which is represented as a positive value. The negative
amount is returned for Payflow merchants.
N O T E : To test this value as a negative amount agaist the simulator, send
the amount as 1250 in the Set Express Checkout request and use
the returned TOKEN in the Get Express Checkout Details request to
see the ADJUSTMENTAMT response as a negative value.
not 1,199.95.
SHIPTOFIRSTNAME Ship-to first name.

SHIPTOLASTNAME Ship-to last name.


SHIPTOSTREET Ship-to street address.

If you include a shipping address and provide a value for the
AddressOverride (ADDROVERRIDE) parameter, PayPal returns this
same address in the Get Express Checkout Details response.
SHIPTOSTREET2 Extended Ship-to street address. Example: Bldg. 6, Mail Stop 3.

SHIPTOCITY Ship-to city.

SHIPTOSTATE Ship-to state.

SHIPTOZIP Ship-to postal code.

SHIPTOCOUNTRY Ship-to country.

SHIPTOBUSINESS Customer’s business name.

CUSTOM Free-form field for your own use as set by you in the Set Express
Checkout request.
INVNUM Merchant invoice number. If you do not provide an invoice number, the
transaction ID (PNREF) will be submitted.
Limitations: Nine-character alphanumeric string.
PHONENUM Account holder’s telephone number.

BILLTONAME Bill-to name.

N O T E : The bill-to address details are returned returned only if
REQBILLINGADDRESS is set to 1 in the call to Set Express
Checkout.
Limitations: 32 alphanumeric characters.

STREET Bill-to street.

N O T E : The bill-to address details are returned only if
Checkout.
STREET2 Second bill-to street address.

Checkout.
CITY Bill-to city address.

Checkout.
STATE Bill-to state address.

Checkout.
ZIP U.S. zip code or other country-specific postal code.

Checkout.
COUNTRYCODE Bill-to country code.

Checkout.
Limitations: Four alphanumeric characters.
COUNTRYNAME Bill-to country name.

Checkout.

ADDRESSOWNER The eBay company that owns this bill-to address.

Checkout.
ADDRESSSTATUS Status of the bill-to address on file with PayPal. The values are:
z Y = confirmed
z N = unconfirmed
The bill-to address details are returned only if REQBILLINGADDRESS is

set to 1 in the call to Set Express Checkout.
Do Express Checkout Payment Request Parameter Descriptions
TABLE A.7 Do Express Checkout Payment request parameters

payment
Payment request.

TOKEN (Required) Value returned by the Set Express Checkout response.

ACTION (Required) Is D to indicate this is a Set Express Checkout request.


PAYERID (Required) Unique PayPal customer account identification number, as

returned by Get Express Checkout Details response. This value is returned
in the URL when the customer is redirected to your website.
AMT (Required) Amount.

not 1,199.95.
ORDERURL (Optional) Your URL for displaying information about this transaction,
such as receipt, shipment tracking, or order details.
ORDERDESC (Optional) Description of items the customer is purchasing.

CUSTOM (Optional) Free-form field for your own use.

INVNUM (Optional) Merchant invoice number. The merchant invoice number is

used for authorizations and settlements and, depending on your merchant
bank, will appear on your customer's credit card statement and your bank
reconciliation report. If you do not provide an invoice number, the
transaction ID (PNREF) will be submitted.
Limitations: Nine alphanumeric characters.
BUTTONSOURCE (Optional) Identification code for use by third-party applications to

identify transactions.
NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN)
about this transaction.
N O T E : If you do not specify NotifyURL in the request, the notification
URL from your Merchant Profile is used, if one exists.
L_NAMEn (Optional) Line-item name.

Character length and limitations: 36 alphanumeric characters.
L_DESCn (Optional) Line-item description for each different item purchased such as
hiking boots or cooking utensils.
N O T E : You can view line item information in the Transaction Details
report in your PayPal merchant account.

L_COSTn (Required if L_QTYn is supplied) Cost of the line item. The line-item unit
price can be a positive or a negative value but not 0.
codes for any of the supported PayPal currencies. See CURRENCY
in this table for details.
not 1,199.95.
L_TAXAMTn (Optional) Line-item tax amount.

not 1,199.95.
L_QTYn (Required if L_COSTn is supplied) Line-item unit quantity.

Limitations: 10-character integer.
ITEMAMT (Required if L_COSTn is specified) Sum of cost of all items in this order.
not 1,199.95.
TAXAMT (Required if L_TAXAMTn is specified) Sum of tax for all items in this
order.
not 1,199.95.
FREIGHTAMT (Optional) Total shipping cost for this order.

not 1,199.95.

HANDLINGAMT (Optional) Total handling cost for this order.

not 1,199.95.
DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a
positive amount.
not 1,199.95.
INSURANCEAMT (Optional) Total shipping insurance cost for this order.

not 1,199.95.
SHIPTOFIRSTNAME (Optional) Ship-to first name.

SHIPTOLASTNAME (Optional) Ship-to last name.

Limitations: 30-character alphanumeric string
SHIPTOSTREET (Optional) Ship-to street address.

If you include a shipping address and provide a value for the
ADDROVERRIDE parameter, PayPal returns this same address in the Get
Express Checkout Details response.
SHIPTOSTREET2 (Optional) Extended Ship-to street address. Example: Bldg. 6, Mail Stop
3.
SHIPTOCITY (Optional) Ship-to city.

If SHIPTOCITY is passed, you also must pass SHIPTOSTREET,
SHIPTOSTATE, SHIPTOZIP, and SHIPTOCOUNTRY.
SHIPTOSTATE (Optional) Ship-to state.

If SHIPTOSTATE is passed, you also must pass SHIPTOSTREET,
SHIPTOCITY, SHIPTOZIP, and SHIPTOCOUNTRY.

SHIPTOZIP (Optional) Ship-to postal code.

If SHIPTOZIP is passed, you also must pass SHIPTOSTREET,
SHIPTOCITY, SHIPTOSTATE, and SHIPTOCOUNTRY.
SHIPTOCOUNTRY (Optional) Ship-to country.

If SHIPTOCOUNTRY is passed, you also must pass SHIPTOSTREET,
SHIPTOCITY, SHIPTOSTATE, and SHIPTOZIP.
PHONENUM (Optional) Account holder’s telephone number.

Do Express Checkout Payment Response Parameter Descriptions
TABLE A.8 Do Express Checkout Payment response parameters
TOKEN A time-stamped value by which you identify to PayPal that you are
processing this payment with Express Checkout.
PPREF Unique PayPal transaction ID.

If the request ACTION was A (Authorization), you should store the value
of PPREF if you need to research a specific transaction with PayPal.
PAYMENTTYPE Returns one of the following values:

z instantonly - The payment is made with no delay.
z any - The payment may be made with no delay or the payment is
pending (see PENDINGSTATUS).
FEEAMT Processor charge for the transaction.

not 1,199.95.

Do Authorization Parameter Descriptions
TABLE A.8 Do Express Checkout Payment response parameters
NOTE Is 0 (default) or 1. If ALLOWNOTE is set to 1 in the Set Express Checkout

request, NOTE will contain the text entered by the buyer in the Express
Checkout flow.
PENDINGREASON The reason the payment is pending. Values are:

z none = No pending reason.
z address = The payment is pending because your customer did not
include a confirmed shipping address and your Payment Receiving
Preferences is set such that you want to manually accept or deny each
of these payments. To change your preference, go to the Preferences
section of your Profile.
z echeck = The payment is pending because it was made by an eCheck
that has not yet cleared.
z intl = The payment is pending because you hold a non-U.S. account
and do not have a withdrawal mechanism. You must manually accept
or deny this payment from your Account Overview.
z multi-currency = You do not have a balance in the currency sent,
and you do not have your Payment Receiving Preferences set to
automatically convert and accept this payment. You must manually
accept or deny this payment.
z verify = The payment is pending because you are not yet verified.
You must verify your account before you can accept this payment.
z completed = The payment has been completed, and the funds have
been added successfully to your account balance.
z other = The payment is pending for a reason other than those listed
above. For more information, contact PayPal customer service.
Do Authorization Parameter Descriptions
TABLE A.9 Do Authorization request parameters
TRXTYPE (Required) The type of transaction to perform. For a Do Authorization,

the value is A.

Do Reauthorization Parameter Descriptions
TABLE A.9 Do Authorization request parameters

ORIGID (Required) Payflow transaction ID. To authorize an Order, set this

parameter to the value of the PNREF returned in the Do Express Checkout
Payment response when Do Express Checkout Payment request was
submitted with TRXTYPE=O.
Limitations: 12 case-sensitive alphanumeric characters.
AMT (Optional) Amount. If you do not pass a value for AMT, the amount of the
original transaction is sent in the Do Authorization request.
not 1,199.95.
TABLE A.10 Do Authorization response parameters

Do Reauthorization Parameter Descriptions
TABLE A.11 Do Reauthorization request parameters
TRXTYPE (Required) How you want to obtain payment. Is A, which indicates that
this payment is an Authorization or a Do Authorization subject to
settlement with the Delayed Capture request.


Void Parameter Descriptions
TABLE A.11 Do Reauthorization request parameters
ORIGID (Required) Payflow transaction ID, which is the value returned in the
PNREF in the response to the original transaction when:
TRXTYPE=A or TRXTYPE=O.
DOREAUTHORIZATION (Required) Indicates whether this transaction is a Do Reauthorization. The

value is 1.
TABLE A.12 Do Reauthorization response parameters

NOTE Stores the response message.

Void Parameter Descriptions
TABLE A.13 Void request parameters
TRXTYPE (Required) Type of transaction to perform. The value is V.


ORIGID (Required) Payflow transaction ID. Set this parameter to the value of the
PNREF returned in the original transaction response when Do Express
Checkout Payment request was submitted with TRXTYPE=O.
NOTE (Optional) An informal note about this settlement that is displayed to the
customer in email and in the customer’s transaction history

Credit Parameter Descriptions
TABLE A.14 Void response parameters

Credit Parameter Descriptions
TABLE A.15 Credit request parameters
TRXTYPE (Required) Type of transaction to perform. The value is C.


PNREF returned in the original Authorization or Order Do Express
Checkout Payment transaction response.
AMT (Optional) Required if the amount to credit differs from the original Sale
or Delayed Capture amount.
Limitations:Nine numeric characers plus decimal (.) character. No
not 1,199.95.
MEMO (Optional) Custom memo about the credit.

Limitations: 255 alphanumeric characers.
TABLE A.16 Credit response parameters


Delayed Capture Parameter Descriptions
TABLE A.17 Delayed Capture request parameters
TRXTYPE (Required) Type of transaction to perform. The value is D.


PNREF returned in the original Authorization or Order Do Express
Checkout Payment transaction response.
AMT (Optional) Required if the capture amount differs from the original
Authorization amount.
Limitations:Nine numeric characers plus decimal (.) character. No
not 1,199.95.
NOTE (Optional) An informal note about this settlement that is displayed to the
customer in email and in the customer’s transaction history
CAPTURECOMPLETE (Optional) Indicates if this Delayed Capture transaction is the last capture
you intend to make. The values are:
z Y (default)
z N
If CAPTURECOMPLETE is Y, any remaining amount of the original

reauthorized transaction is automatically voided.
TABLE A.18 Delayed Capture response parameters

PAYMENTTYPE Type of payment. Values are:

z instantonly - The payment is made with no delay.
z any - The payment may be made with no delay or the payment is
pending.

TABLE A.18 Delayed Capture response parameters

B Currency Codes
The following currencies are supported for use in transactions.
TABLE B.1 Currencies and Currency Codes
Code Currency
36 Australian Dollar
124 Canadian Dollar
756 Swiss Franc
203 Czech Koruna
208 Danish Krone
978 Euro
826 Pound Sterling
344 Hong Kong Dollar
348 Hungarian Forint
376 Israeli New Sheqel
392 Japanese Yen
484 Mexican Peso
578 Norwegian Krone
554 New Zealand Dollar
985 Polish Zloty
752 Swedish Krona
702 Singapore Dollar
840 U.S. Dollar (default)

Currency Codes
B

C Country Codes
N O T E : This
table lists country codes Country Code
defined by ISO 3166-1.
BELARUS BY
Table 1: Country Codes
BELGIUM BE
Country Code BELIZE BZ
AFGHANISTAN AF BENIN BJ
ÅLAND ISLANDS AX BERMUDA BM
ALBANIA AL BHUTAN BT
ALGERIA DZ BOLIVIA BO
AMERICAN SAMOA AS BOSNIA AND HERZE- BA
GOVINA
ANDORRA AD
BOTSWANA BW
ANGOLA AO
BOUVET ISLAND BV
ANGUILLA AI
BRAZIL BR
ANTARCTICA AQ
BRITISH INDIAN IO
ANTIGUA AND BAR- AG
OCEAN TERRITORY
BUDA
BRUNEI DARUSSALAM BN
ARGENTINA AR
BULGARIA BG
ARMENIA AM
BURKINA FASO BF
ARUBA AW
BURUNDI BI
AUSTRALIA AU
CAMBODIA KH
AUSTRIA AT
CAMEROON CM
AZERBAIJAN AZ
CANADA CA
BAHAMAS BS
CAPE VERDE CV
BAHRAIN BH
CAYMAN ISLANDS KY
BANGLADESH BD
BARBADOS BB
75
Country Codes
Country Code Country Code
CENTRAL AFRICAN CF EQUATORIAL GUINEA GQ

REPUBLIC
ERITREA ER
CHAD TD
ESTONIA EE
CHILE CL
ETHIOPIA ET
CHINA CN
FALKLAND ISLANDS FK
CHRISTMAS ISLAND CX (MALVINAS)
COCOS (KEELING) CC FAROE ISLANDS FO
ISLANDS
FIJI FJ
COLOMBIA CO
FINLAND FI
COMOROS KM
FRANCE FR
CONGO CG
FRENCH GUIANA GF
CONGO, THE DEMO- CD
FRENCH POLYNESIA PF
CRATIC REPUBLIC OF
THE FRENCH SOUTHERN TF
TERRITORIES
COOK ISLANDS CK
GABON GA
COSTA RICA CR
GAMBIA GM
COTE D'IVOIRE CI
GEORGIA GE
CROATIA HR
GERMANY DE
CUBA CU
GHANA GH
CYPRUS CY
GIBRALTAR GI
CZECH REPUBLIC CZ
GREECE GR
DENMARK DK
GREENLAND GL
DJIBOUTI DJ
GRENADA GD
DOMINICA DM
GUADELOUPE GP
DOMINICAN REPUBLIC DO
GUAM GU
ECUADOR EC
GUATEMALA GT
EGYPT EG
GUERNSEY GG
EL SALVADOR SV
76
GUINEA GN KOREA, REPUBLIC OF KR

GUINEA-BISSAU GW KUWAIT KW
GUYANA GY KYRGYZSTAN KG
HAITI HT LAO PEOPLE'S DEMO- LA
CRATIC REPUBLIC
HEARD ISLAND AND HM
MCDONALD ISLANDS LATVIA LV
HOLY SEE (VATICAN VA LEBANON LB
CITY STATE)
LESOTHO LS
HONDURAS HN
LIBERIA LR
HONG KONG HK
LIBYAN ARAB JAMA- LY
HUNGARY HU HIRIYA
ICELAND IS LIECHTENSTEIN LI
INDIA IN LITHUANIA LT
INDONESIA ID LUXEMBOURG LU
IRAN, ISLAMIC REPUB- IR MACAO MO
LIC OF
MACEDONIA, THE MK
IRAQ IQ FORMER YUGOSLAV
REPUBLIC OF
IRELAND IE
MADAGASCAR MG
ISLE OF MAN IM
MALAWI MW
ISRAEL IL
MALAYSIA MY
ITALY IT
MALDIVES MV
JAMAICA JM
MALI ML
JAPAN JP
MALTA MT
JERSEY JE
MARSHALL ISLANDS MH
JORDAN JO
MARTINIQUE MQ
KAZAKHSTAN KZ
MAURITANIA MR
KENYA KE
MAURITIUS MU
KIRIBATI KI
MAYOTTE YT
KOREA, DEMOCRATIC KP
PEOPLE'S REPUBLIC OF MEXICO MX
77
Country Codes
MICRONESIA, FEDER- FM PALAU PW

ATED STATES OF
PALESTINIAN TERRI- PS
MOLDOVA, REPUBLIC MD TORY, OCCUPIED
OF
PANAMA PA
MONACO MC
PAPUA NEW GUINEA PG
MONGOLIA MN
PARAGUAY PY
MONTSERRAT MS
PERU PE
MOROCCO MA
PHILIPPINES PH
MOZAMBIQUE MZ
PITCAIRN PN
MYANMAR MM
POLAND PL
NAMIBIA NA
PORTUGAL PT
NAURU NR
PUERTO RICO PR
NEPAL NP
QATAR QA
NETHERLANDS NL
REUNION RE
NETHERLANDS ANTI- AN
ROMANIA RO
LLES
RUSSIAN FEDERATION RU
NEW CALEDONIA NC
RWANDA RW
NEW ZEALAND NZ
SAINT HELENA SH
NICARAGUA NI
SAINT KITTS AND KN
NIGER NE
NEVIS
NIGERIA NG
SAINT LUCIA LC
NIUE NU
SAINT PIERRE AND PM
NORFOLK ISLAND NF MIQUELON
NORTHERN MARIANA MP SAINT VINCENT AND VC
ISLANDS THE GRENADINES
NORWAY NO SAMOA WS
OMAN OM SAN MARINO SM
PAKISTAN PK
78
SAO TOME AND PRINC- ST TANZANIA, UNITED TZ

IPE REPUBLIC OF
SAUDI ARABIA SA THAILAND TH
SENEGAL SN TIMOR-LESTE TL
SERBIA AND MON- CS TOGO TG
TENEGRO
TOKELAU TK
SEYCHELLES SC
TONGA TO
SIERRA LEONE SL
TRINIDAD AND TT
SINGAPORE SG TOBAGO
SLOVAKIA SK TUNISIA TN
SLOVENIA SI TURKEY TR
SOLOMON ISLANDS SB TURKMENISTAN TM
SOMALIA SO TURKS AND CAICOS TC
ISLANDS
SOUTH AFRICA ZA
TUVALU TV
SOUTH GEORGIA AND GS
THE SOUTH SANDWICH UGANDA UG
ISLANDS
UKRAINE UA
SPAIN ES
UNITED ARAB EMIR- AE
SRI LANKA LK ATES
SUDAN SD UNITED KINGDOM GB
SURINAME SR UNITED STATES US
SVALBARD AND JAN SJ UNITED STATES MINOR UM
MAYEN OUTLYING ISLANDS
SWAZILAND SZ URUGUAY UY
SWEDEN SE UZBEKISTAN UZ
SWITZERLAND CH VANUATU VU
SYRIAN ARAB REPUB- SY VENEZUELA VE
LIC
VIET NAM VN
TAIWAN, PROVINCE OF TW
VIRGIN ISLANDS, BRIT- VG
CHINA
ISH
TAJIKISTAN TJ
79
Country Codes
Country Code
VIRGIN ISLANDS, U.S. VI

WALLIS AND FUTUNA WF
WESTERN SAHARA EH
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW
80
Index
A DISCOUNT parameter 59
ACTION parameter 12, 51, 58, 62

ADDRESSOWNER parameter 62 E
ADDROVERRIDE parameter 55
EMAIL parameter 56, 58
ADJUSTMENTAMT parameter 59
Euro 73
AMT parameter 12
Express Checkout
AMTparameter 51, 63, 68, 70, 71
ACTION values 12
application
overview of process 9
testing 47
Set Express Checkout example 12
Australian Dollar 73
Express Checkout flow 11
AVSADDR parameter 62
F
B
FEEAMT parameter 66
BA_CUSTOM parameter 52
Forint 73
BA_DESC parameter 52
BAID parameter 57
BILLINGTYPE parameter 52 H
BILLTONAME parameter 60
HDRBACKCOLOR parameter 56
BUTTONSOURCE parameter 63
HDRBORDERCOLOR parameter 56
HDRIMG parameter 56
C Hong Kong Dollar 73
Hungarian Forint 73
Canadian Dollar 73
CANCELURL parameter 13, 51
CAPTURECOMPLETE parameter 32, 71 I
CITY parameter 61
INVNUM parameter 54, 60, 63
COLOR parameter 56
Israeli New Sheqel 73
CORRELATIONID parameter 36
COUNTRYCODE parameter 61
COUNTRYNAME parameter 61 J
currency code format 53, 54, 64, 65
currency codes 73 Japanese Yen 73
CURRENCY parameter 51
CUSTOM parameter 54, 60, 63 K
Customer Support 7
CVV2MATCH parameter 37 Koruna 73
Czech Koruna 73 Krona 73
Krone 73
D
Danish Krone 73
Index
L ADDROVERRIDE 55
AMT 12, 15, 51, 63, 68, 70, 71
L_BILLINGAGREEMENTDESCRIPTIONn AVSADDR 62
parameter 52
BA_CUSTOM 52
L_BILLINGTYPEn parameter 52
BA_DESC 52
L_COSTn parameter 53
BAID 57
L_DESCn parameter 53
BILLINGTYPE 52
L_NAMEn parameter 52
BILLTONAME 60
L_QTYn parameter 53
BUTTONSOURCE 63
L_TAXAMTn parameter 53, 64
CALCELURL 13
LOCALECODE parameter 55
CANCELURL 51
CAPTURECOMPLETE 32, 71
M CITY 61
COLOR 56
MAXAMT parameter 54
CORRELATIONID 36
MEMO parameter 70
COUNTRYCODE 61
Mexican Peso 73
COUNTRYNAME 61
CUSTOM 54, 60, 63
N CVV2MATCH 37
DISCOUNT 59
New Zealand Dollar 73 EMAIL 56, 58
Norwegian Krone 73 FEEAMT 66, 67
NOSHIPPING parameter 55
HDRBACKCOLOR 56
NOTE parameter 59, 67, 69, 71 HDRBORDERCOLOR 56
NOTIFYURL parameter 63 HDRIMG 56
HOSTADDRESS 49
O HOSTPORT 49, 50
INVNUM 54, 60, 63
operation L_BILLINGAGREEMENTDESCRIPTIONn 52
testing 47 L_BILLINGTYPEn 52
ORDERDESC parameter 54, 63 L_COSTn 53
ORIGID parameter 68, 69, 70, 71 L_DESCn 53
L_NAMEn 52
P L_QTYn 53
L_TAXAMTn 53, 64
PAGESTYLE parameter 56 LOCALECODE 55
PARTNER parameter 50 MAXAMT 54
PAYERID NOSHIPPING 55
in RETURNURL 15 NOTE 69, 71
PAYERID parameter 58, 63 NOTIFYURL 63
PAYERSTATUS parameter 59 ORDERDESC 54, 63
Payflow parameter ORIGID 38, 68, 69, 70, 71
CURRENCY 51 PAGESTYLE 56
MEMO 70 PARMLIST 49
Payflow parameters PARTNER 50
ACTION 12, 14, 15, 51, 58, 62 PAYERID 15, 58, 63
ADDRESSOWNER 62 PAYERSTATUS 59

Index
PAYMENTTYPE 66, 71 RESULT 35

PENDINGREASON 67 RESULT value 39
PNREF 35, 38 RETURNURL parameter 51
PPREF 36, 66, 68, 69, 70, 71 RETURNURLparameter 13
PROXYADDRESS 49, 50
PROXYLOGON 49
PROXYPASSWORD 50 S
PROXYPORT 49 sale transaction type 28
REQBILLINGADDRESS 55 SHIPTOCITY parameter 56, 60, 65
RESPMSG 36, 39 SHIPTOCOUNTRY parameter 57, 60, 65, 66
RESULT 35, 39 SHIPTOFIRSTNAME parameter 56, 59, 65
RETURNURL 13, 51 SHIPTOLASTNAME parameter 56, 59, 65
SHIPTOCITY 56, 60, 65 SHIPTOPHONENUM parameter 57
SHIPTOCOUNTRY 57, 60, 65, 66 SHIPTOSTATE parameter 56, 60, 65
SHIPTOFIRSTNAME 56, 59, 65 SHIPTOSTREET2 parameter 56, 60, 65
SHIPTOLASTNAME 56, 59, 65 SHIPTOSTREETparameter 56, 60, 65
SHIPTOPHONENUM 57 SHIPTOZIP parameter 57, 60, 66
SHIPTOSTATE 56, 60, 65 Singapore Dollar 73
SHIPTOSTREET 56, 60, 65 STATE parameter 61
SHIPTOSTREET2 56, 60, 65 storefront
SHIPTOZIP 57, 60, 66 testing 47
STATE 61 STREET 61
STREET2 61 STREET2 parameter 61
TENDER 51, 58, 68 Swedish Krona 73
TOKEN 14, 15, 52, 57, 58, 62, 66 Swiss Franc 73
TRXTYPE 27, 38, 51, 58, 62, 67, 68, 69, 70, 71
VENDOR 50
ZIP 61 T
Payflow parameters ADJUSTMENTAMT 59 TENDER 62
Payflow parameters NOTE 59 TENDER parameter 51, 58, 68
Payflow Test Account 46 testing operation 47
PAYMENTTYPE parameter 66, 71 TOKEN parameter 52, 57, 58, 62, 66
PayPal-supported currencies 73 transaction response
PENDINGREASON parameter 67 PNREF parameter 38
PHONENUM parameter 60 RESPMSG parameter 39
PNREF 35 RESULT parameter 39
format of value 38 transactions
PNREF value 38 sale 28
Polish Zloty 73 TRXTYPE parameter 51, 58, 62, 67, 68, 69, 70, 71
Pound Sterling 73
PPREF parameter 36, 66, 68, 69, 70, 71
U
U.S. Dollar 73
R
REQBILLINGADDRESS parameter 55
RESPMSG parameter 36 V
RESPMSG value 39 VENDOR parameter 50

Index
Y
Yen 73
Z
ZIP parameter 61
Zloty 73

PFP ExpressCheckout PP

Uploaded by

Copyright:

Available Formats

PFP ExpressCheckout PP

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PFP ExpressCheckout PP

Uploaded by

Copyright:

Available Formats

Express Checkout for

For Professional Use Only

A usage Professional Uniquement

Last updated: April 2009

Document Number: 200042.en_US-200904

Chapter 1 Express Checkout Processing Flow . . . . . . . . . . . . . 9

Chapter 2 Express Checkout Recurring Payments . . . . . . . . . . . 19

Chapter 3 PayPal Button Placement and Page Designs . . . . . . . . 23

Express Checkout for Payflow Pro 3

Chapter 4 Express Checkout Transaction Types . . . . . . . . . . . . 27

Chapter 5 Transaction Responses . . . . . . . . . . . . . . . . . . . 35

Chapter 6 Express Checkout Testing . . . . . . . . . . . . . . . . . 45

Appendix A Express Checkout Parameter Reference . . . . . . . . . . 49

4 Express Checkout for Payflow Pro

Set Express Checkout Request Parameter Descriptions . . . . . . . . . . . . . . . . 51

Appendix B Currency Codes . . . . . . . . . . . . . . . . . . . . . . . 73

Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . . 75

Express Checkout for Payflow Pro 5

6 Express Checkout for Payflow Pro

How to Contact Customer Support

TABLE 1.1 Document history

Express Checkout for Payflow Pro 7

8 Express Checkout for Payflow Pro

This chapter describes Express Checkout processing:

What Is Express Checkout?

How Express Checkout Works

Express Checkout for Payflow Pro 9

FIGURE 1.1 Express Checkout flow

10 Express Checkout for Payflow Pro

Express Checkout Flow

Express Checkout for Payflow Pro 11

Express Checkout ACTION Values

TABLE 1.1 ACTION values for Express Checkout

Request ACTION value

Express Checkout Token

Express Checkout Sale Transaction Example

Set Express Checkout (ACTION=S)

12 Express Checkout for Payflow Pro

Redirecting the Customer to PayPal Example

Express Checkout for Payflow Pro 13

The following example uses the META REFRESH tag.

Get Express Checkout Details (ACTION=G)

14 Express Checkout for Payflow Pro

Redirecting the Customer to Your Website Example

Do Express Checkout Payment (ACTION=D)

Express Checkout for Payflow Pro 15

Other Express Checkout Concepts

Obtaining the Buyer’s Telephone Number During Checkout

16 Express Checkout for Payflow Pro

Express Checkout for Payflow Pro 17

18 Express Checkout for Payflow Pro

Creating Multiple Billing Agreement Descriptions

TABLE 2.1 Set Express Checkout fields for recurring payments

L_BILLINGTYPEn Type of billing agreement. For recurring payments, the

L_BILLINGAGREEMENTDESCRIPTIONn Description of goods or services. You can pass up to a

N O T E : You must pass the same L_BILLINGAGREEMENTDESCRIPTIONn string later in the

Express Checkout for Payflow Pro 19

Creating a Single Billing Agreement Description

TABLE 2.2 Set Express Checkout fields for recurring payments