Name-Value Pair API Developer Guide and Reference

For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l'instant.

Last Updated: February 2007

PayPal Name-Value Pair API Developer Guide and Reference Document Number: 100018.en_US-200702
2006 PayPal, Inc. All rights reserved. PayPal and the PayPal logo are registered trademarks of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution. PayPal FSA Register Number: 226056. Notice of non-liability: PayPal, Inc. is providing the information in this document to you AS-IS with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice. PayPal, Inc. does not guarantee that the features described in this document will be announced or made available to anyone in the future.

Contents

Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 1

Overview to the PayPal NVP API . . . . . . . . . . . . . . 11

Creating Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Developing with the PayPal NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Business Functions of the NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 2

Making an NVP API Call . . . . . . . . . . . . . . . . . . . 13

Required Security Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Specific API Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 URL-Encoding Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1. Constructing the Request Parameter String. . . . . . . . . . . . . . . . . . . . . . . . 13

2. HTTPS Posting the Request to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . 15 API Servers for API Certificate Security . . . . . . . . . . . . . . . . . . . . . . . . . 16 API Servers for API Signature Security . . . . . . . . . . . . . . . . . . . . . . . . . 16 3. Processing the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 URL-Decoding the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3

Charging a Credit Card Using DoDirectPayment . . . . . . 19

Final Sale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Authorizing a Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Recording the Final Shipping Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Including Subtotals of Item Cost, Shipping, Handling, and Tax . . . . . . . . . . . . . . . 21

Name-Value Pair API Developer Guide and Reference

February 2007

Contents

Adding Line Item Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 4

Accepting PayPal in Express Checkout . . . . . . . . . . . 23

1. Starting the Checkout Using SetExpressCheckout . . . . . . . . . . . . . . . . . . 24 2. Redirecting the Customers Browser to PayPal Login Page . . . . . . . . . . . . . 24 3. Getting Payer Details Using GetExpressCheckoutDetails . . . . . . . . . . . . . . 25 4. Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . 25

Basic Checkout with PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Controlling the Shipping Address Using SetExpressCheckout . . . . . . . . . . . . . . . 26 Requiring a Confirmed Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Suppressing Display of Shipping Address on PayPal . . . . . . . . . . . . . . . . . . 26 Overriding the Shipping Address Stored on PayPal . . . . . . . . . . . . . . . . . . . 27 Changing the Language on the PayPal Login Page Using SetExpressCheckout . . . . . . 28 Changing the Logo on the PayPal Pages Using SetExpressCheckout . . . . . . . . . . . 28 Specifying a Custom Payment Page Style. . . . . . . . . . . . . . . . . . . . . . . . 28 Specifying Logo and Color Settings Individually . . . . . . . . . . . . . . . . . . . . . 29 Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails. . . . . . . . 30 Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . 31 Authorizing for Single Capture Using SetExpressCheckout and DoExpressCheckoutPayment. 31 Authorizing for Multiple Captures Using SetExpressCheckout and DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Changing the URL for IPN Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 32 Including Line Item Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 33 Including Subtotals Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . 34 Updating Order Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . 34 Updating the Shipping Address Using DoExpressCheckoutPayment . . . . . . . . . . . . 35

Chapter 5

Back-Office Administration . . . . . . . . . . . . . . . . . 37
Making a Single Capture Against an Order Using DoCapture. . . . . . . . . . . . . . 37 Making Multiple Partial Captures Against an Order Using DoCapture . . . . . . . . . 38 Including an Invoice Number and Note on the Capture Using DoCapture . . . . . . . 39

Capturing, Authorizing, Voiding, and Reauthorizing . . . . . . . . . . . . . . . . . . . . . 37

Refunding Using RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Full Refund. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Partial Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Including a Note with the Refund . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Searching for Transactions Using TransactionSearch . . . . . . . . . . . . . . . . . . . . 41

February 2007

Name-Value Pair API Developer Guide and Reference

Contents

Viewing Details of a Single Transaction Using GetTransactionDetails . . . . . . . . . . . 42

Appendix A NVP API Method and Field Reference . . . . . . . . . . . . 43

General Characteristics of Requests and Parameters . . . . . . . . . . . . . . . . . . . . 43 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Multi-Value Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 PayPal-Supported Transactional Currencies . . . . . . . . . . . . . . . . . . . . . . 43 DoDirectPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 DoDirectPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 DoDirectPayment Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SetExpressCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SetExpressCheckout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 GetExpressCheckoutDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . 58 GetExpressCheckoutDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . 59 DoExpressCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . 60 DoExpressCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . 64 DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 DoVoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 DoReauthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Appendix B Error Message Reference . . . . . . . . . . . . . . . . . . 85

Error Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Express Checkout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125 MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Name-Value Pair API Developer Guide and Reference

February 2007

Contents

Appendix C NVP API Web Samples . . . . . . . . . . . . . . . . . . . 131

Descriptions of the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 Charging a Credit Card Using Direct Payment . . . . . . . . . . . . . . . . . . . . .131 Accepting PayPal in Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . .132 Getting Transaction Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134 Common Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 Samples Using Classic ASP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 Samples Using PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137 Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137 Samples Using ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137 Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137 Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137 Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Appendix D The Java SDK . . . . . . . . . . . . . . . . . . . . . . . 139

Installing the Java SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 Recommended Hardware Configuration. . . . . . . . . . . . . . . . . . . . . . . . .139 Download and Unzip the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140 Post-installation Set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140 Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . .141 SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .142 Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143 Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . .143 Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . .144

Appendix E The ASP.NET SDK . . . . . . . . . . . . . . . . . . . . . 145

Installing the ASP.NET SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 Downloading and Installing the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . .146 Post-installation Set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

February 2007

Name-Value Pair API Developer Guide and Reference

Contents

Optional Custom Configurations in Web.config . . . . . . . . . . . . . . . . . . . . .147 SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 Enabling Proxy Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Uninstalling the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . .149 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .150 Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150 Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . .151 Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . .152 Installing the Samples in IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152 Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

Appendix F

Country Codes

. . . . . . . . . . . . . . . . . . . . . . 155

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Name-Value Pair API Developer Guide and Reference

February 2007

Contents

February 2007

Name-Value Pair API Developer Guide and Reference

Preface

This Document
The PayPal Name-Value Pair API Developer Guide and Reference describes the PayPal Name-Value Pair API.

Intended Audience
The PayPal Name-Value Pair API Developer Guide and Reference is written for web developers who are implementing solutions using the Name-Value Pair API.

Notational Conventions
This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below:

Typeface
serif italics

How Used
A document title. A term being discussed or defined. For example: A file is a readable or writable stream of characters Boolean values (not keywords). For example: The function returns true if it encounters an error.

monospaced

Pathnames or file names that appear in body text frames. Code-related names that appear in body text frames. Such names are used for functions, callbacks, arguments, data structures, and fields. For example: AbstractResponseType is the SOAP response type definition on which all PayPal API response methods are based. Components of Internet protocol requests and responses, such as HTTPS and FORM variables. For example: The PayPal system uses a method=POST request to return IPN status variables related to subscriptions, such as txn_type.

Serif bold

User interface names, such as window names or menu selections. For example: On the Profile page, click Email to confirm your email address

Name-Value Pair API Developer Guide and Reference

February 2007

Preface
Documentation Problems

Typeface
San-serif oblique

How Used
Placeholders used in the context of a format or programming standard or formal descriptions of PayPal system syntax. Placeholders indicate values or names that the reader should provide. Example: For example, amount is the variable for a single-item shopping cart, but amount_X is the name of the variable for a multi-item shopping cart. amount_3 is the item amount for the third item in a multiple-item shopping cart.

To convey additional information, this document may also apply color and underlining to words or phrases that use the typefaces described above. Such use is described below:

Text attribute

How Used
Hypertext link to a page in the current document or to another document in the set. Hypertext link to a URL or that initiates a web action, such as sending mail.

xxxxxx
xxxxxx

Documentation Problems
If you discover any errors in or have any problems with this documentation, please email us by following the instructions below. Describe the error or problem as completely as possible and give us the document title, the date of the document, and the page number or page range. To contact Developer Technical Support about documentation problems: Log in to your account at https://developer.paypal.com/ by entering your email address and password in the Member Log In box Click Help Center at the bottom of the box on the right side of the page. Click Email PayPal Technical Support. Complete the form.

Revision History
Revision history for PayPal Name-Value Pair API Developer Guide and Reference.
TABLE P.1 Revision History Date
February 2007 Octboer

Description
Updates for bug fixes. First public release.

10

February 2007

Name-Value Pair API Developer Guide and Reference

Overview to the PayPal NVP API

The PayPal Name-Value Pair (NVP) API is a simple interface to PayPals business functions, risk management, and business logic. At its most basic, using the NVP API is as easy as posting a name-value pair string over an HTTPS connection to PayPals server and then processing the response, which is also a name-value pair string.

Creating Name-Value Pairs

Follow these guidelines when creating name-value pairs: Separate the parameter name from the value using an equal sign (=). For example:
FIRSTNAME=Robert

Separate all name-value pairs using an ampersand (&). For example:

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

URL-encode the name-value pair string.

Developing with the PayPal NVP API

You can take two general approaches to developing with the PayPal NVP API: 1. Integrate to the NVP API directly. Get the sample programs for ASP.NET, Classic ASP, Java, PHP, and ColdFusion from the Integration Center at:
https://www.paypal.com/sdk

For details about the using the NVP API directly, see Appendix C, NVP API Web Samples. 2. Integrate to the NVP API through an SDK. The Java and ASP.NET SDKs provide some simple functions for integrating with the NVP API. For details about the PayPal NVP SDK, see Appendix D, The Java SDK or Appendix E, The ASP.NET SDK.

Name-Value Pair API Developer Guide and Reference

February 2007

11

Overview to the PayPal NVP API

Business Functions of the NVP API

Business Functions of the NVP API

The business functions of the NVP APIs are summarized below. The technical details of making an API call and processing the response are described in Chapter 2, Making an NVP API Call. Examples of use are in Chapter 3, Charging a Credit Card Using DoDirectPayment, Chapter 4, Accepting PayPal in Express Checkout, and Chapter 5, Back-Office Administration.
TABLE 1.1 Summary Overview of the PayPal APIs API Name Express Checkout:
SetExpressCheckout GetExpressCheckoutDetails DoExpressCheckoutPayment DoDirectPayment

Business Function Accept PayPal in checkout on your website. Get paid immediately or authorize a payment for later capture.

Charge a credit card. Get paid immediately or authorize a payment for later capture. Capture payments previously authorized through Express Checkout, DoDirectPayment, or Website Payments Standard. Make a single capture or multiple captures. Reauthorize or void previous authorizations.

Authorize and Capture:

DoCapture DoAuthorize DoVoid DoReauthorize RefundTransaction TransactionSearch GetTransactionDetails MassPay

Issue full or multiple partial refunds Search for your transactions by a beginning date or other criteria View the specific details about a transaction Pay multiple recipients with a single request

12

February 2007

Name-Value Pair API Developer Guide and Reference

Making an NVP API Call

N O T E : Before

reading this section, make sure you have set up your PayPal accounts and obtained your API Credentials as detailed on the PayPal Integration Center at:
https://www.paypal.com/IntegrationCenter/ic_certificate.html

Making a Name-Value Pair (NVP) API call consists of the following basic steps: 1. Constructing a request parameter string of name-value pairs for the specific API method. 2. HTTPS-posting the parameter string to a PayPal server. 3. Processing the name-value pairs in the response from the server.

1. Constructing the Request Parameter String

Each request consists of required and optional parameters and their values. Parameter names and their values can be upper- or lowercase. For clarity, we show parameter NAMES in uppercase, and we divide the parameters into two categories: required security parameters and body parameters.
TABLE 2.1 General Format of a Request Required Security Parameters
USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature &SUBJECT=optionalThirdPartyEmailAddress&VERSION=2.3 N O T E : The following parameters are always required:

In our examples, we show the required security parameters like this:

[requiredSecurityParameters]

USER PWD VERSION=2.3 Body Parameters

&METHOD=methodName&otherRequiredAndOptionalParameters

In practice, you need to concatenate all parameters and values into a single URL-encoded string, and you can specify the parameters in any order.

Name-Value Pair API Developer Guide and Reference

February 2007

13

Making an NVP API Call

1. Constructing the Request Parameter String

Required Security Parameters

The required security parameters are described below. These are your PayPal API Credentials.
TABLE 2.2 Required Security Parameters: API Credentials Parameter
USER PWD VERSION=2.3 SIGNATURE

Value Required Required Required Optional Your PayPal API Username. Your PayPal API Password. Version number of the NVP API service. Your API signature string.
N O T E : If you use an API Certificate, do not include this parameter.

SUBJECT

Optional

Email address of a PayPal account that has granted you permission to make this call.
N O T E : Set this parameter only if you are calling an API on a different users

behalf.
IMPO RTANT: You

must protect the values for USER, PWD, and SIGNATURE in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. You may see sample code where these values are stored in an HTML form. The following is an example of what you should NOT do: <form method=post action=https://api-3t.sandbox.paypal.com/nvp> <!-- UNPROTECTED VALUES. DO NOT USE IN PRODUCTION! --> <input type=hidden name=USER value=xxxxxx.paypal.com> <input type=hidden name=PWD value=abcdefg> <input type=hidden name=SIGNATURE value=xxxxxxxxxxxxxxx> ... </form>

Specific API Parameters

The first parameter of the request body is the name of the API method. After the required METHOD parameter, each method has other required and optional parameters:
METHOD=methodName&otherRequiredAndOptionalParameters

All API methods and their parameters are detailed in Appendix A, NVP API Method and Field Reference. Examples of use are in Chapter 3, Charging a Credit Card Using

14

February 2007

Name-Value Pair API Developer Guide and Reference

Making an NVP API Call

2. HTTPS Posting the Request to PayPal

DoDirectPayment, Chapter 4, Accepting PayPal in Express Checkout, and Chapter 5, Back-Office Administration.

URL-Encoding Methods
You need to URL-encode the values of parameters in the request string so that certain characters like & and spaces are treated correctly. Use the following methods to ensure the proper encoding
TABLE 2.3 URL-Encoding Methods Language ASP.NET Classic ASP Java PHP ColdFusion URL-Encoding Method
System.Web.HttpUtility.UrlEncode(buffer, Encoding.Default) Server.URLEncode java.net.URLEncoder.encode urlencode() URLEncodedFormatstring [, charset ]

2. HTTPS Posting the Request to PayPal

Post the URL-encoded parameter string over an HTTPS connection to one of the PayPal API servers.

Name-Value Pair API Developer Guide and Reference

February 2007

15

Making an NVP API Call

3. Processing the Response

API Servers for API Certificate Security

If you use an API Certificate, post your request to one of these servers: Sandbox: https://api.sandbox.paypal.com/nvp Production: https://api.paypal.com/nvp

API Servers for API Signature Security

If you use an API Signature, post your request to one of these server: Sandbox: https://api-3t.sandbox.paypal.com/nvp Production: https://api-3t.paypal.com/nvp

3. Processing the Response

A response from the PayPal servers is a URL-encoded name-value pair string, just like the request, except it has the following general format.
TABLE 2.4 General Format of a Successful Response Success Response Fields Specific API Response Fields
ACK=Success&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber &NAME1=value1&NAME2=value2&NAME3=value3&...

In our examples, we show the successful response header fields like this:
[successResponseFields]

Each response includes the ACK field. If the ACK fields value is Success or SuccessWithWarning, you should process the specific API response fields. In a successful response, you can ignore all fields up to and including the BUILD field. The important fields begin after the BUILD field. The possible successful response fields for each method are detailed in Appendix A, NVP API Method and Field Reference. What you do with the fields depends on the particular API method you are calling: fill-in a FORM for your user, update your database, and so on.

16

February 2007

Name-Value Pair API Developer Guide and Reference

Making an NVP API Call

3. Processing the Response

URL-Decoding the Response

The values in the response are URL-encoded. You need to URL-decode it to change certain characters into readable form. Use the following methods to decode.
TABLE 2.5 URL-Encoding Methods Language ASP.NET Classic ASP Java PHP ColdFusion URL-Decoding Method
System.Web.HttpUtility.UrlDecode(buffer, Encoding.Default)

No built-in function. Several implementation examples are available on the Internet.

java.net.URLDecoder.decode urldecode() URLDecodeurlEncodedString[, charset])

Error Responses
If the ACK value is Error or Warning, specific API response fields are not returned. An error response has the following general format.
TABLE 2.6 Format of an Error Response Response Fields on Error
ACK=Error&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage &L_LONGMESSAGE0=longMessage&L_SEVERITYCODE0=severityCode

Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error.

For possible causes of errors and how to correct them, see the explanation of the specific error code, short message, and long message in Appendix B, Error Message Reference.

Name-Value Pair API Developer Guide and Reference

February 2007

17

Making an NVP API Call

3. Processing the Response

18

February 2007

Name-Value Pair API Developer Guide and Reference

Charging a Credit Card Using DoDirectPayment

Use DoDirectPayment to charge a credit card or to authorize a credit card for later capture. Always include the following parameters with DoDirectPayment: PAYMENTACTION CREDITCARDTYPE ACCT EXPDATE CVV2 IPADDRESS FIRSTNAME LASTNAME On success, the DoDirectPayment response returns the Address Verification System (AVS) code, a PayPal transaction ID, and the amount charged.

Final Sale
To charge a credit card for a final sale, include the PAYMENTACTION=Sale field.
EXAMPLE 3.1 Charging a Credit Card for a Final Sale [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=212.95 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Sale

Request

Response

[successResponseFields]&AVSCODE=X&TRANSACTIONID=9CX07910UV614511L&AMT=212.95

Name-Value Pair API Developer Guide and Reference

February 2007

19

Charging a Credit Card Using DoDirectPayment

Authorizing a Payment

Authorizing a Payment
To authorize a credit card for later capture, include the PAYMENTACTION=Authorization field.
EXAMPLE 3.2 Authorizing a Credit Card for Later Capture [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=305.92 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Authorization

Request

Response

[successResponseFields]&AVSCODE=X&TRANSACTIONID=4EL6476506322203C&AMT=305.92

To capture the payment, use DoCapture. For details, see Capturing, Authorizing, Voiding, and Reauthorizing on page 37.

Recording the Final Shipping Address

To record a ship-to address for this charge, include the following fields SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOCOUNTRY SHIPTOPHONENUM SHIPTOZIP
EXAMPLE 3.3 Including a Ship-To Address [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=212.95 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Sale Request
&SHIPTONAME=Louise+P.+Flowerchild&SHIPTOSTREET=1234+Easy+Street &SHIPTOSTREET2=Apt+22+bis&SHIPTOCITY=New+Orleans&SHIPTOSTATE=LA &SHIPTOCOUNTRY=US&SHIPTOPHONENUM=504-555-1212&SHIPTOZIP=70114

20

February 2007

Name-Value Pair API Developer Guide and Reference

Charging a Credit Card Using DoDirectPayment

Including Subtotals of Item Cost, Shipping, Handling, and Tax

Response

[successResponseFields]&AVSCODE=X&TRANSACTIONID=0W099911J1541261D&AMT=212.95

Including Subtotals of Item Cost, Shipping, Handling, and Tax

If you want the PayPal user to see subtotals of item cost, shipping charges, handling charges, and sales tax, include the following parameters: ITEMAMT SHIPPINGAMT HANDLINGAMT TAXAMT
N O T E : Be

sure that the summed values of ITEMAMT, SHIPPINGAMT, HANDLINGAMT, and TAXAMT equal the value of AMT. You cannot include a zero amount for any of these fields, and you must set all of them.

EXAMPLE 3.4 Including Subtotals [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=127.87 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Sale

Request

&ITEMAMT=115.00&SHIPPINGAMT=7.02&HANDLINGAMT=1.00&TAXAMT=4.85

Response

[successResponseFields]&AVSCODE=X&TRANSACTIONID=79V13941UC416632T&AMT=127.87

Adding Line Item Details

If you want the PayPal user to see details about the items purchased with the credit card, include these parameters: L_NAMEn: item name or description L_NUMBERn: line item number L_QTYn: item quantity L_TAXAMTn: sales tax for the item L_AMTn: cost of item

Name-Value Pair API Developer Guide and Reference

February 2007

21

Charging a Credit Card Using DoDirectPayment

Adding Line Item Details

You can detail as many items as you want. Beginning with 0, append an index number to the field name and increment that index number by one for each item.
EXAMPLE 3.5 Adding Line Item Detail [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=127.87 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Sale&L_DESC0=Cat+Nibbles Request

&L_NUMBER0=SKU+98099&L_QTY0=2&L_TAXAMT0=0.85&L_AMT0=8.00 L_DESC1=+Flea+Collar&L_NUMBER1=2&L_QTY1=1&L_TAXAMT1=1.10& L_AMT1=17.00&ITEMAMT=37.00&TAXAMT=1.95

Response

[successResponseFields]&AVSCODE=X&TRANSACTIONID=3B288546P5019992D&AMT=127.87

22

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

By choosing Express Checkout, the customer can save time by skipping several checkout steps using the billing and shipping information stored on PayPal. This section describes how to use Express Checkout to accept payments using PayPal and contains the following topics: Basic Checkout with PayPal on page 23 Controlling the Shipping Address Using SetExpressCheckout on page 26 Changing the Language on the PayPal Login Page Using SetExpressCheckout on page 28 Changing the Logo on the PayPal Pages Using SetExpressCheckout on page 28 Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails on page 30 Making a Sale Using DoExpressCheckoutPayment on page 31 Authorizing for Single Capture Using SetExpressCheckout and DoExpressCheckoutPayment on page 31 Authorizing for Multiple Captures Using SetExpressCheckout and DoExpressCheckoutPayment on page 32 Changing the URL for IPN Using DoExpressCheckoutPayment on page 32 Including Line Item Details Using DoExpressCheckoutPayment on page 33 Including Subtotals Using DoExpressCheckoutPayment on page 34 Updating Order Details Using DoExpressCheckoutPayment on page 34 Updating the Shipping Address Using DoExpressCheckoutPayment on page 35

Basic Checkout with PayPal

N O T E : See the Express Checkout Integration Guide for details on Express Checkout including

page flow, integration points, button placement, and page design. Express Checkout with PayPal requires the following steps: 1. Starting the Checkout Using SetExpressCheckout 2. Redirecting the Customers Browser to PayPal Login Page 3. Getting Payer Details Using GetExpressCheckoutDetails 4. Making a Sale Using DoExpressCheckoutPayment

Name-Value Pair API Developer Guide and Reference

February 2007

23

Accepting PayPal in Express Checkout

Basic Checkout with PayPal

In SetExpressCheckout response, you obtain a TOKEN that uniquely identifies this threestep transaction. You pass this TOKEN in the request to GetExpressCheckoutDetails and DoExpressCheckoutPayment. Both GetExpressCheckoutDetails and DoExpressCheckoutPayment return this TOKEN in the response. This example shows basic checkout using the minimum number of parameters.

1. Starting the Checkout Using SetExpressCheckout

The SetExpressCheckout request method notifies PayPal that you are using Express Checkout to obtain payment from your customer. You must always include the following parameters in SetExpressCheckout request: AMT RETURNURL CANCELURL
EXAMPLE 4.1 Starting the Checkout [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html

Request

Response

[successResponseFields]&TOKEN=EC-3DJ78083ES565113B
N O T E : Because

we do not specify a value for PAYMENTACTION, this parameter defaults to

Sale. Save TOKEN for use on the remaining Express Checkout calls.

2. Redirecting the Customers Browser to PayPal Login Page

After you receive a successful response from SetExpressCheckout, add the TOKEN from SetExpressCheckout response as a name/value pair to the following URL, and redirect your customers browser to it:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse

For redirecting the customers browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 Object Moved with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.

24

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Basic Checkout with PayPal

3. Getting Payer Details Using GetExpressCheckoutDetails

The GetExpressCheckoutDetails method returns information about the customer, including name and address stored on PayPal. You must always include the following parameters in GetExpressCheckoutDetails: TOKEN: use the value from SetExpressCheckout response The response contains this TOKEN and customer details.
EXAMPLE 4.2 Getting Payer Details Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails&
TOKEN=EC-3DJ78083ES565113B

[successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&
PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOCOUNTRYNAME=United+S tates& SHIPTOZIP=99221&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmed

Response

Make sure TOKEN matches the value in SetExpressCheckout response. Save PAYERID for use on the next call.

4. Making a Sale Using DoExpressCheckoutPayment

Request to obtain payment with PayPal Express Checkout using DoExpressCheckoutPayment request. By default, you make a final sale with DoExpressCheckoutPayment request. You can also request authorization for later capture of payment. For more information, see Authorizing for Multiple Captures Using SetExpressCheckout and DoExpressCheckoutPayment on page 32. You must always include the following parameters in DoExpressCheckoutPayment request: TOKEN: use the value from GetExpressCheckoutDetails response PAYERID: use the value from GetExpressCheckoutDetails response PAYMENTACTION: set to Sale. This is the default value in SetExpressCheckout. AMT: use the same value as in SetExpressCheckout request
EXAMPLE 4.3 Making a Sale [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-0E881823PA052770A&AMT=10.00& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale

Request

Name-Value Pair API Developer Guide and Reference

February 2007

25

Accepting PayPal in Express Checkout

Controlling the Shipping Address Using SetExpressCheckout

Response

[successResponseFields&TOKEN=EC-0E881823PA052770A& TRANSACTIONID=8SC56973LM923823H&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T20:16:05Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

Controlling the Shipping Address Using SetExpressCheckout

You can make changes to the behavior of the shipping address with the REQCONFIRMSHIPPING, NOSHIPPING, and ADDROVERRIDE parameters in SetExpressCheckout request.
N O T E : The

shipping address is specified in the SHIPTOxxx parameters.

Requiring a Confirmed Address

To require that the shipping address be a PayPal confirmed address, set REQCONFIRMSHIPPING to 1 in SetExpressCheckout request.
N O T E : The

value of REQCONFIRMSHIPPING overrides the setting in your Merchant Account Profile.

EXAMPLE 4.4 Requiring a Confirmed Address [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &REQCONFIRMSHIPPING=1

Request

Response

[successResponseFields]&TOKEN=EC-0E881823PA052770A

Suppressing Display of Shipping Address on PayPal

To suppress the display of the customers shipping address on the PayPal web pages, set NOSHIPPING to 1 in SetExpressCheckout request. You might want to do this if you are selling a product or service that does not require shipping.
EXAMPLE 4.5 Suppressing the Shipping Address [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &NOSHIPPING=1

Request

26

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Controlling the Shipping Address Using SetExpressCheckout

Response

[successResponseFields]&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails does not return the shipping address.

EXAMPLE 4.6 GetExpressCheckoutDetails Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-17C76533PL706494P

[successResponseFields]&TOKEN=ECResponse
17C76533PL706494P&EMAIL=abcdef@anycompany.com&PAYERID=95HR9CM6D56Q2& PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith&COUNTRYCODE=US& ADDRESSID=PayPal&ADDRESSSTATUS=None

Overriding the Shipping Address Stored on PayPal

To override the shipping address stored on PayPal, call SetExpressCheckout to set ADDROVERRIDE to 1 and set the shipping address fields (see Table A.7, Ship to Address (Optional)). The customer cannot edit the address if it has been overridden.
EXAMPLE 4.7 Overriding the Shipping Address [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &SHIPTONAME=Peter+Smith&SHIPTOSTREET=144+Main+St.&SHIPTOCITY=SAN+JOSE &SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOZIP=99911& ADDROVERRIDE=1

Request

Response

[successResponseFields]&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails returns the overridden shipping address.

EXAMPLE 4.8 GetExpressCheckoutDetails Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails&TOKEN=EC17C76533PL706494P

Name-Value Pair API Developer Guide and Reference

February 2007

27

Accepting PayPal in Express Checkout

Changing the Language on the PayPal Login Page Using SetExpressCheckout

[successResponseFields]&TOKEN=EC-17C76533PL706494P&
PAYER=abcdef@anycompany.com&PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified& FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=Peter+Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=SAN+JOSE&SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOCOUNTRYNAME=United+S tates&SHIPTOZIP=95112& ADDRESSID=PayPal&ADDRESSSTATUS=Unconfirmed

Response

Changing the Language on the PayPal Login Page Using SetExpressCheckout

To change the language displayed on the PayPal login page, set LOCALECODE to one of the allowable values in SetExpressCheckout. For LOCALECODE values, see Table A.6, SetExpressCheckout Request Parameters. The following example sets LOCALECODE to French.
EXAMPLE 4.9 Changing the PayPal Login Page Language to French [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& CURRENCYCODE=EUR& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &LOCALECODE=fr_FR

Request

Response

[successResponseFields]&TOKEN=EC-17C76533PL706494P

Changing the Logo on the PayPal Pages Using SetExpressCheckout

You can modify the logo and other color settings on the PayPal pages in two ways: Specifying a predefined Custom Payment Page Style Setting logo and color settings individually

Specifying a Custom Payment Page Style

You can set the Custom Payment Page Style for the PayPal pages by setting the PAGESTYLE parameter in SetExpressCheckout. Set PAGESTYLE to one of the Page Style Names you defined in your Custom Payment Pages on https://www.paypal.com.

28

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Changing the Logo on the PayPal Pages Using SetExpressCheckout

The following example sets PAGESTYLE to DesignerFotos-Yellow in the SetExpressCheckout method

EXAMPLE 4.10 Specifying a Custom Payment Page Style [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& PAGESTYLE=DesignerFotos-Yellow

Request

Response

[successResponseFields]&TOKEN=EC-17C76533PL706494P

Specifying Logo and Color Settings Individually

You can modify the PayPal web pages to look like your own web pages by setting the following parameters in SetExpressCheckout: HDRIMG: specify an image to appear at the top left of the payment page HDRBORDERCOLOR: set the border color around the header of the payment page HDRBACKCOLOR: set the background color for the background of the header of the payment page PAYFLOWCOLOR: set the background color for the payment page
EXAMPLE 4.11 Specifying Logo and Color Settings Individually [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& HDRIMG=https://www.anycompany.com/images/HeaderImage.gif& HDRBORDERCOLOR=3366FF&HDRBACKCOLOR=D3EFF5&PAYFLOWCOLOR=F8F5F5

Request

Response

[successResponseFields]&TOKEN=EC-17C76533PL706494P

Name-Value Pair API Developer Guide and Reference

February 2007

29

Accepting PayPal in Express Checkout

Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails

Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails

Use the payer name and shipping address returned by GetExpressCheckoutDetails response to fill in form fields on your payment review page which you display after the customer returns from PayPal.
EXAMPLE 4.12 Form-Filling Your Payment Review Page Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-3DJ78083ES565113B

[successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&
PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOCOUNTRYNAME=United+S tates&SHIPTOZIP=99221& ADDRESSID=PayPal&ADDRESSSTATUS=Confirmed

Response

Get the payer name from the following parameters in GetExpressCheckoutDetails response: SALUTATION FIRSTNAME MIDDLENAME LASTNAME SUFFIX Get the shipping address from the following parameters in GetExpressCheckoutDetails response: SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY SHIPTOPHONENUM SHIPTOZIP

30

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Making a Sale Using DoExpressCheckoutPayment

Making a Sale Using DoExpressCheckoutPayment

Use DoExpressCheckoutPayment to make a final sale. For more information, see Basic Checkout with PayPal on page 23.

Authorizing for Single Capture Using SetExpressCheckout and DoExpressCheckoutPayment

You can authorize payment for final sale by setting PAYMENTACTION to Authorization in SetExpressCheckout and DoExpressCheckoutPayment. See Making a Single Capture Against an Order Using DoCapture on page 37 for more information on Authorization and Capture.

EXAMPLE 4.13 Authorizing for Single Capture in SetExpressCheckout [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& PAYMENTACTION=Authorization

Request

Response

[successResponseFields]&
TOKEN=EC-30P862430W113011F

EXAMPLE 4.14 Authorizing for Single Capture in DoExpressCheckoutPayment [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-30P862430W113011F&PAYERID=95HR9CM6D56Q2&AMT=10.00

PAYMENTACTION=Authorization

Request

[successResponseFields]&TOKEN=EC-30P862430W113011F&
TRANSACTIONID=4D479374VP578364Y&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:02:42Z&AMT=10.00& CURRENCYCODE=USD&TAXAMT=0.00&PAYMENTSTATUS=Pending& PENDINGREASON=authorization&REASONCODE=None

Response

Save TRANSACTIONID and use it for the value of AUTHORIZATIONID in DoCapture request. For information about DoCapture, see Capturing, Authorizing, Voiding, and Reauthorizing on page 37.

Name-Value Pair API Developer Guide and Reference

February 2007

31

Accepting PayPal in Express Checkout

Authorizing for Multiple Captures Using SetExpressCheckout and DoExpressCheckoutPayment

Authorizing for Multiple Captures Using SetExpressCheckout and DoExpressCheckoutPayment

You can authorize payment for multiple captures by setting PAYMENTACTION to Order in SetExpressCheckout and DoExpressCheckoutPayment. See Making Multiple Partial Captures Against an Order Using DoCapture on page 38 for more information on Authorization and Capture.

EXAMPLE 4.15 Authorizing for Multiple Captures in SetExpressCheckout [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=1.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& PAYMENTACTION=Order

Request

Response

[successResponseFields]&
TOKEN=EC-8NB10343BA3562027

EXAMPLE 4.16 Authorizing for Multiple Captures in DoExpressCheckoutPayment [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8NB10343BA3562027&PAYERID=95HR9CM6D56Q2&AMT=1.00& PAYMENTACTION=Order

Request

Response

[successResponseFields]&TOKEN=EC-8NB10343BA3562027& TRANSACTIONID=O-2YX05090CA6454418&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=None&ORDERTIME=2006-08-22T22:22:03Z&AMT=1.00& CURRENCYCODE=USD&TAXAMT=0.00&PAYMENTSTATUS=None&PENDINGREASON=order& REASONCODE=None

Save TRANSACTIONID and use it for the value of AUTHORIZATIONID in DoCapture request. For information about DoCapture, see Capturing, Authorizing, Voiding, and Reauthorizing on page 37.

Changing the URL for IPN Using DoExpressCheckoutPayment

You can change the URL for receiving Instant Payment Notification (IPN) about this transaction by setting the NOTIFYURL parameter in DoExpressCheckoutPayment.

32

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Including Line Item Details Using DoExpressCheckoutPayment
N O T E : If

you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists.

For more information about IPN, see the Order Management Integration Guide.
EXAMPLE 4.17 Changing the URL for IPN [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00& PAYMENTACTION=Sale&NOTIFYURL=https://www.anycompany.com/process-ipn/

Request

[successResponseFields]&TOKEN=EC-8AX1275942659774U&
TRANSACTIONID=1MA55216691247718&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:39:13Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

Response

Including Line Item Details Using DoExpressCheckoutPayment

You can include line item details by setting the following parameters in DoExpressCheckoutPayment: L_NAMEn: item name or description L_NUMBERn: line item number L_QTYn: item quantity L_TAXAMTn: sales tax for the item L_AMTn: cost of item In the following example, we set line item details for two items. These details are recorded on PayPal.
EXAMPLE 4.18 Including Line Item Details [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-4XH62109C8044521N&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=6.24& ITEMAMT=5.75&TAXAMT=0.49&L_NUMBER0=1&L_NAME0=A+Tale+of+Two+Cities&L_AMT0=2.50& L_QTY0=1&L_TAXAMT0=0.21&L_NAME1=Oliver+Twist&L_NUMBER1=2&L_AMT1=3.25&L_QTY1=1& L_TAXAMT1=0.28

Request

[successResponseFields]&TOKEN=EC-4XH62109C8044521N&
TRANSACTIONID=77U91743M2649930P&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:49:50Z&AMT=6.24& CURRENCYCODE=USD&FEEAMT=0.48&TAXAMT=0.28&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

Response

Name-Value Pair API Developer Guide and Reference

February 2007

33

Accepting PayPal in Express Checkout

Including Subtotals Using DoExpressCheckoutPayment

Including Subtotals Using DoExpressCheckoutPayment

If you want the PayPal user to see subtotals of item cost, shipping charges, handling charges, and sales tax, include the following parameters in DoExpressCheckoutPayment: ITEMAMT SHIPPINGAMT HANDLINGAMT TAXAMT
N O T E : Be

sure that the summed values of ITEMAMT, SHIPPINGAMT, HANDLINGAMT, and TAXAMT equal the value of AMT. You cannot include a zero amount for any of these fields, and you must set all of them.

EXAMPLE 4.19 Including Subtotals [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment TOKEN=EC-0EU150885J108392M&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=6.24&

AMT=192.22&ITEMAMT=176.02&SHIPPINGAMT=14.34&HANDLINGAMT=1.10&TAXAMT=0.76

Request

[successResponseFields]&TOKEN=EC0EU150885J108392M&TRANSACTIONID=29W817045L6797418&TRANSACTIONTYPE=expresscheck out&PAYMENTTYPE=instant&ORDERTIME=2006-0823T16:20:22Z&AMT=192.22&CURRENCYCODE=USD&FEEAMT=5.87&TAXAMT=0.76&PAYMENTSTATUS =Completed&PENDINGREASON=None&REASONCODE=None

Response

Updating Order Details Using DoExpressCheckoutPayment

You may need to update order details on PayPal if the customer makes a change to the order after returning to your order review page. If the change causes new values for one or more of the following parameters, you need to update the order details on PayPal using DoExpressCheckoutPayment: DESC: item description CUSTOM: field for your own use INVNUM: your invoice or tracking number These three parameters may have been set in SetExpressCheckout.
EXAMPLE 4.20 Updating Order Details [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=ECRequest
5JA9268562132991T&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& DESC=Order+for+5+books&CUSTOM=Thank+you+for+your+business!&INVNUM=ABC1234567

34

February 2007

Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Updating the Shipping Address Using DoExpressCheckoutPayment

[successResponseFields]&TOKEN=EC5JA9268562132991T&TRANSACTIONID=9JJ517146A732773R&TRANSACTIONTYPE=expresscheck out&PAYMENTTYPE=instant&ORDERTIME=2006-0823T16:14:54Z&AMT=10.00&CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS= Completed&PENDINGREASON=None&REASONCODE=None

Response

Updating the Shipping Address Using DoExpressCheckoutPayment

You may need to update the shipping address on PayPal if the customer updates the shipping address after returning to your order review page. If this happens, you need to update the shipping address for this transaction on PayPal. You can update the shipping address by setting the following parameters in DoExpressCheckoutPayment: SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY SHIPTOPHONENUM SHIPTOZIP
EXAMPLE 4.21 Updating the Shipping Address [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment&
METHOD=DoExpressCheckoutPayment&TOKEN=EC-47C20533CU265432F& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& SHIPTONAME=Michael+Brown&SHIPTOSTREET=22+First+Street&SHIPTOCITY=Chicago& SHIPTOCOUNTRY=US&SHIPTOSTATE=IL&SHIPTOZIP=60605

Request

[successResponseFields]&TOKEN=EC-47C20533CU265432F&
TRANSACTIONID=59L39584YA765250B&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-23T16:08:12Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None

Response

Name-Value Pair API Developer Guide and Reference

February 2007

35

Accepting PayPal in Express Checkout

Updating the Shipping Address Using DoExpressCheckoutPayment

36

February 2007

Name-Value Pair API Developer Guide and Reference

Back-Office Administration

This section gives you examples of the following functions: Capturing, Authorizing, Voiding, and Reauthorizing on page 37 Refunding Using RefundTransaction on page 40 Searching for Transactions Using TransactionSearch on page 41 Viewing Details of a Single Transaction Using GetTransactionDetails on page 42

Capturing, Authorizing, Voiding, and Reauthorizing

There are four APIs related to authorization and capture: DoCapture DoAuthorization DoVoid DoReauthorization
IMPO RTANT: To

use these APIs, you need to know the TRANSACTIONID of the original transaction. Use the value of the original TRANSACTIONID as the value of the AUTHORIZATIONID with DoCapture, DoAuthorization, DoVoid, and DoReauthorization.

Making a Single Capture Against an Order Using DoCapture

To capture only once, set the authorization identification number and the amount on DoCapture.
IMPO RTANT: Capturing

only once is default. To be explicit, you can set COMPLETETYPE=Complete. COMPLETETYPE=Complete closes all outstanding authorizations for the order. You can not make anymore captures.

EXAMPLE 5.1 Capturing the Full Amount of an Authorization Request [requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=01987219673867 &AMT=99.12&COMPLETETYPE=Complete

Name-Value Pair API Developer Guide and Reference

February 2007

37

Back-Office Administration
Capturing, Authorizing, Voiding, and Reauthorizing

[successResponseFields]&AUTHORIZATIONID=01987219673867
&TRANSACTIONID=7JZ9679864YA2699519&PARENTTRANSACTIONID=01987219673867 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=express-checkout &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=99.12 &CURRENCYCODE=USD&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Response

Making Multiple Partial Captures Against an Order Using DoCapture

You can capture a partial amount of an authorization by setting COMPLETETYPE=NotComplete On the final capture, set COMPLETETYPE=Complete or do not specify COMPLETETYPE. This example shows three captures: The first two are partial captures. COMPLETETYPE is set to NotComplete The last capture is for the full remaining amount. COMPLETETYPE is set to Complete.
EXAMPLE 5.2 Capturing A Partial Amount of an Authorization First Partial Capture Request [requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=112.00&COMPLETETYPE=NotComplete

Response

[successResponseFields]&AUTHORIZATIONID=4EL6476506322203 &TRANSACTIONID=4Y117666R06578920&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:23:15Z&AMT=112.00 &CURRENCYCODE=USD&FEEAMT=3.55&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Second Partial Capture Request

[requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=103.12&COMPLETETYPE=NotComplete

Response

[successResponseFields]&AUTHORIZATIONID=4EL6476506322203 &TRANSACTIONID=7JY48864YA2699519&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=103.12 &CURRENCYCODE=USD&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

38

February 2007

Name-Value Pair API Developer Guide and Reference

Back-Office Administration
Capturing, Authorizing, Voiding, and Reauthorizing

Final Capture Request

[requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=103.12&COMPLETETYPE=Complete

[successResponseFields]&AUTHORIZATIONID=4EL6476506322203
&TRANSACTIONID=7JZ89864YA2699519&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=90.80 &CURRENCYCODE=USD&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Response

Including an Invoice Number and Note on the Capture Using DoCapture

Whether the capture is for the full or a partial amount, you can include a note about the capture and your own invoice or other identification number.
EXAMPLE 5.3 Including an Invoice Number and Note on a Capture Request [requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &COMPLETETYPE=Complete&AMT=304.92&INVNUM=H091234&NOTE=UPS+trk#+b86283978 [successResponseFields]&AUTHORIZATIONID=4EL6476506322203
&TRANSACTIONID=7JZ89864YA2694419&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=304.92 &CURRENCYCODE=USD&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None

Response

Name-Value Pair API Developer Guide and Reference

February 2007

39

Back-Office Administration
Refunding Using RefundTransaction

R e f u n d i n g U s i n g R e f u n d Tr a n s a c t i o n
With RefundTransaction, you can refund the full amount or a partial amount of a transaction. Specify the original transaction ID and the refund type: Full or Partial.

Full Refund
IMPO RTANT: If

you refund the full amount, do not set the AMT field.

EXAMPLE 5.4 Refunding the Full Amount of a Transaction [requiredSecurityParameters]&METHOD=RefundTransaction&TRANSACTIONID=01945456967386 Request

7 &REFUNDTYPE=Full

Response

[successResponseFields]&REFUNDTRANSACTIONID=4RP55200GJ177180N
&FEEREFUNDAMT=4.01&GROSSREFUNDAMT=127.87&NETREFUNDAMT=123.86

Partial Refunds
To refund a partial amount, set REFUNDTYPE to Partial and set the AMT.
EXAMPLE 5.5 Refunding A Partial Amount Request [requiredSecurityParameters]&METHOD=RefundTransaction &TRANSACTIONID=9CX07910UV614511L&REFUNDTYPE=Partial&AMT=12.95 [successResponseFields]&REFUNDTRANSACTIONID=1H0011898K637700R
&FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57

Response

Including a Note with the Refund

Whether the refund is full or partial, you can also include a note about the refund.
EXAMPLE 5.6 Including a Note with the Refund [requiredSecurityParameters]&METHOD=RefundTransaction&TRANSACTIONID=01945456967386 7 &REFUNDTYPE=Partial&AMT=12.95&NOTE=Customer+changed+mind. [successResponseFields]&REFUNDTRANSACTIONID=1H0011898K637700R
&FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57

Request

Response

40

February 2007

Name-Value Pair API Developer Guide and Reference

Back-Office Administration
Searching for Transactions Using TransactionSearch

Searching for Transactions Using TransactionSearch

To find all transactions that occurred on a particular date, use TransactionSearch and set the STARTDATE field to the date you desire. The date must be in UTC/GMT format.
EXAMPLE 5.7 Searching for Transactions by STARTDATE Request [requiredSecurityParameters]&METHOD=TransactionSearch &STARTDATE=2006-08-15T17:00:00Z [successResponseFields]&L_TIMESTAMP0=2006-08-18T05:58:41Z&
L_TIMEZONE0=GMT&L_TYPE0=Authorization&L_NAME0=John+Doe& L_TRANSACTIONID0=3XK029742B016373C&L_STATUS0=Pending&L_AMT0=1.00& L_TIMESTAMP1=2006-08-18T05:56:20Z&L_TIMEZONE1=GMT&L_TYPE1=Payment& L_NAME1=John+Doe&L_TRANSACTIONID1=4BV19600WF261673U&L_STATUS1=Completed &L_AMT1=1.00&L_FEEAMT1=-0.33&L_NETAMT1=0.67& L_TIMESTAMP2=2006-08-18T05:53:22Z&L_TIMEZONE2=GMT&L_TYPE2=Payment &L_NAME2=John+Doe&L_TRANSACTIONID2=6XB50622KC566325C&L_STATUS2=Completed &L_AMT2=1.00&L_FEEAMT2=-0.33&L_NETAMT2=0.67& L_TIMESTAMP3=2006-08-18T05:38:04Z&L_TIMEZONE3=GMT &L_TYPE3=Payment&L_NAME3=John+Doe&L_TRANSACTIONID3=80774637LP956560E& L_STATUS3=Completed&L_AMT3=1.00&L_FEEAMT3-0.33&L_NETAMT3=0.67& L_TIMESTAMP4=2006-08-17T03:02:44Z&L_TIMEZONE4=GMT&L_TYPE4=Payment& L_NAME4=Pettibone+Smythe-Jones&L_TRANSACTIONID4=8G40321568512733L& L_STATUS4=Completed&L_AMT4=104.00&L_FEEAMT4=-3.32&L_NETAMT4=100.68

Respons

TransactionSearch returns a multi-valued array of all transactions that match the search criteria. Each transaction begins with its date: L_TIMESTAMPn, where n starts with 0 and increments by one for each transaction.

Name-Value Pair API Developer Guide and Reference

February 2007

41

Back-Office Administration
Viewing Details of a Single Transaction Using GetTransactionDetails

Vi e w i n g D e ta i l s o f a S i n g l e Tr a n s a c t i o n U s i n g G e t Tr a n s a c t i o n D e ta i l s
To view all details about a single transaction, use GetTransactionDetails.
EXAMPLE 5.8 Viewing A Transactions Details Request [requiredSecurityParameters]&METHOD=GetTransactionDetails &TRANSACTIONID=3B288546P5019992D [successResponseFields]&RECEIVERBUSINESS=Jims+Hardware
&RECEIVEREMAIL=jim@hardwareplace.com&RECEIVERID=WNSJNN89XVWFA &PAYERID=B3KS3VFYNG9SN&PAYERSTATUS=unverified&FIRSTNAME=James& LASTNAME=Biguy&COUNTRYCODE=US&SHIPTOSTATE=&ADDRESSID=PayPal&ADDRESSSTATUS=None &TRANSACTIONID=3B288546P5019992D&RECEIPTID=3596-6202-14612615 &TRANSACTIONTYPE=webaccept&PAYMENTTYPE=instant& ORDERTIME=2006-08-15T17:00:00Z&AMT=127.87&CURRENCYCODE=USD&FEEAMT=4.01 &TAXAMT=0.00&PENDINGREASON=None&REASONCODE=None&SALESTAX=0.00&L_QTY0=1

Response

42

February 2007

Name-Value Pair API Developer Guide and Reference

A
Parameters

NVP API Method and Field Reference

General Characteristics of Requests and Parameters

The request parameter string follows the query component syntax defined in Uniform Resource Identifier (URI): Generic Syntax. Parameter names and their values can be upper- or lowercase. We show parameter names in uppercase for clarity. All values must be URL-encoded.

Multi-Value Fields
Fields that accept multiple values have names like this:
L_FIELDNAMEn

where L_ is literal, FIELDNAME is the name of the parameter, and n is an index number, starting at 0 and incremented by one for each value of the field. Index numbers must be sequential. For example, if an order contains multiple items, you can add an item cost for each item using the L_AMTn parameter:
L_AMT0=4.95&L_AMT1=6.72&L_AMT2=7.95

PayPal-Supported Transactional Currencies

The following currencies are supported by PayPal for use in transactions.
TABLE A.1 ISO-4217 Code AUD CAD CHF CZK DKK EUR GBP PayPal-Supported Currencies and Currency Codes for Transactions Currency Australian Dollar Canadian Dollar Swiss Franc Czech Koruna Danish Krone Euro Pound Sterling

Name-Value Pair API Developer Guide and Reference

February 2007

43

NVP API Method and Field Reference

DoDirectPayment TABLE A.1 ISO-4217 Code HKD HUF JPY NOK NZD PLN SEK SGD USD PayPal-Supported Currencies and Currency Codes for Transactions Currency Hong Kong Dollar Hungarian Forint Japanese Yen Norwegian Krone New Zealand Dollar Polish Zloty Swedish Krona Singapore Dollar U.S. Dollar

DoDirectPayment
DoDirectPayment Request

TABLE A.2 Parameter METHOD

DoDirectPayment Parameters Description Name of the API: DoDirectPayment How you want to obtain payment: Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters IP address of the payers browser.
I M P O R T A N T : PayPal records this IP addresses as a means to detect

Required? Yes Yes

PAYMENTACTION

IPADDRESS

Yes

possible fraud. Character length and limitations: 15 single-byte characters, including periods, for example: 255.255.255.25. Allowable values: any valid Internet Protocol address.

44

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoDirectPayment TABLE A.2 Parameter AMT DoDirectPayment Parameters Description
Total of order, including shipping, handling, and tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).

Required? Yes

CREDITCARDTYPE

Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: Visa MasterCard Discover Amex Switch Solo
I M P O R T A N T : If the credit card type is Switch or Solo, the value of

Yes

PAYMENTACTION must be Authorization and the CURRENCYCODE must be GBP. In addition, either STARTDATE or ISSUENUMBER must be specified. ACCT Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type. Credit card expiration date. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero. Payers first name. Character length and limitations: 25 single-byte characters Payers last name. Character length and limitations: 25 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see State and Province Abbreviations on page 49. Yes

EXPDATE

Yes

FIRSTNAME LASTNAME STREET CITY STATE

Yes Yes No No No

Name-Value Pair API Developer Guide and Reference

February 2007

45

NVP API Method and Field Reference

DoDirectPayment TABLE A.2 Parameter COUNTRYCODE DoDirectPayment Parameters Description Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, Country Codes. U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters Your URL for receiving Instant Payment Notification (IPN) about this transaction.
N O T E : If you do not specify this URL in the request, the notification URL

Required? No

ZIP NOTIFYURL

No No

from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters CURRENCYCODE A three-character currency code. Default: USD. This parameter accepts only the following currencies: AUD Australian Dollar CAD Canadian Dollar EUR Euro GBP Pound Sterling JPY Japanese Yen USD U.S. Dollar
Sum of cost of all items in this order.

No

ITEMAMT

No

Limitations: The value must be a positive number and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N O T E : ITEMAMT is required if you specify a value for L_AMTn.

SHIPPINGAMT

Total shipping costs for this order.

No

Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N O T E : If you specify a value for SHIPPINGAMT, you must also specify a

value for ITEMAMT. HANDLINGAMT

Total handling costs for this order.

No

Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N O T E : If you specify a value for HANDLINGAMT, you must specify a value

for ITEMAMT.

46

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoDirectPayment TABLE A.2 Parameter TAXAMT DoDirectPayment Parameters Description Sum of tax for all items in this order. Required? No

Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
DESC CUSTOM INVNUM BUTTONSOURCE Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters Your URL for receiving Instant Payment Notification (IPN) about this transaction.
N O T E : If you do not specify this URL in the request, the notification URL

No No No No

NOTIFYURL

No

from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters L_NAMEn Item name. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. L_NUMBERn Item number. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. L_QTYn Item quantity. Character length and limitations: Any positive integer These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth. No No No

Name-Value Pair API Developer Guide and Reference

February 2007

47

NVP API Method and Field Reference

DoDirectPayment TABLE A.2 Parameter L_TAXAMTn DoDirectPayment Parameters Description Item sales tax. Required? No

Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
These parameters should be ordered sequentially beginning with 0, for example, L_TAXAMT0, L_TAXAMT1, and so forth. L_AMTn Cost of item No

Limitations: Value can be positive, negative or zero and must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. If you specify a value for L_AMTn, you must specify a value for ITEMAMT. CVV2 Card Verification Value, version 2.
N O T E : Your Merchant Account settings determine whether this field is

See description.

required. Contact your PayPal Account Manager for more information. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits.
I M P O R T A N T : To comply with credit card processing regulations, once a

transaction has been completed, you must not store the value of CVV2. STARTDATE Month and year that Switch or Solo card was issued. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero. Issue number of Switch or Solo card. Character length: two numeric digits maximum. Email address of payer. Character length and limitations: 127 single-byte characters Second street address. Character length and limitations: 100 single-byte characters Phone number. Character length and limit: 20 single-byte characters No

ISSUENUMBER EMAIL STREET2 PHONENUM

No No No No

48

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoDirectPayment TABLE A.2 Parameter Ship to Address DoDirectPayment Parameters Description Optional shipping address. The parameters for the optional Ship to Address are described in Table A.3, Ship to Address (Optional).
I M P O R T A N T : Ship to Address is optional, but if you include it, certain

Required? No

fields are required. TABLE A.3 Parameter SHIPTONAME SHIPTOSTREET SHIPTOCITY SHIPTOSTATE Ship to Address (Optional) Description Persons name associated with this address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see State and Province Abbreviations on page 49. U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, Country Codes. Second street address. Character length and limitations: 100 single-byte characters Phone number. Character length and limit: 20 single-byte characters Required? Yes Yes Yes Yes

SHIPTOZIP SHIPTOCOUNTRY

Yes Yes

SHIPTOSTREET2 SHIPTOPHONENUM

No No

State and Province Abbreviations

The following table contains abbreviations for Canadian provinces and U.S. states. Enter these values in STATE or SHIPTOSTATE parameter.
TABLE A.1 Abbreviations for Canadian Provinces and U.S. States Canadian Province or U.S. State Alberta British Columbia Abbreviation AB BC

Name-Value Pair API Developer Guide and Reference

February 2007

49

NVP API Method and Field Reference

DoDirectPayment TABLE A.1 Abbreviations for Canadian Provinces and U.S. States Canadian Province or U.S. State Manitoba New Brunswick Newfoundland and Labrador Northwest Territories Nova Scotia Nunavut Ontario Prince Edward Island Quebec Saskatchewan Yukon Alabama Alaska American Samoa Arizona Arkansas California Colorado Connecticut Delaware District of Columbia Federated States of Micronesia Florida Georgia Guam Hawaii Idaho Illinois Abbreviation MB NB NF NT NS NU ON PE QC SK YK AL AK AS AZ AR CA CO CT DE DC FM FL GA GU HI ID IL

50

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoDirectPayment TABLE A.1 Abbreviations for Canadian Provinces and U.S. States Canadian Province or U.S. State Indiana Iowa Kansas Kentucky Louisiana Maine Marshall Islands Maryland Massachusetts Michigan Minnesota Mississippi Missouri Montana Nebraska Nevada New Hampshire New Jersey New Mexico New York North Carolina North Dakota Northern Mariana Islands Ohio Oklahoma Oregon Palau Pennsylvania Abbreviation IN IA KS KY LA ME MH MD MA MI MN MS MO MT NE NV NH NJ NM NY NC ND MP OH OK OR PW PA

Name-Value Pair API Developer Guide and Reference

February 2007

51

NVP API Method and Field Reference

DoDirectPayment TABLE A.1 Abbreviations for Canadian Provinces and U.S. States Canadian Province or U.S. State Puerto Rico Rhode Island South Carolina South Dakota Tennessee Texas Utah Vermont Virgin Islands Virginia Washington West Virginia Wisconsin Wyoming Armed Forces Americas Armed Forces Armed Forces Pacific Abbreviation PR RI SC SD TN TX UT VT VI VA WA WV WI WY AA AE AP

DoDirectPayment Response
TABLE A.4 AVS Code A B C D AVS Response Codes Matched Details Address only (no ZIP) Address only (no ZIP) None Address and Postal Code

Meaning Address International A International N International X

52

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoDirectPayment TABLE A.4 AVS Code E F G I N P R S U W X Y Z All others AVS Response Codes Matched Details Not applicable Address and Postal Code Not applicable Not applicable None Postal Code only (no Address) Not applicable Not applicable Not applicable Nine-digit ZIP code (no Address) Address and nine-digit ZIP code Address and five-digit ZIP Five-digit ZIP code (no Address) Not applicable

Meaning Not allowed for MOTO (Internet/Phone) transactions UK-specific X Global Unavailable International Unavailable No Postal (International Z) Retry Service not Supported Unavailable Whole ZIP Exact match Yes ZIP Error

TABLE A.5 CVV2 Code M N P S U X All others

CVV2 Response Codes Matched Details CVV2 None Not applicable Not applicable Not applicable Not applicable Not applicable

Meaning Match No match Not Processed Service not Supported Unavailable No response Error

Name-Value Pair API Developer Guide and Reference

February 2007

53

NVP API Method and Field Reference

Express Checkout

Express Checkout
SetExpressCheckout Request

TABLE A.6 Parameter METHOD RETURNURL

SetExpressCheckout Request Parameters Description Name of the API: SetExpressCheckout URL to which the customers browser is returned after choosing to pay with PayPal.
N O T E : PayPal recommends that the value be the final review page on

Required Yes Yes

which the customer confirms the order and payment. Character length and limitations: no limit. CANCELURL URL to which the customer is returned if he does not approve the use of PayPal to pay you.
N O T E : PayPal recommends that the value be the original page on which

Yes

the customer chose to pay with PayPal. Character length and limitations: no limit AMT The total cost of the order to the customer. If shipping cost and tax charges are known, include them in this value; if not, this value should be the current sub-total of the order.
N O T E : Limitations: Must not exceed $10,000 USD in any currency. No

Yes

currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). CURRENCYCODE MAXAMT A three-character currency code for one of the currencies listed in PayPalSupported Transactional Currencies. Default: USD. The expected maximum total amount of the complete order, including shipping cost and tax charges.
N O T E : Limitations: Must not exceed $10,000 USD in any currency.

No No

No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).

54

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout TABLE A.6 Parameter PAYMENTACTION SetExpressCheckout Request Parameters Description How you want to obtain payment: Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. Order indicates that this payment is an order authorization subject to settlement with PayPal Authorization & Capture. Sale indicates that this is a final sale for which you are requesting payment.
N O T E : You cannot set this value to Sale on SetExpressCheckout

Required No

request and then change this value to Authorization on the final API DoExpressCheckoutPayment request. Character length and limit: Up to 13 single-byte alphabetic characters Allowable Values: Authorization Order Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale.. EMAIL Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page. Character length and limit: 127 single-byte alphanumeric characters Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use, such as a tracking number or other value you want PayPal to return on GetExpressCheckoutDetails response and DoExpressCheckoutPayment response. Character length and limitations: 256 single-byte alphanumeric characters Your own unique invoice or tracking number. PayPal returns this value to you on DoExpressCheckoutPayment response. Character length and limitations: 127 single-byte alphanumeric characters The value 1 indicates that you require that the customers shipping address on file with PayPal be a confirmed address.
N O T E : Setting this field overrides the setting you have specified in your

No

DESC CUSTOM

No No

INVNUM

No

REQCONFIRMSHIPPI NG

No

Merchant Account Profile. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1 Default: 0

Name-Value Pair API Developer Guide and Reference

February 2007

55

NVP API Method and Field Reference

Express Checkout TABLE A.6 Parameter NOSHIPPING SetExpressCheckout Request Parameters Description The value 1 indicates that on the PayPal pages, no shipping address fields should be displayed whatsoever. Character length and limitations: Four single-byte numeric character. Allowable values: 0, 1 Default: 0 The value 1 indicates that the PayPal pages should display the shipping address set by you in this SetExpressCheckout request, not the shipping address on file with PayPal for this customer.
N O T E : Displaying the PayPal street address on file does not allow the

Required No

ADDROVERRIDE

No

customer to edit that address. Allowable values: 0, 1 Default: 0 TOKEN A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout.
N O T E : The token expires after three hours.

No

If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Allowable values: See the description of TOKEN in Table A.8, SetExpressCheckout Response Fields. LOCALECODE Locale of pages displayed by PayPal during Express Checkout. Character length and limitations: Any two-character country code. The following two-character country codes are supported by PayPal: AU DE FR IT GB ES US Any other value will default to US.
N O T E : For the list of country codes, see Appendix

No

F, Country Codes.
No

PAGESTYLE

Sets the Custom Payment Page Style for payment pages associated with this button/link. This value 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. Character length and limitations: 30 single-byte alphabetic characters.

56

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout TABLE A.6 Parameter HDRIMG SetExpressCheckout Request Parameters Description 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. Character length and limitations: 127 Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. Character length and limitations: Six character HTML hexadecimal color code in ASCII Sets the background color for the header of the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII Sets the background color for the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII Optional shipping address. The parameters for the optional Ship to Address are described in Table A.7, Ship to Address (Optional).
I M P O R T A N T : Ship to Address is optional, but if you include it, certain

Required No

HDRBORDERCOLOR

No

HDRBACKCOLOR

No

PAYFLOWCOLOR

No

Shipping Address

No

fields are required. TABLE A.7 Parameter SHIPTONAME SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY Ship to Address (Optional) Description Persons name associated with this shipping address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province. Character length and limitations: 40 single-byte characters Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, Country Codes. U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters Required Yes Yes Yes Yes Yes

SHIPTOZIP

Yes

Name-Value Pair API Developer Guide and Reference

February 2007

57

NVP API Method and Field Reference

Express Checkout TABLE A.7 Parameter SHIPTOSTREET2 PHONENUM Ship to Address (Optional) Description Second street address. Character length and limitations: 100 single-byte characters Phone number. Character length and limit: 20 single-byte characters Required No No

SetExpressCheckout Response

TABLE A.8 Parameter TOKEN

SetExpressCheckout Response Fields Description A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout.
N O T E : The token expires after three hours.

If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Redirecting the Customers Browser to PayPal Login Page

After you receive a successful response from SetExpressCheckout, add the TOKEN from SetExpressCheckout response as a name/value pair to the following URL, and redirect your customers browser to it:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse

For redirecting the customers browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 Object Moved with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.

GetExpressCheckoutDetails Request

TABLE A.9 Parameter METHOD

GetExpressCheckoutDetails Parameters Description Name of the API: GetExpressCheckoutDetails Required? Yes

58

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout TABLE A.9 Parameter TOKEN GetExpressCheckoutDetails Parameters Description A timestamped token, the value of which was returned by SetExpressCheckout response. Character length and limitations: 20 single-byte characters Allowable values: An unexpired token Required? Yes

GetExpressCheckoutDetails Response

TABLE A.10 GetExpressCheckoutDetails Response Fields Field TOKEN Description The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters Possible values: See the description of TOKEN in Table A.8, SetExpressCheckout Response Fields. Email address of payer. Character length and limitations: 127 single-byte characters Unique PayPal customer account number. Character length and limitations:17 single-byte characters maximum. Status of payer. Character length and limitations: 10 single-byte alphabetic characters. Possible values: verified, unverified Payers salutation. Character length and limitations: 20 single-byte characters Payers first name. Character length and limitations: 25 single-byte characters Payers middle name. Character length and limitations: 25 single-byte characters Payers last name. Character length and limitations: 25 single-byte characters Payers suffix. Character length and limitations: 12 single-byte characters Payers country of residence in the form of ISO standard 3166 two-character country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, Country Codes.

EMAIL PAYERID PAYERSTATUS

SALUTATION FIRSTNAME MIDDLENAME LASTNAME SUFFIX COUNTRYCODE

Name-Value Pair API Developer Guide and Reference

February 2007

59

NVP API Method and Field Reference

Express Checkout TABLE A.10 GetExpressCheckoutDetails Response Fields Field BUSINESS SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY Description Payers business name. Character length and limitations: 127 single-byte characters Persons name associated with this address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Second street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province Character length and limitations: 40 single-byte characters Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, Country Codes. U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters Status of street address on file with PayPal A free-form field for your own use, as set by you in the Custom element of SetExpressCheckout request. Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number, as set by you in the element of the same name in SetExpressCheckout request . Character length and limitations: 127 single-byte alphanumeric characters Payers contact telephone number.
N O T E : PayPal returns a contact telephone number only if your Merchant

SHIPTOZIP ADDRESSSTATUS CUSTOM

INVNUM

PHONENUM

account profile settings require that the buyer enter one. Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers)

DoExpressCheckoutPayment Request
Request to obtain payment with PayPal Express Checkout.
IMPO RTANT: PayPal

requires that a merchant using Express Checkout display to the customer the same amount that the merchant sends to PayPal in the AMT parameter with the DoExpressCheckoutPayment request API.

60

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

TABLE A.11 DoExpressCheckoutPayment Parameters Parameter METHOD TOKEN Description Name of the API: DoExpressCheckoutPayment The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters How you want to obtain payment: Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. Order indicates that this payment is an order authorization subject to settlement with PayPal Authorization & Capture. Sale indicates that this is a final sale for which you are requesting payment.
N O T E : You cannot set this value to Sale on SetExpressCheckout

Required? Yes Yes

PAYMENTACTION

Yes

request and then change this value to Authorization on the final API DoExpressCheckoutPayment request. Character length and limit: Up to 13 single-byte alphabetic characters Allowable Values: Authorization Order Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale.. PAYERID Encrypted PayPal customer account identification number as returned by GetExpressCheckoutDetails response. Character length and limitations: 127 single-byte characters. Total of order, including shipping, handling, and tax.
N O T E : Limitations: Must not exceed $10,000 USD in any currency.

Yes

AMT

Yes

No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).

DESC CUSTOM INVNUM

Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters

No No No

Name-Value Pair API Developer Guide and Reference

February 2007

61

NVP API Method and Field Reference

Express Checkout TABLE A.11 DoExpressCheckoutPayment Parameters Parameter BUTTONSOURCE Description An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters Your URL for receiving Instant Payment Notification (IPN) about this transaction.
N O T E : If you do not specify this value in the request, the notification URL

Required? No

NOTIFYURL

No

from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters ITEMAMT Sum of cost of all items in this order. No

Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
SHIPPINGAMT Total shipping costs for this order.
N O T E : Character length and limitations: Must not exceed $10,000 USD in

No

any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. HANDLINGAMT Total handling costs for this order.
N O T E : Character length and limitations: Must not exceed $10,000 USD in

No

any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. TAXAMT Sum of tax for all items in this order.
N O T E : Character length and limitations: Must not exceed $10,000 USD in

No

any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. CURRENCYCODE L_NAMEn A three-character currency code for one of the currencies listed in PayPalSupported Transactional Currencies. Default: USD. Item name. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. No No

62

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout TABLE A.11 DoExpressCheckoutPayment Parameters Parameter L_NUMBERn Description Item number. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. L_QTYn Item quantity. Character length and limitations: Any positive integer These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth. L_TAXAMTn Item sales tax. Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. These parameters should be ordered sequentially beginning with 0, for example, L_TAXAMT0, L_TAXAMT1, and so forth. L_AMTn Cost of item Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. Shipping Address Optional shipping address. The parameters for the optional Ship to Address are described in Table A.12, Optional Ship to Address.
I M P O R T A N T : Ship to Address is optional, but if you include it, certain

Required? No

No

No

No

No

fields are required. TABLE A.12 Optional Ship to Address Parameter SHIPTONAME SHIPTOSTREET SHIPTOCITY Description Persons name associated with this address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters Required? Yes Yes Yes

Name-Value Pair API Developer Guide and Reference

February 2007

63

NVP API Method and Field Reference

Express Checkout TABLE A.12 Optional Ship to Address Parameter SHIPTOSTATE SHIPTOCOUNTRY Description State or province. Character length and limitations: 40 single-byte characters Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, Country Codes. U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters Second street address. Character length and limitations: 100 single-byte characters Phone number. Character length and limit: 20 single-byte characters Required? Yes Yes

SHIPTOZIP SHIPTOSTREET2 SHIPTOPHONENUM

Yes No No

DoExpressCheckoutPayment Response

TABLE A.13 DoExpressCheckout Payment Response Fields Field TOKEN Description The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations:20 single-byte characters Allowable values: See the description of TOKEN in Table A.8, SetExpressCheckout Response Fields. Unique transaction ID of the payment.
N O T E : If the PaymentAction of the request was Authorization or

TRANSACTIONID

Order, this value is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations:19 single-byte characters Possible values: Transaction specific TRANSACTIONTYPE The type of transaction Character length and limitations:15 single-byte characters Possible values: cart express-checkout

64

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout TABLE A.13 DoExpressCheckout Payment Response Fields Field PAYMENTTYPE Description Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Possible values: none echeck instant Time/date stamp of payment Possible values: Transaction specific The final amount charged, including any shipping and taxes from your Merchant Profile.

ORDERTIME AMT

Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Possible Values: Transaction specific CURRENCYCODE FEEAMT A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. PayPal fee amount charged for the transaction

Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Possible values: Transaction specific SETTLEAMT TAXAMT Amount deposited in your PayPal account after a currency conversion. Possible values: Transaction specific Tax charged on the transaction.

Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Possible values: Transaction specific EXCHANGERATE Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customers account. Character length and limitations: a decimal that does not exceed 17 characters, including decimal point Possible values: Transaction specific

Name-Value Pair API Developer Guide and Reference

February 2007

65

NVP API Method and Field Reference

Express Checkout TABLE A.13 DoExpressCheckout Payment Response Fields Field PAYMENTSTATUS Description Status of the payment: Completed: The payment has been completed, and the funds have been added successfully to your account balance. Pending: The payment is pending. See the PendingReason element for more information. The reason the payment is pending: none: No pending reason address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. 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. other: The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service. The reason for a reversal if TransactionType is reversal: none: No reason code chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. refund: A reversal has occurred on this transaction because you have given the customer a refund. other: A reversal has occurred on this transaction due to a reason not listed above.

PENDINGREASON

REASONCODE

66

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoCapture

DoCapture

TABLE A.14 DoCapture Parameters Parameter METHOD AUTHORIZATIONID Description Name of API: DoCapture The authorization identification number of the payment you want to capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment. Character length and limits: 19 single-byte characters maximum. Amount to capture. Required? Yes Yes

AMT

Yes

Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
CURRENCYCODE COMPLETETYPE A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. The value Complete indicates that this the last capture you intend to make. The value NotComplete indicates that you intend to make additional captures.
N O T E : If Complete, any remaining amount of the original authorized

No Yes

transaction is automatically voided and all remaining open authorizations are voided. Character length and limits: 12 single-byte alphanumeric characters INVNUM Your invoice number or other identification number that is displayed to the merchant and customer in his transaction history.
N O T E : This value on DoCapture will overwrite a value previously set on

No

DoAuthorization.
N O T E : The value is recorded only if the authorization you are capturing is

an order authorization, not a basic authorization. Character length and limits: 127 single-byte alphanumeric characters NOTE An informational note about this settlement that is displayed to the payer in email and in his transaction history. No

Character length and limits: 255 single-byte characters

Name-Value Pair API Developer Guide and Reference

February 2007

67

NVP API Method and Field Reference

DoCapture TABLE A.15 DoCapture Response Fields Field AUTHORIZATIONID Description The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters maximum Unique transaction ID of the payment. Character length and limitations: 17 single-byte characters PARENTTRANSACTIONID Parent or related transaction identification number. This field is populated for the following transaction types: Reversal. Capture of an authorized transaction. Reversal. Reauthorization of a transaction. Capture of an order. The value of ParentTransactionID is the original OrderID. Authorization of an order. The value of ParentTransactionID is the original OrderID. Capture of an order authorization. Void of an order. The value of ParentTransactionID is the original OrderID. Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format Receipt identification number Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format The type of transaction cart express-checkout Character length and limitations: 15 single-byte characters Indicates whether the payment is instant or delayed.

TRANSACTIONID

RECEIPTID

TRANSACTIONTYPE

PAYMENTTYPE

Character length and limitations: Seven single-byte characters

ORDERTIME AMT FEEAMT SETTLEAMT TAXAMT Time/date stamp of payment. For example: 2006-08-15T17:23:15Z.

The final amount charged, including any shipping and taxes from your Merchant Profile. PayPal fee amount charged for the transaction Amount deposited in your PayPal account if there is a currency conversion. Tax charged on the transaction, if any

68

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoAuthorization TABLE A.15 DoCapture Response Fields Field EXCHANGERATE Description Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customers non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customers account.

Character length and limitations: a decimal multiplier

PAYMENTSTATUS Status of the payment. The status of the payment: None: No status Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. Completed: The payment has been completed, and the funds have been added successfully to your account balance. Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. Expired: the authorization period for this payment has been reached. Failed: The payment has failed. This happens only if the payment was made from your customers bank account. Pending: The payment is pending. See the PendingReason field for more information. Refunded: You refunded the payment. Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element. Processed: A payment has been accepted. Voided: An authorization for this transaction has been voided.

DoAuthorization

TABLE A.16 DoAuthorization Parameters Parameter METHOD Description Name of the API: DoAuthorization Required? Yes

Name-Value Pair API Developer Guide and Reference

February 2007

69

NVP API Method and Field Reference

DoVoid TABLE A.16 DoAuthorization Parameters Parameter TRANSACTIONID Description The value of the orders transaction identification number returned by PayPal. Required? Yes

Character length and limits: 19 single-byte characters maximum

AMT Amount to authorize. Yes

Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
TRANSACTIONENTIT Y Type of transaction to authorize. The only allowable value is Order, which means that the transaction represents a customer order that can be fulfilled over 29 days. A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. No

CURRENCYCODE

No

TABLE A.17 DoAuthorization Response Fields Field TRANSACTIONID Description An authorization identification number. Character length and limits: 19 single-byte characters

AMT

The amount you specified in the request.

DoVoid

TABLE A.18 DoVoid Request Parameters Parameter METHOD Description Name of API: DoVoid Required? Yes

70

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

DoReauthorization TABLE A.18 DoVoid Request Parameters Parameter AUTHORIZATIONID Description The value of the original authorization identification number returned by a PayPal product.
I M P O R T A N T : If you are voiding a transaction that has been reauthorized,

Required? Yes

use the ID from the original authorization, and not the reauthorization. Character length and limits: 19 single-byte characters NOTE An informational note about this void that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters No

TABLE A.19 DoVoid Response Fields Field AUTHORIZATIONID Description The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters

DoReauthorization

TABLE A.20 DoReauthorization Request Parameters Parameter METHOD AUTHORIZATIONID Description Name of API: DoReauthorization The value of a previously authorized transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum Amount to reauthorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. Required? Yes Yes

AMT

Yes

CURRENCYCODE

No

Name-Value Pair API Developer Guide and Reference

February 2007

71

NVP API Method and Field Reference

RefundTransaction TABLE A.21 DoReauthorization Response Fields Field AUTHORIZATIONID Description A new authorization identification number. Character length and limits:19 single-byte characters

RefundTransaction

TABLE A.22 RefundTransaction Request Parameters Parameter METHOD TRANSACTIONID REFUNDTYPE Description Name of API call: RefundTransaction Unique identifier of a transaction Character length and limitations: 17 single-byte alphanumeric characters Type of refund you are making Other Full Partial Refund amount. Amount is required if RefundType is Partial.
N O T E : If RefundType is Full, do not set Amount.

Required? Yes Yes Yes

AMT

No

NOTE

Custom memo about the refund. Character length and limitations: 255 single-byte alphanumeric characters

No

TABLE A.23 DoRefund Response Fields Field REFUNDTRANSACTIONID NETREFUNDAMT FEEREFUNDAMT GROSSREFUNDAMT Description Unique transaction ID of the refund. Character length and limitations:17 single-byte characters Amount subtracted from PayPal balance of original recipient of payment to make this refund Transaction fee refunded to original recipient of payment Amount of money refunded to original payer

72

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

TransactionSearch

TransactionSearch
With TransactionSearch you must always set the StartDate field. Some other behavior: Setting TransactionID overrides all other fields (even the required StartDate field). The effect of setting other elements is additive or can alter the search criteria. TransactionSearch returns up to 100 matches. Partial matches are displayed. For example, setting the TransactionSearchRequest FirstName to Jess returns results such as Jessica and Jesse. The most important returned element is TransactionID, which you can pass to GetTransactionDetails in order to retrieve all available information about a specific transaction.
TABLE A.24 TransactionSearch Parameters Parameter METHOD STARTDATE ENDDATE EMAIL RECEIVER RECEIPTID TRANSACTIONID Description Name of API call: TransactionSearch The earliest transaction date at which to start the search.
N O T E : No wildcards are allowed. The value must be in UTC/GMT format.

Required Yes Yes

The latest transaction date to be included in the search Search by the buyers email address Character length and limitations: 127 single-byte alphanumeric characters Search by the receivers email address. If the merchant account has only one email, this is the primary email. Can also be a non-primary email. Search by the PayPal Account Optional receipt ID Search by the transaction ID.
N O T E : The returned results are from the merchants transaction records.

No No No No No

Character length and limitations: 19 single-byte characters maximum INVNUM Search by invoice identification key, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased.
N O T E : No wildcards are allowed.

No

Character length and limitations: 127 single-byte characters maximum ACCT Search by credit card number, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased.
N O T E : No wildcards are allowed.

No

Character length and limitations: Must be at least 11 and no more than 25 single-byte numeric characters maximum. Special punctuation, such as dashes or spaces, is ignored.

Name-Value Pair API Developer Guide and Reference

February 2007

73

NVP API Method and Field Reference

TransactionSearch TABLE A.24 TransactionSearch Parameters Parameter SALUTATION FIRSTNAME MIDDLENAME LASTNAME SUFFIX AUCTIONITEMNUMBE R TRANSACTIONCLASS Description Buyers salutation Character length and limitations: 20 single-byte characters Buyers first name Character length and limitations: 25 single-byte characters Buyers middle name Character length and limitations: 25 single-byte characters Buyers last name Character length and limitations: 2025 single-byte characters Payers suffix Character length and limitations: 12 single-byte characters Search by auction item number of the purchased goods Search by classification of transaction.
N O T E : Some kinds of possible classes of transactions are not searchable

Required No No No No No No No

with this field. You cannot search for bank transfer withdrawals, for example. All: all transaction classifications Sent: only payments sent Received: only payments received MassPay: only mass payments MoneyRequest: only money requests FundsAdded: only funds added to balance FundsWithdrawn: only funds withdrawn from balance Referral: only transactions involving referrals Fee: only transactions involving fees Subscription: only transactions involving subscriptions Dividend: only transactions involving dividends Billpay: only transactions involving BillPay Transactions Refund: only transactions involving funds CurrencyConversions: only transactions involving currency conversions BalanceTransfer: only transactions involving balance transfers Reversal: only transactions involving BillPay reversals Shipping: only transactions involving UPS shipping fees BalanceAffecting: only transactions that affect the account balance ECheck: only transactions involving eCheck AMT Search by transaction amount No

74

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

TransactionSearch TABLE A.24 TransactionSearch Parameters Parameter TRANSACTIONSTATU S Description Search by transaction status: Pending: The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field. Processing: The payment is being processed. Success: The payment has been completed and the funds have been added successfully to your account balance. Denied: You denied the payment. This happens only if the payment was previously pending. Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. Search by transaction status: Pending: The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field. Processing: The payment is being processed. Success: The payment has been completed and the funds have been added successfully to your account balance. Denied: You denied the payment. This happens only if the payment was previously pending. Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. Required No

STATUS

No

TABLE A.25 TransactionSearch Response Fields Field L_TIMESTAMPn Description The date and time (in UTC/GMT format) the transaction occurred These parameters should be ordered sequentially beginning with 0, for example, L_TIMESTAMP0, L_TIMESTAMP1, and so forth. L_TIMEZONEn The time zone of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_TIMEZONE0, L_TIMEZONE1, and so forth. L_TYPEn The type of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_TYPE0, L_TYPE1, and so forth. L_EMAILn The email address of either the payer or the payment recipient (the payee). If the payment amount is positive, this field is the recipient of the funds. If the payment is negative, this field is the paying customer. These parameters should be ordered sequentially beginning with 0, for example, L_EMAIL0, L_EMAIL1, and so forth.

Name-Value Pair API Developer Guide and Reference

February 2007

75

NVP API Method and Field Reference

GetTransactionDetails TABLE A.25 TransactionSearch Response Fields Field L_NAMEn Description Display name of the payer These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. L_TRANSACTIONIDn Sellers transaction ID These parameters should be ordered sequentially beginning with 0, for example, L_TRANSACTIONID0, L_TRANSACTIONID1, and so forth. L_STATUSn The status of the transaction. These parameters should be ordered sequentially beginning with 0, for example, L_STATUS0, L_STATUS1, and so forth. L_AMTn The total gross amount charged, including any profile shipping cost and taxes These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. L_FEEAMTn The fee that PayPal charged for the transaction These parameters should be ordered sequentially beginning with 0, for example, L_FEEAMT0, L_FEEAMT1, and so forth. L_NETAMTn The net amount of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_NETAMT0, L_NETAMT1, and so forth.

GetTransactionDetails

TABLE A.26 GetTransactionDetails Parameters Parameter METHOD TRANSACTIONID Description Name of the API: GetTransactionDetails Unique identifier of a transaction.
N O T E : The details for some kinds of transactions cannot be retrieved with

Required? Yes Yes

GetTransactionDetails. You cannot obtain details of bank transfer withdrawals, for example. Character length and limitations: 17 single-byte alphanumeric characters

76

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

GetTransactionDetails TABLE A.27 GetTransactionDetails Response Fields Parameter RECEIVERBUSINESS Description Email address or account ID of the payment recipient (the seller). Equivalent to Receiver if payment is sent to primary account. Character length and limitations: 127 single-byte alphanumeric characters Primary email address of the payment recipient (the seller). If you are the recipient of the payment and the payment is sent to your non-primary email address, the value of Receiver is still your primary email address. Character length and limitations: 127 single-byte alphanumeric characters Unique account ID of the payment recipient (the seller). This value is the same as the value of the recipient's referral ID. Email address of payer Character length and limitations: 127 single-byte characters Unique customer ID Character length and limitations: 17 single-byte characters Status of payers email address: Verified Unverified Payers first name Character length and limitations: 25 single-byte characters Payers last name Character length and limitations: 25 single-byte characters Payers middle name Character length and limitations: 25 single-byte characters Payers business name. Character length and limitations: 127 single-byte characters Payment senders country of residence using standard two-character ISO 3166 country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, Country Codes. Payers salutation Character length and limitations: 20 single-byte characters Payers suffix Character length and limitations: 12 single-byte characters eBay company that maintains this address

RECEIVEREMAIL

RECEIVERID EMAIL PAYERID PAYERSTATUS

FIRSTNAME LASTNAME MIDDLENAME PAYERBUSINESS SHIPTOCOUNTRY

SALUTATION SUFFIX ADDRESSOWNER

Name-Value Pair API Developer Guide and Reference

February 2007

77

NVP API Method and Field Reference

GetTransactionDetails TABLE A.27 GetTransactionDetails Response Fields Parameter ADDRESSSTATUS Description Status of the address on file with PayPal: None Confirmed Unconfirmed Name of city. Character length and limitations: 120 single-byte alphanumeric characters Expanded name of country. Character length and limitation: 64 single-byte characters Persons name associated with this address. Character length and limitations: 32 single-byte alphanumeric characters Phone number associated with this address Postal code State or province. Character length and limitations: 120 single-byte alphanumeric characters First street address. Character length and limitations: 300 single-byte alphanumeric characters Second street address. Character length and limitations: 300 single-byte alphanumeric characters Original transaction to which this transaction is related. This field is populated for the following transaction types: Reversal Capture of an authorized transaction. Reauthorization of a transaction. Capture of an order. The value of ParentTransactionID is the original OrderID. Authorization of an order. The value of ParentTransactionID is the original OrderID. Capture of an order authorization. Void of an order. The value of ParentTransactionID is the original OrderID. Character length and limitations: 19 single-byte characters PayPal transaction identification number Character length and limitations: 19 single-byte characters Receipt ID Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format

SHIPTOCITY SHIPTOCOUNTRYNAM E SHIPTONAME SHIPTOPHONENUM SHIPTOZIP SHIPTOSTATE SHIPTOSTREET SHIPTOSTREET2 PARENTTRANSACTIO NID

TRANSACTIONID RECEIPTID

78

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

GetTransactionDetails TABLE A.27 GetTransactionDetails Response Fields Parameter TRANSACTIONTYPE Description The type of transaction cart: Transaction created by customer via the PayPal Shopping Cart feature. send-money: Transaction created by customer from the Send Money tab on the PayPal website. web-accept: Transaction created by customer via Buy Now, Donation, or Auction Smart Logos. subscr-*: Transaction created by customer via Subscription. eot means end of subscription term. merch-pmt: preapproved payment. mass-pay: Transaction created via MassPay. virtual-terminal: Transaction created via merchant virtual terminal. Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Date and time of payment Full amount of the customers payment, before transaction fee is subtracted Transaction fee associated with the payment Amount deposited into the accounts primary balance after a currency conversion from automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment. This amount is calculated after fees and taxes have been assessed. Amount of tax for transaction Exchange rate for transaction

PAYMENTTYPE ORDERTIME AMT FEEAMT SETTLEAMT

TAXAMT EXCHANGERATE

Name-Value Pair API Developer Guide and Reference

February 2007

79

NVP API Method and Field Reference

GetTransactionDetails TABLE A.27 GetTransactionDetails Response Fields Parameter PAYMENTSTATUS Description Status of the payment. The status of the payment: None: No status Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. Completed: The payment has been completed, and the funds have been added successfully to your account balance. Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. Expired: the authorization period for this payment has been reached. Failed: The payment has failed. This happens only if the payment was made from your customers bank account. Pending: The payment is pending. See the PendingReason field for more information. Refunded: You refunded the payment. Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element. Processed: A payment has been accepted. Voided: An authorization for this transaction has been voided.
N O T E : PendingReason is returned in the response only if PaymentStatus is

PENDINGREASON

Pending. The reason the payment is pending: none: No pending reason address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. 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. other: The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.

80

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

GetTransactionDetails TABLE A.27 GetTransactionDetails Response Fields Parameter REASONCODE Description The reason for a reversal if TransactionType is reversal: none: No reason code chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. refund: A reversal has occurred on this transaction because you have given the customer a refund. other: A reversal has occurred on this transaction due to a reason not listed above. Invoice number you set in the original transaction. Character length and limitations: 127 single-byte alphanumeric characters Custom field you set in the original transaction. Character length and limitations: 127 single-byte alphanumeric characters Memo entered by your customer in PayPal Website Payments note field. Character length and limitations: 255 single-byte alphanumeric characters Amount of tax charged on payment Item name set by you or entered by the customer. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_name variable. For example, item_name1, item_name2, and so forth. Character length and limitations: 127 single-byte alphanumeric characters These parameters should be ordered sequentially beginning with 0, for example, L_DESC0, L_DESC1, and so forth. L_NUMBERn Item number set by you. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_number variable. For example, item_number1, item_number2, and so forth. Character length and limitations: 127 single-byte alphanumeric characters These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. L_QTYn Quantity set by you or entered by the customer. Character length and limitations: no limit These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth. L_AMTn Cost of item These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth.

INVNUM CUSTOM NOTE SALESTAX L_DESCn

Name-Value Pair API Developer Guide and Reference

February 2007

81

NVP API Method and Field Reference

GetTransactionDetails TABLE A.27 GetTransactionDetails Response Fields Parameter L_OPTIONSn Description PayPal item options for shopping cart These parameters should be ordered sequentially beginning with 0, for example, L_OPTIONS0, L_OPTIONS1, and so forth. SUBSCRIPTIONID SUBSCRIPTIONDATE EFFECTIVEDATE RETRYTIME USERNAME PASSWORD ID generated by PayPal for the subscriber. Character length and limitations: no limit Subscription start date Date when the subscription modification will be effective Date PayPal will retry a failed subscription payment. Username generated by PayPal and given to subscriber to access the subscription. Character length and limitations: 64 alphanumeric single-byte characters Password generated by PayPal and given to subscriber to access the subscription. For security, the value of the password is hashed. Character length and limitations: 128 alphanumeric single-byte characters The number of payment installments that will occur at the regular rate. Character length and limitations: no limit Indicates whether reattempts should occur upon payment failures Indicates whether regular rate recurs. 1 = Yes The amount subscriber is to be charged in one payment. Character length and limitations: no limit The period of time that the subscriber will be charged. Character length and limitations: no limit Customers auction ID Auctions close date Counter used for multi-item auction payments

RECURRENCES REATTEMPT RECURRING SUBSCRIPTIONAMT PERIOD BUYERID CLOSINGDATE MULTIITEM

82

February 2007

Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Mass Payment

Mass Payment

TABLE A.28 MassPay Parameters Parameter METHOD RECEIVERTYPE Description Name of the API: MassPay Indicates how you identify the recipients of payments in all the individual mass payment items: either by EmailAddress (L_EMAILn in the individual item) or by UserID (L_RECEIVERID_n in the individual item). Payment amount. A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. Email address of recipient.
N O T E : You must specify either L_EMAILn or L_RECEIVERIDn, but you

Require d? Yes Yes

L_AMTn CURRENCYCODE L_EMAILn

Yes Yes Depends on RECEIVE RTYPE

must not mix them. Use only one or the other, but not both, in a single request. Character length and limitations: 127 single-byte characters maximum. These parameters should be ordered sequentially beginning with 0, for example, L_EMAIL0, L_EMAIL1, and so forth. L_RECEIVERIDn Unique PayPal customer account number. This value corresponds to the value of PAYERID returned by GetTransactionDetails. These parameters should be ordered sequentially beginning with 0, for example, L_RECEIVERID0, L_RECEIVERID1, and so forth. L_UNIQUEIDn Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. These parameters should be ordered sequentially beginning with 0, for example, L_UNIQUEID0, L_UNIQUEID1, and so forth. L_NOTEn Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters These parameters should be ordered sequentially beginning with 0, for example, L_NOTE0, L_NOTE1, and so forth. EMAILSUBJECT The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients. Character length and limitations: 255 single-byte alphanumeric characters

Depends on RECEIVE RTYPE No

No

No

Name-Value Pair API Developer Guide and Reference

February 2007

83

NVP API Method and Field Reference

Mass Payment TABLE A.29 MassPay Response Fields The fields in the response are the standard response header fields. See [successResponseHeader].

84

February 2007

Name-Value Pair API Developer Guide and Reference

Error Message Reference

This chapter contains error messages for the API.

Error Response Format

If the ACK value is Error or Warning, specific API response fields are not returned. An error response has the following general format
TABLE B.1 Response Fields on Error Format of an Error Response Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error.

ACK=Error&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage &L_LONGMESSAGE0=longMessage&L_SEVERITYCODE0=severityCode

Validation Errors

TABLE B.1 Validation Errors Error Code 81000 81001 81002 81003 81004 81100 81101 81102 81103 81104 81105 Short Message Missing Parameter Invalid Parameter Unspecified Method Unspecified Method Unspecified Method Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Long Message Required Parameter Missing : Unable to identify parameter A Parameter is Invalid : Unable to identify parameter Method Specified is not Supported No Method Specified No Request Received OrderTotal (Amt) : Required parameter missing MaxAmt : Required parameter missing ReturnURL: Required parameter missing NotifyURL : Required parameter missing CancelURL : Required parameter missing ShipToStreet : Required parameter missing

Developers Guide

February 2007

85

Error Message Reference

Validation Errors TABLE B.1 Validation Errors Error Code 81106 81107 81108 81109 81110 81111 81112 81113 81114 81115 81116 81117 81118 81119 81120 81121 81122 81123 81124 81125 81126 81127 81128 81129 81130 81131 81132 81133 81134 81135 Short Message Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Long Message ShipToStreet2 : Required parameter missing ShipToCity : Required parameter missing ShipToState : Required parameter missing ShipToZip : Required parameter missing ShipToCountry : Required parameter missing ReqConfirmShipping : Required parameter missing NoShipping : Required parameter missing AddrOverride : Required parameter missing LocaleCode : Required parameter missing PaymentAction : Required parameter missing Email : Required parameter missing Token : Required parameter missing PayerID : Required parameter missing ItemAmt : Required parameter missing ShippingAmt : Required parameter missing HandlingTotal Amt : Required parameter missing TaxAmt : Required parameter missing IPAddress : Required parameter missing ShipToName : Required parameter missing L_Amt : Required parameter missing Amt : Required parameter missing L_TaxAmt : Required parameter missing AuthorizationID : Required parameter missing CompleteType : Required parameter missing CurrencyCode : Required parameter missing TransactionID : Required parameter missing TransactionEntity : Required parameter missing Acct : Required parameter missing ExpDate : Required parameter missing FirstName : Required parameter missing

86

February 2007

Developers Guide

Error Message Reference

Validation Errors TABLE B.1 Validation Errors Error Code 81136 81137 81138 81139 81140 81141 81142 81143 81144 81145 81146 81147 81148 81149 81150 81200 81201 81203 81205 81206 81207 81208 81209 81210 81211 81212 81213 81214 81215 81219 Short Message Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Long Message LastName : Required parameter missing Street : Required parameter missing Street2 : Required parameter missing City : Required parameter missing State : Required parameter missing Zip : Required parameter missing CountryCode : Required parameter missing RefundType : Required parameter missing StartDate : Required parameter missing EndDate : Required parameter missing MPID : Required parameter missing CreditCardType : Required parameter missing User : Required parameter missing Pwd : Required parameter missing Version : Required parameter missing Amt : Invalid parameter MaxAmt : Invalid parameter NotifyURL : Invalid parameter ShipToStreet : Invalid parameter ShipToStreet2 : Invalid parameter ShipToCity : Invalid parameter ShipToState : Invalid parameter ShipToZip : Invalid parameter Country : Invalid parameter ReqConfirmShipping : Invalid parameter Noshipping : Invalid parameter AddrOverride : Invalid parameter LocaleCode : Invalid parameter PaymentAction : Invalid parameter ItemAmt : Invalid parameter

Developers Guide

February 2007

87

Error Message Reference

Validation Errors TABLE B.1 Validation Errors Error Code 81220 81221 81222 81223 81224 81225 81226 81227 81229 81230 81232 81234 81235 81236 81237 81238 81239 81243 81244 81245 81247 81248 81249 81250 81251 Short Message Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Internal Error Long Message ShippingAmt : Invalid parameter HandlingTotal Amt : Invalid parameter TaxAmt : Invalid parameter IPAddress : Invalid parameter ShipToName : Invalid parameter L_Amt : Invalid parameter Amt : Invalid parameter L_TaxAmt : Invalid parameter CompleteType : Invalid parameter CurrencyCode : Invalid parameter TransactionEntity : Invalid parameter ExpDate : Invalid parameter FirstName : Invalid parameter LastName : Invalid parameter Street : Invalid parameter Street2 : Invalid parameter City : Invalid parameter RefundType : Invalid parameter StartDate : Invalid parameter EndDate : Invalid parameter CreditCardType : Invalid parameter Username : Invalid parameter Password : Invalid parameter Version : Invalid parameter Internal Service Error

88

February 2007

Developers Guide

Error Message Reference

General API Errors

General API Errors

TABLE B.2 Error Code 10002

General API Errors Long Message Username/Password is incorrect Correcting This Error This error can be caused by an incorrect API username, an incorrect API password, or an invalid API signature. Make sure that all three of these values are correct. For your security, PayPal does not report exactly which of these three values might be in error.

Short Message Authentication /Authorization Failed

10002

Authentication /Authorization Failed Authentication /Authorization Failed Internal Error Authentication /Authorization Failed Authentication /Authorization Failed Authentication /Authorization Failed Authentication /Authorization Failed Restricted account Authentication /Authorization Failed

You do not have permissions to make this API call Account is locked or inactive

10002

10002 10002

Internal Error Internal Error

10002

Account is not verified

10002

This call is not defined in the database!

10002

Token is not valid

10002 10002

Account is restricted Token is not valid

Developers Guide

February 2007

89

Error Message Reference

Direct Payment API Errors TABLE B.2 Error Code 10002 General API Errors Long Message API access is disabled for this account Correcting This Error

Short Message Authentication /Authorization Failed Authentication /Authorization Failed Restricted account

10002

Client certificate is disabled

10002

Account is restricted

Direct Payment API Errors

TABLE B.2 Direct Payment API Errors Error Code 10500 Short Message Invalid Configuration Invalid Configuration Invalid Data Long Message This transaction cannot be processed due to an invalid merchant configuration. This transaction cannot be processed due to an invalid merchant configuration. This transaction cannot be processed. Please use a valid credit card. This transaction cannot be processed. Please enter a valid Credit Card Verification Number. This transaction cannot be processed. This transaction cannot be processed. Please contact PayPal Customer Service. This transaction cannot be processed. Please enter a valid credit card expiration date. Corrective Action Occurs when you have not agreed to the billing agreement. Occurs when the billing agreement is disabled or inactive. The credit card used is expired.

10501

10502

10504

Invalid Data

The CVV provide is invalid. The CVV is between 3-4 digits long. The transaction was refused because the AVS response returned the value of N, and the merchant account is not able to accept such transactions. Your PayPal account is restricted - contact PayPal for more information. The expiration date must be a two-digit month and four-digit year.

10505

Gateway Decline Invalid Configuration Invalid Data

10507

10508

90

February 2007

Developers Guide

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10509 10510 10511 10512 Short Message Invalid Data Invalid Data Invalid Data Invalid Data Long Message This transaction cannot be processed. The credit card type is not supported. Try another card type. This transaction cannot be processed. This transaction cannot be processed. Please enter a first name. This transaction cannot be processed. Please enter a last name. Please enter a credit card. This transaction cannot be processed. This transaction cannot be processed. Please enter a valid credit card. This transaction cannot be processed. This transaction cannot be processed. The amount to be charged is zero. This transaction cannot be processed. The currency is not supported at this time. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please enter a valid credit card number and type. Corrective Action You must submit an IP address of the buyer with each API call. The credit card type entered is not currently supported by PayPal. The merchant selected an value for the PaymentAction field that is not supported. The first name of the buyer is required for this merchant. The last name of the buyer is required for this merchant. The credit card field was blank. The total amount and item amounts do not match. The credit card entered is invalid.

10513

Invalid Data

10519 10520 10521

Invalid Data Invalid Data Invalid Data

10523 10525

Internal Error Invalid Data

None - this is a PayPal internal error. The merchant entered a amount of zero.

10526

Invalid Data

The currency code entered is not supported.

10527

Invalid Data

The credit card entered is invalid.

10534

Gateway Decline Gateway Decline

The credit card entered is currently restricted by PayPal. Contact PayPal for more information. The credit card entered is invalid.

10535

Developers Guide

February 2007

91

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10536 Short Message Invalid Data Long Message This transaction cannot be processed. Corrective Action The merchant entered an invoice ID that is already associated with a transaction by the same merchant. By default, the invoice ID must be unique for all transactions. To change this setting, log into PayPal or contact customer service. The transaction was declined by the country filter managed by the merchant. To accept this transaction, change your risk settings on PayPal. The transaction was declined by the maximum amount filter managed by the merchant. To accept this transaction, change your risk settings on PayPal. The transaction was declined by PayPal. Contact PayPal for more information. The transaction was declined by PayPal because of an invalid address. The credit card entered is currently restricted by PayPal. Contact PayPal for more information. The email address provided by the buyer is in an invalid format. The transaction was declined by PayPal. Contact PayPal for more information. The transaction was declined by PayPal because of possible fraudulent activity. Contact PayPal for more information. The transaction was declined by PayPal because of possible fraudulent activity on the IP address. Contact PayPal for more information. None - this is a PayPal internal error. The merchant account attempting the transaction is not a business account at PayPal. Check your account settings.

10537

Filter Decline

This transaction cannot be processed. This transaction cannot be processed.

10538

Filter Decline

10539 10540

Filter Decline Invalid Data

This transaction cannot be processed. The transaction cannot be processed due to an invalid address. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please enter a valid email address. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. The merchant's accouht is not able to process transactions.

10541

Gateway Decline Invalid Data

10542

10544 10545

Gateway Decline Gateway Decline Gateway Decline Internal Error Invalid Configuration

10546

10547 10548

92

February 2007

Developers Guide

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10549 Short Message Invalid Configuration Long Message This transaction cannot be processed. The merchant's account is not able to process transactions. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. Corrective Action The merchant account attempting the transaction is not able to process Direct Payment transactions. Contact PayPal for more information. Access to Direct Payment was disabled for your account. Contact PayPal for more information. The merchant account attempting the transaction does not have a confirmed email address with PayPal. Check your account settings. The merchant attempted a transaction where the amount exceeded the upper limit for that merchant. The transaction was declined because of a merchant risk filter for AVS. Specifically, the merchant has set to decline transaction when the AVS returned a no match (AVS = N). The transaction was declined because of a merchant risk filter for AVS. Specifically, the merchant has set to decline transaction when the AVS returned a partial match. The transaction was declined because of a merchant risk filter for AVS. Specifically, the merchant has set to decline transaction when the AVS was unsupported.

10550 10552

Invalid Configuration Invalid Configuration Gateway Decline Filter Decline

10553 10554

10555

Filter Decline

This transaction cannot be processed.

10556

Filter Decline

This transaction cannot be processed.

10561

Invalid Data

There's an error with this transaction. Please enter complete billing address. This transaction cannot be processed. Please enter a valid credit card expiration year. This transaction cannot be processed. Please enter a valid credit card expiration month. This transaction cannot be processed. The merchant country is not supported. There was a problem processing this transaction.

10562

Invalid Data

10563

Invalid Data

10564 10565

Gateway Decline Merchant country unsupported

Developers Guide

February 2007

93

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10566 Short Message Credit card type unsupported Invalid Data Long Message The credit card type is not supported. This transaction cannot be processed. Please enter a valid credit card number and type. There's an error with this transaction. Please enter a valid billing address. There's an error with this transaction. Please enter a valid address1 in the billing address. There's an error with this transaction. Please enter a valid address2 in the billing address. There's an error with this transaction. Please enter a valid city in the billing address. There's an error with this transaction. Please enter a valid state in the billing address. There's an error with this transaction. Please enter a valid postal code in the billing address. There's an error with this transaction. Please enter a valid country in the billing address. There's an error with this transaction. Please enter a complete billing address. There's an error with this transaction. Please enter an address1 in the billing address. There's an error with this transaction. Please enter an address1 in the billing address. There's an error with this transaction. Please enter a city in the billing address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. Corrective Action

10567

10701

Invalid Data

10702

Invalid Data

10703

Invalid Data

10704

Invalid Data

10705

Invalid Data

10706

Invalid Data

10707

Invalid Data

10708

Invalid Data

10709

Invalid Data

10709

Invalid Data

10710

Invalid Data

94

February 2007

Developers Guide

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10710 Short Message Invalid Data Long Message There's an error with this transaction. Please enter a city in the billing address. There's an error with this transaction. Please enter your state in the billing address. There's an error with this transaction. Please enter your five digit postal code in the billing address. There's an error with this transaction. Please enter a country in the billing address. There's an error with this transaction. Please enter a country in the billing address. There's an error with this transaction. Please enter a valid billing address. There's an error with this transaction. Please enter a valid state in the billing address. There's an error with this transaction. Please enter your five digit postal code in the billing address. There's an error with this transaction. Please enter a valid postal code in the billing address. There's an error with this transaction. Please enter a valid city and state in the billing address. There's an error with this transaction. Please enter a valid shipping address. There's an error with this transaction. Please enter a valid address1 in the shipping address. Corrective Action There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid.

10711

Invalid Data

10712

Invalid Data

10713

Invalid Data

10713

Invalid Data

10714

Invalid Data

10715

Invalid Data

10716

Invalid Data

10717

Invalid Data

10718

Invalid Data

10719

Invalid Data

10720

Invalid Data

Developers Guide

February 2007

95

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10721 Short Message Invalid Data Long Message There's an error with this transaction. Please enter a valid address2 in the shipping address. There's an error with this transaction. Please enter a valid city in the shipping address. There's an error with this transaction. Please enter a valid state in the shipping address. There's an error with this transaction. Please enter your five digit postal code in the shipping address. There's an error with this transaction. Please enter a valid country in the shipping address. There's an error with this transaction. Please enter a complete shipping address. There's an error with this transaction. Please enter a complete shipping address. There's an error with this transaction. Please enter an address1 in the shipping address. There's an error with this transaction. Please enter an address1 in the shipping address. There's an error with this transaction. Please enter a city in the shipping address. There's an error with this transaction. Please enter a city in the shipping address. There's an error with this transaction. Please enter your state in the shipping address. Corrective Action There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid.

10722

Invalid Data

10723

Invalid Data

10724

Invalid Data

10725

Invalid Data

10726

Invalid Data

10726

Invalid Data

10727

Invalid Data

10727

Invalid Data

10728

Invalid Data

10728

Invalid Data

10729

Invalid Data

96

February 2007

Developers Guide

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10730 Short Message Invalid Data Long Message There's an error with this transaction. Please enter your five digit postal code in the shipping address. There's an error with this transaction. Please enter a country in the shipping address. There's an error with this transaction. Please enter a country in the shipping address. There's an error with this transaction. Please enter a valid shipping address. There's an error with this transaction. Please enter a valid state in the shipping address. There's an error with this transaction. Please enter your five digit postal code in the shipping address. There's an error with this transaction. Please enter your five digit postal code in the shipping address. There's an error with this transaction. Please enter a valid city and state in the shipping address. This transaction cannot be processed. Please enter a valid country code in the billing address. This transaction cannot be processed. Please enter a valid country code in the shipping address. This transaction cannot be processed. Please use a valid country on the billing address. Corrective Action There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. There was a problem with a particular field in the address. The long error message will tell you what field is invalid.

10731

Invalid Data

10731

Invalid Data

10732

Invalid Data

10733

Invalid Data

10734

Invalid Data

10735

Invalid Data

10736

Invalid Data

10744

Invalid Data

10745

Invalid Data

10746

Invalid Data

Developers Guide

February 2007

97

Error Message Reference

Direct Payment API Errors TABLE B.2 Direct Payment API Errors Error Code 10747 Short Message Invalid Data Long Message This transaction cannot be processed. This transaction cannot be processed without a Credit Card Verification number. There's an error with this transaction. Please enter a valid state in the shipping address. There's an error with this transaction. Please enter a valid state in the billing address. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed due to an unsupported currency. The transaction cannot be processed. The country and billing address associated with this credit card do not match. There's been an error due to invalid API username and/or password. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. The country listed for your business address is not currently supported. This transaction cannot be processed. Please check the status of your first transaction before placing another order. Corrective Action The merchant entered an IP address that was in an invalid format. The IP address must be in a format such as 123.456.123.456. The merchant's configuration requires a CVV to be entered, but no CVV was provided with this transaction. Contact PayPal if you wish to change this setting. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. The merchant provided an address either in the United States or Canada, but the state provided is not a valid state in either country. The transaction was declined by the issuing bank, not PayPal. The merchant should attempt another card. The transaction was declined by PayPal. Contact PayPal for more information. The currency code entered by the merchant is not supported. None - this is a PayPal internal error.

10748

Invalid Data

10750

Invalid Data

10751

Invalid Data

10752

Gateway Decline Gateway Decline Invalid Data

10754 10755

10756

Gateway Decline

10758

Invalid Configuration Gateway Decline Invalid Configuration

The API username or password is incorrect for this merchant. The transaction was declined by PayPal. Contact PayPal for more information. The merchant's country of residence listed in their PayPal account is not currently supported to allow Direct Payment transactions. The transaction was declined because PayPal is currently processing a transaction by the same buyer for the same amount. Can occur when a buyer submits multiple, identical transactions in quick succession.

10759

10760

10761

Gateway Decline

98

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.2 Direct Payment API Errors Error Code 10762 10763 15001 Short Message Gateway Decline Invalid Data Gateway Decline Long Message This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. Corrective Action The CVV provide is invalid. The CVV is between 3-4 digits long. None - this is a PayPal internal error. The transaction was rejected by PayPal because of excessive failures over a short period of time for this credit card. Contact PayPal for more information. The transaction was declined by PayPal. Contact PayPal for more information. The transaction was declined because the merchant does not have a valid commercial entity agreement on file with PayPal. Contact PayPal for more information. The transaction was declined because the CVV entered does not match the credit card. The transaction was declined by the issuing bank, not PayPal. The merchant should attempt another card. The transaction was declined by the issuing bank, not PayPal. The merchant should attempt another card. The transaction was declined by the issuing bank because of an expired credit card. The merchant should attempt another card.

15002 15003

Gateway Decline Invalid Configuration

This transaction cannot be processed. This transaction cannot be processed.

15004

Gateway Decline Processor Decline Processor Decline Processor Decline

This transaction cannot be processed. Please enter a valid Credit Card Verification Number. This transaction cannot be processed. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please use a valid credit card.

15005

15006

15007

Express Checkout API Errors

TABLE B.3 SetExpressCheckout API Errors Error Code 10001 Short Message ButtonSource value truncated. Long Message The transaction could not be loaded Correcting This Error...

Developers Guide

February 2007

99

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10001 10004 Short Message Internal Error Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Permission denied PaymentActio n of Order Temporarily Unavailable Authorization only is not allowed for merchant. Transaction refused because of an invalid argument. See additional error messages for details. Long Message Internal Error Transaction refused because of an invalid argument. See additional error messages for details. Correcting This Error...

10004

The transaction id is not valid

10007 10102

You do not have permissions to make this API call PaymentAction of Order is temporarily unavailable. Please try later or use other PaymentAction. This merchant account is not permitted to set PaymentAction to Authorization. Please contact Customer Service. ReturnURL is missing.

10402

10404

100

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10405 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. You're not authorized to access this info. Invalid token Long Message CancelURL is missing. Correcting This Error...

10407

Invalid buyer email address (BuyerEmail).

10409

Express Checkout token was issued for a merchant account other than yours.

10410

Invalid token.

Developers Guide

February 2007

101

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10411 Short Message This Express Checkout session has expired. Long Message This Express Checkout session has expired. Token value is no longer valid. Correcting This Error... The token returned by SetExpressCheckout response expires after three hours. If you attempt to send the DoExpressCheckoutPaym ent after that time, you will receive error code 10411 in the DoExpressCheckoutPaym ent response. If you receive this error, you must return your customer to PayPal to approve the use of PayPal again. Display an error message to inform the customer that the transaction expired, and provide a button to return to PayPal. In this situation, you are effectively restarting the entire checkout process. (Do not reuse the expired token value on SetExpressCheckout request.) However, because you already know the final OrderTotal, be sure to update the value for that element if appropriate. You might also want to update the values for ReturnURL and CancelURL, if necessary.

102

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10412 Short Message Duplicate invoice Long Message Payment has already been made for this InvoiceID. Correcting This Error... PayPal checks that InvoiceID values are unique for any particular merchant. If you send an InvoiceID value already associated with another transaction in the PayPal system, PayPal returns error code 10412. You might not be able to correct this error during an actual checkout. If you get this error, research why might occur and modify your implementation of Express Checkout to ensure that you generate unique invoice identification numbers. PayPal allows a token only once for a successful transaction. Handling this error If you determine that your customers are clicking your Place Order button twice, PayPal recommends that you disable the button after your customer has clicked it.

10415

Transaction refused because of an invalid argument. See additional error messages for details.

A successful transaction has already been completed for this token.

10425

Express Checkout has been disabled for this merchant. Transaction refused because of an invalid argument. See additional error messages for details.

Express Checkout has been disabled for this merchant. Please contact Customer Service.

10432

Invoice ID value exceeds maximum allowable length.

Developers Guide

February 2007

103

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10433 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message Value of OrderDescription element has been truncated. Correcting This Error...

10434

Value of Custom element has been truncated.

10436

PageStyle value exceeds maximum allowable length.

10437

cpp-header-image value exceeds maximum allowable length.

10438

cpp-header-image value exceeds maximum allowable length.

104

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10439 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Risk Control Country Filter Failure Risk Control Max Amount Failure Long Message cpp-header-image value exceeds maximum allowable length. Correcting This Error...

10440

cpp-header-image value exceeds maximum allowable length.

10471

ReturnURL: Invalid parameter

10472

CancelURL is invalid.

10537

The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings.

10538

Developers Guide

February 2007

105

Error Message Reference

Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 10539 Short Message Payment declined by your Risk Controls settings: PayPal Risk Model. Shipping Address Country Error Shipping Address1 Empty Shipping Address City Empty Shipping Address State Empty Shipping Address Postal Code Empty Shipping Address Country Empty Shipping Address Invalid City State Postal Code Long Message Payment declined by your Risk Controls settings: PayPal Risk Model. Correcting This Error...

10725

There was an error in the Shipping Address Country field The field Shipping Address1 is required

10727

10728

The field Shipping Address City is required

10729

The field Shipping Address State is required

10730

The field Shipping Address Postal Code is required The field Shipping Address Country is required A match of the Shipping Address City, State, and Postal Code failed.

10731

10736

TABLE B.4 GetExpressCheckoutDetails API Errors Error Code 10001 10001 Short Message Internal Error Internal Error Long Message Internal Error Transaction failed due to internal error Correcting This Error...

106

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.4 GetExpressCheckoutDetails API Errors Error Code 10001 Short Message ButtonSource value truncated. ButtonSource value truncated. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Invalid transaction type Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message The transaction could not be loaded The transaction could not be loaded Transaction refused because of an invalid argument. See additional error messages for details. Correcting This Error...

10001

10004

10004

The transaction id is not valid

10004

You can not get the details for this type of transaction The transaction could not be loaded

10004

10004

The transaction id is not valid

Developers Guide

February 2007

107

Error Message Reference

Express Checkout API Errors TABLE B.4 GetExpressCheckoutDetails API Errors Error Code 10007 10007 10007 10408 Short Message Permission denied Permission denied Permission denied Express Checkout token is missing. You're not authorized to access this info. Invalid token This Express Checkout session has expired. Long Message You do not have permissions to make this API call You do not have permission to get the details of this transaction You do not have permissions to make this API call Express Checkout token is missing. Correcting This Error...

10409

Express Checkout token was issued for a merchant account other than yours. Invalid token. This Express Checkout session has expired. Token value is no longer valid.

10410 10411

TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10001 10001 Short Message Internal Error Internal Error Long Message Transaction failed due to internal error Warning an internal error has occurred. The transaction id may not be correct The transaction could not be loaded Internal Error Correcting This Error...

10001

ButtonSource value truncated. Internal Error

10001

108

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10004 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Permission denied Transaction refused because of an invalid argument. See additional error messages for details. Express Checkout token is missing. You're not authorized to access this info. Invalid token This Express Checkout session has expired. Duplicate invoice Long Message Transaction refused because of an invalid argument. See additional error messages for details. Correcting This Error...

10004

The transaction id is not valid

10007 10406

You do not have permissions to make this API call The PayerID value is invalid.

10408

Express Checkout token is missing.

10409

Express Checkout token was issued for a merchant account other than yours. Invalid token. This Express Checkout session has expired. Token value is no longer valid. Payment has already been made for this InvoiceID.

10410 10411

10412

Developers Guide

February 2007

109

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10413 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Long Message The totals of the cart item amounts do not match order amounts. Correcting This Error... If you include any of the following element values with DoExpressCheckoutPayment, the sum of their values must equal the value of OrderTotal. ItemTotal ShippingTotal HandlingTotal TaxTotal If you get this error, research why it might have occurred and modify your implementation of Express Checkout to ensure proper addition of the values.

10414

Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details.

The amount exceeds the maximum amount for a single transaction.

10415

A successful transaction has already been completed for this token.

10416

You have exceeded the maximum number of payment attempts for this token.

You can send a maximum of 10 DoExpressCheckoutPayment API calls for any single token value, after which the token becomes invalid.

110

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10417 Short Message Transaction cannot complete. Long Message The transaction cannot complete successfully. Instruct the customer to use an alternative payment method. Correcting This Error... It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment. The most likely cause is that the customers credit card failed bank authorization. Another possible, though rare, cause is that the final OrderTotal is significantly higher than the original estimated OrderTotal you sent with SetExpressCheckout at Integration Point 1, and the final OrderTotal does not pass PayPals risk model analysis. If the customer has no other PayPal funding source that is likely to succeed, DoExpressCheckoutPayment response returns error code 10417. Instruct the customer that PayPal is unable to process the payment and redisplay alternative payment methods with which the customer can pay.

10418

Transaction refused because of an invalid argument. See additional error messages for details. Express Checkout PayerID is missing. Transaction refused because of an invalid argument. See additional error messages for details.

The currencies of the shopping cart amounts must be the same.

10419

Express Checkout PayerID is missing.

10420

Express Checkout PaymentAction is missing.

Developers Guide

February 2007

111

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10421 Short Message This Express Checkout session belongs to a different customer. Long Message This Express Checkout session belongs to a different customer. Token value mismatch. Correcting This Error... When your customer logs into PayPal, the PayPal PayerID is associated with the Express Checkout token. This error is caused by mixing tokens for two different PayerIDs. The Token and PayerID returned for any particular customer by GetExpressCheckoutDetails response must be the same ones you send with DoExpressCheckoutPayment. Verify that your programs are properly associating the Tokens and PayerIDs. It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment request. If the customer has a different PayPal funding source that is likely to succeed, DoExpressCheckoutPayment response returns error code 10422 so you can redirect the customer back to PayPal. This error occurs if at Integration Point 1, you set PaymentAction to Sale with SetExpressCheckout request but at Integration Point 3, you set PaymentAction to Authorization with DoExpressCheckoutPayment. PayPal does not allow this switch from Sale to Authorization in a single checkout session. PayPal does allow the reverse, however. You can set PaymentAction to Authorization with SetExpressCheckout at Integration Point 1 and switch PaymentAction to Sale with DoExpressCheckoutPayment at Integration Point 3. If you receive this error message, PayPal recommends that you return your customer to PayPal to review and approve new valid funding sources. Although this error is rare, you should consider trapping the error to display a message to the customer describing what happened, along with a button or hyperlink to return to PayPal. For the rules of this calculation, see the chapter about best practices in the PayPal Express Checkout Integration Guide.

10422

Customer must choose new funding sources.

The customer must return to PayPal to select new funding sources.

10423

Transaction refused because of an invalid argument. See additional error messages for details.

This transaction cannot be completed with PaymentAction of Authorization.

10424

Transaction refused because of an invalid argument. See additional error messages for details.

Shipping address is invalid.

112

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10431 10432 Short Message Item amount is invalid. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message Item amount is invalid. Invoice ID value exceeds maximum allowable length. Correcting This Error...

10433

Value of OrderDescription element has been truncated.

10434

Value of Custom element has been truncated.

10435

The customer has not yet confirmed payment for this Express Checkout session.

10441

The NotifyURL element value exceeds maximum allowable length.

Developers Guide

February 2007

113

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10442 Short Message ButtonSource value truncated. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. This transaction cannot be processed at this time. Please try again later. Unconfirmed email Invalid Data Long Message The ButtonSource element value exceeds maximum allowable length. This transaction cannot be completed with PaymentAction of Order. Correcting This Error...

10443

10444

The transaction currency specified must be the same as previously specified.

10445

This transaction cannot be processed at this time. Please try again later.

10446 10474

A confirmed email is required to make this API call. This transaction cannot be processed. The country code in the shipping address must match the buyers country of residence. The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. The buyer selects the country of residence when they sign up for their PayPal account. The country of residence is displayed after the dash in the title on the Account Overview page.

10537

Risk Control Country Filter Failure

10538

Risk Control Max Amount Failure

114

February 2007

Developers Guide

Error Message Reference

Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10539 Short Message Payment declined by your Risk Controls settings: PayPal Risk Model. Shipping Address Country Error Shipping Address1 Empty Shipping Address City Empty Shipping Address State Empty Shipping Address Postal Code Empty Shipping Address Country Empty Shipping Address Invalid City State Postal Code Long Message Payment declined by your Risk Controls settings: PayPal Risk Model. Correcting This Error...

10725

There was an error in the Shipping Address Country field The field Shipping Address1 is required The field Shipping Address City is required The field Shipping Address State is required The field Shipping Address Postal Code is required The field Shipping Address Country is required A match of the Shipping Address City, State, and Postal Code failed.

10727

10728

10729

10730

10731

10736

Developers Guide

February 2007

115

Error Message Reference

Authorization and Capture API Errors

Authorization and Capture API Errors

TABLE B.6 Authorization & Capture API Error Messages Error Code 10001 10001 10004 10007 10009 10010 Short Message Internal Error Internal Error Internal Error Permission denied Transaction refused Transaction refused because of an invalid argument. See additional error messages for details. Authorization voided. Long Message Internal Error Transaction failed due to internal error Invalid argument You do not have permissions to make this API call Account is locked or inactive Invalid argument Retry the request at a later time or close order. Returned By API Call... Correcting This Error...

10600

Authorization is voided.

DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid

Close the order or authorization.

10601

Authorization expired.

Authorization has expired.

Close the order or authorization.

10602

Authorization completed.

Authorization has already been completed.

Close the order or authorization.

10603

The buyer is restricted.

The buyer account is restricted.

Contact the buyer.

116

February 2007

Developers Guide

Error Message Reference

Authorization and Capture API Errors TABLE B.6 Authorization & Capture API Error Messages Error Code 10604 Short Message Authorization must include both buyer and seller. Unsupported currency. Buyer cannot pay. Auth&Capture unavailable. Long Message Authorization transaction cannot be unilateral. It must include both buyer and seller to make an auth. Currency is not supported. Transaction rejected, please contact the buyer. Authorization & Capture feature unavailable. Returned By API Call... DoAuthorization Correcting This Error... Review the order to ensure customer and seller are both PayPal members. Retry the request with a PayPal-supported currency. Contact the buyer.

10605 10606

DoAuthorization DoCapture DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoCapture

10607

Contact PayPal Customer Service

10608

Funding source missing. Invalid transactionID.

The funding source is missing. Transaction id is invalid.

Contact the buyer.

10609

Check the validity of the authorization ID and reattempt the request.

10610

Amount limit exceeded. Not enabled.

Amount specified exceeds allowable limit. Authorization & Capture feature is not enabled for the merchant. Contact customer service. Maxmimum number of allowable settlements has been reached. No more settlement for the authorization. Currency of capture must be the same as currency of authorization. You can void only the original authorization, not a reauthorization.

Reattempt the request with a lower amount. Contact PayPal Customer Service.

10611

10612

No more settlement.

Close the order.

10613

Currency mismatch. Cannot void reauth.

DoCapture

Ensure that the currencies are the same, and retry the request. Void the authorization.

10614

DoVoid

Developers Guide

February 2007

117

Error Message Reference

Authorization and Capture API Errors TABLE B.6 Authorization & Capture API Error Messages Error Code 10615 Short Message Cannot reauth reauth. Maximum number of reauthorization allowed for the auth is reached. Reauthorizatio n not allowed. Transaction already voided or expired. Long Message You can reauthorize only the original authorization, not a reauthorization. Maximum number of reauthorization allowed for the auth is reached. Returned By API Call... DoReauthorization Correcting This Error... Capture the reauthorization.

10616

DoReauthorization

Capture or close the authorization

10617

Reauthorization is not allowed inside honor period. Transaction has already been voided or expired.

DoReauthorization

Capture the authorization ro reauthorize outside of honor period. Close the orde or authorizationr.

10618

DoAuthorization DoCapture DoReauthorization DoVoid DoCapture

10619

Invoice ID value exceeds maximum allowable length. Order has already been voided, expired or completed. Order has expired. Order is voided. Maximum number of authorization allowed for the order is reached. Duplicate invoice

Invoice ID value exceeds maximum allowable length.

Check the length of the invoice ID and reattempt the request.

10620

Order has already been voided, expired or completed. Order has expired.

DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoReauthorization DoVoid

Close this order.

10621

Close this order.

10622

Order is voided.

Close this order.

10623

Maximum number of authorization allowed for the order is reached.

Capture this order.

10624

Payment has already been made for this InvoiceID.

DoAuthorization

Review the invoice ID and reattempt the request.

118

February 2007

Developers Guide

Error Message Reference

Authorization and Capture API Errors TABLE B.6 Authorization & Capture API Error Messages Error Code 10625 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Risk Long Message The amount exceeds the maximum amount for a single transaction. Returned By API Call... DoAuthorization DoCapture DoReauthorization Correcting This Error... Reattempt the request with a lower amount.

10626

Transaction refused due to risk model The invoice ID field is not supported for basic authorizations

DoAuthorization DoCapture DoReauthorization DoAuthorization DoReauthorization DoVoid

Contact the buyer.

10627

Transaction refused because of an invalid argument. See additional error messages for details. This transaction cannot be processed at this time. Please try again later. Reauthorizatio n not allowed. Item amount is invalid. This authorization cannot be voided, reauthorized, or captured against.

The Invoice ID field can only be used with DoCapture.

10628

This transaction cannot be processed at this time. Please try again later.

DoAuthorization DoCapture DoReauthorization DoVoid

Retry the request at a later time.

10629

Reauthorization is not allowed for this type of authorization. Item amount is invalid.

DoReauthorization

Use DoAuthorization to authorize the an order. Check the item amount to ensure that it is not zero or negative.

10630

DoAuthorization DoCapture

11094

This authorization can only be handled through the marketplace which created it. It cannot directly be voided, reauthorized, or captured against.

Developers Guide

February 2007

119

Error Message Reference

RefundTransaction API Errors

RefundTransaction API Errors

TABLE B.7 RefundTransaction API Errors Error Code 10001 10001 10001 Short Message Internal Error Internal Error ButtonSource value truncated. Internal Error Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message Internal Error Warning an internal error has occurred. The transaction id may not be correct The transaction could not be loaded Correcting This Error...

10001 10004

Internal Error The partial refund amount must be a positive amount

10004

You can not specify a partial amount with a full refund

10004

A transaction id is required

120

February 2007

Developers Guide

Error Message Reference

RefundTransaction API Errors TABLE B.7 RefundTransaction API Errors Error Code 10004 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Permission denied Long Message The partial refund amount must be a positive amount Correcting This Error...

10004

You can not specify a partial amount with a full refund

10004

A transaction id is required

10004

Transaction class is not supported

10004

The transaction id is not valid

10007

You do not have permission to refund this transaction

Developers Guide

February 2007

121

Error Message Reference

RefundTransaction API Errors TABLE B.7 RefundTransaction API Errors Error Code 10007 10009 Short Message Permission denied Transaction refused Long Message You do not have permissions to make this API call You do not have a verified ACH This error can be caused by insufficient funds in your PayPal balance to cover the amount of the refund and either your not having yet verified the bank account associated with your PayPal account or your not having any bank account associated with your PayPal account at all. Ensure that you have sufficient funds in your PayPal balance and that you have verified the associated bank account. Correcting This Error...

10009 10009 10009 10009

Transaction refused Transaction refused Transaction refused Transaction refused

The partial refund amount must be less than or equal to the original transaction amount The partial refund amount must be less than or equal to the remaining amount The partial refund amount is not valid Because a complaint case exists on this transaction, only a refund of the full or full remaining amount of the transaction can be issued You are over the time limit to perform a refund on this transaction Can not do a full refund after a partial refund Account is locked or inactive The partial refund must be the same currency as the original transaction This transaction has already been fully refunded

10009 10009 10009 10009 10009

Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused

122

February 2007

Developers Guide

Error Message Reference

TransactionSearch API Errors TABLE B.7 RefundTransaction API Errors Error Code 10009 10009 10009 10009 10009 10011 Short Message Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Invalid transaction id value Transaction refused because of an invalid argument. See additional error messages for details. Long Message Account is restricted You can not refund this type of transaction You can not do a partial refund on this transaction The account for the counterparty is locked or inactive You can not refund this type of transaction Transaction refused because of an invalid transaction id value Transaction class is not supported Correcting This Error...

11001

TransactionSearch API Errors

TABLE B.3 Error Code 10001 10001 10003

TransactionSearch API Errors Long Message Internal Error The transaction could not be loaded Start date is a required parameter

Short Message Internal Error ButtonSource value truncated. Transaction refused because of an invalid argument. See additional error messages for details.

Developers Guide

February 2007

123

Error Message Reference

TransactionSearch API Errors TABLE B.3 Error Code 10004 TransactionSearch API Errors Long Message Start date is invalid

Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details.

10004

End date is invalid

10004

Currency is not supported

10004

Transaction class is not supported

10004

Receipt id is not valid

10004

Payer email is invalid

10004

Auction item id is not valid

10004

Receiver email is invalid

10004

You can not search for a transaction id and a receipt id

10004

Receiver can only be specified for payments you've received

124

February 2007

Developers Guide

Error Message Reference

GetTransactionDetails API Errors TABLE B.3 Error Code 10004 TransactionSearch API Errors Long Message The transaction id is not valid

Short Message Transaction refused because of an invalid argument. See additional error messages for details. Permission denied Permission denied Search warning

10007 10007 11002

You do not have permissions to search for this transaction You do not have permissions to make this API call The number of results were truncated. Please change your search parameters if you wish to see all your results.

GetTransactionDetails API Errors

TABLE B.8 GetTransactionDetails API Errors Error Code 10001 Short Message Internal Error Long Message Internal Error

MassPay API Errors

TABLE B.9 MassPay API Errors Error Code 10001 10001 10001 10001 Short Message Invalid account number. Internal Error Internal Error ButtonSource value truncated. Long Message The transaction failed as a result of an invalid credit card number. Check the number or attempt with another card. Internal Error The transaction could not be loaded The transaction could not be loaded

Developers Guide

February 2007

125

Error Message Reference

MassPay API Errors TABLE B.9 MassPay API Errors Error Code 10001 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Account locked Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message The masspay receiver_type is not a recognizable type

10002 10004

The user account is locked The number of input records is greater than maximum allowed

10004

The number of input records is less than or equal to zero

10004

The note string length exceeds the maximum limit of 4000 characters

10004

The amount is missing

126

February 2007

Developers Guide

Error Message Reference

MassPay API Errors TABLE B.9 MassPay API Errors Error Code 10004 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message The currency is missing

10004

Currency is not supported

10004

The amount is not a valid number

10004

The amount exceeds the max limit of a single mass pay item ~1

10004

The amount is less than or equal to zero

Developers Guide

February 2007

127

Error Message Reference

MassPay API Errors TABLE B.9 MassPay API Errors Error Code 10004 Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Permission denied User not allowed Restricted account Unconfirmed email Limit Exceeded Limit Exceeded Receive only account Long Message The unique id string length exceeds the maximum limit of 30 characters

10004

The unique id string contains a space as a character

10004

The transaction id is not valid

10007 10301 10303 10304 10305 10306 10307

You do not have permissions to make this API call The user is not allowed to send money through Mass Pay Account is restricted The user account has unconfirmed email The user account needs to have its sending limit removed in order to make a mass payment. The users international account needs to have its sending limit removed in order to make a mass payment The user account is receive only and therefore cannot send payments out

128

February 2007

Developers Guide

Error Message Reference

MassPay API Errors TABLE B.9 MassPay API Errors Error Code 10308 Short Message Masspay server configuration error Masspay server unavailable Unable to create payment Unable to submit payment Masspay server error Masspay Invalid Data Masspay input parse error Masspay Invalid Email Internal Error Insufficient funds Masspay Invalid UserID Long Message There is some configuration error

10309

The mass pay server is unavailable

10310 10311

Unable to create payments for masspay Unable to submit payments for masspay

10312 10313 10314 10317 10320 10321 10327

The masspay server has reported errors The masspay input file includes invalid data The input to the masspay server is incorrect. Please make sure that you are using a correctly formatted input. The masspay input file includes invalid Email Internal Error The account does not have sufficient funds to do this masspay The masspay input file includes invalid UserID

Developers Guide

February 2007

129

Error Message Reference

MassPay API Errors

130

February 2007

Developers Guide

NVP API Web Samples

This chapter describes the NVP API Web Samples which access the NVP API directly. This section includes the following topics: Descriptions of the Samples on page 131 Samples Using Classic ASP on page 136 Samples Using PHP on page 136 Samples Using ColdFusion on page 137

Descriptions of the Samples

The web samples consist of the following: Charging a Credit Card Using Direct Payment on page 131 Accepting PayPal in Express Checkout on page 132 Getting Transaction Details on page 134 Common Files on page 135 The main page of the samples, index.html or Default.htm, contains links to each sample.
N O T E : We describe the code samples for all programming languages in this section. Language

specific filenames are shown as filename.ext. For example, DoDirectPayment.ext stands for DoDirectPayment.java, DoDirectPayment.php, and so forth.

Charging a Credit Card Using Direct Payment

This sample shows how to use Direct Payment to charge a credit card. Access this sample from the following choices displayed on index.html or Default.htm:
DoDirectPayment - Sale Charge a credit card. In the DoDirectPayment request, the PAYMENTACTION parameter is set to Sale.

DoDirectPayment - Authorization Authorize a credit card for later sale. In the DoDirectPayment request, the PAYMENTACTION parameter is set to Authorization.

Developers Guide

February 2007

131

NVP API Web Samples

Descriptions of the Samples

The primary files for this sample are:

TABLE C.1 File DoDirectPayment.ext Direct Payment Files Description This is the main web page for the DoDirectPayment sample. This page allows the user to enter name, address, amount, and credit card information. It also accept input variable paymentType which becomes the value of the PAYMENTACTION parameter. When the user clicks the Submit button, DoDirectPaymentReceipt.ext is called. Called by index.html or Default.htm. Calls DoDirectPaymentReceipt.ext. Submits a credit card transaction to PayPal using a DoDirectPayment request. The code collects transaction parameters from the form displayed by DoDirectPayment.ext then constructs and sends the DoDirectPayment request string to the PayPal server. The paymentType variable becomes the PAYMENTACTION parameter of the request string. After the PayPal server returns the response, the code displays the API request and response in the browser. If the response from PayPal was a success, it displays the response parameters. If the response was an error, it displays the errors. Called by DoDirectPayment.ext. Calls CallerService.ext.

DoDirectPaymentReceipt.ext

Accepting PayPal in Express Checkout

This sample shows how to use Express Checkout to accept payments using PayPal. Access this sample from the following choices displayed on index.html or Default.htm:
ExpressCheckout - Sale Do basic checkout with PayPal. In the SetExpressCheckout request, the PAYMENTACTION parameter is set to Sale. Authorize for a single capture. In the SetExpressCheckout request, the PAYMENTACTION parameter is set to Authorization. Authorize for multiple captures. In the SetExpressCheckout request, the PAYMENTACTION parameter is set to Order.

ExpressCheckout Authorization ExpressCheckout - Order

132

February 2007

Developers Guide

NVP API Web Samples

Descriptions of the Samples

The primary files for this sample are:

TABLE C.2 File SetExpressCheckout.ext Express Checkout Files Description This is the main web page for the Express Checkout sample. The page allows the user to enter amount and currency type. It also accept input variable paymentType which becomes the value of the PAYMENTACTION parameter. When the user clicks the Submit button, ReviewOrder.ext is called. Called by index.html or Default.htm. Calls ReviewOrder.ext. This file is called after the user clicks on a button during the checkout process to use PayPal's Express Checkout. The user logs in to their PayPal account. This file is called twice. On the first pass, the code executes the if statement:
if (! isset ($token))

ReviewOrder.ext

The code collects transaction parameters from the form displayed by SetExpressCheckout.ext then constructs and sends a SetExpressCheckout request string to the PayPal server. The paymentType variable becomes the PAYMENTACTION parameter of the request string. The RETURNURL parameter is set to this file; this is how ReviewOrder.ext is called twice. On the second pass, the code executes the else statement. On the first pass, the buyer completed the authorization in their PayPal account; now the code gets the payer details by sending a GetExpressCheckoutDetails request to the PayPal server. Then the code calls GetExpressCheckoutDetails.ext.
N O T E : Be sure to check the value of PAYPAL_URL. The buyer

is sent to this URL to authorize payment with their PayPal account. For testing purposes, this should be set to the PayPal sandbox. Called by SetExpressCheckout.ext. Calls GetExpressCheckoutDetails.ext, CallerService.ext, and Display.ext. GetExpressCheckoutDetails.ext This functionality is called after the buyer returns from PayPal and has authorized the payment. Displays the payer details returned by the GetExpressCheckoutDetails response and calls DoExpressCheckoutPayment.ext to complete the payment authorization. Called by ReviewOrder.ext. Calls DoExpressCheckoutPayment.ext and CallerService.ext.

Developers Guide

February 2007

133

NVP API Web Samples

Descriptions of the Samples TABLE C.2 File DoExpressCheckoutPayment.ext Express Checkout Files Description This functionality is called to complete the payment with PayPal and display the result to the buyer. The code constructs and sends the DoExpressCheckoutPayment request string to the PayPal server. Called by GetExpressCheckoutDetails.ext and CallerService.ext.

Getting Transaction Details

This sample shows how to use the GetTransactionDetails request. Access this sample from the following choice displayed on index.html or Default.htm:
GetTransactionDetails Gets transaction details for a specific transaction ID. The main page displays a text box where the user enters a transaction ID. When the user clicks the Submit button, the code constructs an NVP API request to GetTransactionDetails and sends it to the PayPal server.

The primary files for this sample are:

TABLE C.3 File GetTransactionDetails.ext Get Transaction Details Files Description This is the main page for GetTransactionDetails sample. This page displays a text box where the user enters a transaction ID and a Submit button that calls TransactionDetails.ext. Calls TransactionDetails.ext. Sends a GetTransactionDetails NVP API request to PayPal. The code retrieves the transaction ID and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API Signature. After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received. Called by GetTransactionDetails.html.

TransactionDetails.ext

134

February 2007

Developers Guide

NVP API Web Samples

Descriptions of the Samples

Common Files
The following files are common to the samples.
TABLE C.4 File index.html Default.htm sdk.css CallerService.ext Common Files Description The main web page with links to each sample. Calls DoDirectPayment.ext, SetExpressCheckout.ext, and GetTransactionDetails.html. Cascading Style Sheet (CSS) used by index.html or Default.htm. This is the configuration file for the samples.This file contains the parameters needed to make an API call. The samples come with an API Signature for making API calls to the PayPal sandbox. The API Signature is described in Table C.5, Called by TransactionDetails.ext, ReviewOrder.ext, DoDirectPaymentReceipt.ext, and Display.ext. Display.ext Displays request and response parameters. If there is an error, displays request and error parameters. Called by DoDirectPaymentReceipt.ext, TransactionDetails.ext, and DoExpressCheckoutPayment.ext.

Details of Sample API Signature.

API Signature

The API Signature that comes with the samples belongs to the following user:
TABLE C.5 Details of Sample API Signature
sdk-three_api1.sdk.com QFZCWN5HZM8VBG7Q A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

API Username API Password API Signature

IMPO RTANT: You must protect the API Signature values in your implementation. Consider

storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.

Developers Guide

February 2007

135

NVP API Web Samples

Samples Using Classic ASP

Samples Using Classic ASP

This section contains information for configuring and running the NVP API Web Samples Using Classic ASP.

Required Software
No additional software is required.

Installing the Samples

The samples must be installed in IIS. The samples require IIS version 5.1 or above. Create a virtual directory named PayPalClassicAspNvpSamples in IIS that points to Samples_Root.

Running the Samples

First, make sure that you have installed the required software and the samples. You can run the samples by entering the following address in a web browser:
http://name_of_Server:port/PayPalClassicAspNvpSamples/Default.htm

Samples Using PHP

This section contains information for configuring and running the NVP API Web Samples Using PHP.

Required Software
The following software is required:
TABLE C.6 Software PHP with CURL extension enabled Apache HTTP Server Required Software Version 4.4.2 or greater 1.3.17 or greater Download Location http://www.php.net/downloads.php http://httpd.apache.org/

You must install and configure PHP with the Apache HTTP Server.

136

February 2007

Developers Guide

NVP API Web Samples

Samples Using ColdFusion

Installing the Samples

Copy the sample folder, php_nvp_samples, to the docroot of the Apache HTTP Server. By default docroot is in datadir/htdocs.

Running the Samples

First, make sure that you have installed the required software and the samples. You can run the samples by entering the following address in a web browser:
http://name_of_Apache_HTTP_Server:port/php_nvp_samples/index.html

Samples Using ColdFusion

This section contains information for configuring and running the NVP API Web Samples Using ColdFusion.

Required Software
The following software is required:
TABLE C.7 Standard
ColdFusion

Supported Standards Version

7.x MX

Download Location http://www.adobe.com/products/coldfusion/

Installing the Samples

N O T E : The

samples assume that ColdFusion is running on Microsoft Windows.

1. Copy the sample folder to your ColdFusion application server web document root, ColdFusionMX7_root_directory\wwwroot.

Running the Samples

First, make sure that you have installed the required software and the samples. You can run the samples by entering the following address in a web browser:
http://name_of_Server:port/cf_nvp_samples/index.html

Developers Guide

February 2007

137

NVP API Web Samples

Samples Using ColdFusion

138

February 2007

Developers Guide

The Java SDK

This section describes how to use the Java SDK for the NVP API and includes the following topics: Installing the Java SDK on page 139 Profiles on page 141 Sample Applications on page 143

Installing the Java SDK

This section details the software and hardware supported and required by the PayPal SDK, installation, and post-installation tasks.

Supported Standards
The PayPal SDK has been verified to work with the following standards.
TABLE D.1 Standard Java Runtime Environment Supported Human Languages Supported Standards Version 1.4.2 or greater

The PayPal SDK is available in U.S. English.

SDK Version Number

This guide describes PayPal Java SDK version 5.0.

Recommended Hardware Configuration

The minimum hardware requirements for using the PayPal SDK in development and test are listed below. Production systems might require more capacity, depending on their expected load.
TABLE D.2 Component RAM Recommended Hardware Configuration Minimum Capacity 256 MB

Developers Guide

February 2007

139

The Java SDK

Installing the Java SDK TABLE D.2 Component CPU Disk space Recommended Hardware Configuration Minimum Capacity Pentium 1 GHz 50 MB

Download and Unzip the SDK

The latest version of the PayPal SDK is available at https://www.paypal.com/sdk. 1. Download the zipfile distribution. 2. Unzip the zipfile to any directory of you choose.
N O T E : We

refer to the directory in which you choose to extract the SDK as: SDK_root.

Post-installation Set-up
This section details steps you must take before you start using the PayPal SDK.
Adding SDK JAR Files to CLASSPATH

Before developing applications with the Java SDK, be sure to add the SDK JAR files in SDK_root/lib to your CLASSPATH environment variable.
SDK Directories and Optional Configurations

The Java SDK components are organized into different subdirectories, as shown in Table D.3, PayPal SDK for Java: Directories and Contents.
TABLE D.3 Directory cert docs lib licenses samples src tools PayPal SDK for Java: Directories and Contents Descrption PayPal public certificates for Live PayPal and PayPal Sandbox SDK API documentation SDK libraries License files Example code that use the SDK. SDK source code Third-party applications

140

February 2007

Developers Guide

The Java SDK

Complete SDK and API Class Documentation

Complete SDK and API Class Documentation

Complete Javadoc documentation for all PayPal SDK interfaces, classes, methods, structures, and data types are included with the SDK distribution. To view the documentation, open the following file with your web browser:
SDK_root/docs/index.html

SDK Logging
The PayPal SDK uses log4j public domain logging software. For complete information, see the documentation at http://logging.apache.org/log4j/docs/
Setting Log Levels

Set the value of the level element in SDK_root/lib/log4j.properties.

TABLE D.4 Level ALL ERROR INFO DEBUG SDK Logging Levels Description Same as DEBUG Log only severe errors Date/time of API operation, operation name, elapsed time, success or failure indication Full text of requests and responses and other debugging messages. Because DEBUG logging can degrade the performance of the SDK, be careful about using it for day-today operation.
N O T E : Because requests and responses are asynchronous, the recording of requests and

responses might appear out of sequence in the log file. Logfile Backup

The default size of the SDK log is 10MB. You can set this size larger or smaller with the value of param name=MaxFileSize in log4j.properties. When the log file reaches its maximum size, a backup file is created and a new logfile begins.

Profiles
Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes: A PayPal API username and password. If you are using API Certificates, the path to the API certificate in P12 format and the private key password to that certificate.

Developers Guide

February 2007

141

The Java SDK

Profiles

If you are using API Signatures, the signature string. The optional name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject The PayPal environment for processing API calls: live or sandbox. An EWP profile is associated with EWP Services includes: The path to the merchants local copy of that public certificate The private key password for that public certificate The path to a merchants private key file for digitally signing data The URL to which the button form POSTs The optional URL of a payment button image. The default is PayPals standard Buy Now button. For more information about how EWP works, see the Website Payments Standard Integration Guide, available at https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf.

Overview to Profile-related Classes

The primary interfaces and classes for SDK profiles are described in Table D.5, Interface and Classes for SDK Profiles, on page 142
TABLE D.5 Interface and Classes for SDK Profiles Descriptions This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs. Developers must create an instance of APIProfile for each account that accesses the APIs. For single-merchant developers, only a single APIProfile instance is needed. PayPal provides two implementation classes suitable for the needs of most SDK developers: CertificateAPIProfile and SignatureAPIProfile. However, you are free to write a custom implementation if you need additional functionality the default classes do not offer. This interface defines the basic information that PayPal needs to know about a user of PayPals Encrypted Website Payments (EWP) service. Developers must create an instance of EWPProfile for each account that generates the encrypted button code; for single-merchant users this will just be a single instance). PayPal provides a basic implementation class called DefaultEWPProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need functionality the default class does not offer.

Interface/Class APIProfile interface

EWPProfile interface

142

February 2007

Developers Guide

The Java SDK

Sample Applications TABLE D.5 Interface and Classes for SDK Profiles Descriptions This class creates both APIProfile and EWPProfile objects. It contains static methods that handle the instantiation and construction of profile objects. This data class represents all profiles the SDK knows about. It contains two collections, one for APIProfiles and one for EWPProfiles. This class is provided to ProfileHandler to save profile data and returned from ProfileHandler to retrieve profile data.

Interface/Class ProfileFactory class

Profiles class

Sample Application s
The PayPal SDK includes sample applications in the SDK_root/samples directory. Each subdirectory comes with a README file that explains how to set up the application.
TABLE D.6 PayPal SDK for Java: Sample Code in SDK_root/samples Descrption API certificates used by the sample applications JavaScript implementation for Apache Tomcat of the following PayPal APIs: Direct Payment for final sale and for authorization Express Checkout for final sale and for authorization TransactionSearch GetTransactionDetails RefundTransaction DoCapture DoVoid Native Java application to call TransactionSearch, GetTransactionDetails, and DirectPayment

Subdirectory Cert JSP

SampleApp

Sample API User with API Signature

The samples come with an API Signature for use with the SDK and the PayPal Sandbox. This API Signature belongs to the following user:
TABLE D.7 API Username API Password API Signature Details of the SDK Sample API Signature sdk-three_api1.sdk.com QFZCWN5HZM8VBG7Q A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

Developers Guide

February 2007

143

The Java SDK

Sample Applications
IMPO RTANT: You must protect the API Signature values in your implementation. Consider

storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.

Sample API User with API Certificate

The samples come with an API digital certificate for use with the SDK and the PayPal Sandbox. This certificate belongs to the following user:
TABLE D.8 Details of the SDK Sample API Certificate
SDK_root\samples\Certs\sdk-seller.p12

Location of Certificate API Username API Password PKCS12 Passphrase

IMPO RTANT: You

sdk-seller_api1.sdk.com 12345678 password

must protect the API Certificate values in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.

144

February 2007

Developers Guide

The ASP.NET SDK

This section describes how to use the ASP.NET SDK for the NVP API and includes the following topics: Installing the ASP.NET SDK on page 145 Profiles on page 149 Sample Applications on page 150

Installing the ASP.NET SDK

This section details the software and hardware supported and required by the PayPal SDK, installation, and post-installation tasks.

Supported Standards
The PayPal SDK has been verified to work with the following standards.
TABLE E.1 Standard Microsoft .NET Framework Supported Human Languages Supported Standards Version 1.1, Service Pack 1

The PayPal SDK is available in U.S. English.

SDK Version Number

This guide describes PayPal ASP.NET SDK version 5.0.

Minimum Hardware Requirements

The following table lists the minimum hardware requirements for using the PayPal SDK in development and test. Production systems might require more capacity, depending on their expected load.
TABLE E.2 Component RAM CPU Minimum System Hardware Requirements Minimum Capacity 256 MB Pentium 1 GHz

Developers Guide

February 2007

145

The ASP.NET SDK

Installing the ASP.NET SDK TABLE E.2 Component Disk space Minimum System Hardware Requirements Minimum Capacity 50 MB

Required: Microsoft .NET Framework 1.1, Service Pack 1

IMPO RTANT: The

PayPal SDK requires Service Pack 1 for Microsoft .NET Framework 1.1. You can get Service Pack 1 from the Microsoft web site.

Downloading and Installing the SDK

The latest version of the PayPal SDK is available at https://www.paypal.com/sdk. You can download either a self-extracting installation program or a zipfile distribution. The installation is straightforward and requires no special instruction. You have the option to install the SDK source, if you like.

Post-installation Set-up
This section details steps to take before you start using the PayPal SDK.
Referencing the SDK DLLs

Before developing applications with the SDK, be sure to add references in your ASP.NET projects to the SDK dynamic load libraries (DLLs) in SDK_root\bin.
Installing the Samples

The SDK comes with sample applications for your study and use. These samples can be installed in Microsoft Internet Information Server (IIS). For more information about the samples, see Sample Applications on page 150. For more information about installing in IIS, see Installing the Samples in IIS on page 152.
SDK Directories and Optional Configurations

The SDK components are organized into different subdirectories, as shown in Table E.3, PayPal SDK Directories and Contents.
TABLE E.3 Directory bin docs PayPal SDK Directories and Contents Descrption Compiled SDK DLLs Ndoc class documentation and SDK guide samples\ASPNET Example code that use the SDK, in subdirectories

146

February 2007

Developers Guide

The ASP.NET SDK

Installing the ASP.NET SDK TABLE E.3 Directory samples\cert src PayPal SDK Directories and Contents Descrption sdk-seller.p12 API certificate for API user sdkseller_api1.sdk.com Visual Studio project files and SDK source files. This folder is present only if you installed the source of the SDK.

Optional Custom Configurations in Web.config

You can add optional custom settings to the Web.config file.
Adding PayPal Settings

First, add a <section name=paypal> tag, as shown below. The section must be enclosed in <configSections> that comes immediately after the top-level <configuration> tag.
<configuration> <configSections> <section name=paypal type=com.paypal.sdk.core.ConfigSectionHandler, paypal_base/> <configSections>

The optional custom settings themselves are in a <paypal> block later in the file:
<paypal> ... custom settings ... </paypal>

SDK Logging
The PayPal SDK uses log4net public domain logging software. For information about log4net, see the log4net documentation at http://logging.apache.org/log4net/release/manual/introduction.html. This section describes SDK logging levels, in which configuration files you set the desired level, and request logging.
Log Levels

The SDK varies the amount of detail it records according to four logging levels.
TABLE E.4 Level ALL ERROR SDK Logging Levels Description Same as DEBUG Log only severe errors

Developers Guide

February 2007

147

The ASP.NET SDK

Installing the ASP.NET SDK TABLE E.4 Level INFO DEBUG SDK Logging Levels Description Date/time of API operation, operation name, elapsed time, success or failure indication Full text of requests and responses and other debugging messages. DEBUG logging can degrade the performance of the SDK. Be careful about using it for day-to-day operation.
N O T E : Because requests and responses are asynchronous, the recording of requests and

responses might appear out of sequence in the log file. Setting SDK Log Levels

To enable logging for your SDK-based web applications, add the following lines inside the <configuration> block of the Web.config file. You can copy these lines from the SDK_root\samples\ASPNET\Web.config file. You might want to change the value of the file element to write log records to a location you prefer. Set the value of the level element to the desired detail described in Table E.4, SDK Logging Levels.
<configSections> <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/> </configSections> <log4net> <appender name="PAYPALLOGFILE" type="log4net.Appender.RollingFileAppender"> <file value="logs/paypal.sdk.log" /> <appendToFile value="true" /> <encoding value="UTF-8" /> <rollingStyle value="5" /> <maxSizeRollBackups value="10" /> <maximumFileSize value="10MB" /> <staticLogFileName value="true" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{dd MMM yyyy HH:mm:ss} %-5p [%C{1}] %m%n" /> </layout> </appender> <logger name="com.paypal.sdk"> <level value="ALL" /> <appender-ref ref="PAYPALLOGFILE" /> </logger> </log4net>

148

February 2007

Developers Guide

The ASP.NET SDK

Complete SDK and API Class Documentation

Enabling Proxy Support

If your application is behind a proxy server, you must enable proxy support in the Web.config file. For details on how to use the system.net element in the Web.config file, please refer to Configuring Internet Applications in the MSDN Library.

Uninstalling the SDK

To uninstall the SDK, use the Microsoft Windows control panel Add/Remove Programs.

Complete SDK and API Class Documentation

Complete Microsoft .NET Ndoc documentation for all PayPal SDK interfaces, classes, methods, structures, and data types are included with the SDK distribution. To view the documentation, open the following file with your web browser:
SDK_root/docs/PayPalBaseAPI.chm

Profiles
Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes: A PayPal API username and password. If you are using API Certificates, the path to the API certificate in P12 format and the private key password to that certificate. If you are using API Signatures, the signature string. The optional name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject. The PayPal environment for processing API calls: live or sandbox. An EWP profile is associated with EWP Services includes: The path to the merchants local copy of that public certificate The private key password for that public certificate The path to a merchants private key file for digitally signing data The URL to which the button form POSTs The optional URL of a payment button image. The default is PayPals standard Buy Now button.

Developers Guide

February 2007

149

The ASP.NET SDK

Sample Applications

For more information about how EWP works, see the Website Payments Standard Integration Guide, available at https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf.

Overview to Profile-related Classes

The primary interfaces and classes for SDK profiles are described in Table E.5, Summary of ASP.NET SDK Profile-related Interfaces and Classes.

TABLE E.5

Summary of ASP.NET SDK Profile-related Interfaces and Classes Description This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs. Developers must create an instance of IAPIProfile for each account that accesses the APIs. For single-merchant developers, only a single IAPIProfile instance is needed. PayPal provides a default implementation class called DefaultAPIProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need additional functionality the default class does not offer. This class creates the IAPIProfile object. It contains static methods that handle the instantiation and construction of profile objects. This interface defines the basic information that PayPal needs to know about a user of PayPals Encrypted Website Payments (EWP) service. Developers must create an instance of EWPProfile for each account that generates the encrypted button code; for single-merchant users this will just be a single instance). PayPal provides a basic implementation class called DefaultEWPProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need functionality the default class does not offer.

Interface/Class IAPIProfile interface

ProfileFactory class EWPProfile interface

Sample Applications
The PayPal SDK includes sample applications in the SDK_root\samples\ASPNET folder. The samples\ASPNET folder is divided into subfolders by products.
TABLE E.6 Samples by Product Products DoCapture

Subfolder in SDK_Root\samples\ASPNET admin

150

February 2007

Developers Guide

The ASP.NET SDK

Sample API User with API Signature TABLE E.6 Samples by Product Products DoVoid GetTransactionDetails MassPay RefundTransaction TransactionSearch wppro Express Checkout Final Sale Authorization Direct Payment API Final Sale Authorization

Subfolder in SDK_Root\samples\ASPNET

Sample API User with API Signature

The samples come with an API Signature for use with the SDK and the PayPal Sandbox. This API Signature belongs to the following user:
TABLE E.7 API Username API Password API Signature Details of the SDK Sample API Signature sdk-three_api1.sdk.com QFZCWN5HZM8VBG7Q A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

IMPO RTANT: You must protect the API Signature values in your implementation. Consider

storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.

Developers Guide

February 2007

151

The ASP.NET SDK

Sample API User with API Certificate

Sample API User with API Certificate

The samples come with an API digital certificate for use with the SDK and the PayPal Sandbox. This certificate belongs to the following user:
TABLE E.8 Details of the SDK Sample API Certificate
SDK_root\samples\Certs\sdk-seller.p12

Location of Certificate API Username API Password PKCS12 Passphrase

IMPO RTANT: You

sdk-seller_api1.sdk.com 12345678 password

must protect the API Certificate values in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.

Installing the Samples in IIS

N O T E : Be

sure that you are logged in as an administrator, that IIS running, and that WinHttpCertCfg.exe is in your PATH.

To install the samples in Microsoft IIS: 1. Run SDK_root\samples\ASPNET\InstallSample.bat. 2. To enable logging, change the permissions on the localComputerName\ASPNET folder to Full Control. InstallSample.bat does the following: Creates a virtual directory named PaypalASPNETSample in IIS that points to SDK_root\samples\ASPNET. Loads the sample API certificate SDK_root\samples\Certs\sdk-seller.p12 into the Microsoft Windows system store. Uses the WinHttpCertCfg.exe command to grant unlimited access for account Everyone to that certificate.

152

February 2007

Developers Guide

The ASP.NET SDK

Running the Samples

Running the Samples

To run the samples, in Internet Explorer, open the following URL: http://localhost/PaypalASPNETSamples.

Developers Guide

February 2007

153

The ASP.NET SDK

Running the Samples

154

February 2007

Developers Guide

F
Country

Country Codes

N O T E : This

table lists country codes defined by ISO 3166-1.

Country

Code

BELARUS Table 1: Country Codes

Code

BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI KH CM CA CV KY

BELGIUM BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZEGOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS

AFGHANISTAN LAND ISLANDS ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AND BARBUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS

AF AX AL DZ AS AD AO AI AQ AG AR AM AW AU AT AZ BS BH BD BB

155

Country Codes

Country

Code

Country

Code

CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS (KEELING) ISLANDS COLOMBIA COMOROS CONGO CONGO, THE DEMOCRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D'IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR

CF TD CL CN CX CC CO KM CG CD

EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS (MALVINAS) FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY

GQ ER EE ET FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GT GG

CK CR CI HR CU CY CZ DK DJ DM DO EC EG SV

156

Country

Code

Country

Code

GUINEA GUINEA-BISSAU GUYANA HAITI HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE (VATICAN CITY STATE) HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN, ISLAMIC REPUBLIC OF IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI

GN GW GY HT HM VA HN HK HU IS IN ID IR IQ IE IM IL IT JM JP JE JO KZ KE KI

KOREA, REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE'S DEMOCRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO

KR KW KG LA LV LB LS LR LY LI LT LU MO MK

MG MW MY MV ML MT MH MQ MR MU YT MX

KOREA, DEMOCRATIC KP PEOPLE'S REPUBLIC OF

Country Codes

Country

Code

Country

Code

MICRONESIA, FEDERATED STATES OF MOLDOVA, REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN

FM MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE NG NU NF MP NO OM PK

PALAU PALESTINIAN TERRITORY, OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO

PW PS PA PG PY PE PH PN PL PT PR QA RE RO RU RW SH KN LC PM VC WS SM

158

Country

Code

Country

Code

SAO TOME AND PRINCIPE SAUDI ARABIA SENEGAL SERBIA AND MONTENEGRO SEYCHELLES SIERRA LEONE SINGAPORE SLOVAKIA SLOVENIA SOLOMON ISLANDS SOMALIA SOUTH AFRICA SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS SPAIN SRI LANKA SUDAN SURINAME SVALBARD AND JAN MAYEN SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUBLIC TAIWAN, PROVINCE OF CHINA TAJIKISTAN

ST SA SN CS SC SL SG SK SI SB SO ZA GS

TANZANIA, UNITED REPUBLIC OF THAILAND TIMOR-LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU UGANDA UKRAINE

TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN

ES LK SD SR SJ SZ SE CH SY TW TJ

UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM

VIRGIN ISLANDS, BRIT- VG ISH

Country Codes

Country

Code

VIRGIN ISLANDS, U.S. WALLIS AND FUTUNA WESTERN SAHARA YEMEN ZAMBIA ZIMBABWE

VI WF EH YE ZM ZW

160

Index

A
ACCT 19, 45, 73 ACK 16, 17, 85 Add/Remove Programs 149 Address Verification System 19 ADDRESSOWNER 77 ADDRESSSTATUS 60, 78 ADDROVERRIDE 56 AMT 40 DoAuthorization request 70 DoAuthorization response 70 DoCapture 67 DoCapture response 68 DoDirectPayment 45 DoExpressCheckoutPayment 61 DoExpressCheckoutPayment response 65 DoReauthorization 71 GetTransactionDetails response 79 refunding 40 RefundTransaction 72 TransactionSearch 74 API Certificate 16 API Credentials 14 API Password 143, 151 API Signature 16 api.sandbox.paypal.com 16 api-3t.paypal.com 16 api-3t.sandbox.paypal.com 16 APIProfile interface 142 AUCTIONITEMNUMBER 74 AUD 43 Australian Dollar 43 AUTHORIZATIONID 37, 67, 68 DoReauthorization request 71 DoReauthorization response 72 DoVoid 71 DoVoid response 71 AuthorizationID 64 AVS 19

B
BUILD 16, 17, 85 BUSINESS 60 BUTTONSOURCE 47, 62 BUYERID 82

C
CAD 43 Canadian Dollar 43 Canceled-Reversal 69, 80 Capturing A Partial Amount of an Authorization 38 Capturing the Full Amount of an Authorization 37 Card Verification Value. See CVV2. certificate sample 144, 152 CertificateAPIProfile class 142 CHF 43 chm documentation 149 CITY 45 CLASSPATH 140 CLOSINGDATE 82 ColdFusion 137 Completed 69, 80 COMPLETETYPE 37, 38, 67 CORRELATIONID 16, 17, 85 COUNTRYCODE 46, 59 CREDITCARDTYPE 19, 45 currency codes 43 CURRENCYCODE 46, 54, 62, 65, 67, 70, 71, 83 CUSTOM 47, 55, 60, 61, 81 CVV2 19, 48 Czech Koruna 43 CZK 43

D
Danish Krone 43 DefaultAPIProfile class 150 Denied 69, 80 Denied (transaction status) 75

Name-Value Pair API Developer Guide and Reference

February 2007

161

Index

DESC 47, 55, 61 digital certificate sample 144, 152 Direct Payment 143 Direct Payment API 151 DKK 43 DoAuthorization 37 DoCapture 20, 37, 143, 150 documentation 146 DoDirectPayment 19 DoReauthorization 37 DoVoid 37, 143, 151

HDRBACKCOLOR 57 HDRBORDERCOLOR 57 HDRIMG 57 HKD 44 Hong Kong Dollar 44 HUF 44 Hungarian Forint 44

I
IAPIProfile interface 150 IIS 152 Including a Note with the Refund 40 InstallSample.bat 152 INVNUM 47, 55, 60, 61, 67, 73, 81 IPADDRESS 19, 44 ITEMAMT 21, 34, 62

E
EFFECTIVEDATE 82 EMAIL 48, 55, 59, 77 TransactionSearch 73 EMAILSUBJECT 83 ENDDATE 73 EUR 43 Euro 43 EWP profile defined 142, 149 EWPProfile interface 142, 150 EXCHANGERATE 65, 69, 79 EXPDATE 19, 45 Expired 69, 80 Express Checkout 143, 151

J
Japanese Yen 44 Java Development Kit 1.4 139 Javadoc documentation for PayPal SDK 141 JPY 44 JSP 143

K
Koruna 43 Krona 44 Krone 43

F
FEEAMT 65, 68, 79 FEEREFUNDAMT 72 FIRSTNAME 19, 45, 59, 74, 77 Forint 44

L
L 63 L_AMTn 21, 33, 48, 63, 76, 81, 83 L_DESCn 81 L_EMAILn 75, 83 L_FEEAMTn 76 L_NAMEn 21, 33, 47, 62, 76 L_NETAMTn 76 L_NOTEn 83 L_NUMBERn 21, 33, 47, 63, 81 L_OPTIONSn 82 L_QTY 63 L_QTYn 21, 33, 47, 63, 81 L_RECEIVERIDn 83

G
GBP 43 Get Transaction Details 151 GetTransactionDetails 42, 143 GROSSREFUNDAMT 72

H
HANDLINGAMT 21, 34, 46, 62

162

February 2007

Name-Value Pair API Developer Guide and Reference

Index

L_STATUSn 76 L_TAXAMTn 21, 33, 48, 63 L_TIMESTAMPn 75 L_TIMEZONEn 75 L_TRANSACTIONIDn 76 L_TYPEn 75 L_UNIQUEIDn 83 LASTNAME 19, 45, 59, 74, 77 LOCALECODE 56 log4j.properties 141 log4net 147 logging levels 147

NVP, defined 13 NZD 44

O
ORDERTIME 65, 68, 79

P
PAGESTYLE 56 PARENTTRANSACTIONID 68, 78 PASSWORD 82 PAYERBUSINESS 77 PAYERID 59, 61, 77 PAYERSTATUS 59, 77 PAYFLOWCOLOR 57 PAYMENTACTION 19, 44, 55, 61 PaymentAction 64 must be Authorization if CreditCardType is Switch or Solo 45 PAYMENTSTATUS 66, 69, 80 PAYMENTTYPE 65, 68, 79 paypal tag in Web.Config 147 PayPal-supported currencies 43 Pending 69, 80 Pending (transaction status) 75 PENDINGREASON 66, 80 PendingReason 69, 80 PERIOD 82 PHONENUM 48, 58, 60 PLN 44 Polish Zloty 44 Pound Sterling 43 Processed 69, 80 Processing (transaction status) 75 ProfileFactory class 143, 150 Profiles class 143 PWD 14

M
MassPay 151 MAXAMT 54 METHOD 14 DoAuthorization 69 DoCapture 67 DoDirectPayment 44 DoExpressCheckoutPayment 61 DoReauthorization 71 DoVoid 70 GetExpressCheckoutDetails 58 GetTransactionDetails 76 MassPay 83 RefundTransaction 72 TransactionSearch 73 Microsoft .NET 1.1 145 MIDDLENAME 59, 74, 77 MULTIITEM 82

N
NETREFUNDAMT 72 New Zealand Dollar 44 NOK 44 Norwegian Krone 44 NOSHIPPING 56 NotComplete 38 NOTE DoCapture 67 DoVoid request 71 GetTransactionDetails response 81 RefundTransaction 72 NOTIFYURL 46, 47, 62

R
REASONCODE 66, 81 ReasonCode 69, 80 REATTEMPT 82 RECEIPTID 68, 73, 78 RECEIVER 73 RECEIVERBUSINESS 77

Name-Value Pair API Developer Guide and Reference

February 2007

163

Index

RECEIVEREMAIL 77 RECEIVERID 77 RECEIVERTYPE 83 RECURRENCES 82 RECURRING 82 Refunded 69, 80 Refunding A Partial Amount 40 Refunding The Full Amount of a Transaction 40 RefundTransaction 40, 143, 151 REFUNDTRANSACTIONID 72 REFUNDTYPE 40, 72 REQCONFIRMSHIPPING 55 RETRYTIME 82 Reversed 69, 80 Reversed (transaction status) 75

src 147 STARTDATE 41, 73 STATE 45 STATUS 75 STREET 45 STREET2 48 SUBJECT 14 SUBSCRIPTIONAMT 82 SUBSCRIPTIONDATE 82 SUBSCRIPTIONID 82 Success (transaction status) 75 successResponseFields, defined 16 SUFFIX 59, 74, 77 Swedish Krona 44 Swiss Franc 43 system store 152

S
SALESTAX 81 SALUTATION 59, 74, 77 Sample API Certificate 144, 152 sample API credentials 143, 144, 151, 152 Sample API Signature 143, 151 sample application 150 SampleApp 143 Sandbox 16 sdk-seller.p12 144, 147, 152 sdk-seller_api1.sdk.com 143, 144, 151, 152 sdk-three_api1.sdk.com 143, 151 SEK 44 Service Pack 1 for Microsoft .NET Framework 1.1 146 SETTLEAMT 65, 68, 79 SGD 44 SHIPPINGAMT 21, 34, 46, 62 SHIPTOCITY 20, 49, 57, 60, 63, 78 SHIPTOCOUNTRY 20 SHIPTOCOUNTRYCODE 49, 57, 60, 64, 77 SHIPTONAME 20, 49, 57, 60, 63, 78 SHIPTOPHONENUM 20, 49, 64, 78 SHIPTOSTATE 49, 57, 60, 64, 78 SHIPTOSTREET 20, 49, 57, 60, 63, 78 SHIPTOSTREET2 20, 49, 58, 60, 64, 78 SHIPTOZIP 20, 49, 57, 60, 64, 78 SIGNATURE 14 SignatureAPIProfile class 142 Singapore Dollar 44 source files 147

T
TAXAMT 21, 34, 47, 62, 65, 68, 79 TOKEN 64 DoExpressCheckoutPayment 61 GetExpressCheckoutDetails 59 GetExpressCheckoutDetails response 59 SetExpressCheckout 56 SetExpressCheckout response 58 Token 24, 58 token 24, 58 TRANSACTIONCLASS 74 TRANSACTIONENTITY 70 TRANSACTIONID 37 DoAuthorization 70 DoAuthorization response 70 DoCapture response 68 DoExpressCheckoutPayment response 64 GetTransactionDetails 76 GetTransactionDetails response 78 RefundTransaction 72 TransactionSearch 73 TransactionSearch 41, 143, 151 TRANSACTIONSTATUS 75 TRANSACTIONTYPE 64, 68, 79 TransactionType 66, 81

U
U.S. Dollar 44

164

February 2007

Name-Value Pair API Developer Guide and Reference

Index

UrlDecode 17 urldecode() 17 URLDecoder 17 URLDecodeurlEncodedString 17 URLEncode 15 UrlEncode 15 urlencode() 15 URL-encoded string 13 URLEncodedFormatstring 15 URLEncoder.encode 15 URL-encoding 15, 16, 43 methods 15 USD 44 USER 14 USERNAME 82 UTC/GMT 75

V
VERSION 16, 17, 85 VERSION=2.3 13, 14 Voided 69, 80

W
Web.config 147, 148 paypal tag 147 Website Payments Standard Integration Guide 142, 150 WinHttpCertCfg.exe 152 WinHttpPCertCfg.exe 152

Y
Yen 44

Z
ZIP 46 Zloty 44

Name-Value Pair API Developer Guide and Reference

February 2007

165