PayPal Name-Value Pair API - 2007 Reference Manual

Download

Name-Value Pair API Reference for Germany

For Professional Use in Germany Only Currently only available in English.

A usage Professional en Allemagne uniquement Disponible en Anglais uniquement pour l’instant.

Last updated: April 2007

PayPal Name-Value Pair API Developer Guide and Reference

Document Number: 100018.en_DE-20070410

© 2007 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. 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.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Introducing the PayPal NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Integrating with the PayPal API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Basic Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Create a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Get API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Create and Post the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Interpret the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Taking Your Application Live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Set Up a PayPal Business Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Set Up API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Modify Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Request-Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Posting Using HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 2 Accepting PayPal in Express Checkout . . . . . . . . . . .17

Basic Checkout with PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

1. Starting the Checkout Using SetExpressCheckout . . . . . . . . . . . . . . . . . . 18

2. Redirecting the Customer’s Browser to PayPal Login Page . . . . . . . . . . . . . 18

3. Getting Payer Details Using GetExpressCheckoutDetails . . . . . . . . . . . . . . 19

4. Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . 19

Support giropay and electronic funds transfer . . . . . . . . . . . . . . . . . . . . . . . . 20

Initiate the Flow with SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . 20

Redirecting the Customer to PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Name-Value Pair API Developer Guide and Reference April 2007 3

Contents

Completing the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Controlling the Shipping Address Using SetExpressCheckout . . . . . . . . . . . . . . . 21

Suppressing Display of Shipping Address on PayPal . . . . . . . . . . . . . . . . . . 21

Overriding the Shipping Address Stored on PayPal . . . . . . . . . . . . . . . . . . . 22

Changing the Language on the PayPal Login Page Using SetExpressCheckout . . . . . . 23

Changing the Logo on the PayPal Pages Using SetExpressCheckout . . . . . . . . . . . 23

Specifying a Custom Payment Page Style. . . . . . . . . . . . . . . . . . . . . . . . 23

Specifying Logo and Color Settings Individually . . . . . . . . . . . . . . . . . . . . . 24

Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails. . . . . . . . 24

Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . 25

Changing the URL for IPN Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 25

Including Line Item Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 26

Including Subtotals Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . 27

Updating Order Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . 27

Updating the Shipping Address Using DoExpressCheckoutPayment . . . . . . . . . . . . 28

Chapter 3 Back-Office Administration . . . . . . . . . . . . . . . . .31

Refunding Using RefundTransaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Full Refund. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Partial Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Including a Note with the Refund . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Searching for Transactions Using TransactionSearch . . . . . . . . . . . . . . . . . . . . 32

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

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

General Characteristics of Requests and Parameters . . . . . . . . . . . . . . . . . . . . 35

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Multi-Value Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

PayPal-Supported Transactional Currencies . . . . . . . . . . . . . . . . . . . . . . 35

Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

SetExpressCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

SetExpressCheckout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

GetExpressCheckoutDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . 41

GetExpressCheckoutDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . 42

DoExpressCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . 43

DoExpressCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . 47

4 April 2007 Name-Value Pair API Developer Guide and Reference

Contents

RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix B Error Message Reference . . . . . . . . . . . . . . . . . . 63

Error Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Express Checkout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Appendix C NVP API Web Samples. . . . . . . . . . . . . . . . . . . . 95

Descriptions of the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Accepting PayPal in Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . 95

Getting Transaction Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Common Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Samples Using PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Download and Unzip the Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Samples Using Classic ASP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Download and Unzip the Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Samples Using ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Download and Unzip the Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Name-Value Pair API Developer Guide and Reference April 2007 5

Contents

Appendix D The Java SDK . . . . . . . . . . . . . . . . . . . . . . . 103

Installing the Java SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Recommended Hardware Configuration. . . . . . . . . . . . . . . . . . . . . . . . .104

Download and Unzip the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Post-installation Set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . .105

SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . .108

Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . .108

Appendix E The ASP.NET SDK . . . . . . . . . . . . . . . . . . . . . 109

Installing the ASP.NET SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

Downloading and Installing the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Post-installation Set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Optional Custom Configurations in Web.config . . . . . . . . . . . . . . . . . . . . . 111

SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Enabling Proxy Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Uninstalling the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . . 113

Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Installing the Samples in IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Appendix F Country Codes . . . . . . . . . . . . . . . . . . . . . . 117

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

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

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

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.

https://developer.paypal.com/ by entering your email address and

Name-Value Pair API Developer Guide and Reference April 2007 7

Preface

Revision History

Revision history for PayPal Name-Value Pair API Developer Guide and Reference.

TABLE P.1 Revision History

Date Description

April 2007 Revised document to represent specifics for Germany.

February 2007 Bug fixes including updating Line Item Details for Express Checkout APIs, dding

December 2006 Updates for bug fixes.

October 2006 First public release.

SHIPTOCOUNTRYCODE, and adding Switch/Solo codes for AVS and CVV2.

8 April 2007 Name-Value Pair API Developer Guide and Reference

Overview

This chapter describes the PayPal Name-Value Pair (NVP) API at a high level and contains the following sections:

z Introducing the PayPal NVP API z Basic Steps z Taking Your Application Live z Technical Details

Introducing the PayPal NVP API

The PayPal NVP API is a simple programmatic interface that allows you, the merchant, to access PayPal’s business functionality to:

z Accept PayPal in checkout on your website using Express Checkout. z Pay one or more recipients using Mass Payment. z Issue full refunds or multiple partial refunds. z Search transactions using a start date or other criteria. z View details of a specific transaction.

The PayPal NVP API makes it easy to add PayPal to your web application. You construct an NVP string and post it to the PayPal server using HTTPS. PayPal posts back a reponse in NVP format.

Integrating with the PayPal API

You can develop with the PayPal NVP API using two different approaches:

Integrate Directly

You can integrate directly with the PayPal NVP API using the programming language of your choice. This is the most straightforward and flexible approach. You can download web samples that show how to integrate directly using PHP, Classic ASP, and ColdFusion.

For more information, see Appendix C, “NVP API Web Samples.”

Integrate Using an SDK

You can integrate with the NVP API using a software development kit (SDK). SDKs are provided for Java and ASP.NET. The SDKs provide simple functions for integrating with the NVP API.

Name-Value Pair API Developer Guide and Reference April 2007 9

Overview

Basic Steps

For details about the PayPal NVP SDK, see Appendix D, “The Java SDK” or Appendix E,

“The ASP.NET SDK.”

Samples

To help you get started with the PayPal NVP API, samples are provided at https://www.paypal.com/IntegrationCenter/ic_nvp.html. Using the samples, you can send API calls to the PayPal Sandbox test environment.

Basic Steps

This section describes the basic steps for programming with the PayPal NVP API. During application development, your application communicates with the PayPal Sandbox test

environment. The following section, “Taking Your Application Live” on page 11, describes how to move your application to the live PayPal environment.

N OTE: The simplest way to get started is to download and try out the sample applications as

described in “Integrating with the PayPal API” on page 9.

Create a Web Application

Your NVP API implementation usually runs in a web application. You can write your own application or use one of the samples as a starting point.

Get API Credentials

To access the PayPal API, you need API credentials, either an API signature or API certificate, that identify you.

Use the following sample API signature and password in your sample programs that run in the PayPal Sandbox test environment.

N OTE: If you are using the samples, this signature is already in the code.

TABLE 1.1 Details of the Sample API Signature

API username sdk-three_api1.sdk.com

API password QFZCWN5HZM8VBG7Q

API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

10 April 2007 Name-Value Pair API Developer Guide and Reference

Create and Post the Request

Create an NVP request string and post it to PayPal sandbox server. Add code to your web application to do the following tasks:

1. URL-encode the name and value parameters in the request to ensure correct transmission of all characters. This is described in “URL-Encoding” on page 13.

2. Construct the NVP API request string as described in “Request Format” on page 14. The NVP format is described in “NVP Format” on page 12.

3. Post the NVP request to the PayPal Sandbox as described in “Posting Using HTTPS” on

page 16.

Interpret the Response

PayPal processes your request and posts back a reponse in NVP format. Add code to your web application to do the following tasks:

1. Receive the HTTP post response, and extract the NVP string.

Overview

Taking Your Application Live

2. URL-decode the parameter values as described in “URL-Encoding” on page 13.

3. Take appropriate action for successful and failed reponses.

Taking Your Application Live

After you have finished coding and testing your application, deploy your application to the live PayPal server using your PayPal business account and API credentials for that account.

Set Up a PayPal Business Account

When you are ready to deploy your application to the live PayPal server, create a PayPal business account on

Set Up API Credentials

To use the APIs, you need a set of credentials to identify yourself to PayPal. Create an API signature for your business account.

For instructions on setting up API credentials for the business account, go to

https://www.paypal.com/IntegrationCenter/ic_certificate.html.

www.paypal.com.

Name-Value Pair API Developer Guide and Reference April 2007 11

Overview

Technical Details

IMPORTANT: If you are using API signature, you must protect the API signature values in

N OTE: While API signature is recommended, you can also use API certificate.

Modify Your Code

In your application, change the following items from the PayPal Sandbox values to the live PayPal server values:

z The server address in the URL. (See “Posting Using HTTPS” on page 16.) z API credentials you set up in “Set Up API Credentials” on page 11.

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 that executes your ecommerce application can access it.

The sample code does not store these values securely. The sample code

should never be used in production.

Technical Details

This section describes details of the technologies used by the PayPal NVP API.

Request-Response Model

When you use the PayPal NVP API, you post an NVP request to PayPal, and PayPal posts back an NVP response.

URL Format

The request and response are in URL-encoded format, which is defined by the Worldwide Web Consortium (W3C). URL is defined as part of the URI specification. Find out more about URI at

http://www.w3.org/Addressing/.

NVP Format

NVP is a way of specifying names and values in a string. NVP is the informal name for the query in the URI specification. The NVP string is appended to the URL.

An NVP string conforms to the following guidelines:

z The name is separated from the value by an equal sign (=). For example:

FIRSTNAME=Robert

z Name-value pairs are separated by an ampersand (&). For example:

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

z The NVP string is URL-encoded.

12 April 2007 Name-Value Pair API Developer Guide and Reference

Overview

Technical Details

URL-Encoding

The request and response are URL-encoded. URL-encoding ensures that you can transmit special characters, characters that are not allowed in a URL, and characters that have special meaning in a URL, such as the equal sign and ampersand. For example, the following NVP string:

NAME=Robert Moore&COMPANY=R. H. Moore & Associates

is URL-coded as follows:

NAME=Robert+Moore&COMPANY=R%2E+H%2E+Moore+%26+Associates

Use the following methods to URL-encode or URL-decode your NVP strings:

TABLE 1.2 URL-Encoding Methods

Language Method

ASP.NET Encode System.Web.HttpUtility.UrlEncode(buffer,

Encoding.Default)

Decode System.Web.HttpUtility.UrlDecode(buffer,

Encoding.Default)

Classic ASP

Java Encode java.net.URLEncoder.encode

PHP Encode urlencode()

ColdFusion Encode URLEncodedFormatstring [, charset ]

Encode Server.URLEncode

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

Internet.

Decode java.net.URLDecoder.decode

Decode urldecode()

Decode URLDecodeurlEncodedString[, charset])

Name-Value Pair API Developer Guide and Reference April 2007 13

Overview

Technical Details

Request Format

Each NVP request consists of required and optional parameters and their values. Parameter names are not case sensitive. The examples in this document use UPPERCASE for parameter names and divide the parameters into required security parameters and body parameters.

TABLE 1.3 General Format of a Request

Required Security Parameters

Body Parameters

USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature

&SUBJECT=optionalThirdPartyEmailAddress&VERSION=2.3

The following parameters are always required:

USER

PWD

VERSION=2.3

OTE: The examples show the required security parameters like this:

[requiredSecurityParameters]

&METHOD=methodName&otherRequiredAndOptionalParameters

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

Required Security Parameters

The required security parameters are described below. These are your PayPal API credentials.

TABLE 1.4 Required Security Parameters: API Credentials

Parameter Value

USER Required Your PayPal API Username.

PWD Required Your PayPal API Password.

VERSION=2.3 Required Version number of the NVP API service.

SIGNATURE Optional Your PayPal API signature string.

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. Set this parameter only if you are calling an API on a different user’s

behalf.

IMPORTANT: 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 that executes your ecommerce application can access it.

The sample code does not store these values securely. The sample code should never be used in production.

14 April 2007 Name-Value Pair API Developer Guide and Reference

Overview

Technical Details

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 in production:

API Parameters

The request body must contain the name of the API method in the METHOD parameter. In addition, each method has required and optional parameters:

METHOD=methodName&requiredAndOptionalParameters

All API methods and their parameters are detailed in Appendix A, “NVP API Method and

Field Reference.” Examples of use are in Chapter 2, “Accepting PayPal in Express Checkout,”

and Chapter 3, “Back-Office Administration.”

Response Format

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 1.5 General Format of a Successful Response

Success Response Fields

API Response Fields

ACK=Success&TIMESTAMP=date/timeOfResponse

&CORRELATIONID=debuggingToken&VERSION=2.300000

&BUILD=buildNumber

&NAME1=value1&NAME2=value2&NAME3=value3&...

Each response includes the ACK field. If the ACK field’s value is Success or SuccessWithWarning, you should process the 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, such as filling-in a FORM for your user, updating your database, and so on.

The examples show the successful response header fields like this:

[successResponseFields]

Name-Value Pair API Developer Guide and Reference April 2007 15

Overview

Technical Details

Error Responses

If the ACK value is Error or Warning, API response fields are not returned. An error response has the following general format.

TABLE 1.6 Format of an Error Response

Response Fields on 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.”

ACK Parameter Values

The following table lists values for the ACK parameter.

ACK=Error&TIMESTAMP=date/timeOfResponse&

CORRELATIONID=debuggingToken&VERSION=2.300000&

BUILD=buildNumber&L_ERRORCODE0=errorCode&

L_SHORTMESSAGE0=shortMessage

L_LONGMESSAGE0=longMessage

&L_SEVERITYCODE0=severityCode

ABLE 1.7 ACK Parameter Values

Type of Response Value

Successful response Success

SuccessWithWarning

Error response Error

Warning

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

Posting Using HTTPS

Your web application posts the URL-encoded NVP string over an HTTPS connection to one of the PayPal API servers. PayPal provides a live server and a Sandbox server that allows you to process transactions in a test environment.

API Servers for API Signature Security

If you use an API signature, post the request to one of these servers:

Sandbox: https://api-3t.sandbox.paypal.com/nvp

Live: https://api-3t.paypal.com/nvp

API Servers for API Certificate Security

If you use an API certificate, post the request to one of these servers:

Sandbox: https://api.sandbox.paypal.com/nvp

Live: https://api.paypal.com/nvp

16 April 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:

z “Basic Checkout with PayPal” on page 17 z “Controlling the Shipping Address Using SetExpressCheckout” on page 21 z “Changing the Language on the PayPal Login Page Using SetExpressCheckout” on

page 23

z “Changing the Logo on the PayPal Pages Using SetExpressCheckout” on page 23 z “Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails” on page 24 z “Making a Sale Using DoExpressCheckoutPayment” on page 25 z “Changing the URL for IPN Using DoExpressCheckoutPayment” on page 25 z “Including Line Item Details Using DoExpressCheckoutPayment” on page 26 z “Including Subtotals Using DoExpressCheckoutPayment” on page 27 z “Updating Order Details Using DoExpressCheckoutPayment” on page 27 z “Updating the Shipping Address Using DoExpressCheckoutPayment” on page 28

Basic Checkout with PayPal

N OTE: See the Integrationshandbuch Express-Kaufabwicklung 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 Customer’s Browser to PayPal Login Page

3. Getting Payer Details Using GetExpressCheckoutDetails

4. Making a Sale Using DoExpressCheckoutPayment

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.

Name-Value Pair API Developer Guide and Reference April 2007 17

Accepting PayPal in Express Checkout

Basic Checkout with PayPal

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:

z AMT z RETURNURL

z CANCELURL

You are also advised to include the following parameters to ensure a smooth flow in case the funding methods giropay or electronic funds transfer are being used:

z GIROPAYSUCCESSURL z GIROPAYFAILURL z BANKTXNPENDINGURL

EXAMPLE 2.1 Starting the Checkout

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-3DJ78083ES565113B

Request

Response

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html

[successResponseFields]

N OTE: 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 Customer’s 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 customer’s browser to it:

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse

For redirecting the customer’s 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.

18 April 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:

z TOKEN: use the value from SetExpressCheckout response

The response contains this TOKEN and customer details.

EXAMPLE 2.2 Getting Payer Details

&METHOD=GetExpressCheckoutDetails&

&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&

Request

Response

[requiredSecurityParameters]

TOKEN=EC-3DJ78083ES565113B

[successResponseFields]

PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US& SHIPTOZIP=99221&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmed

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 must always include the following parameters in DoExpressCheckoutPayment

request:

z TOKEN: use the value from GetExpressCheckoutDetails response z PAYERID: use the value from GetExpressCheckoutDetails response z PAYMENTACTION: set to Sale. This is the default value in SetExpressCheckout. z AMT: use the same value as in SetExpressCheckout request

EXAMPLE 2.3 Making a Sale

[requiredSecurityParameters]

TOKEN=EC-0E881823PA052770A&AMT=10.00&

Request

Name-Value Pair API Developer Guide and Reference April 2007 19

PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale

&METHOD=DoExpressCheckoutPayment&

Accepting PayPal in Express Checkout

Support giropay and electronic funds transfer

TOKEN=EC-0E881823PA052770A&

Response

[successResponseFields&

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

Support giropay and electronic funds transfer

Initiate the Flow with SetExpressCheckout

To support giropay payments, you pass the following three URLs as part of the SetExpressCheckout request. These URLs tell PayPal where to redirect the customer based on the success or failure of each type of payment transaction.

TABLE 2.1 SetExpressCheckout fields for giropay

NVP SOAP Description Required?

GIROPAYSUCCESSURL giropaySuccessURL The URL on the merchant site to

redirect to after a successful giropay payment.

GIROPAYCANCELURL giropayCancelURL The URL on the merchant site to

BANKTXNPENDINGURL BanktxnPendingURL The URL on the merchant site to

Redirecting the Customer to PayPal

After selecting a funding source on PayPal, the customer is redirected back to your website, as in the regular Express Checkout flow. There is one additional field, REDIRECTREQUIRED, returned in the response from both GetExpressCheckoutDetails and DoExpressCheckoutPayment.

If the value of this field is true, you redirect the customer from your Order Review page to

https://www.paypal.com/webscr?cmd=_complete-express-checkout&token=TOKEN . Append the

token that you received in SetExpressCheckout. PayPal then redirects the customer from this redirect page to the necessary page for the selected funding source.

No redirect to after a giropay or bank transfer payment is cancelled or fails.

No transfer to after a bank transfer payment.

20 April 2007 Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Controlling the Shipping Address Using SetExpressCheckout

Completing the Transaction

Corresponding the three fields passed to SetExpressCheckout (see Table 2.1,

“SetExpressCheckout fields for giropay”), you must add the following three additional pages

to your website:

TABLE 2.2 Additional pages required for giropay integration

Page Description

Order Completion The page to redirect the customer to after a successful giropay payment.

Order Cancellation The page to redirect the customer to after a giropay or bank-transfer payment

is cancelled or fails

Order Pending The page to redirect the customer to after a bank-transfer payment.

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 OTE: The shipping address is specified in the SHIPTOxxx parameters.

Suppressing Display of Shipping Address on PayPal

To suppress the display of the customer’s 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.

XAMPLE 2.1 Suppressing the Shipping Address

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Request

Response

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &NOSHIPPING=1

[successResponseFields]

Name-Value Pair API Developer Guide and Reference April 2007 21

Accepting PayPal in Express Checkout

Controlling the Shipping Address Using SetExpressCheckout

GetExpressCheckoutDetails does not return the shipping address.

EXAMPLE 2.2 GetExpressCheckoutDetails

&METHOD=GetExpressCheckoutDetails&

&TOKEN=EC-

Request

Response

[requiredSecurityParameters]

TOKEN=EC-17C76533PL706494P

[successResponseFields]

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.3, “Ship to Address

(Optional)”).

The customer cannot edit the address if it has been overridden.

EXAMPLE 2.3 Overriding the Shipping Address

Request

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &SHIPTONAME=Peter+Smith& &SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=99911&

ADDROVERRIDE=1

&METHOD=SetExpressCheckout&AMT=10.00&

SHIPTOSTREET=144+Main+St.&SHIPTOCITY=SAN+JOSE

Response

[successResponseFields]

&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails returns the overridden shipping address.

EXAMPLE 2.4 GetExpressCheckoutDetails

Request

Response

[requiredSecurityParameters]

17C76533PL706494P

[successResponseFields]

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&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=95112& ADDRESSID=PayPal&ADDRESSSTATUS=Unconfirmed

&METHOD=GetExpressCheckoutDetails&TOKEN=EC-

&TOKEN=EC-17C76533PL706494P&

22 April 2007 Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Changing the Language on the PayPal Login Page Using SetExpressCheckout

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

“SetExpressCheckout Request Parameters”. The following example sets LOCALECODE to

French.

EXAMPLE 2.5 Changing the PayPal Login Page Language to French

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Request

Response

[requiredSecurityParameters]

CURRENCYCODE=EUR& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &LOCALECODE=fr_FR

[successResponseFields]

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:

z Specifying a predefined Custom Payment Page Style z 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.

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

EXAMPLE 2.6 Specifying a Custom Payment Page Style

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html&

Request

Response

Name-Value Pair API Developer Guide and Reference April 2007 23

PAGESTYLE=DesignerFotos-Yellow

[successResponseFields]

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Accepting PayPal in Express Checkout

Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails

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:

z HDRIMG: specify an image to appear at the top left of the payment page z HDRBORDERCOLOR: set the border color around the header of the payment page z HDRBACKCOLOR: set the background color for the background of the header of the payment

page

z PAYFLOWCOLOR: set the background color for the payment page

EXAMPLE 2.7 Specifying Logo and Color Settings Individually

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Request

Response

[requiredSecurityParameters]

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

[successResponseFields]

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 2.8 Form-Filling Your Payment Review Page

Request

[requiredSecurityParameters]

TOKEN=EC-3DJ78083ES565113B

&METHOD=GetExpressCheckoutDetails&

&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&

Response

[successResponseFields]

PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=99221& ADDRESSID=PayPal&ADDRESSSTATUS=Confirmed

24 April 2007 Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Making a Sale Using DoExpressCheckoutPayment

Get the payer name from the following parameters in GetExpressCheckoutDetails response:

z SALUTATION z FIRSTNAME z MIDDLENAME z LASTNAME z SUFFIX

Get the shipping address from the following parameters in GetExpressCheckoutDetails response:

z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE

z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM z SHIPTOZIP

Making a Sale Using DoExpressCheckoutPayment

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

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.

N OTE: 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 2.9 Changing the URL for IPN

[requiredSecurityParameters]

TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00&

Request

Name-Value Pair API Developer Guide and Reference April 2007 25

PAYMENTACTION=Sale&NOTIFYURL=https://www.anycompany.com/process-ipn/

&METHOD=DoExpressCheckoutPayment&

Accepting PayPal in Express Checkout

Including Line Item Details Using DoExpressCheckoutPayment

&TOKEN=EC-8AX1275942659774U&

Response

[successResponseFields]

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

Including Line Item Details Using DoExpressCheckoutPayment

You can include line item details by setting the following parameters in DoExpressCheckoutPayment:

z L_NAMEn: item name or description z L_NUMBERn: line item number z L_QTYn: item quantity z L_TAXAMTn: sales tax for the item z L_AMTn: cost of item

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.

The following example sets line item details for two items. These details are recorded on PayPal.

EXAMPLE 2.10 Including Line Item Details

&METHOD=DoExpressCheckoutPayment&

&TOKEN=EC-4XH62109C8044521N&

n, you must specify the TAXAMT parameter. The values for

Request

Response

[requiredSecurityParameters]

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

[successResponseFields]

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

If you specify L_AMT L_QTY

n should add up to the ITEMAMT.

n, you must specify the ITEMAMT parameter. The values for L_AMTn and

If you specify L_TAXAMT L_TAXAMT

n and L_QTYn should add up to TAXAMT.

26 April 2007 Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Including Subtotals Using DoExpressCheckoutPayment

Here are examples of ITEMAMT and TAXAMT:

ITEMAMT = (L_AMT0 * L_QTY0) + (L_AMT1 + L_QTY1) + L_AMT2 TAXAMT = (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 * L_QTY1) + L_TAXAMT2

N OTE: If the line item details do not add up to ITEMAMT or TAXAMT, the line item details are

discarded, and the transaction is processed using the values of ITEMAMT or TAXAMT. The ACK value in the response is set to SuccessWithWarning.

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:

z ITEMAMT

z SHIPPINGAMT

z HANDLINGAMT

z TAXAMT

N OTE: 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 2.11 Including Subtotals

&METHOD=DoExpressCheckoutPayment

&TOKEN=EC-

Request

Response

[requiredSecurityParameters]

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

[successResponseFields]

0EU150885J108392M&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

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:

Name-Value Pair API Developer Guide and Reference April 2007 27

Accepting PayPal in Express Checkout

Updating the Shipping Address Using DoExpressCheckoutPayment

z DESC: item description z CUSTOM: field for your own use z INVNUM: your invoice or tracking number

These three parameters may have been set in SetExpressCheckout.

EXAMPLE 2.12 Updating Order Details

&METHOD=DoExpressCheckoutPayment&

&TOKEN=EC-

Request

Response

[requiredSecurityParameters]

TOKEN=

5JA9268562132991T&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& DESC=Order+for+5+books&CUSTOM=Thank+you+for+your+business!&INVNUM=ABC1234567

EC-

[successResponseFields]

5JA9268562132991T&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

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:

z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM

z SHIPTOZIP

28 April 2007 Name-Value Pair API Developer Guide and Reference

Updating the Shipping Address Using DoExpressCheckoutPayment

EXAMPLE 2.13 Updating the Shipping Address

Accepting PayPal in Express Checkout

Request

Response

[requiredSecurityParameters]

METHOD=DoExpressCheckoutPayment&TOKEN=EC-47C20533CU265432F& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00&

SHIPTONAME=Michael+Brown&SHIPTOSTREET=22+First+Street&SHIPTOCITY=Chicago& SHIPTOCOUNTRYCODE=US&SHIPTOSTATE=IL&SHIPTOZIP=60605

[successResponseFields]

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

&METHOD=DoExpressCheckoutPayment&

&TOKEN=EC-47C20533CU265432F&

Name-Value Pair API Developer Guide and Reference April 2007 29

Accepting PayPal in Express Checkout

Updating the Shipping Address Using DoExpressCheckoutPayment

30 April 2007 Name-Value Pair API Developer Guide and Reference

Back-Office Administration

This section gives you examples of the following functions:

z “Refunding Using RefundTransaction” on page 31 z “Searching for Transactions Using TransactionSearch” on page 32 z “Viewing Details of a Single Transaction Using GetTransactionDetails” on page 33

Refunding Using RefundTransaction

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

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

EXAMPLE 3.1 Refunding the Full Amount of a Transaction

&METHOD=RefundTransaction&TRANSACTIONID=01945456967386

Request

Response

[requiredSecurityParameters]

7 &REFUNDTYPE=Full

[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 3.2 Refunding A Partial Amount

&METHOD=RefundTransaction

&REFUNDTRANSACTIONID=1H0011898K637700R

Request

Response

[requiredSecurityParameters]

&TRANSACTIONID=9CX07910UV614511L&REFUNDTYPE=Partial&AMT=12.95

[successResponseFields]

&FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57

Name-Value Pair API Developer Guide and Reference April 2007 31

Back-Office Administration

Searching for Transactions Using TransactionSearch

Including a Note with the Refund

Whether the refund is full or partial, you can also include a note about the refund.

EXAMPLE 3.3 Including a Note with the Refund

&METHOD=RefundTransaction&TRANSACTIONID=01945456967386

&REFUNDTRANSACTIONID=1H0011898K637700R

Request

Response

[requiredSecurityParameters]

7 &REFUNDTYPE=Partial&AMT=12.95&NOTE=Customer+changed+mind.

[successResponseFields]

&FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57

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 3.4 Searching for Transactions by STARTDATE

&METHOD=TransactionSearch

&L_TIMESTAMP0=2006-08-18T05:58:41Z&

Request

Respons

[requiredSecurityParameters]

&STARTDATE=2006-08-15T17:00:00Z

[successResponseFields]

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

TransactionSearch returns a multi-valued array of all transactions that match the search criteria. Each transaction begins with its date: L_TIMESTAMP

n, where n starts with 0 and

increments by one for each transaction.

32 April 2007 Name-Value Pair API Developer Guide and Reference

Back-Office Administration

Viewing Details of a Single Transaction Using GetTransactionDetails

To view all details about a single transaction, use GetTransactionDetails.

EXAMPLE 3.5 Viewing A Transaction’s Details

Request

Response

[requiredSecurityParameters]

&TRANSACTIONID=

[successResponseFields]

&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

3B288546P5019992D

&METHOD=GetTransactionDetails

&RECEIVERBUSINESS=Jims+Hardware

Name-Value Pair API Developer Guide and Reference April 2007 33

Back-Office Administration

Viewing Details of a Single Transaction Using GetTransactionDetails

34 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field

Reference

General Characteristics of Requests and Parameters

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 PayPal-Supported Currencies and Currency Codes for Transactions

ISO-4217 Code Currency

AUD Australian Dollar

CAD Canadian Dollar

CHF Swiss Franc

CZK Czech Koruna

DKK Danish Krone

EUR Euro

GBP Pound Sterling

Name-Value Pair API Developer Guide and Reference April 2007 35

NVP API Method and Field Reference

Express Checkout

ABLE A.1 PayPal-Supported Currencies and Currency Codes for Transactions

ISO-4217 Code Currency

HKD Hong Kong Dollar

HUF Hungarian Forint

JPY Japanese Yen

NOK Norwegian Krone

NZD New Zealand Dollar

PLN Polish Zloty

SEK Swedish Krona

SGD Singapore Dollar

USD U.S. Dollar

Express Checkout

SetExpressCheckout Request

ABLE A.2 SetExpressCheckout Request Parameters

Parameter Description Required

METHOD Name of the API: SetExpressCheckout Ye s

RETURNURL URL to which the customer’s browser is returned after choosing to

pay with PayPal.

N OTE: PayPal recommends that the value be the final review page

on 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 OTE: PayPal recommends that the value be the original page on

which the customer chose to pay with PayPal.

Character length and limitations: no limit

Ye s

GIROPAYSUCCESSURL URL of your website where the user gets redirected once he

successfully completed a transaction with giropay. This page should be the order confirmation page.

No (recommended)

36 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

ABLE A.2 SetExpressCheckout Request Parameters (Continued)

Parameter Description Required

GIROPAYCANCELURL URL of your website where the user gets redirected when a giropay

or electronic funds transfer transaction fails.

BANKTXNPENDINGURL URL of your website where the user gets redirected when he has

initiated an electronic funds transfer.

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 OTE: 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 (,).

CURRENCYCODE A three-character currency code for one of the currencies listed in

PayPal-Supported Transactional Currencies

. Default: USD.

MAXAMT The expected maximum total amount of the complete order,

including shipping cost and tax charges.

N OTE: 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 (,).

PAYMENTACTION How you want to obtain payment:

z 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

Allowable Values:

z Authorization z Order z Sale

Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale..

No (recommended)

Ye s

EMAIL Email address of the buyer as entered during checkout. PayPal uses

No 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

DESC Description of items the customer is purchasing.

No Character length and limitations: 127 single-byte alphanumeric

characters

Name-Value Pair API Developer Guide and Reference April 2007 37

NVP API Method and Field Reference

Express Checkout

ABLE A.2 SetExpressCheckout Request Parameters (Continued)

Parameter Description Required

CUSTOM 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

INVNUM 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

REQCONFIRMSHIPPING The value 1 indicates that you require that the customer’s shipping

address on file with PayPal be a confirmed address.

N OTE: Setting this field overrides the setting you have specified in

your Merchant Account Profile.

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

NOSHIPPING 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

ADDROVERRIDE 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 OTE: Displaying the PayPal street address on file does not allow

the 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 OTE: 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 Allowable values: See the description of TOKEN in

“SetExpressCheckout Response Fields

.”

Table A.4,

38 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

ABLE A.2 SetExpressCheckout Request Parameters (Continued)

Parameter Description Required

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:

z AU z DE z FR z IT z GB z ES z US

Any other value will default to US.

N OTE: For the list of country codes, see Appendix F, “Country

Codes.”

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.

HDRIMG 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

HDRBORDERCOLOR Sets the border color around the header of the payment page. The

No 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

HDRBACKCOLOR Sets the background color for the header of the payment page.

No Character length and limitation: Six character HTML hexadecimal

color code in ASCII

PAYFLOWCOLOR Sets the background color for the payment page.

No Character length and limitation: Six character HTML hexadecimal

color code in ASCII

Name-Value Pair API Developer Guide and Reference April 2007 39

NVP API Method and Field Reference

Express Checkout

ABLE A.2 SetExpressCheckout Request Parameters (Continued)

Parameter Description Required

Shipping Address Optional shipping address. The parameters for the optional Ship to

Address are described in

(Optional)

IMPORTANT: Ship to Address is optional, but if you include it,

ABLE A.3 Ship to Address (Optional)

Parameter Description Required

SHIPTONAME Person’s name associated with this shipping address.

Character length and limitations: 32 single-byte characters

SHIPTOSTREET First street address.

Character length and limitations: 100 single-byte characters

SHIPTOCITY Name of city.

Character length and limitations: 40 single-byte characters

SHIPTOSTATE State or province.

Character length and limitations: 40 single-byte characters

SHIPTOCOUNTRYCODE Country code.

Character limit: Two single-byte characters. For the list of country codes, see

.”

certain fields are required.

Table A.3, “Ship to Address

Appendix F, “Country Codes.”

Ye s

SHIPTOZIP U.S. Zip code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

SHIPTOSTREET2 Second street address.

Character length and limitations: 100 single-byte characters

PHONENUM Phone number.

Character length and limit: 20 single-byte characters

Ye s

40 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

SetExpressCheckout Response

TABLE A.4 SetExpressCheckout Response Fields

Parameter Description

TOKEN A timestamped token by which you identify to PayPal that you are processing this

payment with Express Checkout.

N OTE: 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 Customer’s 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 customer’s browser to it:

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse

GetExpressCheckoutDetails Request

ABLE A.5 GetExpressCheckoutDetails Parameters

Parameter Description Required?

METHOD Name of the API: GetExpressCheckoutDetails Ye s

TOKEN 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

Ye s

Name-Value Pair API Developer Guide and Reference April 2007 41

NVP API Method and Field Reference

Express Checkout

GetExpressCheckoutDetails Response

TABLE A.6 GetExpressCheckoutDetails Response Fields

Field Description

TOKEN 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

Response Fields

EMAIL Email address of payer.

Character length and limitations: 127 single-byte characters

PAYERID Unique PayPal customer account identification number.

.”

Character length and limitations:13 single-byte alphanumeric characters.

PAYERSTATUS Status of payer.

Character length and limitations: 10 single-byte alphabetic characters. Possible values: verified, unverified

Table A.4, “SetExpressCheckout

SALUTATION Payer’s salutation.

Character length and limitations: 20 single-byte characters

FIRSTNAME Payer’s first name.

Character length and limitations: 25 single-byte characters

MIDDLENAME Payer’s middle name.

Character length and limitations: 25 single-byte characters

LASTNAME Payer’s last name.

Character length and limitations: 25 single-byte characters

SUFFIX Payer’s suffix.

Character length and limitations: 12 single-byte characters

COUNTRYCODE Payer’s 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

BUSINESS Payer’s business name.

Character length and limitations: 127 single-byte characters

SHIPTONAME Person’s name associated with this address.

Character length and limitations: 32 single-byte characters

Appendix F, “Country Codes.”

SHIPTOSTREET First street address.

Character length and limitations: 100 single-byte characters

42 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

ABLE A.6 GetExpressCheckoutDetails Response Fields (Continued)

Field Description

SHIPTOSTREET2 Second street address.

Character length and limitations: 100 single-byte characters

SHIPTOCITY Name of city.

Character length and limitations: 40 single-byte characters

SHIPTOSTATE State or province

Character length and limitations: 40 single-byte characters

SHIPTOCOUNTRYCODE Country code.

Character limit: Two single-byte characters. For the list of country codes, see

SHIPTOZIP U.S. Zip code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

ADDRESSSTATUS Status of street address on file with PayPal

CUSTOM 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

Appendix F, “Country Codes.”

INVNUM 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

PHONENUM Payer’s contact telephone number.

N OTE: PayPal returns a contact telephone number only if your Merchant 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)

REDIRECTREQUIRED If the value equals “True,” you must redirect the user after the DoExpressCheckout

call. The value here indicates that you should inform your user on the Review Order page that he will be redirected to PayPal to complete the transaction.

DoExpressCheckoutPayment Request

Request to obtain payment with PayPal Express Checkout.

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

Name-Value Pair API Developer Guide and Reference April 2007 43

NVP API Method and Field Reference

Express Checkout

TABLE A.7 DoExpressCheckoutPayment Parameters

Parameter Description Required?

METHOD Name of the API: DoExpressCheckoutPayment Ye s

TOKEN The timestamped token value that was returned by

SetExpressCheckout response and passed on GetExpressCheckoutDetails request.

Character length and limitations: 20 single-byte characters

PAYMENTACTION How you want to obtain payment:

z 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 Allowable Values:

z Authorization z Order z Sale

Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale..

PAYERID Unique PayPal customer account identification number as returned by

GetExpressCheckoutDetails response.

Character length and limitations: 13 single-byte alphanumeric characters.

AMT Total of order, including shipping, handling, and tax.

N OTE: 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 (,).

Ye s

DESC Description of items the customer is purchasing.

Character length and limitations: 127 single-byte alphanumeric characters

CUSTOM A free-form field for your own use.

Character length and limitations: 256 single-byte alphanumeric characters

INVNUM Your own invoice or tracking number.

Character length and limitations: 127 single-byte alphanumeric characters

BUTTONSOURCE An identification code for use by third-party applications to identify

transactions. Character length and limitations: 32 single-byte alphanumeric characters

44 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

ABLE A.7 DoExpressCheckoutPayment Parameters (Continued)

Parameter Description Required?

NOTIFYURL Your URL for receiving Instant Payment Notification (IPN) about this

transaction.

N OTE: If you do not specify this value in the request, the notification URL

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.

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 (,).

N OTE: ITEMAMT is required if you specify a value for L_AMTn.

SHIPPINGAMT Total shipping costs for this order.

N OTE: 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.

HANDLINGAMT Total handling costs for this order.

N OTE: Character length and limitations: Must not exceed $10,000 USD in

TAXAMT Sum of tax for all items in this order.

N OTE: Character length and limitations: Must not exceed $10,000 USD in

N OTE: TAXAMT is required if you specify a value for L_TAXAMTn.

CURRENCYCODE A three-character currency code for one of the currencies listed in PayPal-

Supported Transactional Currencies. Default: USD.

L_NAMEn Item name.

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

Name-Value Pair API Developer Guide and Reference April 2007 45

NVP API Method and Field Reference

Express Checkout

ABLE A.7 DoExpressCheckoutPayment Parameters (Continued)

Parameter Description Required?

L_NUMBERn Item number.

Character length and limitations: 127 single-byte characters

L_QTYn Item quantity.

Character length and limitations: Any positive integer

L_TAXAMTn Item sales tax.

L_AMTn Cost of item

These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth.

These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth.

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

No Character length and limitations: Must not exceed $10,000

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

I MPORTANT: Ship to Address is optional, but if you include it, certain

ABLE A.8 Optional Ship to Address

Parameter Description Required?

SHIPTONAME Person’s name associated with this address.

Character length and limitations: 32 single-byte characters

SHIPTOSTREET First street address.

Character length and limitations: 100 single-byte characters

SHIPTOCITY Name of city.

Character length and limitations: 40 single-byte characters

Table A.8, “Optional Ship to Address.”

fields are required.

Ye s

46 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

Express Checkout

ABLE A.8 Optional Ship to Address (Continued)

Parameter Description Required?

SHIPTOSTATE State or province.

Ye s

Character length and limitations: 40 single-byte characters

SHIPTOCOUNTRYCODE Country code.

Ye s

Character limit: Two single-byte characters For the list of country codes, see

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

Appendix F, “Country Codes.”

Ye s

Character length and limitations: 20 single-byte characters

SHIPTOSTREET2 Second street address.

Character length and limitations: 100 single-byte characters

SHIPTOPHONENUM Phone number.

Character length and limit: 20 single-byte characters

DoExpressCheckoutPayment Response

ABLE A.9 DoExpressCheckout Payment Response Fields

Field Description

TOKEN 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

Response Fields

.”

Table A.4, “SetExpressCheckout

TRANSACTIONID Unique transaction ID of the payment.

N OTE: If the PaymentAction of the request was Authorization or 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:

z cart z express-checkout

Name-Value Pair API Developer Guide and Reference April 2007 47

NVP API Method and Field Reference

Express Checkout

ABLE A.9 DoExpressCheckout Payment Response Fields (Continued)

Field Description

PAYMENTTYPE Indicates whether the payment is instant or delayed.

Character length and limitations: Seven single-byte characters Possible values:

z none z echeck z instant

ORDERTIME Time/date stamp of payment

Possible values: Transaction specific

AMT The final amount charged, including any shipping and taxes from your Merchant Profile.

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 A three-character currency code for one of the currencies listed in PayPay-Supported

Transactional Currencies. Default: USD.

FEEAMT PayPal fee amount charged for the transaction

Possible values: Transaction specific

SETTLEAMT Amount deposited in your PayPal account after a currency conversion.

Possible values: Transaction specific

TAXAMT Tax charged on the transaction.

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 nonprimary currency, the conversion occurs in the customer’s account.

Character length and limitations: a decimal that does not exceed 17 characters, including decimal point

Possible values: Transaction specific

48 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

ABLE A.9 DoExpressCheckout Payment Response Fields (Continued)

Field Description

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

PENDINGREASON The reason the payment is pending:

z none: No pending reason z address: The payment is pending because your customer did not include a confirmed

shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.

z echeck: The payment is pending because it was made by an eCheck that has not yet

cleared.

z intl: The payment is pending because you hold a non-U.S. account and do not have a

withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.

z multi-currency: You do not have a balance in the currency sent, and you do not

have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.

z verify: The payment is pending because you are not yet verified. You must verify

your account before you can accept this payment.

z other: The payment is pending for a reason other than those listed above. For more

information, contact PayPal customer service.

Express Checkout

REASONCODE The reason for a reversal if TransactionType is reversal:

z none: No reason code z chargeback: A reversal has occurred on this transaction due to a chargeback by your

customer.

z guarantee: A reversal has occurred on this transaction due to your customer

triggering a money-back guarantee.

z buyer-complaint: A reversal has occurred on this transaction due to a complaint

about the transaction from your customer.

z refund: A reversal has occurred on this transaction because you have given the

customer a refund.

z other: A reversal has occurred on this transaction due to a reason not listed above.

REDIRECTREQUIRED If the value equals "True" you have to redirect the user to PayPal. PayPal will direct the

user according to the selected payment methods (e.g. to giropay). When redirecting the user to Paypal you need to append the Token-value to the following

redirect URL https://www.paypal.com/webscr?cmd=_complete-express-

checkout&token=TOKEN. TOKEN needs to equal the Token-value that you received in the

SetExpressCheckoutResponse.

Name-Value Pair API Developer Guide and Reference April 2007 49

NVP API Method and Field Reference

RefundTransaction

TABLE A.10 RefundTransaction Request Parameters

Parameter Description Required?

METHOD Name of API call: RefundTransaction Ye s

TRANSACTIONID Unique identifier of a transaction

Ye s

Character length and limitations: 17 single-byte alphanumeric characters

REFUNDTYPE Type of refund you are making

z Other z Full z Partial

AMT Refund amount.

Ye s

Amount is required if RefundType is Partial.

N OTE: If RefundType is Full, do not set Amount unless your

merchant account has been enabled to issue refunds greater than the amount in referenced transactions.

NOTE Custom memo about the refund.

Character length and limitations: 255 single-byte alphanumeric characters

ABLE A.11 DoRefund Response Fields

Field Description

REFUNDTRANSACTIONID Unique transaction ID of the refund.

Character length and limitations:17 single-byte characters

NETREFUNDAMT Amount subtracted from PayPal balance of original recipient of payment to

make this refund

FEEREFUNDAMT Transaction fee refunded to original recipient of payment

GROSSREFUNDAMT Amount of money refunded to original payer

TransactionSearch

With TransactionSearch you must always set the StartDate field. Some other behavior:

z Setting TransactionID overrides all other fields (even the required StartDate field). z The effect of setting other elements is additive or can alter the search criteria.

50 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

TransactionSearch

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.12 TransactionSearch Request Parameters

Parameter Description Required

METHOD Name of API call: TransactionSearch Ye s

STARTDATE The earliest transaction date at which to start the search.

NOTE: No wildcards are allowed. The value must be in UTC/GMT

format.

ENDDATE The latest transaction date to be included in the search No

EMAIL Search by the buyer’s email address

Character length and limitations: 127 single-byte alphanumeric characters

RECEIVER Search by the receiver’s email address. If the merchant account has only

one email, this is the primary email. Can also be a non-primary email.

RECEIPTID Search by the PayPal Account Optional receipt ID No

TRANSACTIONID Search by the transaction ID.

NOTE: The returned results are from the merchant’s transaction records.

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.

NOTE: No wildcards are allowed.

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.

NOTE: No wildcards are allowed.

Ye s

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.

SALUTATION Buyer’s salutation

Character length and limitations: 20 single-byte characters

FIRSTNAME Buyer’s first name

Character length and limitations: 25 single-byte characters

Name-Value Pair API Developer Guide and Reference April 2007 51

NVP API Method and Field Reference

TransactionSearch

ABLE A.12 TransactionSearch Request Parameters (Continued)

Parameter Description Required

MIDDLENAME Buyer’s middle name

Character length and limitations: 25 single-byte characters

LASTNAME Buyer’s last name

Character length and limitations: 2025 single-byte characters

SUFFIX Payer’s suffix

Character length and limitations: 12 single-byte characters

AUCTIONITEMNUMBER Search by auction item number of the purchased goods No

TRANSACTIONCLASS Search by classification of transaction.

NOTE: Some kinds of possible classes of transactions are not searchable

with this field. You cannot search for bank transfer withdrawals, for example.

z All: all transaction classifications z Sent: only payments sent z Received: only payments received z MassPay: only mass payments z MoneyRequest: only money requests z FundsAdded: only funds added to balance z FundsWithdrawn: only funds withdrawn from balance z Referral: only transactions involving referrals z Fee: only transactions involving fees z Subscription: only transactions involving subscriptions z Dividend: only transactions involving dividends z Billpay: only transactions involving BillPay Transactions z Refund: only transactions involving funds z CurrencyConversions: only transactions involving currency

conversions

z BalanceTransfer: only transactions involving balance transfers z Reversal: only transactions involving BillPay reversals z Shipping: only transactions involving UPS shipping fees z BalanceAffecting: only transactions that affect the account

balance

z ECheck: only transactions involving eCheck

AMT Search by transaction amount No

52 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

TransactionSearch

ABLE A.12 TransactionSearch Request Parameters (Continued)

Parameter Description Required

STATUS Search by transaction status:

z Pending: The payment is pending. The specific reason the payment

is pending is returned by the GetTransactionDetails API PendingReason field.

z Processing: The payment is being processed. z Success: The payment has been completed and the funds have been

added successfully to your account balance.

z Denied: You denied the payment. This happens only if the payment

was previously pending.

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

ABLE A.13 TransactionSearch Response Fields

Field Description

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

L_NAMEn 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 Seller’s 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.

Name-Value Pair API Developer Guide and Reference April 2007 53

NVP API Method and Field Reference

GetTransactionDetails

ABLE A.13 TransactionSearch Response Fields (Continued)

Field Description

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

ABLE A.14 GetTransactionDetails Request Parameters

Parameter Description Required?

METHOD Name of the API: GetTransactionDetails Yes

TRANSACTIONID Unique identifier of a transaction.

N OTE: The details for some kinds of transactions cannot be retrieved with

GetTransactionDetails. You cannot obtain details of bank transfer withdrawals, for example.

Character length and limitations: 17 single-byte alphanumeric characters

ABLE A.15 GetTransactionDetails Response Fields

Parameter Description

RECEIVERBUSINESS 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

RECEIVEREMAIL 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

Ye s

RECEIVERID Unique account ID of the payment recipient (the seller). This value is the same as

the value of the recipient's referral ID.

54 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

ABLE A.15 GetTransactionDetails Response Fields (Continued)

Parameter Description

EMAIL Email address of payer

Character length and limitations: 127 single-byte characters

PAYERID Unique customer ID.

Character length and limitations: 13 single-byte alphanumeric characters.

PAYERSTATUS Status of payer’s email address:

Verified

Unverified

FIRSTNAME Payer’s first name

Character length and limitations: 25 single-byte characters

LASTNAME Payer’s last name

Character length and limitations: 25 single-byte characters

MIDDLENAME Payer’s middle name

Character length and limitations: 25 single-byte characters

GetTransactionDetails

PAYERBUSINESS Payer’s business name.

Character length and limitations: 127 single-byte characters

SHIPTOCOUNTRYCODE Payment sender’s 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

SALUTATION Payer’s salutation

Character length and limitations: 20 single-byte characters

SUFFIX Payer’s suffix

Character length and limitations: 12 single-byte characters

ADDRESSOWNER eBay company that maintains this address

ADDRESSSTATUS Status of the address on file with PayPal:

None

Confirmed

Unconfirmed

SHIPTOCITY Name of city.

Character length and limitations: 120 single-byte alphanumeric characters

SHIPTONAME Person’s name associated with this address.

Character length and limitations: 32 single-byte alphanumeric characters

Appendix F, “Country Codes.”

SHIPTOPHONENUM Phone number associated with this address

SHIPTOZIP Postal code

Name-Value Pair API Developer Guide and Reference April 2007 55

NVP API Method and Field Reference

GetTransactionDetails

ABLE A.15 GetTransactionDetails Response Fields (Continued)

Parameter Description

SHIPTOSTATE State or province.

Character length and limitations: 120 single-byte alphanumeric characters

SHIPTOSTREET First street address.

Character length and limitations: 300 single-byte alphanumeric characters

SHIPTOSTREET2 Second street address.

Character length and limitations: 300 single-byte alphanumeric characters

PARENTTRANSACTIONID Original transaction to which this transaction is related. This field is populated for

the following transaction types:

z Reversal z Capture of an authorized transaction. z Reauthorization of a transaction. z Capture of an order. The value of ParentTransactionID is the original

OrderID.

z Authorization of an order. The value of ParentTransactionID is the

original OrderID.

z Capture of an order authorization. z Void of an order. The value of ParentTransactionID is the original

OrderID.

Character length and limitations: 19 single-byte characters

TRANSACTIONID PayPal transaction identification number

Character length and limitations: 19 single-byte characters

RECEIPTID Receipt ID

Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format

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

PAYMENTTYPE Indicates whether the payment is instant or delayed.

Character length and limitations: Seven single-byte characters

ORDERTIME Date and time of payment

AMT Full amount of the customer’s payment, before transaction fee is subtracted

56 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

GetTransactionDetails

ABLE A.15 GetTransactionDetails Response Fields (Continued)

Parameter Description

FEEAMT Transaction fee associated with the payment

SETTLEAMT Amount deposited into the account’s 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.

TAXAMT Amount of tax for transaction

EXCHANGERATE Exchange rate for transaction

PAYMENTSTATUS Status of the payment.

The status of the payment:

z None: No status z 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.

z Completed: The payment has been completed, and the funds have been added

successfully to your account balance.

z Denied: You denied the payment. This happens only if the payment was

previously pending because of possible reasons described for the PendingReason element.

z Expired: the authorization period for this payment has been reached. z Failed: The payment has failed. This happens only if the payment was made

from your customer’s bank account.

z Pending: The payment is pending. See the PendingReason field for more

information.

z Refunded: You refunded the payment. z 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.

z Processed: A payment has been accepted. z Voided: An authorization for this transaction has been voided.

Name-Value Pair API Developer Guide and Reference April 2007 57

NVP API Method and Field Reference

GetTransactionDetails

ABLE A.15 GetTransactionDetails Response Fields (Continued)

Parameter Description

PENDINGREASON N OTE: PendingReason is returned in the response only if PaymentStatus is

Pending.

The reason the payment is pending:

z none: No pending reason z address: The payment is pending because your customer did not include a

confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.

z echeck: The payment is pending because it was made by an eCheck that has

not yet cleared.

z intl: The payment is pending because you hold a non-U.S. account and do not

have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.

z multi-currency: You do not have a balance in the currency sent, and you do

not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.

z verify: The payment is pending because you are not yet verified. You must

verify your account before you can accept this payment.

z other: The payment is pending for a reason other than those listed above. For

more information, contact PayPal Customer Service.

REASONCODE The reason for a reversal if TransactionType is reversal:

z none: No reason code z chargeback: A reversal has occurred on this transaction due to a chargeback

by your customer.

z guarantee: A reversal has occurred on this transaction due to your customer

triggering a money-back guarantee.

z buyer-complaint: A reversal has occurred on this transaction due to a

complaint about the transaction from your customer.

z refund: A reversal has occurred on this transaction because you have given

the customer a refund.

z other: A reversal has occurred on this transaction due to a reason not listed

above.

INVNUM Invoice number you set in the original transaction.

Character length and limitations: 127 single-byte alphanumeric characters

CUSTOM Custom field you set in the original transaction.

Character length and limitations: 127 single-byte alphanumeric characters

NOTE Memo entered by your customer in PayPal Website Payments note field.

Character length and limitations: 255 single-byte alphanumeric characters

SALESTAX Amount of tax charged on payment

58 April 2007 Name-Value Pair API Developer Guide and Reference

NVP API Method and Field Reference

GetTransactionDetails

ABLE A.15 GetTransactionDetails Response Fields (Continued)

Parameter Description

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

L_OPTIONSn 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 ID generated by PayPal for the subscriber.

Character length and limitations: no limit

SUBSCRIPTIONDATE Subscription start date

EFFECTIVEDATE Date when the subscription modification will be effective

RETRYTIME Date PayPal will retry a failed subscription payment.

USERNAME Username generated by PayPal and given to subscriber to access the subscription.

Character length and limitations: 64 alphanumeric single-byte characters

PASSWORD 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

RECURRENCES The number of payment installments that will occur at the regular rate.

Character length and limitations: no limit

REATTEMPT Indicates whether reattempts should occur upon payment failures

Name-Value Pair API Developer Guide and Reference April 2007 59

NVP API Method and Field Reference

Mass Payment

ABLE A.15 GetTransactionDetails Response Fields (Continued)

Parameter Description

RECURRING Indicates whether regular rate recurs.

1 = Yes

PERIOD The period of time that the subscriber will be charged.

Character length and limitations: no limit

BUYERID Customer’s auction ID

CLOSINGDATE Auction’s close date

MULTIITEM Counter used for multi-item auction payments

Mass Payment

ABLE A.16 MassPay Parameters

Parameter Description

METHOD Name of the API: MassPay Ye s

RECEIVERTYPE Indicates how you identify the recipients of payments in all the individual

mass payment items: either by EmailAddress (L_EMAIL item) or by UserID (L_RECEIVERID_

n Payment amount. Yes

L_AMT

n in the individual item).

n in the individual

CURRENCYCODE A three-character currency code for one of the currencies listed in PayPay-

Supported Transactional Currencies. Default: USD.

L_EMAIL

n Email address of recipient.

N OTE: You must specify either L_EMAILn or L_RECEIVERIDn, but you

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_RECEIVERID

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

Require d?

Ye s

Depends on

RECEIVE RTYPE

Depends on

RECEIVE RTYPE

60 April 2007 Name-Value Pair API Developer Guide and Reference

ABLE A.16 MassPay Parameters (Continued)

Parameter Description

NVP API Method and Field Reference

Mass Payment

Require d?

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_NOTE

n 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

ABLE A.17 MassPay Response Fields

The fields in the response are the standard response header fields. See [successResponseHeader].

Name-Value Pair API Developer Guide and Reference April 2007 61

NVP API Method and Field Reference

Mass Payment

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

Validation Errors

ABLE B.1 Validation Errors

Error Code Short Message Long Message

81000 Missing Parameter Required Parameter Missing : Unable to identify parameter

81001 Invalid Parameter A Parameter is Invalid : Unable to identify parameter

81002 Unspecified Method Method Specified is not Supported

81003 Unspecified Method No Method Specified

81004 Unspecified Method No Request Received

81100 Missing Parameter OrderTotal (Amt) : Required parameter missing

81101 Missing Parameter MaxAmt : Required parameter missing

81102 Missing Parameter ReturnURL: Required parameter missing

81103 Missing Parameter NotifyURL : Required parameter missing

81104 Missing Parameter CancelURL : Required parameter missing

Name-Value Pair API Developer Guide and Reference March 2007 63

Error Message Reference

Validation Errors

ABLE B.1 Validation Errors

Error Code Short Message Long Message

81105 Missing Parameter ShipToStreet : Required parameter missing

81106 Missing Parameter ShipToStreet2 : Required parameter missing

81107 Missing Parameter ShipToCity : Required parameter missing

81108 Missing Parameter ShipToState : Required parameter missing

81109 Missing Parameter ShipToZip : Required parameter missing

81110 Missing Parameter Country : Required parameter missing

81111 Missing Parameter ReqConfirmShipping : Required parameter missing

81112 Missing Parameter NoShipping : Required parameter missing

81113 Missing Parameter AddrOverride : Required parameter missing

81114 Missing Parameter LocaleCode : Required parameter missing

81115 Missing Parameter PaymentAction : Required parameter missing

81116 Missing Parameter Email : Required parameter missing

81117 Missing Parameter Token : Required parameter missing

81118 Missing Parameter PayerID : Required parameter missing

81119 Missing Parameter ItemAmt : Required parameter missing

81120 Missing Parameter ShippingAmt : Required parameter missing

81121 Missing Parameter HandlingTotal Amt : Required parameter missing

81122 Missing Parameter TaxAmt : Required parameter missing

81123 Missing Parameter IPAddress : Required parameter missing

81124 Missing Parameter ShipToName : Required parameter missing

81125 Missing Parameter L_Amt : Required parameter missing

81126 Missing Parameter Amt : Required parameter missing

81127 Missing Parameter L_TaxAmt : Required parameter missing

81128 Missing Parameter AuthorizationID : Required parameter missing

81129 Missing Parameter CompleteType : Required parameter missing

81130 Missing Parameter CurrencyCode : Required parameter missing

81131 Missing Parameter TransactionID : Required parameter missing

81132 Missing Parameter TransactionEntity : Required parameter missing

81133 Missing Parameter Acct : Required parameter missing

81134 Missing Parameter ExpDate : Required parameter missing

64 March 2007 Name-Value Pair API Developer Guide and Reference

Error Message Reference

ABLE B.1 Validation Errors

Error Code Short Message Long Message

81135 Missing Parameter FirstName : Required parameter missing

81136 Missing Parameter LastName : Required parameter missing

81137 Missing Parameter Street : Required parameter missing

81138 Missing Parameter Street2 : Required parameter missing

81139 Missing Parameter City : Required parameter missing

81140 Missing Parameter State : Required parameter missing

81141 Missing Parameter Zip : Required parameter missing

81142 Missing Parameter CountryCode : Required parameter missing

81143 Missing Parameter RefundType : Required parameter missing

81144 Missing Parameter StartDate : Required parameter missing

81145 Missing Parameter EndDate : Required parameter missing

Validation Errors

81146 Missing Parameter MPID : Required parameter missing

81147 Missing Parameter CreditCardType : Required parameter missing

81148 Missing Parameter User : Required parameter missing

81149 Missing Parameter Pwd : Required parameter missing

81150 Missing Parameter Version : Required parameter missing

81200 Invalid Parameter Amt : Invalid parameter

81201 Invalid Parameter MaxAmt : Invalid parameter

81203 Invalid Parameter NotifyURL : Invalid parameter

81205 Invalid Parameter ShipToStreet : Invalid parameter

81206 Invalid Parameter ShipToStreet2 : Invalid parameter

81207 Invalid Parameter ShipToCity : Invalid parameter

81208 Invalid Parameter ShipToState : Invalid parameter

81209 Invalid Parameter ShipToZip : Invalid parameter

81210 Invalid Parameter Country : Invalid parameter

81211 Invalid Parameter ReqConfirmShipping : Invalid parameter

81212 Invalid Parameter Noshipping : Invalid parameter

81213 Invalid Parameter AddrOverride : Invalid parameter

81214 Invalid Parameter LocaleCode : Invalid parameter

81215 Invalid Parameter PaymentAction : Invalid parameter

Name-Value Pair API Developer Guide and Reference March 2007 65

Error Message Reference

Validation Errors

ABLE B.1 Validation Errors

Error Code Short Message Long Message

81219 Invalid Parameter ItemAmt : Invalid parameter

81220 Invalid Parameter ShippingAmt : Invalid parameter

81221 Invalid Parameter HandlingTotal Amt : Invalid parameter

81222 Invalid Parameter TaxAmt : Invalid parameter

81223 Invalid Parameter IPAddress : Invalid parameter

81224 Invalid Parameter ShipToName : Invalid parameter

81225 Invalid Parameter L_Amt : Invalid parameter

81226 Invalid Parameter Amt : Invalid parameter

81227 Invalid Parameter L_TaxAmt : Invalid parameter

81229 Invalid Parameter CompleteType : Invalid parameter

81230 Invalid Parameter CurrencyCode : Invalid parameter

81232 Invalid Parameter TransactionEntity : Invalid parameter

81234 Invalid Parameter ExpDate : Invalid parameter

81235 Invalid Parameter FirstName : Invalid parameter

81236 Invalid Parameter LastName : Invalid parameter

81237 Invalid Parameter Street : Invalid parameter

81238 Invalid Parameter Street2 : Invalid parameter

81239 Invalid Parameter City : Invalid parameter

81243 Invalid Parameter RefundType : Invalid parameter

81244 Invalid Parameter StartDate : Invalid parameter

81245 Invalid Parameter EndDate : Invalid parameter

81247 Invalid Parameter CreditCardType : Invalid parameter

81248 Invalid Parameter Username : Invalid parameter

81249 Invalid Parameter Password : Invalid parameter

81250 Invalid Parameter Version : Invalid parameter

81251 Internal Error Internal Service Error

66 March 2007 Name-Value Pair API Developer Guide and Reference

General API Errors

TABLE B.2 General API Errors

Short

Error Code

Message Long Message Correcting This Error

Error Message Reference

General API Errors

10002 Authentication

/Authorization Failed

10002 Authentication

/Authorization Failed

10002 Authentication

/Authorization Failed

10002 Internal Error Internal Error

10002 Authentication

/Authorization Failed

10002 Authentication

/Authorization Failed

Username/Password is incorrect This error can be caused by

You do not have permissions to make this API call

Account is locked or inactive

Internal Error

Account is not verified

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.

10002 Authentication

/Authorization Failed

10002 Authentication

/Authorization Failed

10002 Restricted

account

Name-Value Pair API Developer Guide and Reference March 2007 67

This call is not defined in the database!

Token is not valid

Account is restricted Your PayPal merchant

account has been restricted. Contact your PayPal account manager for resolution.

Error Message Reference

Express Checkout API Errors

ABLE B.2 General API Errors

Short

Error Code

Message Long Message Correcting This Error

10002 Authentication

/Authorization Failed

10002 Authentication

/Authorization Failed

10002 Authentication

/Authorization Failed

10002 Restricted

account

Token is not valid

API access is disabled for this account

Client certificate is disabled

Account is restricted

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short

Error Code

Message Long Message Correcting This Error...

10001 ButtonSource

value truncated.

10001 Internal Error Internal Error

10004 Transaction

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

10004 Transaction

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

The transaction could not be loaded

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

The transaction id is not valid

68 March 2007 Name-Value Pair API Developer Guide and Reference

Error Code

Error Message Reference

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short Message Long Message Correcting This Error...

10007 Permission

denied

10102 PaymentActio

n of Order Temporarily Unavailable

10103 Please use

another Solution Type.

10402 Authorization

only is not allowed for merchant.

10404 Transaction

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

10405 Transaction

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

You do not have permissions to make this API call

PaymentAction of Order is temporarily unavailable. Please try later or use other PaymentAction.

Your Solution Type is temporarily unavailable. If possible, please use another Solution Type.

This merchant account is not permitted to set PaymentAction to Authorization. Please contact Customer Service.

ReturnURL is missing.

CancelURL is missing.

10407 Transaction

Invalid buyer email address (BuyerEmail). refused because of an invalid argument. See additional error messages for details.

10409 You're not

authorized to

Express Checkout token was issued for a

merchant account other than yours. access this info.

Name-Value Pair API Developer Guide and Reference March 2007 69

Error Message Reference

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short

Error Code

10410 Invalid token Invalid token.

Message Long Message Correcting This Error...

10411 This Express

Checkout session has expired.

This Express Checkout session has expired.

Token value is no longer valid.

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.

70 March 2007 Name-Value Pair API Developer Guide and Reference

Error Code

Error Message Reference

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short Message Long Message Correcting This Error...

10412 Duplicate

invoice

10415 Transaction

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

Payment has already been made for this

InvoiceID.

A successful transaction has already been

completed for this token.

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.

10425 Express

Checkout has

Express Checkout has been disabled for this

merchant. Please contact Customer Service. been disabled for this merchant.

10432 Transaction

refused

Invoice ID value exceeds maximum allowable

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

Name-Value Pair API Developer Guide and Reference March 2007 71

Error Message Reference

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short

Error Code

Message Long Message Correcting This Error...

10433 Transaction

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

10434 Transaction

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

10436 Transaction

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

Value of OrderDescription element has been

truncated.

Value of Custom element has been truncated.

PageStyle value exceeds maximum allowable

length.

10437 Transaction

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

10438 Transaction

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

cpp-header-image value exceeds maximum

allowable length.

cpp-header-image value exceeds maximum

allowable length.

72 March 2007 Name-Value Pair API Developer Guide and Reference

Error Code

Error Message Reference

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short Message Long Message Correcting This Error...

10439 Transaction

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

10440 Transaction

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

10471 Transaction

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

cpp-header-image value exceeds maximum

allowable length.

cpp-header-image value exceeds maximum

allowable length.

ReturnURL: Invalid parameter

10472 Transaction

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

10537 Risk Control

Country Filter Failure

10538 Risk Control

Max Amount Failure

Name-Value Pair API Developer Guide and Reference March 2007 73

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.

Error Message Reference

Express Checkout API Errors

ABLE B.3 SetExpressCheckout API Errors

Short

Error Code

Message Long Message Correcting This Error...

10539 Payment

declined by your Risk Controls settings: PayPal Risk Model.

10725 Shipping

Address Country Error

10727 Shipping

Address1 Empty

10728 Shipping

Address City Empty

10729 Shipping

Address State Empty

10730 Shipping

Address Postal Code Empty

Payment declined by your Risk Controls

settings: PayPal Risk Model.

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

10731 Shipping

Address Country Empty

10736 Shipping

Address Invalid City State Postal Code

ABLE B.4 GetExpressCheckoutDetails API Errors

Error Code

10001 Internal Error Internal Error

10001 Internal Error Transaction failed due to internal

Short Message Long Message Correcting This Error...

error

The field Shipping Address Country is

required

A match of the Shipping Address City, State,

and Postal Code failed.

74 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.4 GetExpressCheckoutDetails API Errors

Error Message Reference

Express Checkout API Errors

Error Code

Short Message Long Message Correcting This Error...

10001 ButtonSource

value truncated.

10001 ButtonSource

value truncated.

10004 Transaction

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

10004 Transaction

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

The transaction could not be loaded

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

The transaction id is not valid

10004 Invalid

transaction type

10004 Transaction

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

10004 Transaction

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

You can not get the details for this type of transaction

The transaction could not be loaded

The transaction id is not valid

Name-Value Pair API Developer Guide and Reference March 2007 75

Error Message Reference

Express Checkout API Errors

ABLE B.4 GetExpressCheckoutDetails API Errors

Error Code

10007 Permission

10408 Express

10409 You're not

10410 Invalid token Invalid token.

10411 This Express

Short Message Long Message Correcting This Error...

You do not have permissions to

denied

Checkout token is missing.

authorized to access this info.

Checkout session has expired.

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.

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

This Express Checkout session has expired. Token value is no longer valid.

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Code

10001 Internal Error Transaction failed due to internal

10001 Internal Error Warning an internal error has

10001 ButtonSource

10001 Internal Error Internal Error

Short Message Long Message Correcting This Error...

error

occurred. The transaction id may not be correct

The transaction could not be value truncated.

loaded

76 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Message Reference

Express Checkout API Errors

Error Code

Short Message Long Message Correcting This Error...

10004 Transaction

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

10004 Transaction

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

10007 Permission

denied

10406 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 transaction id is not valid

You do not have permissions to

make this API call

The PayerID value is invalid.

10408 Express

Checkout

Express Checkout token is

missing. token is missing.

10409 You're not

authorized to access this

Express Checkout token was

issued for a merchant account

other than yours. info.

10410 Invalid token Invalid token.

10411 This Express

Checkout session has

This Express Checkout session

has expired. Token value is no

longer valid. expired.

10412 Duplicate

invoice

Name-Value Pair API Developer Guide and Reference March 2007 77

Payment has already been made

for this InvoiceID.

Error Message Reference

Express Checkout API Errors

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Code

Short Message Long Message Correcting This Error...

10413 Transaction

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

10414 Transaction

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

10415 Transaction

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

The totals of the cart item

amounts do not match order

amounts.

The amount exceeds the

maximum amount for a single

transaction.

A successful transaction has

already been completed for this

token.

If you include any of the following element values with DoExpressCheckoutPayment, the sum of their values must equal the value of OrderTotal.

z ItemTotal z ShippingTotal z HandlingTotal z 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.

10416 Transaction

refused because of an invalid

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. argument. See additional error messages for details.

78 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Message Reference

Express Checkout API Errors

Error Code

Short Message Long Message Correcting This Error...

10417 Transaction

cannot complete.

10418 Transaction

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

The transaction cannot complete successfully. Instruct the customer to use an alternative payment method.

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

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 customer’s 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 PayPal’s 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.

10419 Express

Checkout

Express Checkout PayerID is

missing. PayerID is missing.

10420 Transaction

refused

Express Checkout

PaymentAction is missing. because of an invalid argument. See additional error messages for details.

Name-Value Pair API Developer Guide and Reference March 2007 79

Error Message Reference

Express Checkout API Errors

TABLE B.5 DoExpressCheckoutPayment API Errors

Error Code

10421 This Express

10422 Customer must

10423 Transaction

Short Message Long Message Correcting This Error...

Checkout session belongs to a different customer.

choose new funding sources.

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

This Express Checkout session

belongs to a different customer.

Token value mismatch.

The customer must return to

PayPal to select new funding

sources.

This transaction cannot be

completed with PaymentAction

of Authorization.

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.

10424 Transaction

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

Shipping address is invalid. 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.

80 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Message Reference

Express Checkout API Errors

Error Code

Short Message Long Message Correcting This Error...

10431 Item amount is

invalid.

10432 Transaction

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

10433 Transaction

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

10434 Transaction

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

Item amount is invalid.

Invoice ID value exceeds

maximum allowable length.

Value of OrderDescription

element has been truncated.

Value of Custom element has

been truncated.

10435 Transaction

refused because of an

The customer has not yet

confirmed payment for this

Express Checkout session. invalid argument. See additional error messages for details.

10441 Transaction

refused because of an

The NotifyURL element value

exceeds maximum allowable

length. invalid argument. See additional error messages for details.

Name-Value Pair API Developer Guide and Reference March 2007 81

Error Message Reference

Express Checkout API Errors

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Code

10442 ButtonSource

10443 Transaction

10444 Transaction

10445 This

Short Message Long Message Correcting This Error...

value truncated.

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

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

The ButtonSource element value

exceeds maximum allowable

length.

This transaction cannot be

completed with PaymentAction

of Order.

The transaction currency

specified must be the same as

previously specified.

This transaction cannot be

processed at this time. Please try

again later.

10446 Unconfirmed

10474 Invalid Data This transaction cannot be

10537 Risk Control

Country Filter Failure

10538 Risk Control

Max Amount Failure

A confirmed email is required to

make this API call.

processed. The country code in

the shipping address must match

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

82 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.5 DoExpressCheckoutPayment API Errors

Error Message Reference

Express Checkout API Errors

Error Code

Short Message Long Message Correcting This Error...

10539 Payment

declined by your Risk Controls settings: PayPal Risk Model.

10725 Shipping

Address Country Error

10727 Shipping

Address1 Empty

10728 Shipping

Address City Empty

10729 Shipping

Address State Empty

Payment declined by your Risk

Controls settings: PayPal Risk

Model.

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

10730 Shipping

Address Postal Code Empty

10731 Shipping

Address Country Empty

10736 Shipping

Address Invalid City State Postal Code

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.

Name-Value Pair API Developer Guide and Reference March 2007 83

Error Message Reference

RefundTransaction API Errors

TABLE B.6 RefundTransaction API Errors

Short

Error Code

10001 Internal Error Internal Error

10001 Internal Error Warning an internal error has occurred. The

Message Long Message Correcting This Error...

transaction id may not be correct

10001 ButtonSource

value truncated.

10001 Internal Error Internal Error

10004 Transaction

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

10004 Transaction

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

10004 Transaction

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

The transaction could not be loaded

The partial refund amount must be a positive amount

You can not specify a partial amount with a full refund

A transaction id is required

84 March 2007 Name-Value Pair API Developer Guide and Reference

Error Code

Error Message Reference

RefundTransaction API Errors

ABLE B.6 RefundTransaction API Errors

Short Message Long Message Correcting This Error...

10004 Transaction

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

10004 Transaction

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

10004 Transaction

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

The partial refund amount must be a positive amount

You can not specify a partial amount with a full refund

A transaction id is required

10004 Transaction

Transaction class is not supported refused because of an invalid argument. See additional error messages for details.

10004 Transaction

The transaction id is not valid refused because of an invalid argument. See additional error messages for details.

10007 Permission

denied

Name-Value Pair API Developer Guide and Reference March 2007 85

You do not have permission to refund this

transaction

Error Message Reference

RefundTransaction API Errors

ABLE B.6 RefundTransaction API Errors

Short

Error Code

Message Long Message Correcting This Error...

10007 Permission

denied

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

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.

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

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

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

86 March 2007 Name-Value Pair API Developer Guide and Reference

Error Code

Error Message Reference

TransactionSearch API Errors

ABLE B.6 RefundTransaction API Errors

Short Message Long Message Correcting This Error...

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10009 Transaction

refused

10011 Invalid

transaction id value

11001 Transaction

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

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

TransactionSearch API Errors

ABLE B.2 TransactionSearch API Errors

Error Code Short Message Long Message

10001 Internal Error Internal Error

10001 ButtonSource value

truncated.

10003 Transaction refused because

of an invalid argument. See additional error messages for details.

Name-Value Pair API Developer Guide and Reference March 2007 87

The transaction could not be loaded

Start date is a required parameter

Error Message Reference

TransactionSearch API Errors

ABLE B.2 TransactionSearch API Errors

Error Code Short Message Long Message

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

Start date is invalid

End date is invalid

Currency is not supported

Transaction class is not supported

Receipt id is not valid

Payer email is invalid

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

Auction item id is not valid

Receiver email is invalid

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

Receiver can only be specified for payments you've received

88 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.2 TransactionSearch API Errors

Error Code Short Message Long Message

Error Message Reference

GetTransactionDetails API Errors

10004 Transaction refused because

of an invalid argument. See additional error messages for details.

10007 Permission denied You do not have permissions to search for this transaction

10007 Permission denied You do not have permissions to make this API call

11002 Search warning The number of results were truncated. Please change your search

The transaction id is not valid

parameters if you wish to see all your results.

GetTransactionDetails API Errors

ABLE B.7 GetTransactionDetails API Errors

Short

Error Code

10001 Internal Error Internal Error

Message Long Message

MassPay API Errors

ABLE B.8 MassPay API Errors

Short

Error Code

10001 Inval id account

10001 Internal Error Internal Error

10001 Internal Error The transaction could not be loaded

10001 ButtonSource

Name-Value Pair API Developer Guide and Reference March 2007 89

Message Long Message

The transaction failed as a result of an invalid credit card number.

number.

value truncated.

Check the number or attempt with another card.

The transaction could not be loaded

Error Message Reference

MassPay API Errors

ABLE B.8 MassPay API Errors

Error Code

Short Message Long Message

10001 Transaction

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

10002 Account

locked

10004 Transaction

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

10004 Transaction

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

The masspay receiver_type is not a recognizable type

The user account is locked

The number of input records is greater than maximum allowed

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

10004 Transaction

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

10004 Transaction

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

The note string length exceeds the maximum limit of 4000 characters

The amount is missing

90 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.8 MassPay API Errors

Short

Error Code

Message Long Message

Error Message Reference

MassPay API Errors

10004 Transaction

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

10004 Transaction

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

10004 Transaction

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

The currency is missing

Currency is not supported

The amount is not a valid number

10004 Transaction

refused

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

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

10004 Transaction

The amount is less than or equal to zero refused because of an invalid argument. See additional error messages for details.

Name-Value Pair API Developer Guide and Reference March 2007 91

Error Message Reference

MassPay API Errors

ABLE B.8 MassPay API Errors

Error Code

Short Message Long Message

10004 Transaction

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

10004 Transaction

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

10004 Transaction

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

The unique id string length exceeds the maximum limit of 30

characters

The unique id string contains a space as a character

The transaction id is not valid

10007 Permission

denied

10301 User not

allowed

10303 Restricted

account

10304 Unconfirmed

10305 Limit

Exceeded

10306 Limit

Exceeded

10307 Receive only

account

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

92 March 2007 Name-Value Pair API Developer Guide and Reference

ABLE B.8 MassPay API Errors

Short

Error Code

Message Long Message

Error Message Reference

MassPay API Errors

10308 Masspay

server configuration error

10309 Masspay

server unavailable

10310 Unable to

create payment

10311 Unable to

submit payment

10312 Masspay

server error

10313 Masspay

Invalid Data

10314 Masspay input

parse error

10317 Masspay

Invalid Email

There is some configuration error

The mass pay server is unavailable

Unable to create payments for masspay

Unable to submit payments for masspay

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

10320 Internal Error Internal Error

10321 Insufficient

The account does not have sufficient funds to do this masspay funds

10327 Masspay

The masspay input file includes invalid UserID Invalid UserID

Name-Value Pair API Developer Guide and Reference March 2007 93

Error Message Reference

MassPay API Errors

94 March 2007 Name-Value Pair API Developer Guide and Reference

NVP API Web Samples

This chapter describes the NVP API Web Samples which access the NVP API directly. This section includes the following topics:

z “Descriptions of the Samples” on page 95 z “Samples Using PHP” on page 99 z “Samples Using PHP” on page 99 z “Samples Using Classic ASP” on page 100

Descriptions of the Samples

The web samples consist of the following:

z “Accepting PayPal in Express Checkout” on page 95 z “Getting Transaction Details” on page 97 z “Common Files” on page 98

The main page of the samples, index.html or Default.htm, contains links to each sample.

N OTE: We describe the code samples for all programming languages in this section. Language

specific filenames are shown as stands for SetExpressCheckout.java, SetExpressCheckout.php, and so forth.

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.

filename.ext. For example, SetExpressCheckout.ext

Name-Value Pair API Developer Guide and Reference April 2007 95

NVP API Web Samples

Descriptions of the Samples

The primary files for this sample are:

TABLE C.1 Express Checkout Files

File Description

SetExpressCheckout.

ReviewOrder.

ext This file is called after the user clicks on a button during the

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

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

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.

N OTE: Be sure to check the value of PAYPAL_URL. The buyer

ext.

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

Display.

ext.

ext, CallerService.ext, and

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

ext.

ext and CallerService.ext.

96 April 2007 Name-Value Pair API Developer Guide and Reference

ABLE C.1 Express Checkout Files (Continued)

File Description

DoExpressCheckoutPayment.ext This functionality is called to complete the payment with

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.

NVP API Web Samples

Descriptions of the Samples

PayPal and display the result to the buyer. The code constructs and sends the

DoExpressCheckoutPayment request string to the PayPal server.

Called by GetExpressCheckoutDetails. CallerService.

ext.

The main page displays a text box where the user enters a transaction ID. When the user clicks the constructs an NVP API request to GetTransactionDetails and sends it to the PayPal server.

ext and

Submit button, the code

The primary files for this sample are:

ABLE C.2 Get Transaction Details Files

File Description

GetTransactionDetails.

TransactionDetails.

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

ext.

Name-Value Pair API Developer Guide and Reference April 2007 97

NVP API Web Samples

Common Files

The following files are common to the samples.

TABLE C.3 Common Files

File Description

index.html Default.htm

sdk.css Cascading Style Sheet (CSS) used by index.html or Default.htm.

CallerService.

ext This is the configuration file for the samples.This file contains the

The main web page with links to each sample. Calls SetExpressCheckout.

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

with API Signature” on page 98.

Called by TransactionDetails.ext, ReviewOrder.ext, and Display.ext.

Display.

ext Displays request and response parameters. If there is an error, displays

request and error parameters. Called by TransactionDetails.

DoExpressCheckoutPayment.

Sample API User with API Signature

ext, and GetTransactionDetails.html.

“Sample API User

ext, and

ext.

The samples come with an API signature for use with the samples and the PayPal Sandbox. This API signature belongs to the following user:

ABLE C.1 Details of the Sample API Signature

API username sdk-three_api1.sdk.com

API password QFZCWN5HZM8VBG7Q

API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

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

98 April 2007 Name-Value Pair API Developer Guide and Reference

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:

ABLE C.4 Required Software

Software Version Download Location

NVP API Web Samples

Samples Using PHP

PHP with CURL extension enabled

Apache HTTP Server 1.3.17 or greater http://httpd.apache.org/

4.4.2 or greater http://www.php.net/downloads.php

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

Download and Unzip the Samples

The latest version of the Web Samples are available at https://www.paypal.com/IntegrationCenter/ic_nvp.html.

1. Download the zipfile distribution.

2. Unzip the zipfile to any directory of you choose.

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

Name-Value Pair API Developer Guide and Reference April 2007 99

NVP API Web Samples

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.

Download and Unzip the Samples

The latest version of the Web Samples are available at https://www.paypal.com/IntegrationCenter/ic_nvp.html.

1. Download the zipfile distribution.

2. Unzip the zipfile to any directory of you choose.

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

100 April 2007 Name-Value Pair API Developer Guide and Reference

PayPal Name-Value Pair API - 2007 Reference Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Preface

This Document

Intended Audience

Documentation Problems

Revision History

Overview

Introducing the PayPal NVP API

Integrating with the PayPal API

Basic Steps

Create a Web Application

Get API Credentials

Create and Post the Request

Interpret the Response

Taking Your Application Live

Set Up a PayPal Business Account

Set Up API Credentials

Technical Details

Modify Your Code

Request-Response Model

Request Format

Response Format

Posting Using HTTPS

Basic Checkout with PayPal

1. Starting the Checkout Using SetExpressCheckout

2. Redirecting the Customer’s Browser to PayPal Login Page

3. Getting Payer Details Using GetExpressCheckoutDetails

4. Making a Sale Using DoExpressCheckoutPayment

Support giropay and electronic funds transfer

Initiate the Flow with SetExpressCheckout

Redirecting the Customer to PayPal

Controlling the Shipping Address Using SetExpressCheckout

Completing the Transaction

Suppressing Display of Shipping Address on PayPal

Overriding the Shipping Address Stored on PayPal

Changing the Language on the PayPal Login Page Using SetExpressCheckout

Specifying a Custom Payment Page Style

Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails

Specifying Logo and Color Settings Individually

Making a Sale Using DoExpressCheckoutPayment

Changing the URL for IPN Using DoExpressCheckoutPayment

Including Line Item Details Using DoExpressCheckoutPayment

Including Subtotals Using DoExpressCheckoutPayment

Updating Order Details Using DoExpressCheckoutPayment

Updating the Shipping Address Using DoExpressCheckoutPayment

Back-Office Administration

Refunding Using RefundTransaction

Full Refund

Partial Refunds

Searching for Transactions Using TransactionSearch

Including a Note with the Refund

Viewing Details of a Single Transaction Using GetTransactionDetails

General Characteristics of Requests and Parameters

Parameters

Multi-Value Fields

PayPal-Supported Transactional Currencies

Express Checkout

SetExpressCheckout Request

SetExpressCheckout Response

GetExpressCheckoutDetails Request

GetExpressCheckoutDetails Response

DoExpressCheckoutPayment Request

DoExpressCheckoutPayment Response

RefundTransaction

TransactionSearch

GetTransactionDetails

Mass Payment

Error Message Reference

Error Response Format

Validation Errors

General API Errors

Express Checkout API Errors

RefundTransaction API Errors

TransactionSearch API Errors

GetTransactionDetails API Errors

MassPay API Errors

NVP API Web Samples