PayPal Express Checkout - 2013 Payflow Pro Guide

Express Checkout for Payflow

Last updated: June 2013

Express Checkout for Payflow Document Number: 200042.en_US-201306

© 2013 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, 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 i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information co ntained 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 f rom 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.

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 Buyer to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Get Express Checkout Details (ACTION=G) . . . . . . . . . . . . . . . . . . . . . . 14

Redirecting the Buyer to Your Website . . . . . . . . . . . . . . . . . . . . . . . . . 15

Do Express Checkout Payment (ACTION=D) . . . . . . . . . . . . . . . . . . . . . . 15

Other Express Checkout Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Obtaining the Buyer’s Telephone Nu mber During Checkout . . . . . . . . . . . . . . 16

Eliminating Your Order Review Page . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Pending Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2 Billing Agreements and Reference Transactions . . . . . . 19

About Reference Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

About Billing Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

About Billing Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Ways To Obtain a BAID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Obtaining the BAID With Express Checkout Purchase . . . . . . . . . . . . . . . . . . . 21

Example of Obtaining the BAID With Express Checkout Purchase . . . . . . . . . . . 24

Obtaining the BAID Without Express Checkout Purchase. . . . . . . . . . . . . . . . . . 25

Example of Obtaining the BAID Without Express Checkout Purchase . . . . . . . . . 28

Express Checkout for Payflow 3

Contents

Updating a Billing Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Example of Updating a Billing Agreement . . . . . . . . . . . . . . . . . . . . . . . . 29

Using Reference Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Reference Transaction Request Passing the BAID . . . . . . . . . . . . . . . . . . . 30

Reference Transaction Request Passing the PNREF Value as ORIGID . . . . . . . . 31

Chapter 3 Express Checkout Transaction Types . . . . . . . . . . . .33

Honor Period and Authorization Period . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Payment Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Sale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Do Reauthorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Do Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Delayed Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Complete Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Partial Capture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 4 Transaction Responses . . . . . . . . . . . . . . . . . . . 41

Response Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 42

Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Normalized Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

PayPal Card Security Code Results. . . . . . . . . . . . . . . . . . . . . . . . . . . 44

PNREF Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

PNREF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

RESULT Values for Transaction Declines or Errors . . . . . . . . . . . . . . . . . . . 45

Chapter 5 Express Checkout Testing . . . . . . . . . . . . . . . . .51

Testing Your Integration Using the Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . 51

Create A Business Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Create a Payflow Test Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Link Your Payflow Account to the Sandbox . . . . . . . . . . . . . . . . . . . . . . . 51

4 Express Checkout for Payflow

Contents

Testing Your Integration Using the PayPal Simulator . . . . . . . . . . . . . . . . . . . . 52

Appendix A Express Checkout Parameter Reference . . . . . . . . . .53

Connection Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

User Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Express Checkout Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . 55

Set Express Checkout Request Parameter Descriptions . . . . . . . . . . . . . . . . 55

Set Express Checkout Response Parameter Descriptions . . . . . . . . . . . . . . . 61

Get Express Checkout Details Request Parameter Descriptions . . . . . . . . . . . . 62

Get Express Checkout Details Response Parameter Descriptions . . . . . . . . . . . 62

Do Express Checkout Payment Request Parameter Descriptions . . . . . . . . . . . 66

Do Express Checkout Payment Response Parameter Descriptions . . . . . . . . . . 70

Do Authorization Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Do Reauthorization Parameter Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . 73

Void Parameter Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Credit Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Delayed Capture Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Billing Agreement Parameter Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . 76

Create Customer Billing Agreement Request Parameters . . . . . . . . . . . . . . . 76

Create Customer Billing Agreement Response Parameters. . . . . . . . . . . . . . . 77

Update Customer Billing Agreement Request Parameters . . . . . . . . . . . . . . . 77

Update Customer Billing Agreement Response Parameters . . . . . . . . . . . . . . 78

Reference Transaction Parameter Descriptions . . . . . . . . . . . . . . . . . . . . . . . 79

Reference Transaction Request Parameters . . . . . . . . . . . . . . . . . . . . . . 79

Reference Transaction Response Parameters . . . . . . . . . . . . . . . . . . . . . 83

Appendix B Currency Codes . . . . . . . . . . . . . . . . . . . . . . .85

Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . . 87

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Express Checkout for Payflow 5

Contents

6 Express Checkout for Payflow

Preface

Intended Audience

This guide assumes that its readers:

 Are experienced web or application developers  Have a background in payments services  Are developing payment services applications that are integrating Express Checkout to

process transactions to be sent over the Payflow gateway

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

Document History

TABLE 3.1 Document history

Date Description

June 2013 Updated the description of the REQBILLINGADDRESS field in the Set

Express Checkout request parameters table.

Updated URLs. Updated the account creation instructions in the Testing Your

Integration Using the Sandbox section.

April 2012 Updated references to Website Payments Pro to PayPal Payments Pro. October 2009 Updated currency codes.

http://www.paypal.com/mts.

Express Checkout for Payflow 7

Document History

TABLE 3.1 Document history

Date Description

August 2009 Revised and updated.

June 2009 Added SHIPTONAME parameter. May 2009 Updated to correct for technical inaccuracies. April 2009 Added creating billing agreements for setting up Recurring Payments

Added reference transactions and RecurringPayments billing

type.

Revised billing agreements.

Removed PayPal Button Placement.

Added “Eliminating Y our Order Review Page” to Chapter 1, “Express

Checkout Processing Flow.”

through Express Checkout.

Added order line-item details parameters.

Updated with PHONENUM parameter in Set Express Checkout request.

8 Express Checkout for Payflow

Express Checkout Processing

Flow

This chapter describes Express Checkout processing:

 “What Is Express Checkout?” on page 9  “How Express Checkout Works” on page 9  “Express Checkout Flow” on page 11  “Express Checkout Sale Transaction Example” on page 12  “Other Express Checkout Concepts” on page 16

What Is Express Checkout?

Express Checkout is PayPal’s method of payment. It offers your buyers 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 namevalue pair parameters, and include this basic set of required parameters:

 Connection parameters  User parameters  Transaction type (TRXTYPE) such as Sale (TRXTYPE=S), Authorization (TRXTYPE=A), or

Order (TRXTYPE=0)

 Tender type, which is always PayPal (TENDER=P)

How Express Checkout Works

The figure below summarizes the Express Checkout flow.

Express Checkout for Payflow 9

Express Checkout Processing Flow

How Express Checkout Works

FIGURE 1.1 Express Checkout flow

The figure shows a typical set of web pages representing a merchant’s website. (The web page layout may differ somewhat from your own web design.) The buyer uses the PayPal logo to choose PayPal as their method of payment. Express Checkout gives you the flexibility to place the PayPal logo at two points in the checkout flow:

 On your Shopping Cart page at the start of checkout, as shown  On your Payment Methods page with other billing options

The numbered callouts in the figure correspond to the numbered events described below.

10 Express Checkout for Payflow

Express Checkout Processing Flow

Express Checkout Flow

1. On your website, your buyer checks out either by clicking the Check out with PayPal

button from your Shopping Cart page (as shown in the figure layout) or by selecting PayPal from your Payment Methods page. This buyer 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 figure above, the token is represented by an orange “donut.” The token keeps track of your buyer throughout the checkout process.

3. You direct your buyer 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 buyer clicks the Continue button, PayPal sends the buyer 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 buyer.

5. Optionally you can send the Get Express Checkout Details request to obtain details about

your buyer such as the buyer’s telephone number and shipping address. You send the token to identify the buyer. The server returns the requested information.

6. When your buyer 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 response parameter data about the transaction.

Unlike most Payflow 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 and controls what is displayed

to the buyer on the PayPal site when the buyer chooses PayPal at checkout.

2. Get Express Checkout Details is an optional request enabling you to obtain information

about the transaction 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 buyer experience as the Express

Checkout flow.

RESULT and RESPMSG values, along with other

Express Checkout for Payflow 11

Express Checkout Processing Flow

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

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 buyer with this particular Express Checkout flow. You pass it back to the server in these Express Checkout requests:

ACTION for each Express Checkout request.

 In the HTTP request to redirect the buyer’s browser to the PayPal web site  In the Get Express Checkout Details request to obtain the buyer’s shipping information  In the Do Express Checkout Payment request to carry out the transaction

Express Checkout Sale Transaction Example

This section describes the Express Checkout flow in greater detail using a Sale transaction as the example. See descriptions of all required and optional Express Checkout transaction parameters.

 Set Express Checkout (ACTION=S)  Redirecting the Buyer to PayPal  Get Express Checkout Details (ACTION=G)  Redirecting the Buyer to Your Website  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 buyer chooses to pay with PayPal.

Appendix A, “Express Checkout Parameter Reference,” for detailed

Set Express Checkout requires that you pass data for the following parameters.

 ACTION

 AMT

12 Express Checkout for Payflow

Express Checkout Processing Flow

Express Checkout Sale Transaction Example

 RETURNURL

 CANCELURL

This is an example Set Express Checkout request 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

NOTE: It is strongly recommended that RETURNURL be the URL of the final review page on

your website where the buyer confirms the order and payment. Likewise, CANCELURL should be the URL of the original page on your website where the buyer 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 4, “Transaction Responses.” The TOKEN value returned associates

this buyer with this particular Express Checkout flow.

Redirecting the Buyer to PayPal

After your buyer clicks the PayPal button and you submit the Set Express Checkout request, you will want to automatically direct your buyer 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.

NOTE: Express Checkout has a variation on this redirect URL (called useraction) that

allows you to bypass the call to the button displayed on the PayPal website from “Continue” to “Pay Now.” For more information, see

“Eliminating Your Order Review Page” on page 17.

Get Express Checkout Details and to change the text of

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

Express Checkout for Payflow 13

Express Checkout Processing Flow

Express Checkout Sale Transaction Example

below. Remember to replace <TOKEN> with the token value that you received in the Set Express Checkout response.

The following example uses the META REFRESH tag.

<body>

<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_expresscheckout&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 buyer’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.

 ACTION

 TOKEN

The following is an example Get Express Checkout Details request:

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:

14 Express Checkout for Payflow

RESULT=0 &RESPMSG=Approved &AVSADDR=Y &TOKEN=EC-17C76533PL706494P &PAYERID=FHY4JXY7CV9PG &EMAIL=buyer_name@aol.com &PAYERSTATUS=verified &FIRSTNAME=J &LASTNAME=Smith &CUSTOM=TRVV14459 &BUSINESS=Monroe Creek Regional Interiors &SHIPTONAME=J Smith &SHIPTOSTREET=5262 Green Street #8 &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOZIP=95148 &SHIPTOCOUNTRY=US

Redirecting the Buyer to Your Website

Express Checkout Processing Flow

Express Checkout Sale Transaction Example

PayPal redirects the buyer 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.

 ACTION

 TOKEN

 PAYERID

 AMT

The following is an example Do Express Checkout Payment request:

Express Checkout for Payflow 15

Express Checkout Processing Flow

Other Express Checkout Concepts

TRXTYPE=S &VENDOR=vendor &USER=user &PWD=pwd &TENDER=P PARTNER=partner &ACTION=D &TOKEN=EC-17C76533PL706494P &PAYERID=FHY4JXY7CV9PG &AMT=35.00

The following is an example response:

RESULT=0 &PNREF=EFHP0CDBF5C7 &RESPMSG=Approved &AVSADDR=Y &TOKEN=EC-17C76533PL706494P &PAYERID=FHY4JXY7CV9PG &PPREF=2P599077L3553652G &PAYMENTTYPE=instantonly

The response returns a 12-character PNREF (Payflow Transaction ID) that is used to identify this transaction in PayPal reports.

Other Express Checkout Concepts

The following topics are related to processing Express Checkout transactions.

 “Obtaining the Buyer’s Telephone Number During Checkout” on page 16  “Pending Responses” on page 17  “Eliminating Your Order Review Page” on page 17

Obtaining the Buyer’s Telephone Number During Checkout

You have three options regarding the buyer’s contact telephone number. You can choose to:

 Not request the contact telephone number (default)  Request the contact telephone number as an optional field  Require that the buyer enter their contact telephone number to proceed.

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.

To choose one of the three preceding options:

1. Log in to your PayPal account.

16 Express Checkout for Payflow

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.

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 buyer 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 the PayPal Review page to appear as “Pay Now” 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.

NOTE: As a best practice, you should incorporate the “Pay Now” button text in the Express

Checkout flow that redirects the buyer to PayPal from your shopping cart at the start of checkout.

Express Checkout Processing Flow

Other Express Checkout Concepts

Values and resulting button text are described below:

 If you do not set useraction or you set useraction to continue, PayPal displays the

button text “Continue.”

 If you set useraction to commit, PayPal displays the button text “Pay Now.”

To display the “Pay Now” 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=_expresscheckout&token=tokenvalue&useraction=commit"

Pending Responses

If the Do Express Checkout Payment PENDINGREASON response is a value other than none or completed, the payment is pending. T ypically, this means the buyer 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.

NOTE: PayPal recommends that you block eChecks as a payment method in your PayPal

account profile if you are unable to handle pending st ate payments.

To find out the status of a pending payment, you can:

 Submit an Inquiry transaction.  Check the status from the PayPal User Interface. See PayPal online help for details.

Express Checkout for Payflow 17

Express Checkout Processing Flow

Other Express Checkout Concepts

18 Express Checkout for Payflow

Billing Agreements and Reference Transactions

This chapter describes how you can automatically bill a buyer’s PayPal account based on buyer information you obtained in a previous transaction. To perform this type of transaction you first must obtain a billing agreement between you and the buyer.

 “About Reference Transactions” on page 19  “About Billing Agreements” on page 20  “Wa ys To Obtain a BAID” on page 20  “Obtaining the BAID With Express Checkout Purchase” on page 21  “Obtaining the BAID Without Express Checkout Purchase” on page 25  “Updating a Billing Agreement” on page 29  “Using Reference Transactions” on page 30

IMPORTANT: You must be enabled by PayPal to use reference transactions. Contact

PayPal for details.

About Reference Transactions

A reference transaction takes existing billing information already gathered from a previously authorized transaction and reuses it to charge the buyer in a subsequent transaction.

Before you can use a reference transaction, you must set up a billing agreement with the buyer .

About Billing Agreements.) When you obtain the billing agreement, you can withdraw

(See funds from the buyer’s PayPal account without manual intervention using a reference transaction. (

TRXTYPE is A or S).

To enable line-item support in reference transactions, which includes the parameters below, you must contact Merchant Technical Support at

 L_NAMEn  L_DESCn  L_COSTn  L_TAXAMTn  L_QTYn

You can only use reference transactions with Authorization or Sale transactions

http://www.paypal.com/mts:

Express Checkout for Payflow 19

Billing Agreements and Reference Transactions

About Billing Agreements

A billing agreement allows PayPal to withdraw funds from the buyer’s PayPal account without requiring the buyer to log in to PayPal. Billing agreements are maintained by PayPal.

You must establish a billing agreement with a buyer if, for example, you and the buyer agree that you will bill that buyer on a regularly scheduled basis such as monthly for a magazine subscription. Before a billing agreement can take effect, the buyer must log in to PayPal once to consent to it. With buyer consent, PayPal creates a billing agreement ID (BAID) to represent the agreement. You pass the BAID in subsequent requests to bill the buyer. PayPal withdraws funds without requiring the buyer to log in. A billing agreement is good until you or the buyer cancels it.

A buyer may have multiple magazine subscriptions, each with a separate billing agreement. In such cases, be sure to associate each transaction with the correct billing agreement.

About Billing Types

To specify how the buyer will be billed, you set the billing type in the call to Set Express Checkout.

TABLE 2.1 Billing type values

Value Description

MerchantInitiatedBilling Use to obtain a BAID in the Express Checkout flow. To initiate

RecurringBilling Use to obtain a BAID for creating a recurring billing profile to

RecurringPayments Use to obtain a TOKEN for creating a recurring payments profile

Table 2.1describes the values of this parameter:

billing the buyer one or more times, call Do Express Checkout Payment outside the Express Checkout flow and pass the BAID to bill the buyer.

bill the buyer on a recurring basis.

Recurring Billing Service User’s Guide for details on using the

BAID to create a recurring billing profile.

to bill the buyer on a recurring basis.

NOTE: This billing type does not create a BAID. See PayPal

Payments Pro Payflow Edition - Recurring Payments Developer’s Guide for details on using this billing type

value to create a Recurring Payments profile.

See the Payflow Pro

Ways To Obtain a BAID

You can obtain a BAID whether or not the buyer logs in to PayPal to make a purchase. The following sections describe how.

20 Express Checkout for Payflow

Billing Agreements and Reference Transactions

Obtaining the BAID With Express Checkout Purchase

 When the buyer is making a purchase

Say that you have implemented Express Checkout on your website. The buyer logs in to purchase an item of merchandise and chooses PayPal to pay for it. In the normal Express Checkout flow, the buyer is then redirected to PayPal to log in to verify their billing information. If the buyer approves payment on the PayPal Review page, you receive the billing agreement as part of the transaction.You can use that billing agreement later to bill the buyer a set amount on a recurring basis, such as once-a-month, for future purchases. The buyer doesn’t need to log into PayPal each time to make a payment.

 When the buyer is not making a purchase

Typically, the buyer chooses a billing agreement without making a purchase when they subscribe for merchandise they will pay for on a recurring schedule. If, for example, the buyer logs in to your website to order a magazine subscription, you set up an agreement to bill the buyer on a scheduled basis—say, once a month. In the billing agreement flow without purchase, the buyer is redirected to PayPal to log in. On the PayPal site, they consent to the billing agreement. Next month, when you send the buyer the first magazine issue, the billing agreement authorizes you to start charging the buyer’s PayPal account on the agreed upon recurring basis without having the buyer log in to PayPal.

The following pages describe ways to obtain a BAID:

 “Obtaining the BAID With Express Checkout Purchase” on page 21  “Obtaining the BAID Without Express Checkout Purchase” on page 25

Obtaining the BAID With Express Checkout Purchase

To set up the billing agreement and obtain the BAID when the buyer makes an Express Checkout purchase from your website, you need only provide additional parameters and values in the Express Checkout calls.

Figure 2.1 summarizes the flow.

Express Checkout for Payflow 21

Billing Agreements and Reference Transactions

Obtaining the BAID With Express Checkout Purchase

FIGURE 2.1 Obtaining the BAID with Express Checkout purchase

The message flow consists of the following comments, which correspond to the circled numbers in obtaining a BAID.

1. When the buyer chooses to set up a billing agreement, call the Set Express Checkout

request (ACTION=S) and pass the following information about the agreement: – The billing type (required)

– A description of the goods or services associated with the agreement (optional) – The type of PayPal payment you require (optional) – A string for your use in any way (optional)

2. PayPal returns a TOKEN that you use in subsequent steps.

3. After the buyer clicks the PayPal button and you submit the Set Express Checkout request,

you will want to automatically direct your buyer to the PayPal website to log in or set up a

22 Express Checkout for Payflow

Figure 2.1. The comments pertain specifically to setting up a billing agreement and

Billing Agreements and Reference Transactions

Obtaining the BAID With Express Checkout Purchase

PayPal account. The redirect URL for this is shown below. TOKEN is the value returned in the Set Express Checkout response.

https://www.paypal.com/cgi-bin/webscr?cmd=_expresscheckout&token=<TOKEN>

When the buyer logs in, the buyer is presented with a PayPal Review page, such as the example page shown in

FIGURE 2.2 PayPal Review page

Figure 2.2.

4. PayPal redirects the buyer’s browser to your return page.

5. Call the Get Express Checkout Details request (ACTION=G) to obtain information about the

buyer and the buyer’s checkout status. PayPal returns checkout details, including whether the billing agreement was accepted.

6. Call the Do Express Checkout Payment request (ACTION=D) to complete the purchase.

7. PayPal returns information about the purchase. If the required billing agreement

information was passed, PayPal returns a BAID. Save the BAID to implement Payflow reference transactions.

Express Checkout for Payflow 23

Billing Agreements and Reference Transactions

Obtaining the BAID With Express Checkout Purchase

Example of Obtaining the BAID With Express Checkout Purchase

This section provides an example of Express Checkout Authorization request and response name-value pair strings, illustrating the billing agreement parameters. Billing agreement parameters are shown in boldface.

Set Express Checkout Request (ACTION=S)

The following is an example of a Set Express Checkout request:

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=S &TENDER=P &RETURNURL=http://return.com &CANCELURL=http://cancel.com&AMT=10.00

&BA_DESC=purchase Time Magazine &BILLINGTYPE=MerchantInitiatedBilling

&BA_CUSTOM=add magazine subscription &PAYMENTTYPE=any

Set Express Checkout Response

RESULT=0 &RESPMSG=Approved &CORRELATIONID=ec093d08c9f39 &TOKEN=EC-36X58962RS656712N

Get Express Checkout Details Request (ACTION=G)

The following request contains no new parameters:

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=G &TENDER=P &TOKEN=EC-36X58962RS656712N

24 Express Checkout for Payflow

Billing Agreements and Reference Transactions

Obtaining the BAID Without Express Checkout Purchase

Get Express Checkout Details Response

RESULT=0 &RESPMSG=Approved &TOKEN=EC-F3BQJQG7UGVDL754 &CORRELATIONID=9c3706997455e &EMAIL=jsmith@paypal.com &PAYERSTATUS=verified &FIRSTNAME=Joe &LASTNAME=Smith &SHIPTONAME=Joe Smith &SHIPTOSTREET=111 Main St &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOZIP=95100 &SHIPTOCOUNTRY=US

Do Express Checkout Payment Request (ACTION=D)

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=D &TENDER=P &AMT=10.00 &TOKEN=EC-36X58962RS656712N &PAYERID=J5MSNK7FP5KA8

Do Express Checkout Payment Response

The response returns the BAID:

RESULT=0 &PNREF=E24P0A03B013 &RESPMSG=Approved &TOKEN=EC-11X52562RT656789N &PPREF=44000000000180903 &CORRELATIONID=3a3204997455r

&BAID=B-12345678901234567

&PAYMENTTYPE=any &PENDINGREASON=authorization

Obtaining the BAID Without Express Checkout Purchase

To set up the billing agreement and obtain the BAID without the buyer making an Express Checkout purchase from your website, you add one new request to create the billing agreement to your current Express Checkout integration.

Figure 2.3 summarizes the flow.

Express Checkout for Payflow 25

Billing Agreements and Reference Transactions

Obtaining the BAID Without Express Checkout Purchase

FIGURE 2.3 Obtaining the BAID without Express Checkout purchase

The message flow consists of the following comments, which correspond to the circled numbers in

Figure 2.1. The comments pertain specifically to setting up a billing agreement and

obtaining a BAID.

1. When the buyer chooses to set up a billing agreement, call the Set Express Checkout

request (ACTION=S) and pass information about the agreement: – The billing type (required)

– A description of the goods or services associated with the agreement (optional) – The type of PayPal payment you require (optional) – A string for your use in any way (optional)

NOTE: Even though the buyer is not making a purchase in this flow, provide a value for AMT,

for example,

AMT=0.00.

2. PayPal returns a TOKEN that you use in subsequent steps.

26 Express Checkout for Payflow

Billing Agreements and Reference Transactions

Obtaining the BAID Without Express Checkout Purchase

3. Redirect the buyer’s browser to PayPal to allow the buyer to log in to PayPal or set up a

PayPal account. After the buyer clicks the PayPal button and you submit the Set Express Checkout request, you will want to automatically direct your buyer to the PayPal website. The redirect URL for this is shown below. TOKEN is the value returned in the Set Express Checkout response.

https://www.paypal.com/cgi-bin/webscr?cmd=_expresscheckout&token=<TOKEN>

The buyer is presented with a PayPal Review page, such as the example page shown in

Figure 2.4. The buyer must click Agree and Continue for steps 5 through 8 below to

occur.

FIGURE 2.4 PayPal Review page

4. PayPal redirects the buyer’s browser to your return page.

5. Call the Get Express Checkout Details request (ACTION=G) to obtain information about the

buyer. PayPal returns the buyer information, including whether the billing agreement was accepted.

6. Call the Create buyer Billing Agreement request (ACTION=X) to obtain the BAID.

7. PayPal returns a BAID. Save the BAID to implement Payflow reference transactions.

Express Checkout for Payflow 27

Billing Agreements and Reference Transactions

Obtaining the BAID Without Express Checkout Purchase

Example of Obtaining the BAID Without Express Checkout Purchase

This section provides an example of obtaining the BAID. The billing agreement parameters (and AMT, which must be 0) are shown in boldface.

Set Express Checkout Request (ACTION=S)

The following is an example of a Set Express Checkout request that passes billing agreement parameters:

IMPORTANT: Even though no payment is sent, the value of TRXTYPE must be A in the

request strings.

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=S &TENDER=P &RETURNURL=http://return.com &CANCELURL=http://cancel.com

&AMT=0.00 &BA_DESC=purchase Time magazine &BILLINGTYPE=MerchantInitiatedBilling

&PAYMENTTYPE=any &BA_CUSTOM=magazine subscription

Set Express Checkout Response

RESULT=0 &RESPMSG=Approved &TOKEN=EC-36X58962RS656712N &CORRELATIONID=a398b1f35ebfa

Create Customer Billing Agreement Request (ACTION=X)

The Create Customer Billing Agreement request passes the TOKEN returned in the Set Express Checkout response:

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=X &TENDER=P &TOKEN=EC-36X58962RS656712N

Create Customer Billing Agreement Response

The response returns the BAID:

28 Express Checkout for Payflow

RESULT=0 &PNREF=E24P0A03B013 &RESPMSG=Approved &TOKEN=EC-36X58962RS656712N &PPREF=44000000000180903 &CORRELATIONID=3a3204997455r

&BAID=B-12345678901234567

Updating a Billing Agreement

You can use the Update Billing Agreement request to cancel the billing agreement or update the billing agreement description.

Some points to note:

 Do not pass TRXTYPE with this transaction.  BAID is the only required parameter (ACTION=U).  The only value you can pass for BA_STATUS is cancel to change the billing agreement

status.

Billing Agreements and Reference Transactions

Updating a Billing Agreement

 You can change the billing agreement description by entering a different string value for

BA_DESC.

 The response does not return a PNREF.

PayPal responds with the BAID and other information about the buyer whose agreement was updated.

Although a buyer can log in to PayPal to manage agreements, the Update Billing Agreement request enables the buyer to cancel an agreement from your website without logging in to PayPal. You can provide your own page for maintaining agreements with the buyer.

Example of Updating a Billing Agreement

The following is an example of updating a billing agreement description. Billing agreement parameters are shown in boldface:

Request

PARTNER=partner &VENDOR=vendor &PWD=password &TENDER=P &USER=user &ACTION=U &BA_DESC=Description &BAID=B-92K90916NV400134C &BA_STATUS=cancel

Express Checkout for Payflow 29

Billing Agreements and Reference Transactions

Using Reference Transactions

Response

RESULT=0 &RESPMSG=Approved &PPREF=68W3371331353001F &CORRELATIONID=6d348905b0d59 &BAID=B-92K90916NV400134C

Using Reference Transactions

This section provides examples of reference transactions that bill PayPal accounts. The examples illustrate two parameter options. In the reference transaction request, you can pass either of the following name-value pair parameters returned in either the response to Create Customer Billing Agreement (ACTION=X) or the response to Do Express Checkout Payment (ACTION=D):

 PNREF passed as value of ORIGID  BAID

The examples below are based on Do Express Checkout Payment (ACTION=D) and illustrate passing the ORIGID and the BAID. The reference transaction request does not pass the Express Checkout TOKEN or PAYERID as described in

“Express Checkout Processing Flow”

on page 9.

Reference Transaction Request Passing the BAID

Request

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=D &TENDER=P &AMT=1&BAID=B-12345678901234567

Response

RESULT=0 &PNREF=E24P0A03B014 &RESPMSG=Approved &PPREF=44000000000180905 &CORRELATIONID=dr093d08c9f01 &FEEAMT=0.33

&BAID=B-12345678901234567

&PAYMENTTYPE=instant &PENDINGREASON=authorization

30 Express Checkout for Payflow

Billing Agreements and Reference Transactions

Using Reference Transactions

Reference Transaction Request Passing the PNREF Value as ORIGID

Request

In this example, the BAID is not required because the ORIGID is being passed:

PARTNER=partner &VENDOR=vendor &PWD=password &USER=user &TRXTYPE=A &ACTION=D &TENDER=P &AMT=1 &ORIGID=E24P0A03B013

Response

RESULT=0 &PNREF=E24P0A03B015 &RESPMSG=Approved &PPREF=44000000000180907 &CORRELATIONID=dr093d08c9f01 &BAID=B-12345678901234567 &PAYMENTTYPE=instant &PENDINGREASON=authorization

Express Checkout for Payflow 31

Billing Agreements and Reference Transactions

Using Reference Transactions

32 Express Checkout for Payflow

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.

 Honor Period and Authorization Period  Payment Transaction Types  Sale  Authorization  Order  Do Reauthorization  Do Authorization  Delayed Capture  Void  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 with a Do Authorization.

Payment Transaction Types

During the Express Checkout flow, the following transaction types are supported:

 Sale (TRXTYPE=S)  Authorization (TRXTYPE=A)

Do Reauthorization or multiple times

 Order (TRXTYPE=O)

Express Checkout for Payflow 33

Express Checkout Transaction Types

Sale

After the Express Checkout flow , you can manage the capture of payment using the following transaction types:

 Do Reauthorization (TRXTYPE=A)  Do Authorization (TRXTYPE=A)  Delayed Capture (TRXTYPE=D)  Void (TRXTYPE=V)  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:

 Set Express Checkout request: TRXTYPE=S, ACTION=S  Get Express Checkout Details request (optional): TRXTYPE=S, ACTION=G  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 backordered 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

Reauthorization. Merchants get around these limitations by choosing to perform an Order

34 Express Checkout for Payflow

Express Checkout Transaction Types

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:

 Set Express Checkout request: TRXTYPE=A, ACTION=S  Get Express Checkout Details request (optional): TRXTYPE=A, ACTION=G  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 &TOKEN=EC-17C76533PL706494P &PAYERID=FHY4JXY7CV9PG &PPREF=2P599077L3553652G

Order

To capture authorized funds, you use the PNREF to reference the original Authorization transaction. See

Delayed Capture for details.

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:

 Back orders, in which you send available merchandise immediately and the remaining

merchandise, as it is available

 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

 Drop shipments, or shipments from other vendors, for which you accep t 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.

Express Checkout for Payflow 35

Express Checkout Transaction Types

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 &TOKEN=EC-17C76533PL706494P &PAYERID=FHY4JXY7CV9PG &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:

 Set ORIGID=PNREF (PNREF returned in the original Authorization response)  Set TRXTYPE=A  Set DoReauthorization=1

This is an example Do Reauthorization request with required parameters:

36 Express Checkout for Payflow

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.

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

Express Checkout Transaction Types

Do Authorization

 Set ORIGID=PNREF (PNREF value returned in the original Order transaction response

only)

NOTE: Do not pass the PPREF returned from the original Order transaction in place of the

PNREF.

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

Express Checkout for Payflow 37

Express Checkout Transaction Types

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:

 Set ORIGID=PNREF (PNREF value returned in the original Authorization, Do

Authorization, or Do Reauthorization transaction response)

 Set TRXTYPE=D

This is an example Delayed Capture request with required parameters.

TRXTYPE=D &TENDER=P &PARTNER=partner &USER=user &VENDOR=vendor &PWD=pwd &ORIGID=EFHP0CDBF5C7

Partial Capture

To set up a partial capture of authorized funds, pass the following parameters in the Delayed Capture request string:

 Set ORIGID=PNREF (PNREF value returned in the original Authorization, Do

Authorization, or Do Reauthorization transaction response)

 Set TRXTYPE=D  Set the value for AMT  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

38 Express Checkout for Payflow

Void

Express Checkout Transaction Types

Void

A Void transaction voids any of the following transaction types:

 Order  Authorizations (Authorization, Do Authorization, or Do Reauthorization)

NOTE: You can use a Void transaction only on transactions that have not yet settled. T o refund

a buyer’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.

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

 Set ORIGID=PNREF (PNREF value returned in the response to the original Authorization or

Order)

Credit

 Set TRXTYPE=V

This is an example Void transaction request with the required parameters set.

TRXTYPE=V &TENDER=P &PARTNER=partner &USER=user &VENDOR=vendor &PWD=pwd &ORIGID=EFHP0CDBF5C7

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:

 Set ORIGID=PNREF (PNREF value returned in the response to the original Sale or Delayed

Capture)

 Set TRXTYPE=C  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 with the required parameters set:

Express Checkout for Payflow 39

Express Checkout Transaction Types

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.

40 Express Checkout for Payflow

Transaction Responses

Transaction response parameters indicate the status of the transaction and return requested information.

 Response Parameters  Address Verification Service Responses From PayPal  Card Security Code Results  PNREF Value  RESULT Values and RESPMSG Text

Response Parameters

When a transaction finishes, the server returns a response 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 4.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.

NOTE: 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.

Express Checkout for Payflow 41

Transaction Responses

Address Verification Service Responses From PayPal

TABLE 4.1 General response parameters

Parameter Description

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.

NOTE: 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 addre ss 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 4.2 Address Verification Service response value mapping

PayPal Processor Address Verification Service Code

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

Meaning AVSADDR AVSZIP

G Global Unavailable X X I International Unavailable X X

42 Express Checkout for Payflow

Transaction Responses

Card Security Code Results

TABLE 4.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 4.3 CVV2MATCH resp onse v alues

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.

Express Checkout for Payflow 43

Transaction Responses

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 4.4 Card security code response code mapping

PayPal Processor CVV2 Code

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

 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).

PayPal Processor Code Description

ID column in PayPal Manager reports.

PROCVV2MATCH

 The PNREF value is used as the ORIGID value (original transaction ID) value in reference

transactions for Authorization (TRXTYPE=A) and Sale (TRXTYPE=S).

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

 VADE0B248932

 ACRAF23DB3C4

NOTE: 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.

44 Express Checkout for Payflow

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:

 A value of 0 (zero) indicates that no errors occurred and the transaction was approved.  A value less than zero indicates that a communication error occurred. In this case, no

transaction is attempted.

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

Transaction Responses

When interpreting RESULT values for the PayPal processor, note the following:

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

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

Source Responses

TABLE 4.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:

 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 user. All fields are case sensitive.

 Invalid Processor information entered. Contact merchant bank to verify.  "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.

 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

Express Checkout for Payflow 45

Transaction Responses

RESULT Values and RESPMSG Text

TABLE 4.5 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

2 Invalid tender type. Your merchant bank account does not support the following

3 Invalid transaction type. Transaction type is not appropriate for this transaction.

4 Invalid amount format. Use the format: “#####.##” Do not include currency

5 Invalid merchant information. Processor does not recognize your merchant

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

credit card type that was submitted.

For example, you cannot credit an authorization-only transaction

symbols or commas.

account information. Contact your bank account acquirer to resolve this problem.

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

 You are trying to process a tender typ e such as Discover Card, but you are not

set up with your merchant bank to accept this card type.

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

46 Express Checkout for Payflow

Transaction Responses

RESULT Values and RESPMSG Text

TABLE 4.5 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

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

VENDOR, P ARTNER, and PASSWORD have been entered correctly. VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow 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

Express Checkout for Payflow 47

Transaction Responses

RESULT Values and RESPMSG Text

TABLE 4.5 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

108 Void error. See RESPMSG. Make sure the transaction ID entered has not already

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

112 Failed AVS check. Address and ZIP code do not match. An authorization may still

113 Merchant sale total will exceed the sales cap with current transaction. ACH

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)

authorization transaction type, or an attempt to capture an authorization transaction that has already been captured.

exist on the cardholder’s account.

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

48 Express Checkout for Payflow

Transaction Responses

RESULT Values and RESPMSG Text

TABLE 4.5 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

126 Fraud Protection Services Filter — Flagged for review by filters

IMPORTANT: 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.

T o eliminate RESULT 126, tu rn 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 1011 Buyer Authentication Service unavailable 1012 Buyer Authentication Service unavailable 1013 Buyer Authentication Service unavailable 1014 Buyer Authentication Service — Merchant is not enrolled for Buyer

Authentication Service (3-D Secure)

Express Checkout for Payflow 49

Transaction Responses

RESULT Values and RESPMSG Text

TABLE 4.5 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

1016 Buyer Authentication Service — 3-D Secure error r esponse received. Instead of

1017 Buyer Authentication Service — 3-D Secure error r esponse is invalid. An error

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

1042 Buyer Authentication Service — Validate Authentication failed: PARES

receiving a PARes response to a Validate Authentication transaction, an error response was received.

response is received and the response is not well formed for a Validate Authentication transaction.

invalid 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

1046 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid acquirer in PARES

1047 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid Merchant ID in PARES

1048 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid card number in PARES

1049 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid currency code in PARES

1050 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid XID in PARES

1051 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid order date in PARES

1052 Buyer Authentication Service — Validate Authentication failed: This PARES

was already validated for a previous Validate Authentication tra nsaction

50 Express Checkout for Payflow

Express Checkout Testing

You can set up the testing of your integration using two methods.

 Testing Your Integration Using the Sandbox  Testing Your Integration Using the PayPal Simulator

Testing Your Integration Using the Sandbox

To set up the testing of your integration using the Sandbox:

 Create A Business Account  Create a Payflow Test Account  Link Your Payflow 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

1. Follow the procedure described on the MTS website:

https://ppmts.custhelp.com/app/answers/detail/a_id/929/

Create a Payflow Test Acco unt

To create Payflow test account, follow the procedure described on the MTS website:

https://ppmts.custhelp.com/app/answers/detail/a_id/929/

Link Your Payflow Account to the Sandbox

To link your Payflow account to the Sandbox, follow the procedure described on th e MTS website:

Be sure to:

 Send all test transaction requests as POSTs to the Payflow host address: https://pilot-

https://ppmts.custhelp.com/app/answers/detail/a_id/929/

payflowpro.paypal.com

“Create a Payflow Test Account” on page 51

 Send Express Checkout redirects to: https://www.sandbox.paypal.com/cgi-

bin/webscr?cmd=_express-checkout&token=<ec-token>

Express Checkout for Payflow 51

Express Checkout Testing

Testing Your Integration Using the PayPal Simulator

NOTE: You must be logged into the Sandbox before redirecting.

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.

Testing Your Integration Using the PayPal Simulator

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.

NOTE: You must activate your account and configure your application for live transactions in

PayPal Manager before accepting real orders.

52 Express Checkout for Payflow

Express Checkout Parameter

Reference

This reference describes all parameters that can be used with the Express Checkout payment solution.

 “Connection Parameter Descriptions” on page 53  “User Parameter Descriptions” on page 54  “Express Checkout Parameter Descriptions” on page 55  “Do Reauthorization Parameter Descriptions” on page 73  “Do Authorization Parameter Descriptions” on page 72  “Void Parameter Descriptions” on page 73  “Credit Parameter Descriptions” on page 74  “Delayed Capture Parameter Descriptions” on page 75  “Billing Agreement Parameter Descriptions” on page 76  “Reference Transaction Parameter Descriptions” on page 79

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

Parameter Description

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 admi nist rator can provide the values.

PROXYPORT (Optional) Proxy server port.

Express Checkout for Payflow 53

Express Checkout Parameter Reference

User Parameter Descriptions

TABLE A.1 Connection request parameters

Parameter Description

PROXYLOGON (Optional) Proxy server logon ID. 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

Parameter Description

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

54 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

Set Express Checkout Request Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

TRXTYPE (Required) How you want to obtain payment:

 A indicates that this payment is an Authorization subject to settlement

with the Delayed Capture request

 O indicates that this payment is an Order subject to settlement with the

Delayed Capture request

 S indicates that this is a final Sale for which you are requesting

payment

NOTE: 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.

Limitations: One alpha character.

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

Limitations: One alpha character.

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

NOTE: You must set CURRENCY to one of the currency codes for any of

the supported PayPal currencies.

Set AMT=0.00 when passing the billing type value MerchantInitiatedBilling to use the TOKEN returned by the Set Express Checkout response as a parameter in a request to create a billing agreement.

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 85.”

RETURNURL (Required) URL to which the buyer’s browser is returned after choosing to

pay. Limitations: Character string with no maximum length.

Express Checkout for Payflow 55

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

CANCELURL (Required) URL to which the buyer is returned if the buyer cancels the

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

L_BILLINGTYPEn (Optional) Describes the billing type for a PayPal account that will be

order. Limitations: Character string with no maximum length.

Authorization request. The value is returned in a previous Set Express Checkout response.

Limitations: 20-character alphanumeric string.

billed with Recurring Payments. Set to RecurringPayments to use the TOKEN returned in the Set Express Checkout response to create a Recurring Payments profile. .

Either L_BILLINGTYPEn or BILLINGTYPE must be passed to create a Recurring Payments profile. If you pass L_BILLINGTYPEn and BILLINGTYPE, BILLINGTYPE will be ignored.

Each L_BILLINGTYPEn must have a corresponding description string (L_BILLINGAGREEMENTDESCRIPTIONn).

See PayPal Payments Pro Payflow Edition - Recurring Payments

Developer’s Guide for details on creating Recurring Payments profiles.

Character length and limitations: A string. n is a value in the range 0-9.

L_BILLINGAGREEMEN

TDESCRIPTIONn

BILLINGTYPE (Optional) Describes the billing type for a PayPal account.

BA_DESC

BA_CUSTOM (Optional) Custom annotation field for your exclusive use with billing

(Optional) Describes the billing type for a PayPal account that will be billed with Recurring Payments. See L_BILLINGTYPEn.

Character length and limitations: A string. n is a value in the range 0-9.

The possible values are:

 MerchantInitiatedBilling

Use this value to obtain a BAID in the Set Express Checkout flow.

 RecurringPayments

Use this value to use the TOKEN returned in the Set Express Checkout response to create a Recurring Payments profile. See

Pro Payflow Edition - Recurring Payments Developer’s Guide for

details on creating Recurring Payments profiles.

Character length and limitations: A string. n is a value in the range 0-9.

(Optional) Describes the billing agreement for a PayPal account. If BILLINGTYPE is RecurringPayments, BA_DESC is required. Limitations: 255-character string.

agreements. Limitations: 255-character string

PayPal Payments

56 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

PAYMENTTYPE (Optional) Is one of the following values:

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

pending.

Limitations: 11 characters.

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.

NOTE: You can view line item information in the Transaction Details

report in your PayPal merchant account.

Limitations: 35-character string.

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.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies. See in this table for details.

CURRENCY

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.

Nine numeric characters plus decimal.

L_TAXAMTn (Optional) Line-item tax amount.

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.

Express Checkout for Payflow 57

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

TAXAMT (Required if L_TAXAMTn is specified) Sum of tax for all items in this

FREIGHTAMT (Optional) Total shipping cost for this order.

HANDLINGAMT (Optional) Total handling cost for this order.

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

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies.

DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a

positive amount. 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.

INSURANCEAMT (Optional) Total shipping insurance cost for this order.

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.

58 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

MAXAMT (Optional) The expected maximum total amount of the complete order,

including shipping and tax charges. 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.

ORDERDESC (Optional) Description of items the buyer is purchasing.

Limitations: 127-character alphanumeric string.

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.

Limitations: 256-character alphanumeric string.

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 buyer’s

billing address on file with PayPal be returned. Setting this element will return BILLTONAME, STREET, STREET2, CITY, STATE, ZIP, and COUNTRYCODE.

Limitations: One character.

REQCONFIRMSHIPPIN G

NOSHIPPING (Optional) Is 1 or 0. The value 1 indicates that on the PayPal pages, no

ADDROVERRIDE (Optional) Is 1 or 0. The value 1 indicates that the PayPal pages should

(Optional) Is 1 or 0. The value 1 indicates that you require that the buyer’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.

shipping address fields should be displayed whatsoever. Limitations: Four-character string.

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

Limitations: Four-character string.

Express Checkout for Payflow 59

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

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.

Limitations: 127-character string.

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.

Limitations: Six-character HTML hexadecimal color code in ASCII.

PAYFLOWCOLOR (Optional) Sets the background color for the payment page.

Limitations: Six-character HTML hexadecimal color code in ASCII.

60 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.3 Set Express Checkout request parameters

Parameter Description

EMAIL (Optional) Email address of the buyer as entered during checkout. PayPal

uses this to fill out the PayPal membership sign-up portion of the PayPal login page.

Limitations: 127-character alphanumeric string.

SHIPTONAME (Optional) Ship-to name.

Limitations: 32-character string.

SHIPTOSTREET (Optional) Ship-to street address.

Limitations: 30-character string.

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

3. Limitations: 30-character string.

SHIPTOCITY (Optional) Ship-to city.

Limitations: 40-character string.

SHIPTOSTATE (Optional) Ship-to state.

Limitations: 40-character string.

SHIPTOZIP (Optional) Ship-to postal code.

Limitations: 16-character string.

SHIPTOCOUNTRY (Optional) Ship-to country.

Limitations: Two-character country code.

Set Express Checkout Response Parameter Descriptions

TABLE A.4 Set Express Checkout response parameters

Parameter Description

TOKEN A time-stamped token 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.

Limitations: 20-character string.

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

Express Checkout for Payflow 61

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

Get Express Checkout Details Request Parameter Descriptions

TABLE A.5 Get Express Checkout Details request parameters

Parameter Description

TRXTYPE (Required) How you want to obtain payment:

 A indicates that this payment is an Authorization subject to settlement

with the Delayed Capture request

 O indicates that this payment is an Order subject to settlement with the

Delayed Capture request

 S indicates that this is a final Sale for which you are requesting

payment

NOTE: 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.

Limitations: One alpha character.

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

Limitations: One alpha character.

TOKEN (Required) A time-stamped token, the value of which was returned in the

Set Express Checkout response. Limitations: 20-character alphanumeric string.

Get Express Checkout Details Response Parameter Descriptions

TABLE A.6 Get Express Checkout Details response parameters

Parameter Description

TOKEN The time-stamped token value that was returned in the Set Express

Checkout response. Limitations: 20-character alphanumeric string.

EMAIL Email address of the buyer as entered during checkout.

Limitations: 127-character alphanumeric string.

PAYERID Unique PayPal buyer account identification number.

Limitations: 13-character string.

62 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.6 Get Express Checkout Details response parameters

Parameter Description

PAYERSTATUS Status of buyer. Values are:

 verified  unverified

Limitations: 10-character string.

DISCOUNT Shipping discount for this order. Specify the discount as a positive

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

INSURANCEAMT Total shipping insurance cost for this order.

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.

Limitations: 255-character string.

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.

NOTE: 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.

FIRSTNAME Buyer’s first name.

Limitations: 25-character string.

LASTNAME Buyer’s last name.

Limitations: 25-character string.

Express Checkout for Payflow 63

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.6 Get Express Checkout Details response parameters

Parameter Description

SHIPTONAME Ship-to name.

SHIPTOSTREET Ship-to street address

SHIPTOSTREET2 Extended Ship-to street address. Example: Bldg. 6, Mail Stop 3.

SHIPTOCITY Ship-to city.

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.

Limitations: 32-character string.

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.

Limitations: 30-character string.

Limitations: 40-character string.

SHIPTOSTATE Ship-to state.

Limitations: 40-character string.

SHIPTOZIP Ship-to postal code.

Limitations: 16-character string.

SHIPTOCOUNTRY Ship-to country.

Limitations: Two-character country code.

SHIPTOBUSINESS Buyer’s business name.

Limitations: 127-character string.

CUSTOM Free-form field for your own use as set by you in the Set Express

Checkout request. Limitations: 256-character alphanumeric string.

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.

Limitations: 20-character string. The field mask is:

xxx-xxx-xxxx (US numbers) +xxxxxxxxxxx (international numbers)

64 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.6 Get Express Checkout Details response parameters

Parameter Description

BILLTONAME Bill-to name.

NOTE: The bill-to address details are return ed returned only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: 32 alphanumeric characters.

STREET Bill-to street.

NOTE: The bill-to address details are return ed only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: 100 alphanumeric characters.

STREET2 Second bill-to street address.

NOTE: The bill-to address details are return ed only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: 100 alphanumeric characters.

CITY Bill-to city address.

NOTE: The bill-to address details are return ed only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: 45 alphanumeric characters.

STATE Bill-to state address.

NOTE: The bill-to address details are return ed only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: 45 alphanumeric characters.

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

NOTE: The bill-to address details are return ed only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: 10 alphanumeric characters.

COUNTRYCODE Bill-to country code.

NOTE: The bill-to address details are return ed only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: Four alphanumeric characters.

Express Checkout for Payflow 65

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.6 Get Express Checkout Details response parameters

Parameter Description

ADDRESSSTATUS Status of the bill-to address on file with PayPal. The values are:

 Y = confirmed  N = unconfirmed

The bill-to address details are returned only if REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: One alpha character.

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

Do Express Checkout Payment Request Parameter Descriptions

TABLE A.7 Do Express Checkout Payment request parameters

Parameter Description

TRXTYPE (Required) How you want to obtain payment:

 A indicates that this payment is an Authorization subject to settlement

with the Delayed Capture request

 O indicates that this payment is an Order subject to settlement with the

Delayed Capture request

 S indicates that this is a final Sale for which you are requesting

payment

NOTE: 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.

Limitations: One alpha character.

TOKEN (Required) The timestamped token that was returned in the Set Express

Checkout response. Limitations: 20-character string.

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

Limitations: One alpha character.

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

returned by Get Express Checkout Details response. This value is returned in the URL when the buyer is redirected to your website.

Limitations: 13-character string.

66 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.7 Do Express Checkout Payment request parameters

Parameter Description

AMT (Required) Amount.

ORDERURL (Optional) Your URL for displaying information about this transaction,

such as receipt, shipment tracking, or order details. Limitations: 127-character alphanumeric string.

ORDERDESC (Optional) Description of items the buyer is purchasing.

Limitations: 127-character alphanumeric string.

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

Limitations: 256-character alphanumeric string.

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 buyer'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. Limitations: 32 alphanumeric characters.

NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN)

about this transaction.

NOTE: If you do not specify NotifyURL in the request, the notification

URL from your Merchant Profile is used, if one exists.

Limitations: 2048 alphanumeric characters.

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.

NOTE: You can view line item information in the Transaction Details

report in your PayPal merchant account.

Limitations: 35-character string.

Express Checkout for Payflow 67

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.7 Do Express Checkout Payment request parameters

Parameter Description

L_COSTn (Required if L_QTYn is supplied) Cost of the line item. The line-item unit

L_TAXAMTn (Optional) Line-item tax amount.

price can be a positive or a negative value but not 0.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies. See in this table for details.

Nine numeric characters plus decimal.

CURRENCY

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.

TAXAMT (Required if L_TAXAMTn is specified) Sum of tax for all items in this

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

FREIGHTAMT (Optional) Total shipping cost for this order.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies.

68 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.7 Do Express Checkout Payment request parameters

Parameter Description

HANDLINGAMT (Optional) Total handling cost for this order.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies.

DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a

positive amount. 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.

INSURANCEAMT (Optional) Total shipping insurance cost for this order.

SHIPTONAME (Optional) Ship-to name.

Limitations: 32-character 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.

Limitations: 30-character string.

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

3. Limitations: 30-character string.

SHIPTOCITY (Optional) Ship-to city.

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

Limitations: 40-character string.

SHIPTOSTATE (Optional) Ship-to state.

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

Limitations: 40-character string.

Express Checkout for Payflow 69

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.7 Do Express Checkout Payment request parameters

Parameter Description

SHIPTOZIP (Optional) Ship-to postal code.

SHIPTOCOUNTRY (Optional) Ship-to country.

PHONENUM (Optional) Account holder’s telephone number.

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

Limitations: 16-character string.

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

Limitations: Two-character country code.

Limitations: 20-character string. The field mask is:

xxx-xxx-xxxx (US numbers) +xxxxxxxxxxx (international numbers)

Do Express Checkout Payment Response Parameter Descriptions

TABLE A.8 Do Express Checkout Payment response parameters

Parameter Description

TOKEN The timestamped token that was returned in the Set Express Checkout

response. Limitations: 20-character string.

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.

Limitations: 17-character string.

BAID The billing agreement ID is returned if BILLINGTYPE is passed in the Set

Express Checkout request to set up a billing agreement. Limitations: 19-character string.

PAYMENTTYPE Returns one of the following values:

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

pending (see PENDINGSTATUS).

Limitations: 11 characters.

70 Express Checkout for Payflow

Express Checkout Parameter Reference

Express Checkout Parameter Descriptions

TABLE A.8 Do Express Checkout Payment response parameters

Parameter Description

TAXAMT Sum of tax for all items in this order.

FEEAMT Processor charge for the transaction.

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.

Limitations: 255-character string.

PENDINGREASON The reason the payment is pending. Values are:

 none = No pending reason.  address = The payment is pending because your buyer 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.

 echeck = The payment is pending because it was made by an eCheck

that has not yet cleared.

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

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

 verify = The payment is pending because you are not yet verified.

You must verify your account before you can accept this payment.

 completed = The payment has been completed, and the funds have

been added successfully to your account balance.

 other = The payment is pending for a reason other than those listed

above. For more information, contact PayPal Customer Service.

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

Express Checkout for Payflow 71

Express Checkout Parameter Reference

Do Authorization Parameter Descriptions

TABLE A.9 Do Authorization request parameters

Parameter Description

TRXTYPE (Required) The type of transaction to perform. For a Do Authorization,

the value is A. Limitations: One alpha character.

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

ORIGID (Required) Payflow transaction ID. To autho rize 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. 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.

TABLE A.10 Do Authorization response parameters

Parameter Description

PPREF Unique PayPal transaction ID.

Limitations: 17-character string.

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

72 Express Checkout for Payflow

Express Checkout Parameter Reference

Do Reauthorization Parameter Descriptions

TABLE A.11 Do Reauthorization request parameters

Parameter Description

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.

Limitations: One alpha character.

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

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.

Limitations: 12 case-sensitive alphanumeric characters.

DOREAUTHORIZATION (Required) Indicates whether this transaction is a Do Reauthorization. The

value is 1.

TABLE A.12 Do Reauthorization response parameters

Parameter Description

PPREF Unique PayPal transaction ID.

Limitations: 17-character string.

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

Void Parameter Descriptions

TABLE A.13 Void request parameters

Parameter Description

TRXTYPE (Required) Type of transaction to perform. The value is V.

Limitations: One alpha character.

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

Express Checkout for Payflow 73

Express Checkout Parameter Reference

Credit Parameter Descriptions

TABLE A.13 Void request parameters

Parameter Description

ORIGID (Required) Payflow transaction ID. Set this parameter to the value of the

NOTE (Optional) An informal note about this settlement that is displayed to the

TABLE A.14 Void response parameters

Parameter Description

PPREF Unique PayPal transaction ID.

RESULT Response value for the request.

PNREF returned in the original transaction response when Do Express

Checkout Payment request was submitted with TRXTYPE=O. Limitations: 12 case-sensitive alphanumeric characters.

buyer in email and in the buyer’s transaction history Limitations: 255-character string.

Limitations: 17-character string.

RESPMSG Response message in case if any error occurs.

Credit Parameter Descriptions

TABLE A.15 Credit request parameters

Parameter Description

TRXTYPE (Required) Type of transaction to perform. The value is C.

Limitations: One alpha character.

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

ORIGID (Required) Payflow transaction ID. Set this parameter to the value of the

PNREF returned in the original Authorization or Order Do Express

Checkout Payment transaction response. Limitations: 12 case-sensitive alphanumeric characters.

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

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.

74 Express Checkout for Payflow

Express Checkout Parameter Reference

Delayed Capture Parameter Descriptio n s

TABLE A.15 Credit request parameters

Parameter Description

MEMO (Optional) Custom memo about the credit.

Limitations: 255 alphanumeric characers.

TABLE A.16 Credit response parameters

Parameter Description

PPREF Unique PayPal transaction ID.

Limitations: 17-character string.

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

Delayed Capture Parameter Descriptions

TABLE A.17 Delayed Capture request parameters

Parameter Description

TRXTYPE (Required) Type of transaction to perform. The value is D.

Limitations: One alpha character.

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

ORIGID (Required) Payflow transaction ID. Set this parameter to the value of the

PNREF returned in the original Authorization or Order Do Express

Checkout Payment transaction response. Limitations: 12 case-sensitive alphanumeric characters.

AMT (Optional) Required if the capture amount differs from the original

Authorization amount. 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.

NOTE (Optional) An informal note about this settlement that is displayed to the

buyer in email and in the buyer’s transaction history Limitations: 255-character string.

Express Checkout for Payflow 75

Express Checkout Parameter Reference

Billing Agreement Parameter Descriptions

TABLE A.17 Delayed Capture request parameters

Parameter Description

CAPTURECOMPLETE (Optional) Indicates if this Delayed Capture transaction is the last capture

TABLE A.18 Delayed Capture response parameters

Parameter Description

PPREF Unique PayPal transaction ID.

PAYMENTTYPE Type of payment. Values are:

you intend to make. The values are:

 Y (default)  N

If CAPTURECOMPLETE is Y, any remaining amount of the original reauthorized transaction is automatically voided.

Limitations: 12-character alphanumeric string.

Limitations: 17-character string.

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

pending.

Limitations: 11 characters.

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

Billing Agreement Parameter Descriptions

Create Customer Billing Agreement Request Parameters

TABLE A.19 Create Customer Billing Agreement request parameters

Parameter Description

ACTION (Required) Is X to indicate this is a Create Customer Billing Agreement

without purchase request. Limitations: One alpha character.

TOKEN (Required) A time-stamped token, the value of which was returned in the

Set Customer Billing Agreement response. Limitations: 20-character alphanumeric string.

TRXTYPE (Required) Must be A.

76 Express Checkout for Payflow

Express Checkout Parameter Reference

Billing Agreement Parameter Descriptions

TABLE A.19 Create Customer Billing Agreement request parameters

Parameter Description

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

Create Customer Billing Agreement Response Parameters

TABLE A.20 Create Customer Billing Agreement response parameters

Parameter Description

BAID The billing agreement ID.

Limitations: 19-character string.

TOKEN A time-stamped token, the value of which was returned in the Set

Customer Billing Agreement response. Limitations: 20-character alphanumeric string.

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

Update Customer Billing Agreement Request Parameters

TABLE A.21 Update Customer Billing Agreement request parameters

Parameter Description

ACTION (Required) Is U to indicate this is an Update Billing Agreement request.

Limitations: One alpha character.

TENDER (Required) The tender type (method of payment). It is always P.

Limitations: One alpha character.

BAID (Required) The billing agreement ID.

Limitations: 19-character string.

BA_CUSTOM (Optional) Custom annotation field for your exclusive use.

Limitations: 255-character string.

BA_DESC (Optional) Description of goods or services associated with the billing

agreement. Limitations: 255-character string.

BA_STATUS (Optional) The status of the billing agreement. The only value is cancel.

Express Checkout for Payflow 77

Express Checkout Parameter Reference

Billing Agreement Parameter Descriptions

Update Customer Billing Agreement Response Parameters

TABLE A.22 Update Customer Billing Agreement response parameters

Parameter Description

BAID The billing agreement ID.

Limitations: 19-character string.

BA_CUSTOM Custom annotation fiel d for your exclusi ve us e.

Limitations: 255-character string.

BA_DESC Description of goods or services associated with the billing agreement.

Limitations: 255-character string.

EMAIL Email address of the buyer as entered during checkout.

Limitations: 127-character alphanumeric string.

PAYERSTATUS Status of buyer. Values are:

 verified  unverified

Limitations: 10-character string.

PHONENUM Account holder’s telephone number.

Limitations: 20-character string. The field mask is:

xxx-xxx-xxxx (US numbers) +xxxxxxxxxxx (international numbers)

FIRSTNAME Buyer’s first name.

Limitations: 25-character string.

LASTNAME Buyer’s last name.

Limitations: 25-character string.

SHIPTOBUSINESS Buyer’s business name.

Limitations: 127-character string.

SHIPTOSTREET (Optional) Ship-to street address.

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

Limitations: 30-character string.

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

3. Limitations: 30-character string.

SHIPTOCITY (Optional) Ship-to cit y.

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

Limitations: 40-character string.

78 Express Checkout for Payflow

Express Checkout Parameter Reference

Reference Transaction Parameter Descriptions

TABLE A.22 Update Customer Billing Agreement response parameters

Parameter Description

SHIPTOSTATE (Optional) Ship-to state.

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

Limitations: 40-character string.

SHIPTOZIP (Optional) Ship-to postal code.

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

Limitations: 16-character string.

SHIPTOCOUNTRY (Optional) Ship-to country.

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

Limitations: Two-character country code.

RESULT Response value for the request.

RESPMSG Response message in case if any error occurs.

Reference Transaction Parameter Descriptions

Reference Transaction Request Parameters

TABLE A.23 Reference Transaction Request Parameters

Parameter Description

ACTION (Required) Is the value D. TRXTYPE (Required) Is A (Authorization) or S (Sale). BAID (Required, PayPal and Paymentech Salem processors) BAID returned

from Create Customer Billing Agreement. If you pass BAID, do not pass ORIGID.

ORIGID (Required, other Payflow processors) PNREF returned from Create

Customer Billing. If you pass ORIGID, do not pass BAID.

CUSTIP (Optional) IP address of payer’s browser as recorded in its HTTP request

to your website.

NOTE: PayPal records this IP address as a means to detect possible

fraud.

Limitations: 15-character string in dotted quad format: xxx.xxx.xxx.xxx.

Express Checkout for Payflow 79

Express Checkout Parameter Reference

Reference Transaction Parameter Descriptions

TABLE A.23 Reference Transaction Request Parameters

Parameter Description

PAYMENTTYPE (Optional) Is one of the following values:

REQCONFIRMSHIPPING (Optional) Is 1 or 0. The value 1 indicates that you require that the

CURRENCY (Required) One of the supported currency codes. See Appendix ,

ORDERDESC (Optional) Description of items the buyer is purchasing

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

pending.

Limitations: 11 characters.

buyer’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.

“Currency Codes.”

Limitations: 127-character alphanumeric string.

CUSTOM (Optional) Free-form field for your own use such as a tracking number or

other value you want PayPal to return in the Ge t Ex press Checkout Details response.

Limitations: 256-character alphanumeric string.

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.

BUTTONSOURCE (Optional) Identification code for use by third-party applications to

identify transactions. Limitations: 32 alphanumeric characters.

NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN)

about this transaction.

NOTE: If you do not specify N oti fyURL in the request, the notification

URL from your Merchant Profile is used, if one exists.

Limitations: 2048 alphanumeric characters.

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. Limitations: 35-character string.

80 Express Checkout for Payflow

Express Checkout Parameter Reference

Reference Transaction Parameter Descriptions

TABLE A.23 Reference Transaction Request Parameters

Parameter Description

L_COSTn (Optional) Line-item unit price. The line-item unit price can be a positive

or a negative value but not 0. You may provide a negative value to reflect a discount on an order, for example.

L_TAXAMTn (Optional) Line-item tax amount.

Limitations: 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. No currency symbol. Limitations: Six-character currency.

L_QTYn (Optional) Line-item unit quantity.

Limitations: 10-character integer.

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

AMT=ITEMAMT + TAXAMT + FREIGHTAMT + HANDLINGAMT + INSURANCEAMT - DISCOUNT

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies. See in this table for details.

Nine numeric characters plus decimal.

ITEMAMT (Required if L_COSTn is specified) Sum of cost of all items in this order.

ITEMAMT = L_QTY0*LCOST0 +

L_QTY1*LCOST1...L_QTYn*L_COSTn

CURRENCY

Express Checkout for Payflow 81

Express Checkout Parameter Reference

Reference Transaction Parameter Descriptions

TABLE A.23 Reference Transaction Request Parameters

Parameter Description

TAXAMT (Required if L_TAXAMTn is specified) Sum of tax for all items in this

FREIGHTAMT (Optional) Total shipping cost for this order.

order.

TAXAMT=L_QTY0*L_TAXAMT0 + L_QTY1*L_TAXAMT1 +...L_QTYn *L_TAXAMTn

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies. See in this table for details.

Nine numeric characters plus decimal.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies. See in this table for details.

CURRENCY

HANDLINGAMT (Optional) To tal handling cost for this order.

NOTE: You must set CURRENCY to one of the three-character currency

codes for any of the supported PayPal currencies. See in this table for details.

DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a

positive amount. 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.

SHIPTONAME (Optional) Ship-to name.

Limitations: 32-character string.

SHIPTOSTREET (Optional) Ship-to street address.

Limitations: 30-character string.

CURRENCY

82 Express Checkout for Payflow

Express Checkout Parameter Reference

Reference Transaction Parameter Descriptions

TABLE A.23 Reference Transaction Request Parameters

Parameter Description

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

3. Limitations: 30-character string.

SHIPTOCITY (Optional) Ship-to city.

Limitations: 40-character string.

SHIPTOSTATE (Optional) Ship-to state.

Limitations: 40-character string.

SHIPTOZIP (Optional) Ship-to postal code.

Limitations: 16-character string.

COUNTRYCODE (Optional) Bill-to country code.

NOTE: The bill-to address details are returned only if

REQBILLINGADDRESS is set to 1 in the call to Set Express Checkout.

Limitations: Four alphanumeric characters.

Reference Transaction Response Parameters

TABLE A.24 Reference Transaction Response Parameters

Parameter Description

BAID BAID returned from Create Customer Billing Agreement.

Limitations: 19-character string.

PAYMENTTYPE Returns one of the following values:

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

pending.

Limitations: 11 characters.

Express Checkout for Payflow 83

Express Checkout Parameter Reference

Reference Transaction Parameter Descriptions

84 Express Checkout for Payflow

Currency Codes

The following currencies are supported for use in transactions.

TABLE B.1 Currencies and Currency Codes

Code Currency

AUD Australian Dollar BRL Brazilian Real

NOTE: Supported as a payment currency and a currency

balance for in-country PayPal accounts only. CAD Canadian Dollar CZK Czech Koruna DKK Danish Krone EUR Euro HKD Hong Kong Dollar HUF Hungarian Forint ILS Israeli New Sheqel JPY Japanese Yen MYR Malaysian Ringgit

NOTE: Supported as a payment currency and a currency

balance for in-country PayPal accounts only. MXN Mexican Peso NOK Norwegian Krone NZD New Zealand Dollar PHP Phillippine Peso PLN Polish Zloty GBP Pound Sterling SGD Singapore Dollar SEK Swedish Krona CHF Swiss Franc TWD Taiwan New Dollar

Express Checkout for Payflow 85

Currency Codes

TABLE B.1 Currencies and Currency Codes

Code Currency

THB Thai Baht USD U.S. Dollar

86 Express Checkout for Payflow

Country Codes

NOTE: This table lists country codes

defined by

Table 1: Country Codes

Country Code

AFGHANISTAN AF ÅLAND ISLANDS AX ALBANIA AL ALGERIA DZ AMERICAN SAMOA AS ANDORRA AD ANGOLA AO ANGUILLA AI ANTARCTICA AQ ANTIGUA AND BAR-

BUDA ARGENTINA AR ARMENIA AM ARUBA AW AUSTRALIA AU AUSTRIA AT AZERBAIJAN AZ BAHAMAS BS BAHRAIN BH BANGLADESH BD

ISO 3166-1.

Country Code

BELARUS BY BELGIUM BE BELIZE BZ BENIN BJ BERMUDA BM BHUTAN BT BOLIVIA BO BOSNIA AND HERZE-

GOVINA BOTSWANA BW BOUVET ISLAND BV BRAZIL BR BRITISH INDIAN

OCEAN TERRITORY BRUNEI DARUSSALAM BN BULGARIA BG BURKINA FASO BF BURUNDI BI CAMBODIA KH CAMEROON CM CANADA CA CAPE VERDE CV CAYMAN ISLANDS KY

BARBADOS BB

Express Checkout for Payflow 87

Country Codes

Country Code

CENTRAL AFRICAN

REPUBLIC CHAD TD CHILE CL CHINA CN CHRISTMAS ISLAND CX COCOS (KEELING)

ISLANDS COLOMBIA CO COMOROS KM CONGO CG CONGO, THE DEMO-

CD CRATIC REPUBLIC OF THE

COOK ISLANDS CK COSTA RICA CR COTE D'IVOIRE CI CROATIA HR CUBA CU CYPRUS CY CZECH REPUBLIC CZ DENMARK DK DJIBOUTI DJ DOMINICA DM DOMINICAN REPUBLIC DO ECUADOR EC EGYPT EG EL SALVADOR SV

Country Code

EQUATORIAL GUINEA GQ ERITREA ER ESTONIA EE ETHIOPIA ET FALKLAND ISLANDS

(MALVINAS) FAROE ISLANDS FO FIJI FJ FINLAND FI FRANCE FR FRENCH GUIANA GF FRENCH POLYNESIA PF FRENCH SOUTHERN

TERRITORIES GABON GA GAMBIA GM GEORGIA GE GERMANY DE GHANA GH GIBRALTAR GI GREECE GR GREENLAND GL GRENADA GD GUADELOUPE GP GUAM GU GUATEMALA GT GUERNSEY GG

88 Express Checkout for Payflow

Country Code

GUINEA GN GUINEA-BISSAU GW GUYANA GY HAITI HT HEARD ISLAND AND

MCDONALD ISLANDS HOLY SEE (VATICAN

CITY STATE) HONDURAS HN HONG KONG HK HUNGARY HU ICELAND IS INDIA IN INDONESIA ID

KOREA, REPUBLIC OF KR KUWAIT KW KYRGYZSTAN KG LAO PEOPLE'S DEMO-

CRATIC REPUBLIC LATVIA LV LEBANON LB LESOTHO LS LIBERIA LR LIBYAN ARAB JAMA-

HIRIYA LIECHTENSTEIN LI LITHUANIA LT LUXEMBOURG LU

IRAN, ISLAMIC REPUB-

LIC OF IRAQ IQ IRELAND IE ISLE OF MAN IM ISRAEL IL ITALY IT JAMAICA JM JAPAN JP JERSEY JE JORDAN JO KAZAKHSTAN KZ KENYA KE KIRIBATI KI KOREA, DEMOCRATIC

PEOPLE'S REPUBLIC OF

MACAO MO MACEDONIA, THE

MK FORMER YUGOSLAV REPUBLIC OF

MADAGASCAR MG MALAWI MW MALAYSIA MY MALDIVES MV MALI ML MALTA MT MARSHALL ISLANDS MH MARTINIQUE MQ MAURITANIA MR MAURITIUS MU MAYOTTE YT MEXICO MX

Express Checkout for Payflow 89

Country Codes

Country Code

MICRONESIA, FEDER-

ATED STATES OF MOLDOVA, REPUBLIC OFMD

MONACO MC MONGOLIA MN MONTSERRAT MS MOROCCO MA MOZAMBIQUE MZ MYANMAR MM NAMIBIA NA NAURU NR NEPAL NP NETHERLANDS NL NETHERLANDS ANTI-

LLES NEW CALEDONIA NC NEW ZEALAND NZ NICARAGUA NI NIGER NE NIGERIA NG NIUE NU NORFOLK ISLAND NF

Country Code

PALAU PW PALESTINIAN TERRI-

TORY, OCCUPIED PANAMA PA PAPUA NEW GUINEA PG PARAGUAY PY PERU PE PHILIPPINES PH PITCAIRN PN POLAND PL PORTUGAL PT PUERTO RICO PR QATAR QA REUNION RE ROMANIA RO RUSSIAN FEDERATION RU RWANDA RW SAINT HELENA SH SAINT KITTS AND

NEVIS SAINT LUCIA LC SAINT PIERRE AND

MIQUELON

NORTHERN MARIANA ISLANDS

NORWAY NO OMAN OM

SAINT VINCENT AND

THE GRENADINES SAMOA WS SAN MARINO SM

PAKISTAN PK

90 Express Checkout for Payflow

Country Code

SAO TOME AND PRINC-

IPE SAUDI ARABIA SA SENEGAL SN SERBIA AND MON-

TENEGRO SEYCHELLES SC SIERRA LEONE SL SINGAPORE SG SLOVAKIA SK SLOVENIA SI SOLOMON ISLANDS SB SOMALIA SO SOUTH AFRICA ZA SOUTH GEORGIA AND

GS THE SOUTH SANDWICH ISLANDS

SPAIN ES SRI LANKA LK

TANZANIA, UNITED

REPUBLIC OF THAILAND TH TIMOR-LESTE TL TOGO TG TOKELAU TK TONGA TO TRINIDAD AND

TOBAGO TUNISIA TN TURKEY TR TURKMENISTAN TM TURKS AND CAICOS

ISLANDS TUVALU TV UGANDA UG UKRAINE UA UNITED ARAB EMIR-

ATES SUDAN SD SURINAME SR SVALBARD AND JAN

MAYEN SWAZILAND SZ SWEDEN SE SWITZERLAND CH SYRIAN ARAB REPUB-

LIC TAIWAN, PROVINCE OF

CHINA

UNITED KINGDOM GB

UNITED STATES US

UNITED ST ATES MINOR

OUTLYING ISLANDS

URUGUAY UY

UZBEKISTAN UZ

VANUATU VU

VENEZUELA VE

VIET NAM VN

VIRGIN ISLANDS, BRIT-

ISH TAJIKISTAN TJ

Express Checkout for Payflow 91

Country Codes

Country Code

VIRGIN ISLANDS, U.S. VI WALLIS AND FUTUNA WF WESTERN SAHARA EH YEMEN YE ZAMBIA ZM ZIMBABWE ZW

92 Express Checkout for Payflow

Index

ACTION parameter 12, 55, 62, 66, 76, 77, 79 ADDROVERRIDE parameter 59 ADJUSTMENTAMT parameter 63 AMT parameter 12 AMTparameter 55, 67, 72, 74, 75, 81 application

testing 52 Australian Dollar 85 AVSADDR parameter 66

BA_CUSTOM parameter 56, 77, 78 BA_DESC parameter 56, 77, 78 Baht 86 BAID parameter 23, 27, 29, 30, 70, 77, 78, 83 billing agreement

message flow when obtaining with purchase 22, 26

updating 29

with a customer purchase 21

without a customer purchase 21 billing agreements

canceling 29

using with reference transactions 19 billing types 20 BILLINGTYPE parameter 56 BILLTONAME parameter 65 Brazilian Real 85 BUTTONSOURCE parameter 67, 80

CURRENCY parameter 55, 80 CUSTIP parameter 79 CUSTOM parameter 59, 64, 67, 80 Customer Support 7 CVV2MATCH parameter 43 Czech Koruna 85

Danish Krone 85 DISCOUNT parameter 63, 82 Dollar 85, 86

EMAIL parameter 61, 62 Euro 85 Express Checkout

ACTION values 12 overview of process 9 Set Express Checkout example 12

Express Checkout flow 11

FEEAMT parameter 71 FIRSTNAME parameter 63, 78 Forint 85 Franc 85 FREIGHTAMT parameter 82

Canadian Dollar 85 CANCELURL parameter 13, 56 CAPTURECOMPLETE parameter 38, 76 CITY parameter 65 COLOR parameter 60 CORRELATIONID parameter 42 COUNTRYCODE parameter 65 currency code format 57, 58, 68, 69, 81, 82 currency codes 85

HANDLINGAMT parameter 82 HDRBACKCOLOR parameter 60 HDRBORDERCOLOR parameter 60 HDRIMG parameter 60 Hong Kong Dollar 85 Hungarian Forint 85

Index

INVNUM parameter 59, 64, 67, 80 Israeli New Sheqel 85 ITEMAMT parameter 81

Japanese Yen 85

Koruna 85 Krona 85 Krone 85

L_BILLINGAGREEMENTDESCRIPTIONn

parameter 56 L_BILLINGTYPEn parameter 56 L_COSTn parameter 57, 81 L_DESCn parameter 57, 80 L_NAMEn parameter 57, 80 L_QTYn parameter 57, 81 L_TAXAMTn parameter 57, 68, 81 LASTNAME parameter 63, 78 LOCALECODE parameter 60

Malaysian Ringgit 85 MAXAMT parameter 59 MEMO parameter 75 MerchantInitiatedBilling 20 Mexican Peso 85

New Dollar 85 New Sheqel 85 New Zealand Dollar 85 Norwegian Krone 85 NOSHIPPING parameter 59 NOTE parameter 63, 71, 75 NOTIFYURL parameter 67, 80

operation

testing 52 ORDERDESC parameter 59, 67, 80 ORIGID parameter 30, 72, 73, 74, 75

PAGESTYLE parameter 60 PARTNER parameter 54 PAYERID

in RETURNURL 15 PAYERID parameter 30, 62, 66 PAYERSTATUS parameter 63, 78 Payflow parameter

CURRENCY 55, 80

MEMO 75 Payflow parameters

ACTION 12, 14, 15, 55, 62, 66, 79

ADDROVERRIDE 59

AMT 12, 15, 55, 67, 72, 74, 75, 81

AVSADDR 66

BA_CUSTOM 56

BA_DESC 56, 77, 78

BAID 70, 77, 78, 83

BILLINGTYPE 56

BILLTONAME 65

BUTTONSOURCE 67, 80

CALCELURL 13

CANCELURL 56

CAPTURECOMPLETE 38, 76

CITY 65

COLOR 60

CORRELATIONID 42

COUNTRYCODE 65

CUSTIP 79

CUSTOM 59, 64, 67, 80

CVV2MATCH 43

DISCOUNT 63, 82

EMAIL 61, 62

FEEAMT 71

FIRSTNAME 63, 78

FREIGHTAMT 82

HANDLINGAMT 82

HDRBACKCOLOR 60

HDRBORDERCOLOR 60

94 Express Checkout for Payflow

Index

HDRIMG 60 HOSTADDRESS 53 HOSTPORT 53, 54 INVNUM 59, 64, 67, 80 ITEMAMT 81 L_BILLINGAGREEMENTDESCRIPTIONn 56 L_BILLINGTYPEn 56 L_COSTn 57, 81 L_DESCn 57, 80 L_NAMEn 57, 80 L_QTYn 57, 81 L_TAXAMTn 57, 68, 81 LASTNAME 63, 78 LOCALECODE 60 MAXAMT 59 NOSHIPPING 59 NOTE 75 NOTIFYURL 67, 80 ORDERDESC 59, 67, 80 ORIGID 44, 72, 73, 74, 75 PAGESTYLE 60 PARMLIST 53 PARTNER 54 PAYERID 15, 62, 66 PAYERSTATUS 63, 78 PAYMENTTYPE 57, 70, 76, 80, 83 PENDINGREASON 71 PNREF 41, 44 PPREF 42, 70, 72, 73, 74, 75, 76 PROXYADDRESS 53, 54 PROXYLOGON 54 PROXYPASSWORD 54 PROXYPORT 53 REQBILLINGADDRESS 59 REQCONFIRMSHIPPING 80 RESPMSG 42, 45 RESULT 41, 45 RETURNURL 13, 55 SHIPTOCITY 61, 64, 69, 78, 83 SHIPTOCOUNTRY 61, 64, 70, 78, 79, 83 SHIPTONAME 61, 64, 69, 82 SHIPTOSTATE 61, 64, 69, 79, 83 SHIPTOSTREET 61, 64, 69, 78, 82 SHIPTOSTREET2 61, 64, 69, 78, 83 SHIPTOZIP 61, 64, 70, 79, 83 STATE 65 STREET2 65

TAXAMT 82 TENDER 55, 62, 72, 77 TOKEN 14, 15, 56, 61, 62, 66, 70, 76, 77 TRXTYPE 33, 44, 55, 62, 66, 72, 73, 74, 75, 76, 79 VENDOR 54

ZIP 65 Payflow parameters ADJUSTMENT AMT 63 Payflow parameters NOTE 63 Payflow Test Account 51 PAYMENTTYPE parameter 57, 70, 76, 80, 83 PayPal-supported currencies 85 PENDINGREASON parameter 71 Peso 85 Phillippine Peso 85 PHONENUM parameter 64 PNREF 41

format of value 44 PNREF value 44 Polish Zloty 85 Pound Sterling 85 PPREF parameter 42, 70, 72, 73, 74, 75, 76

Real 85 recurring billing profile 20 Recurring Payments profile 20 RecurringBilling 20 RecurringPayments 20 redirect 23, 27 reference transaction parameter descriptions 31 reference transactions 19 REQBILLINGADDRESS parameter 59 REQCONFIRMSHIPPING parameter 80 RESPMSG parameter 42 RESPMSG value 45 RESULT 41 RESULT value 45 RETURNURL parameter 55 RETURNURLparameter 13 Ringgit 85

sale transaction type 34 SHIPTOCITY parameter 61, 64, 69, 78, 83 SHIPTOCOUNTRY parameter 61, 64, 70, 78, 79, 83

Express Checkout for Payflow 95

Index

SHIPTONAME parameter 61, 64, 69, 82 SHIPTOSTATE parameter 61, 64, 69, 79, 83 SHIPTOSTREET2 parameter 61, 64, 69, 78, 83 SHIPTOSTREETparameter 61, 64, 69, 78, 82 SHIPTOZIP parameter 61, 64, 70, 79, 83 Singapore Dollar 85 STATE parameter 65 storefront

testing 52 STREET 65 STREET2 parameter 65 Swedish Krona 85 Swiss Franc 85

T aiwan New Dollar 85 TAXAMT parameter 82 TENDER 66 TENDER parameter 55, 62, 72, 77 testing operation 52 Thai Baht 86 token 22, 26 TOKEN parameter 30, 56, 61, 62, 66, 70, 76, 77 transaction response

PNREF parameter 44

RESPMSG parameter 45

RESULT parameter 45 transactions

sale 34 TRXTYPE parameter 28, 29, 55, 62, 66, 72, 73, 74, 75,

76, 79

ZIP parameter 65 Zloty 85

U.S. Dollar 86

values, billing type 20 VENDOR parameter 54

Yen 85

96 Express Checkout for Payflow

PayPal Express Checkout - 2013 Payflow Pro Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Preface

Intended Audience

Related Documentation

How to Contact Customer Support

Document History

What Is Express Checkout?

How Express Checkout Works

Express Checkout Flow

Express Checkout Sale Transaction Example

Express Checkout ACTION Values

Express Checkout Token

Set Express Checkout (ACTION=S)

Redirecting the Buyer to PayPal

Get Express Checkout Details (ACTION=G)

Redirecting the Buyer to Your Website

Do Express Checkout Payment (ACTION=D)

Other Express Checkout Concepts

Obtaining the Buyer’s Telephone Number During Checkout

Eliminating Your Order Review Page

Pending Responses

Billing Agreements and Reference Transactions

About Reference Transactions

About Billing Agreements

About Billing Types

Ways To Obtain a BAID

Obtaining the BAID With Express Checkout Purchase

Example of Obtaining the BAID With Express Checkout Purchase

Obtaining the BAID Without Express Checkout Purchase

Example of Obtaining the BAID Without Express Checkout Purchase

Updating a Billing Agreement

Example of Updating a Billing Agreement

Using Reference Transactions

Reference Transaction Request Passing the BAID

Reference Transaction Request Passing the PNREF Value as ORIGID

Express Checkout Transaction Types

Honor Period and Authorization Period

Payment Transaction Types

Sale

Authorization

Order

Do Reauthorization

Do Authorization

Delayed Capture

Complete Capture

Partial Capture

Void

Credit

Transaction Responses

Response Parameters

Address Verification Service Responses From PayPal

Card Security Code Results

Normalized Results

PNREF Value

PayPal Card Security Code Results

PNREF Format

RESULT Values and RESPMSG Text

RESULT Values for Transaction Declines or Errors

Express Checkout Testing

Testing Your Integration Using the Sandbox

Create A Business Account

Create a Payflow Test Acco unt

Link Your Payflow Account to the Sandbox

Testing Your Integration Using the PayPal Simulator

Connection Parameter Descriptions

User Parameter Descriptions

Express Checkout Parameter Descriptions

Set Express Checkout Request Parameter Descriptions

Set Express Checkout Response Parameter Descriptions

Get Express Checkout Details Request Parameter Descriptions

Get Express Checkout Details Response Parameter Descriptions

Do Express Checkout Payment Request Parameter Descriptions

Do Express Checkout Payment Response Parameter Descriptions

Do Authorization Parameter Descriptions

Do Reauthorization Parameter Descriptions

Void Parameter Descriptions