PayPal Name-Value Pair API - 2009 Developer's Guide

Name-Value Pair API Developer Guide

Last updated: 08 April 2009

Name-Value Pair API Developer Guide

Document Number: 100018.en_US-20090408

© 2009 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349. Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability: PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Contents

Preface 9

This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 1 PayPal NVP API Overview . . . . . . . . . . . . . . . . . . 11

Introducing the PayPal NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Integrating with the PayPal API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Basic Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Create a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Get API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Create and Post the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Interpret the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Taking Your Application Live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Set Up a PayPal Business Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Set Up API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Modify Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Request-Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Posting Using HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

API Servers for API Signature Security . . . . . . . . . . . . . . . . . . . . . . . . . 18

API Servers for API Certificate Security . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 2 Authorization and Capture API Operation Reference . . . .19

DoCapture API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

DoCapture Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

DoAuthorization API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

DoAuthorization Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

DoAuthorization Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

DoReauthorization API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Name-Value Pair API Developer Guide 08 April 2009 3

Contents

DoReauthorization Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

DoReauthorization Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

DoVoid API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

DoVoid Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

DoVoid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 DoDirectPayment API . . . . . . . . . . . . . . . . . . . .27

DoDirectPayment Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

DoDirectPayment Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 4 Express Checkout API Operations . . . . . . . . . . . . .39

Callback API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Callback Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Callback Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

SetExpressCheckout API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

SetExpressCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

SetExpressCheckout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

GetExpressCheckoutDetails API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

GetExpressCheckoutDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . 55

GetExpressCheckoutDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . 55

DoExpressCheckoutPayment API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

DoExpressCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . 64

DoExpressCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 5 GetTransactionDetails API . . . . . . . . . . . . . . . . . 75

GetTransactionDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

GetTransactionDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Chapter 6 MassPay API. . . . . . . . . . . . . . . . . . . . . . . . .85

MassPay Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

MassPay Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 7 RefundTransaction API . . . . . . . . . . . . . . . . . . . 89

RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

4 08 April 2009 Name-Value Pair API Developer Guide

Contents

Chapter 8 TransactionSearch API . . . . . . . . . . . . . . . . . . .91

TransactionSearch Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

TransactionSearch Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Chapter 9 Recurring Payments and Reference Transactions API

Operations95

CreateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

CreateRecurringPaymentsProfile Request . . . . . . . . . . . . . . . . . . . . . . . 95

CreateRecurringPaymentsProfile Response . . . . . . . . . . . . . . . . . . . . . .105

GetRecurringPaymentsProfileDetails API . . . . . . . . . . . . . . . . . . . . . . . . . .106

GetRecurringPaymentsProfileDetails Request . . . . . . . . . . . . . . . . . . . . .106

GetRecurringPaymentsProfileDetails Response . . . . . . . . . . . . . . . . . . . .106

ManageRecurringPaymentsProfileStatus API . . . . . . . . . . . . . . . . . . . . . . . .113

ManageRecurringPaymentsProfileStatus Request . . . . . . . . . . . . . . . . . . . 114

ManageRecurringPaymentsProfileStatus Response . . . . . . . . . . . . . . . . . .114

BillOutstandingAmount API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

BillOutstandingAmount Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

BillOutstandingAmount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

UpdateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

UpdateRecurringPaymentsProfile Request . . . . . . . . . . . . . . . . . . . . . . . 116

UpdateRecurringPaymentsProfile Response . . . . . . . . . . . . . . . . . . . . . .123

SetCustomerBillingAgreement API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

SetCustomerBillingAgreement Request . . . . . . . . . . . . . . . . . . . . . . . . .124

SetCustomerBillingAgreement Response . . . . . . . . . . . . . . . . . . . . . . . .127

GetBillingAgreementCustomerDetails API . . . . . . . . . . . . . . . . . . . . . . . . . .127

GetBillingAgreementCustomerDetails Request . . . . . . . . . . . . . . . . . . . . .128

GetBillingAgreementCustomerDetails Response . . . . . . . . . . . . . . . . . . . .128

BAUpdate API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

BAUpdate Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

BAUpdateResponseDetails Response . . . . . . . . . . . . . . . . . . . . . . . . .131

DoReferenceTransaction API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

DoReferenceTransaction Request. . . . . . . . . . . . . . . . . . . . . . . . . . . .134

DoReferenceTransaction Response. . . . . . . . . . . . . . . . . . . . . . . . . . .143

Chapter 10 DoNonReferencedCredit API . . . . . . . . . . . . . . . 147

DoNonReferencedCredit Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

DoNonReferencedCredit Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Name-Value Pair API Developer Guide 08 April 2009 5

Contents

Chapter 11 ManagePendingTransactionStatus API . . . . . . . . . . 151

ManagePendingTransactionStatus Request . . . . . . . . . . . . . . . . . . . . . . . . .151

ManagePendingTransactionStatus Response . . . . . . . . . . . . . . . . . . . . . . . .151

Chapter 12 GetBalance API . . . . . . . . . . . . . . . . . . . . . . 153

GetBalance Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

GetBalance Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

Chapter 13 AddressVerify API . . . . . . . . . . . . . . . . . . . . . 155

AddressVerify Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

AddressVerify Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Chapter A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 159

General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165

SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177

GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .187

DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .189

Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .195

GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199

TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199

RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201

Mass Pay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204

Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206

SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .213

GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .215

CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215

UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224

ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .224

Chapter B Country Codes . . . . . . . . . . . . . . . . . . . . . . 225

6 08 April 2009 Name-Value Pair API Developer Guide

Contents

Chapter C State and Province Codes . . . . . . . . . . . . . . . . . 235

Chapter D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 239

Chapter E AVS and CVV2 Response Codes . . . . . . . . . . . . . 241

AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241

CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243

Name-Value Pair API Developer Guide 08 April 2009 7

Contents

8 08 April 2009 Name-Value Pair API Developer Guide

Preface

This Document

The Name-Value Pair API Developer Guide describes the PayPal Name-Value Pair API.

Intended Audience

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

Revision History

Revision history for Name-Value Pair API Developer Guide.

TABLE P.1 Revision History

Date Description

08 April 2009 Updated information for 57.0: Express Checkout Callback API.

26 Nov. 2008 Updated information for 55.0.

23 Sept. 2008 Added information about using billing agreements with SetExpressCheckout.

3 Sept. 2008 Added information about payment review to GetTransactionDetails.

June 2008 Rearranged material, added error codes, and moved some material to the

Express Checkout Integration Guide.

April 2008 Added Fraud Management Filters information. Changed recurring payments

information.

February 2008 Added that ther VERSION parameter must be 50.0 in the API call to use

recurring payments.

January 2008

z Added billing agreement fields to SetExpressCheckout for recurring

payments

z Updated CreateRecurringPaymentsProfile for new recurring payments

features.

z Added new recurring payments APIs z Added DoNonReferencedCredit API

Name-Value Pair API Developer Guide 08 April 2009 9

Revision History

ABLE P.1 Revision History

Date Description

September 2007 z Update eBay auctions for Express Checkout section

August 2007 Added recurring payments concepts, modified SetExpressCheckout,

April 2007 Added Recurring Payments APIs: SetCustomerBillingAgreement,

February 2007 Bug fixes including updating Line Item Details for Direct Payment and Express

December 2006 Updates for bug fixes.

October 2006 First public release.

z Added fields for the giropay payment method to Express Checkout APIs z Added Direct Payment error 10571.

DoExpressCheckoutPayment, DoReferenceTransaction, and added additional DoReferenceTransaction error codes.

GetBillingAgreementCustomerDetails, and CreateRecurringPaymentsProfile.

Checkout APIs, changing some parameters to optional in DoDirectPayment, adding SHIPTOCOUNTRYCODE, and adding Switch/Solo codes for AVS and CVV2.

10 08 April 2009 Name-Value Pair API Developer Guide

PayPal NVP API Overview

This overview describes the PayPal Name-Value Pair (NVP) API at a high level.

z “Introducing the PayPal NVP API” on page 11 z “Basic Steps” on page 12 z “Taking Your Application Live” on page 13 z “Technical Details” on page 14

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 Charge a credit card using Direct Payment. z Capture payments previously authorized through Express Checkout, Direct Payment, or

Website Payments Standard.

z Reauthorize or void previous authorizations. 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 Classic ASP, PHP, and ColdFusion.

Name-Value Pair API Developer Guide 08 April 2009 11

PayPal NVP API Overview

Basic Steps

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.

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. “Taking Your Application Live” on page 13 describes how to move your application to the live PayPal environment.

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.

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

Details of the Sample API Signature

API username sdk-three_api1.sdk.com

API password QFZCWN5HZM8VBG7Q

API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

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

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

12 08 April 2009 Name-Value Pair API Developer Guide

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

page 18.

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.

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

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.

PayPal NVP API Overview

Taking Your Application Live

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

https://www.paypal.com.

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.

IMPORTANT: If you are using API signature, 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 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.

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

Name-Value Pair API Developer Guide 08 April 2009 13

PayPal NVP API Overview

Technical Details

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

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

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 values for each field in an NVP string are URL-encoded.

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:

14 08 April 2009 Name-Value Pair API Developer Guide

PayPal NVP API Overview

Technical Details

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 Encode Server.URLEncode

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

Internet.

Java Encode java.net.URLEncoder.encode

Decode java.net.URLDecoder.decode

PHP Encode urlencode()

Decode urldecode()

ColdFusion Encode URLEncodedFormatstring [, charset ]

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.

General Format of a Request

Required Security Parameters

Decode URLDecodeurlEncodedString[, charset])

USER=apiUsername

&PWD=apiPassword

&SIGNATURE=apiSignature

&SUBJECT=optionalThirdPartyEmailAddress

&VERSION=56.0

The following parameters are always required:

USER

PWD

VERSION

The examples show the required security parameters like this:

[requiredSecurityParameters]

Body Parameters &METHOD=methodName

&otherRequiredAndOptionalParameters

Name-Value Pair API Developer Guide 08 April 2009 15

PayPal NVP API Overview

Technical Details

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.

Security Parameters

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

Required Security Parameters: API Credentials

Parameter Value

USER (Required) Your PayPal API Username.

PWD (Required) Your PayPal API Password.

VERSION=

SIGNATURE (Optional) Your PayPal API signature string.

SUBJECT (Optional) Email address of a PayPal account that has granted you

IMPORTANT: You must protect the values for USER, PWD, and SIGNATURE in your

<current version> (Required) Version number of the NVP API service, such as 56.0.

If you use an API certificate, do not include this parameter.

permission to make this call. Set this parameter only if you are calling an API on a different user’s

behalf.

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.

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

16 08 April 2009 Name-Value Pair API Developer Guide

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.

General Format of a Successful Response

Success Response Fields ACK=Success&TIMESTAMP=date/timeOfResponse

API Response Fields &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.

Error Responses

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

PayPal NVP API Overview

Technical Details

&CORRELATIONID=debuggingToken&VERSION=...

&BUILD=buildNumber

Format of an Error Response

Response Fields on Error

ACK=Error&TIMESTAMP=date/timeOfResponse&

CORRELATIONID=debuggingToken&VERSION=VersionNo&

BUILD=buildNumber&L_ERRORCODE0=errorCode&

L_SHORTMESSAGE0=shortMessage&

L_LONGMESSAGE0=longMessage&

L_SEVERITYCODE0=severityCode

For possible causes of errors and how to correct them, see the explanation of the specific error code, short message, and long message in “API Error Codes” on page 159.

ACK Parameter Values

The following table lists values for the ACK parameter.

ACK Parameter Values

Type of Response Value

Successful response Success

Error response Failure

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

SuccessWithWarning

FailureWithWarning

Warning

Name-Value Pair API Developer Guide 08 April 2009 17

PayPal NVP API Overview

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

18 08 April 2009 Name-Value Pair API Developer Guide

Authorization and Capture API

Operation Reference

This chapter describes the PayPal API operations related to delayed payment settlement:

z “DoCapture API” on page 19 z “DoAuthorization API” on page 23 z “DoReauthorization API” on page 24 z “DoVoid API” on page 25

DoCapture API

Capture an authorized payment.

z “DoCapture Request” on page 20 z “DoCapture Response” on page 21

Name-Value Pair API Developer Guide 08 April 2009 19

Authorization and Capture API Operation Reference

DoCapture API

DoCapture Request

DoCapture Request Fields

Field Description

METHOD (Required) Must be DoCapture.

AUTHORIZATIONID (Required) The authorization identification number of the payment you want to

capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment.

Character length and limits: 19 single-byte characters maximum.

AMT (Required) Amount to capture.

Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).

CURRENCYCODE (Optional) A three-character currency code. Default: USD.

COMPLETETYPE (Required) The value Complete indicates that this the last capture you intend to

make. The value NotComplete indicates that you intend to make additional captures.

NOTE: If Complete, any remaining amount of the original authorized transaction is

automatically voided and all remaining open authorizations are voided.

Character length and limits: 12 single-byte alphanumeric characters.

INVNUM (Optional) Your invoice number or other identification number that is displayed to the

merchant and customer in his transaction history.

NOTE: This value on DoCapture will overwrite a value previously set on

DoAuthorization.

NOTE: The value is recorded only if the authorization you are capturing is an order

authorization, not a basic authorization.

Character length and limits: 127 single-byte alphanumeric characters.

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

in email and in his transaction history. Character length and limits: 255 single-byte characters.

20 08 April 2009 Name-Value Pair API Developer Guide

Authorization and Capture API Operation Reference

DoCapture API

Field Description

SOFTDESCRIPTOR (Optional) The soft descriptor is a per transaction description of the payment that is

passed to the consumer’s credit card statement. If a value for the soft descriptor field is provided, the full descriptor displayed on the

customer’s statement has the following format:

The soft descriptor can contain only the following characters:

z Alphanumeric characters z - (dash) z * (asterisk) z . (period) z {space}

If you use any other characters (such as “,”), an error code is returned. The soft descriptor does not include the phone number, which can be toggled between

the merchant’s customer service number and PayPal’s customer service number. The maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8

characters are used by the PayPal prefix shown in the data format. Thus, the maximum length of the soft descriptor passed in the API request is:

22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment Receiving Preferences> + 1)

For example, assume the following conditions:

z The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools. z The merchant descriptor set in the Payment Receiving Preferences is set to EBAY. z The soft descriptor is passed in as JanesFlowerGifts LLC.

The resulting descriptor string on the credit card would be:

PAYPAL *EBAY JanesFlow

DoCapture Response

z DoCapture Response Fields z Payer Information Fields z Ship To Address Fields z Payer Name Fields

Name-Value Pair API Developer Guide 08 April 2009 21

Authorization and Capture API Operation Reference

DoCapture API

Do Capture Response Fields

Field Description

AUTHORIZATIONID The authorization identification number you specified in the request.

Character length and limits: 19 single-byte characters maximum.

PayerInfo Type Fields

Field Description

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. Valid values are:

z verified z unverified

Character length and limitations: 10 single-byte alphabetic 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.

BUSINESS Payer’s business name.

Character length and limitations: 127 single-byte characters.

Ship To Address Type Fields

Field Description

ADDRESSSTATUS Status of street address on file with PayPal.

Valid values are:

z none z Confirmed z Unconfirmed

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.

SHIPTOSTREET2 Second street address.

Character length and limitations: 100 single-byte characters.

SHIPTOCITY Name of city.

Character length and limitations: 40 single-byte characters.

22 08 April 2009 Name-Value Pair API Developer Guide

Authorization and Capture API Operation Reference

Field Description

SHIPTOSTATE State or province.

Character length and limitations: 40 single-byte characters. Required for U.S. addresses only.

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

Character length and limitations: 20 single-byte characters.

SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters.

Payer Name Fields

Field Description

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.

DoAuthorization API

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.

DoAuthorization API

Authorize a payment.

z DoAuthorization Request z DoAuthorization Response

Name-Value Pair API Developer Guide 08 April 2009 23

Authorization and Capture API Operation Reference

DoReauthorization API

DoAuthorization Request

DoAuthorization Request Fields

Field Description

METHOD (Required) Must be DoAuthorization.

TRANSACTIONID (Required) The value of the order’s transaction identification number returned by

PayPal. Character length and limits: 19 single-byte characters maximum.

AMT (Required) Amount to authorize.

TRANSACTIONENTITY (Optional) Type of transaction to authorize. The only allowable value is Order,

which means that the transaction represents a customer order that can be fulfilled over 29 days.

CURRENCYCODE (Optional) A three-character currency code. See “Currency Codes” on page 239.

DoAuthorization Response

DoAuthorization Response Fields

Field Description

TRANSACTIONID An authorization identification number.

AMT The amount you specified in the request.

DoReauthorization API

z DoReauthorization Request z DoReauthorization Response

24 08 April 2009 Name-Value Pair API Developer Guide

Authorization and Capture API Operation Reference

DoVoid API

DoReauthorization Request

DoReauthorization Request Fields

Field Description

METHOD (Required) Must be DoReauthorization.

AUTHORIZATIONID (Required) The value of a previously authorized transaction identification number

returned by PayPal. Character length and limits: 19 single-byte characters maximum.

AMT (Required) Amount to reauthorize.

CURRENCYCODE A three-character currency code. See “Currency Codes” on page 239.

DoReauthorization Response

DoReauthorization Response Fields

Field Description

AUTHORIZATIONID A new authorization identification number.

Character length and limits:19 single-byte characters maximum.

DoVoid API

Void an order or an authorization.

z DoVoid Request z DoVoid Response

Name-Value Pair API Developer Guide 08 April 2009 25

Authorization and Capture API Operation Reference

DoVoid API

DoVoid Request

DoVoid Request Fields

Field Description

METHOD (Required) Must be DoVoid.

AUTHORIZATIONID (Required) The value of the original authorization identification number returned by a

PayPal product.

IMPORTANT: If you are voiding a transaction that has been reauthorized, use the ID

from the original authorization, and not the reauthorization.

Character length and limits: 19 single-byte characters.

NOTE (Optional) An informational note about this void that is displayed to the payer in

email and in his transaction history. Character length and limits: 255 single-byte characters

DoVoid Response

DoVoid Response Fields

Field Description

AUTHORIZATIONID The authorization identification number you specified in the request.

Character length and limits: 19 single-byte characters.

26 08 April 2009 Name-Value Pair API Developer Guide

DoDirectPayment API

Process a credit card payment.

z DoDirectPayment Request z DoDirectPayment Response

DoDirectPayment Request

z DoDirectPayment Request Fields z Credit Card Fields z Payer Information Fields z Payer Name Fields z Billing Address Fields z Payment Details Type Fields z Payment Details Item Type Fields z eBay Item Payment Details Item Type Fields z Ship To Address Fields

Name-Value Pair API Developer Guide 08 April 2009 27

DoDirectPayment API

DoDirectPayment Request

DoDirectPayment Request Fields

Field Description

METHOD (Required) Must be DoDirectPayment.

PAYMENTACTION (Optional) How you want to obtain payment:

z Authorization indicates that this payment is a basic authorization subject to

settlement with PayPal Authorization & Capture.

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. Default: Sale

NOTE: Order is not allowed for Direct Payment.

IPADDRESS (Required) IP address of the payer’s browser.

NOTE: PayPal records this IP addresses as a means to detect possible fraud.

Character length and limitations: 15 single-byte characters, including periods, for example: 255.255.255.255.

RETURNFMFDETAILS (Optional) Flag to indicate whether you want the results returned by Fraud

Management Filters. By default, you do not receive this information.

z 0 - do not receive FMF details (default) z 1 - receive FMF details

Credit Card Details Fields

Field Description

CREDITCARDTYPE (Required) Type of credit card.

Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values:

z Visa z MasterCard z Discover z Amex z Maestro: See note. z Solo: See note.

For Canada, only MasterCard and Visa are allowable; Interac debit cards are not supported.

NOTE: If the credit card type is Maestro or Solo, the CURRENCYCODE must be

GBP. In addition, either STARTDATE or ISSUENUMBER must be specified.

ACCT (Required) Credit card number.

Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type.

28 08 April 2009 Name-Value Pair API Developer Guide

DoDirectPayment API

DoDirectPayment Request

Field Description

EXPDATE Credit card expiration date.

This field is required if you are using recurring payments with direct payments. Format: MMYYYY Character length and limitations: Six single-byte alphanumeric characters, including

leading zero.

CVV2 Card Verification Value, version 2. Your Merchant Account settings determine

whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits.Character length for American Express: exactly four digits.To comply with credit card processing regulations, you must not store this value after a transaction has been completed.

STARTDATE (Optional) Month and year that Maestro or Solo card was issued, the MMYYYY

format. Character length: Must be six digits, including leading zero.

ISSUENUMBER (Optional) Issue number of Maestro or Solo card.Character length: two numeric

digits maximum.

Name-Value Pair API Developer Guide 08 April 2009 29

DoDirectPayment API

DoDirectPayment Request

PayerInfo Type Fields

Field Description

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. Valid values are:

z verified z unverified

Character length and limitations: 10 single-byte alphabetic 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.

BUSINESS Payer’s business name.

Character length and limitations: 127 single-byte characters.

Payer Name Fields

Field Description

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.

Address Fields

Field Description

STREET (Required) First street address.

Character length and limitations: 100 single-byte characters.

STREET2 (Optional) Second street address.

Character length and limitations: 100 single-byte characters.

CITY (Required) Name of city.

Character length and limitations: 40 single-byte characters.

30 08 April 2009 Name-Value Pair API Developer Guide

DoDirectPayment API

DoDirectPayment Request

Field Description

STATE (Required) State or province.

Character length and limitations: 40 single-byte characters.

COUNTRYCODE (Required) Country code.

Character limit: Two single-byte characters.

ZIP (Required) U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters.

PHONENUM (Optional) Phone number.

Character length and limit: 20 single-byte characters.

Name-Value Pair API Developer Guide 08 April 2009 31

DoDirectPayment API

DoDirectPayment Request

Payment Details Type Fields

Field Description

AMT (Required) The total cost of the transaction 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.

If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases.

Set this field to 0 if the transaction does not include a one-time purchase; for example, when you set up a billing agreement for a recurring payment that is not immediately charged.

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 (Optional) A three-character currency code. Default: USD.

ITEMAMT (Optional) Sum of cost of all items in this order.

NOTE: ITEMAMT is required if you specify L_AMTn.

SHIPPINGAMT (Optional) Total shipping costs for this order.

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

NOTE: If you specify a value for SHIPPINGAMT, you must also specify a value for

ITEMAMT.

INSURANCEAMT (Optional) Total shipping insurance costs for this order. The value must be a non-

negative currency amount or null if insurance options are offered.

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

SHIPPINGDISCOUNT (Optional) Shipping discount for this order, specified as a negative number.

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

INSURANCEOPTIONOFFE RED

(Optional) If true, the Insurance drop-down on the PayPal Review page displays the string ‘Yes’ and the insurance amount. If true, the total shipping insurance for this order must be a positive number.

Character length and limitations: true or false

32 08 April 2009 Name-Value Pair API Developer Guide

DoDirectPayment API

DoDirectPayment Request

Field Description

HANDLINGAMT (Optional) Total handling costs for this order.

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

NOTE: If you specify a value for HANDLINGAMT, you must also specify a value for

ITEMAMT.

TAXAMT (Optional) Sum of tax for all items in this order.

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

NOTE: TAXAMT is required if you specify L_TAXAMTn

DESC (Optional) Description of items the customer is purchasing.

Character length and limitations: 127 single-byte alphanumeric characters

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

Character length and limitations: 256 single-byte alphanumeric characters

INVNUM (Optional) Your own invoice or tracking number.

Character length and limitations: 127 single-byte alphanumeric characters

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

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

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

transaction.

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

Name-Value Pair API Developer Guide 08 April 2009 33

DoDirectPayment API

DoDirectPayment Request

Payment Details Item Type Fields

Field Description

L_NAMEn (Optional) Item name.

These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).

Character length and limitations: 127 single-byte characters

L_DESCn (Optional) Item description.

Character length and limitations: 127 single-byte characters

n (Opt

L_AMT

These parameters mu L_AMT0, L_AMT1).

NOTE: Character length and limitations: Must not exceed $10,000 USD in any

NOTE: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

L_NUMBERn (Opt

These parameters m L_NUMBER0, L_NUMBER1).

Character length and limitations: 127 single-byte characters

n (Opt

L_QTY

These parameters mu L_QTY0, L_QTY1).

Character length and limitations: Any positive integer

L_TAXAMT

n (Opt

NOTE: Character length and limitations: Must not exceed $10,000 USD in any

These parameters must be ordered sequentially beginning with 0 (for example L_TAXAMT0, L_TAXAMT1).

ional) Cost of item.

st be ordered sequentially beginning with 0 (for example

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.

ional) Item number.

st be ordered sequentially beginning with 0 (for example

ional) Item quantity.

st be ordered sequentially beginning with 0 (for example

ional) Item sales tax.

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.

L_ITEMWEIGHTVALUEn, L_ITEMWEGHTUNITn

(Optional) Item weight corresponds to the weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

Character length and limitations: Any positive integer

L_ITEMLENGTHVALUEn L_I

TEMLENGTHUNITn

(Optional) Item the shipping carrier as is without having to make an additional database query.

length corresponds to the length of the item. You can pass this data to

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMLENGTHVALUE0, L_ITEMLENGTHVALUE1).

Character length and limitations: Any positive integer

34 08 April 2009 Name-Value Pair API Developer Guide

Field Description

DoDirectPayment API

DoDirectPayment Request

L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn

L_ITEMHEIGHTVALUEn L_I

TEMHEIGHTUNITn

(Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

Character length and limitations: Any positive integer

(Optional) Item the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMHEIGHTVALUE0, L_ITEMHEIGHTVALUE1).

Character length and limitations: Any positive integer

height corresponds to the height of the item. You can pass this data to

Name-Value Pair API Developer Guide 08 April 2009 35

DoDirectPayment API

DoDirectPayment Response

EbayItemPaymentDetailsItemType Fields

Field Description

L_EBAYITEMNUMBERn (Optional) Auction item number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).

Character length: 765 single-byte characters

L_EBAYITEMAUCTIONTX NIDn

L_EBAYITEMORDERIDn (Optional) Auction order identification number.

Ship To Address Fields

Field Description

SHIPTONAME Person’s name associated with this address. This field is required for

SHIPTOSTREET First street address. This field is required if the shipping address is used.

SHIPTOSTREET2 (Optional) Second street address.

SHIPTOCITY Name of city. This field is required if the shipping address is used.

(Optional) Auction transaction identification number. These parameters must be ordered sequentially beginning with 0 (for example

L_EBAYITEMAUCTIONTXNID0, L_EBAYITEMAUCTIONTXNID1). Character length: 255 single-byte characters

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMORDERID0, L_EBAYITEMORDERID1).

Character length: 64 single-byte characters

shipping addresses but is optional for credit card billing addresses. Character length and limitations: 32 single-byte characters.

Character length and limitations: 100 single-byte characters.

Character length and limitations: 40 single-byte characters.

SHIPTOSTATE State or province. This field is required if the shipping address is used.

Character length and limitations: 40 single-byte characters.

SHIPTOZIP U.S. ZIP code or other country-specific postal code. This field is required if

a U.S. shipping address is used and may be required for other countries. Character length and limitations: 20 single-byte characters.

SHIPTOCOUNTRYCODE Country code. This field is required if the shipping address is used.

Character limit: 2 single-byte characters.

SHIPTOPHONENUM (Optional) Phone number.

Character length and limit: 20 single-byte characters.

DoDirectPayment Response

36 08 April 2009 Name-Value Pair API Developer Guide

DoDirectPayment API

DoDirectPayment Response

DoDirectPayment Response Fields

Field Description

TRANSACTIONID Unique transaction ID of the payment.

NOTE: If the PaymentAction of the request was Authorization, the value of

TransactionID is your AuthorizationID for use with the Authorization & Capture APIs.

Character length and limitations: 19 single-byte characters.

AMT This value is the amount of the payment as specified by you on

DoDirectPaymentRequest for reference transactions with direct payments.

AVSCODE Address Verification System response code. See “AVS and CVV2 Response Codes”

on page 241 for possible values.

Character limit: One single-byte alphanumeric character

CVV2MATCH Result of the CVV2 check by PayPal.

filterIDn Filter ID, including the filter type, which is either ACCEPT or DENY, the filter ID, and

L_FMF

the entry number,

z 1 = AVS No Match z 2 = AVS Partial Match z 3 = AVS Unavailable/Unsupported z 4 = Card Security Code (CSC) Mismatch z 5 = Maximum Transaction Amount z 6 = Unconfirmed Address z 7 = Country Monitor z 8 = Large Order Number z 9 = Billing/Shipping Address Mismatch z 10 = Risky ZIP Code z 11 = Suspected Freight Forwarder Check z 12 = Total Purchase Price Minimum z 13 = IP Address Velocity z 14 = Risky Email Address Domain Check z 15 = Risky Bank Identification Number (BIN) Check z 16 = Risky IP Address Range z 17 = PayPal Fraud Model

n, starting from 0. Filter ID is one of the following values:

filterNAMEn Filter name, including the filter type, which is either ACCEPT or DENY, the filter

L_FMF

NAME, and the entry number, n, starting from 0.

Name-Value Pair API Developer Guide 08 April 2009 37

DoDirectPayment API

DoDirectPayment Response

38 08 April 2009 Name-Value Pair API Developer Guide

This chapter describes the PayPal API operations related to Express Checkout transactions:

z “SetExpressCheckout API” on page 43 z “GetExpressCheckoutDetails API” on page 54 z “DoExpressCheckoutPayment API” on page 63

Callback API

Updates the PayPal Review page with shipping options, insurance, and tax information.

z “Callback Request” on page 40 z “Callback Response” on page 42

Express Checkout API Operations

Name-Value Pair API Developer Guide 08 April 2009 39

Express Checkout API Operations

Callback API

Callback Request

Callback Request Fields

Field Description

METHOD (Required) Must be Callback.

TOKEN (Optional) A timestamped token, the value of which was returned by

SetExpressCheckout response.

Character length and limitations: 20 single-byte characters

CURRENCYCODE (Required) The three-character currency code for the transaction from the Express

Checkout API. Default: USD

LOCALECODE (Optional) 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.

L_NAMEn Item name from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example,

L_NAME0, L_NAME1).

L_NUMBERn Item number from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_NUMBER0, L_NUMBER1).

L_DESCn Item description from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_DESC0, L_DESC1).

L_AMTn Item unit price from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_AMT0, L_AMT1).

L_QTYn Item unit quantity from the Express Checkout API.

These parameters must be ordered sequentially beginning with 0 (for example, L_QTY0, L_QTY1).

L_ITEMWEIGHTVALUEn L_ITEMWEIGHTUNITn

The weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

40 08 April 2009 Name-Value Pair API Developer Guide

Field Description

Express Checkout API Operations

Callback API

L_ITEMHEIGHTVALUEn, L_ITEMHEIGHTUNITn

L_ITEMWIDTHVALUEn L_ITEMWIDTHUNITn

L_ITEMLENGTHVALUEn L_ITEMLENGTHUNITn

SHIPTOSTREET First street address. Required if using a shipping address.

SHIPTOSTREET2 Second street address.

SHIPTOCITY Name of city. Required if using a shipping address.

SHIPTOSTATE State or province. Required if using a shipping address.

The height of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMHEIGHTVALUE0, ITEMHEIGHTVALUE1).

The width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query..

These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

The length of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example, ITEMLENGTHVALUE0, ITEMLENGTHVALUE1).

Character length and limitations: 100 single-byte characters.

Character length and limitations: 40 single-byte characters.

SHIPTOZIP U.S. ZIP code or other country-specific postal code. Required if using a U.S. shipping

address; may be required for other countries. Character length and limitations: 20 single-byte characters.

SHIPTOCOUNTRY Country code. Required if using a shipping address.

Character limit: 2 single-byte characters.

Name-Value Pair API Developer Guide 08 April 2009 41

Express Checkout API Operations

Callback API

Callback Response

Callback Response Fields

Field Description

METHOD (Required) The method sent to the PayPal server. The value is always

CallbackResponse.

OFFERINSURANCEOPTION(Optional) Indicates whether or not PayPal should display insurance in a drop-down

list on the Review page. When the value is true, PayPal displays the drop-down with the associated amount and the string ‘Yes.’

L_SHIPPINGOPTIONNAM

L_SHIPPINGOPTIONLAB

L_SHIPPINGOPTIONAMO

UNT

L_SHIPPINGOPTIONISD EFAULT

L_TAXAMT

n (Opt

(Required) Is the internal/system name of a shipping option, such as Air, Ground, or Expedited.

These parameters must be ordered sequentially beginning with 0 (for example, L_SHIPPINGOPTIONNAME0, L_SHIPPINGOPTIONNAME1).

Character length and limitations: 50 characters

(Required) The label for the shipping option as displayed to the buyer. Examples: Air: Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized based on the buyer’s locale, which is a part of the callback request.

These parameters must be ordered sequentially beginning with 0 (for example, L_SHIPPINGALABEL0, L_SHIPPINGLABEL1).

Character length and limitations: 50 characters

(Required) Is the amount for this shipping option. These parameters must be ordered sequentially beginning with 0 (for example,

L_SHIPPINGAMOUNT0, L_SHIPPINGAMOUNT1).

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

(Required) The option that is selected by default for the buyer and is also reflected in the “default” total.

ional) New tax amount based on this shipping option and the shipping address.

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

L_INSURANCEAMOUNT

n (Optional) New

insurance amount based on this shipping option and the shipping

address.

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

METHOD (Required) The method sent to the PayPal server. The value is always

CallbackResponse.

42 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

SetExpressCheckout API

Field Description

OFFERINSURANCEOPTION(Optional) Indicates whether or not PayPal should display insurance in a drop-down

list on the Review page. When the value is true, PayPal displays the drop-down with the associated amount and the string ‘Yes.’

SetExpressCheckout API

Initiates an Express Checkout transaction. Optionally, the SetExpressCheckout API operation can set up billing agreements for

reference transactions and recurring payments.

z “Callback Request” on page 40 z “SetExpressCheckout Response” on page 54

SetExpressCheckout Request

z “SetExpressCheckout Request Fields” on page 44 z “Address Fields” on page 48 z “Payment Details Type Fields” on page 48 z “Payment Details Item Type Fields” on page 51 z “EbayItemPaymentDetailsItemType Fields” on page 53 z “Shipping Options Type Fields” on page 53 z “Billing Agreement Details Fields” on page 54

Name-Value Pair API Developer Guide 08 April 2009 43

Express Checkout API Operations

SetExpressCheckout API

SetExpressCheckout Request Fields

Field Description

METHOD (Required) Must be SetExpressCheckout.

TOKEN (Optional) A timestamped token, the value of which was returned by

SetExpressCheckout response.

Character length and limitations: 20 single-byte characters

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

shipping cost and tax charges. If the transaction does not include a one-time purchase, this field is ignored. 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 (,).

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

with PayPal.

NOTE: PayPal recommends that the value be the final review page on which the

customer confirms the order and payment or billing agreement.

Character length and limitations: 2048 characters

CANCELURL (Required) URL to which the customer is returned if he does not approve the use of

PayPal to pay you.

NOTE: PayPal recommends that the value be the original page on which the

customer chose to pay with PayPal or establish a billing agreement.

Character length and limitations: 2048 characters

CALLBACKURL (Optional) URL to which the callback request from PayPal is sent. It must start with

HTTPS for production integration. It can start with HTTPS or HTTP for sandbox testing.

Character length and limitations: 1024 characters

CALLBACKURL (Optional) An override for you to request more or less time to be able to process the

callback request and respond. The acceptable range for the override is 1 to 6 seconds. If you specify a value greater than 6, PayPal uses the default value of 3 seconds.

Character length and limitations: An integer between 1 and 6

REQCONFIRMSHIPPING (Optional) The value 1 indicates that you require that the customer’s shipping address

on file with PayPal be a confirmed address.

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

NOSHIPPING (Optional) The value 1 indicates that on the PayPal pages, no shipping address fields

should be displayed whatsoever. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1

44 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

SetExpressCheckout API

Field Description

ALLOWNOTE (Optional) The value 1 indicates that the customer may enter a note to the merchant

on the PayPal page during checkout. The note is returned in the GetExpressCheckoutDetails response and the DoExpressCheckoutPayment response.

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

ADDRESSOVERRIDE (Optional) 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.

Displaying the PayPal street address on file does not allow the customer to edit that address.

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

LOCALECODE (Optional) 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. See “Country Codes” on page 225.

PAGESTYLE (Optional) 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 (Optional) 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. If you do not specify an image, the business name is displayed.

Character length and limit: 127 single-byte alphanumeric characters

HDRBORDERCOLOR (Optional) Sets the border color around the header of the payment page. The border is

a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. By default, the color is black.

Character length and limitation: Six character HTML hexadecimal color code in ASCII.

Name-Value Pair API Developer Guide 08 April 2009 45

Express Checkout API Operations

SetExpressCheckout API

Field Description

HDRBACKCOLOR (Optional) Sets the background color for the header of the payment page. By default,

the color is white. Character length and limitation: Six character HTML hexadecimal color code in

ASCII.

PAYFLOWCOLOR (Optional) Sets the background color for the payment page. By default, the color is

white. Character length and limitation: Six character HTML hexadecimal color code in

ASCII.

PAYMENTACTION (Optional) How you want to obtain payment:

z Sale indicates that this is a final sale for which you are requesting payment.

(Default)

z Authorization indicates that this payment is a basic authorization subject to

settlement with PayPal Authorization & Capture.

z Order indicates that this payment is an order authorization subject to settlement

with PayPal Authorization & Capture.

If the transaction does not include a one-time purchase, this field is ignored.

NOTE: You cannot set this value to Sale in SetExpressCheckout request and then

change this value to Authorization or Order on the final API DoExpressCheckoutPayment request. If the value is set to Authorization or Order in SetExpressCheckout, the value may be set to Sale or the same value (either Authorization or Order) in DoExpressCheckoutPayment.

Character length and limit: Up to 13 single-byte alphabetic characters Default value: Sale

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

value to pre-fill the PayPal membership sign-up portion of the PayPal login page. Character length and limit: 127 single-byte alphanumeric characters

SOLUTIONTYPE (Optional) Type of checkout flow:

z Sole: Express Checkout for auctions z Mark: Normal Express Checkout

LANDINGPAGE (Optional) Type of PayPal page to display:

z Billing: non-PayPal account z Login: PayPal account login

CHANNELTYPE (Optional) Type of channel:

z Merchant: non-auction seller z eBayItem: eBay auction

GIROPAYSUCCESSURL (Optional) The URL on the merchant site to redirect to after a successful giropay

payment. Use this field only if you are using giropay or bank transfer payment methods in

Germany.

46 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

SetExpressCheckout API

Field Description

GIROPAYCANCELURL (Optional) The URL on the merchant site to redirect to after a successful giropay

payment. Use this field only if you are using giropay or bank transfer payment methods in

Germany.

BANKTXNPENDINGURL (Optional) The URL on the merchant site to transfer to after a bank transfer payment.

Use this field only if you are using giropay or bank transfer payment methods in Germany.

Name-Value Pair API Developer Guide 08 April 2009 47

Express Checkout API Operations

SetExpressCheckout API

Address Fields

Field Description

NAME Person’s name associated with this shipping address. Required if using a

shipping address. Character length and limitations: 32 single-byte characters.

SHIPTOSTREET First street address. Required if using a shipping address.

Character length and limitations: 100 single-byte characters.

SHIPTOSTREET2 (Optional) Second street address.

Character length and limitations: 100 single-byte characters.

SHIPTOCITY Name of city. Required if using a shipping address.

Character length and limitations: 40 single-byte characters.

SHIPTOSTATE State or province. Required if using a shipping address.

Character length and limitations: 40 single-byte characters.

SHIPTOZIP U.S. ZIP code or other country-specific postal code. Required if using a U.S.

shipping address; may be required for other countries. Character length and limitations: 20 single-byte characters.

SHIPTOCOUNTRY Country code. Required if using a shipping address.

Character limit: 2 single-byte characters.

PHONENUM (Optional) Phone number.

Character length and limit: 20 single-byte characters.

Payment Details Type Fields

Field Description

AMT (Required) The total cost of the transaction 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.

If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases.

Set this field to 0 if the transaction does not include a one-time purchase; for example, when you set up a billing agreement for a recurring payment that is not immediately charged.

CURRENCYCODE (Optional) A three-character currency code. Default: USD.

ITEMAMT (Optional) Sum of cost of all items in this order.

NOTE: ITEMAMT is required if you specify L_AMTn.

48 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

SetExpressCheckout API

Field Description

SHIPPINGAMT (Optional) Total shipping costs for this order.

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

NOTE: If you specify a value for SHIPPINGAMT, you must also specify a value for

ITEMAMT.

INSURANCEAMT (Optional) Total shipping insurance costs for this order. The value must be a non-

negative currency amount or null if insurance options are offered.

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

SHIPPINGDISCOUNT (Optional) Shipping discount for this order, specified as a negative number.

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

INSURANCEOPTIONOFFE RED

Character length and limitations: true or false

HANDLINGAMT (Optional) Total handling costs for this order.

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

NOTE: If you specify a value for HANDLINGAMT, you must also specify a value for

ITEMAMT.

TAXAMT (Optional) Sum of tax for all items in this order.

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

NOTE: TAXAMT is required if you specify L_TAXAMTn

DESC (Optional) Description of items the customer is purchasing.

Character length and limitations: 127 single-byte alphanumeric characters

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

Character length and limitations: 256 single-byte alphanumeric characters

Name-Value Pair API Developer Guide 08 April 2009 49

Express Checkout API Operations

SetExpressCheckout API

Field Description

INVNUM (Optional) Your own invoice or tracking number.

Character length and limitations: 127 single-byte alphanumeric characters

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

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

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

transaction.

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

50 08 April 2009 Name-Value Pair API Developer Guide

Payment Details Item Type Fields

Field Description

L_NAMEn (Optional) Item name.

These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).

Character length and limitations: 127 single-byte characters

L_DESCn (Optional) Item description.

Character length and limitations: 127 single-byte characters

L_AMTn (Optional) Cost of item.

These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).

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

NOTE: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

Express Checkout API Operations

SetExpressCheckout API

L_NUMBERn (Optional) Item number.

These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).

Character length and limitations: 127 single-byte characters

L_QTYn (Optional) Item quantity.

These parameters must be ordered sequentially beginning with 0 (for example L_QTY0, L_QTY1).

Character length and limitations: Any positive integer

L_TAXAMTn (Optional) Item sales tax.

NOTE: 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 must be ordered sequentially beginning with 0 (for example

L_TAXAMT0, L_TAXAMT1).

L_ITEMWEIGHTVALUEn, L_ITEMWEGHTUNITn

(Optional) Item weight corresponds to the weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

Character length and limitations: Any positive integer

L_ITEMLENGTHVALUEn L_I

TEMLENGTHUNITn

(Optional) Item the shipping carrier as is without having to make an additional database query.

length corresponds to the length of the item. You can pass this data to

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMLENGTHVALUE0, L_ITEMLENGTHVALUE1).

Character length and limitations: Any positive integer

Name-Value Pair API Developer Guide 08 April 2009 51

Express Checkout API Operations

SetExpressCheckout API

Field Description

L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn

L_ITEMHEIGHTVALUEn L_I

TEMHEIGHTUNITn

(Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

Character length and limitations: Any positive integer

(Optional) Item the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMHEIGHTVALUE0, L_ITEMHEIGHTVALUE1).

Character length and limitations: Any positive integer

height corresponds to the height of the item. You can pass this data to

52 08 April 2009 Name-Value Pair API Developer Guide

EbayItemPaymentDetailsItemType Fields

Field Description

L_EBAYITEMNUMBERn (Optional) Auction item number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).

Character length: 765 single-byte characters

Express Checkout API Operations

SetExpressCheckout API

L_EBAYITEMAUCTIONTX NIDn

(Optional) Auction transaction identification number. These parameters must be ordered sequentially beginning with 0 (for example

L_EBAYITEMAUCTIONTXNID0, L_EBAYITEMAUCTIONTXNID1). Character length: 255 single-byte characters

L_EBAYITEMORDERIDn (Optional) Auction order identification number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMORDERID0, L_EBAYITEMORDERID1).

Character length: 64 single-byte characters

Shipping Options Type Fields

Field Description

L_SHIPPINGOPTIONISD EFAULTn

Shipping option. Required if specifying the Callback URL. When the value of this flat rate shipping option is true, PayPal selects it by default

for the buyer and reflects it in the “default” total.

NOTE: There must be ONE and ONLY ONE default. It is not OK to have no default.

Character length and limitations: Boolean: true or false.

L_SHIPPINGOPTIONNAMEnShipping option. Required if specifying the Callback URL.

The internal name of the shipping option such as Air, Ground, Expedited, and so forth.

Character length and limitations: 50 character-string.

L_SHIPPINGOPTIONLAB ELn

Shipping option. Required if specifying the Callback URL. The label for the shipping option as displayed to the user. Examples include: Air:

Next Day, Expedited: 3-5 days, Ground: 5-7 days, and so forth. Shipping option labels can be localized based on the buyer’s locale, which PayPal sends to your website as a parameter value in the callback request.

Character length and limitations: 50 character-string.

L_SHIPPINGOPTIONAMO UNTn

Shipping option. Required if specifying the Callback URL. The amount of the flat rate shipping option. 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 (,).

Name-Value Pair API Developer Guide 08 April 2009 53

Express Checkout API Operations

GetExpressCheckoutDetails API

Billing Agreement Details Fields

Field Description

L_BILLINGTYPEn (Required) Type of billing agreement.

For recurring payments, this field must be set to RecurringPayments. In this case, you can specify up to ten billing agreements.

NOTE: Other defined values are not valid.

L_BILLINGAGREEMENTD ESCRIPTIONn

Description of goods or services associated with the billing agreement, which is required for each recurring payment billing agreement.

PayPal recommends that the description contain a brief summary of the billing agreement terms and conditions. For example, customer will be billed at “9.99 per month for 2 years”.

Character length and limitations: 127 single-byte alphanumeric bytes.

L_PAYMENTTYPEn (Optional) Specifies type of PayPal payment you require for the billing agreement.

z Any z InstantOnly

NOTE: For recurring payments, this field is ignored.

L_CUSTOMn (Optional) Custom annotation field for your own use.

NOTE: For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric bytes.

SetExpressCheckout Response

SetExpressCheckout Response Fields

Field Description

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

payment with Express Checkout. The token expires after three hours.If you set 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

GetExpressCheckoutDetails API

Obtain information about an Express Checkout transaction.

z “GetExpressCheckoutDetails Request” on page 55 z “GetExpressCheckoutDetails Response” on page 55

54 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

GetExpressCheckoutDetails API

GetExpressCheckoutDetails Request

GetExpressCheckoutDetails Request Fields

Field Description

METHOD (Required) Must be GetExpressCheckoutDetails.

TOKEN (Required) A timestamped token, the value of which was returned by

SetExpressCheckout response.

Character length and limitations: 20 single-byte characters

GetExpressCheckoutDetails Response

z GetExpressCheckoutDetails Response Fields z Payer Information Fields z Payer Name Fields z Ship To Address Fields z Payment Details Type Fields z Payment Details Item Type Fields z eBay Item Payment Details Item Type Fields

Name-Value Pair API Developer Guide 08 April 2009 55

Express Checkout API Operations

GetExpressCheckoutDetails API

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

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

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.

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

PAYPALADJUSTMENT A discount or gift certificate offered by PayPal to the buyer. This amount will be

represented by a negative amount. If the buyer has a negative PayPal account balance, PayPal adds the negative balance to the transaction amount, which is represented as a positive value.

NOTE The text entered by the buyer on the PayPal website if the ALLOWNOTE field was set

to 1 in SetExpressCheckout. Character length and limitations: 255 single-byte characters

REDIRECTREQUIRED Flag to indicate whether you need to redirect the customer to back to PayPal after

completing the transaction.

NOTE: Use this field only if you are using giropay or bank transfer payment methods

in Germany.

Payer Information Fields

Field Description

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. Valid values are:

z verified z unverified

Character length and limitations: 10 single-byte alphabetic characters.

56 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

GetExpressCheckoutDetails API

Field Description

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

BUSINESS Payer’s business name.

Character length and limitations: 127 single-byte characters

Name-Value Pair API Developer Guide 08 April 2009 57

Express Checkout API Operations

GetExpressCheckoutDetails API

Payer Name Fields

Field Description

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

Address Type Fields

Field Description

ADDRESSSTATUS Status of street address on file with PayPal

Valid values are:

z none z Confirmed z Unconfirmed

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

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 Required for U.S. addresses only.

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

Character length and limitations: 20 single-byte characters

SHIPTOCOUNTRYCODE Country code. See “Country Codes” on page 225.

Character limit: Two single-byte characters

58 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

GetExpressCheckoutDetails API

Payment Details Type Fields

Field Description

AMT (Required) The total cost of the transaction 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.

If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases.

Set this field to 0 if the transaction does not include a one-time purchase; for example, when you set up a billing agreement for a recurring payment that is not immediately charged.

CURRENCYCODE (Optional) A three-character currency code. Default: USD.

ITEMAMT (Optional) Sum of cost of all items in this order.

NOTE: ITEMAMT is required if you specify L_AMTn.

SHIPPINGAMT (Optional) Total shipping costs for this order.

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

NOTE: If you specify a value for SHIPPINGAMT, you must also specify a value for

ITEMAMT.

INSURANCEAMT (Optional) Total shipping insurance costs for this order. The value must be a non-

negative currency amount or null if insurance options are offered.

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

SHIPPINGDISCOUNT (Optional) Shipping discount for this order, specified as a negative number.

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

INSURANCEOPTIONOFFE RED

Character length and limitations: true or false

Name-Value Pair API Developer Guide 08 April 2009 59

Express Checkout API Operations

GetExpressCheckoutDetails API

Field Description

HANDLINGAMT (Optional) Total handling costs for this order.

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

NOTE: If you specify a value for HANDLINGAMT, you must also specify a value for

ITEMAMT.

TAXAMT (Optional) Sum of tax for all items in this order.

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

NOTE: TAXAMT is required if you specify L_TAXAMTn

DESC (Optional) Description of items the customer is purchasing.

Character length and limitations: 127 single-byte alphanumeric characters

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

Character length and limitations: 256 single-byte alphanumeric characters

INVNUM (Optional) Your own invoice or tracking number.

Character length and limitations: 127 single-byte alphanumeric characters

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

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

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

transaction.

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

60 08 April 2009 Name-Value Pair API Developer Guide

Payment Details Item Type Fields

Field Description

L_NAMEn (Optional) Item name.

These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).

Character length and limitations: 127 single-byte characters

L_AMTn (Optional) Cost of item.

These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).

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

NOTE: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

L_NUMBERn (Optional) Item number.

These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).

Character length and limitations: 127 single-byte characters

Express Checkout API Operations

GetExpressCheckoutDetails API

L_QTYn (Optional) Item quantity.

These parameters must be ordered sequentially beginning with 0 (for example L_QTY0, L_QTY1).

Character length and limitations: Any positive integer

L_TAXAMTn (Optional) Item sales tax.

NOTE: 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 must be ordered sequentially beginning with 0 (for example

L_TAXAMT0, L_TAXAMT1).

L_ITEMWEIGHTVALUEn, L_ITEMWEGHTUNITn

(Optional) Item weight corresponds to the weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

Character length and limitations: Any positive integer

L_ITEMLENGTHVALUEn, L_ITEMLENGTHUNITn

(Optional) Item length corresponds to the length of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMLENGTHVALUE0, L_ITEMLENGTHVALUE1).

Character length and limitations: Any positive integer

Name-Value Pair API Developer Guide 08 April 2009 61

Express Checkout API Operations

GetExpressCheckoutDetails API

Field Description

L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn

L_ITEMHEIGHTVALUEn, L_ITEMHEIGHTUNITn

(Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

Character length and limitations: Any positive integer

(Optional) Item height corresponds to the height of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMHEIGHTVALUE0, L_ITEMHEIGHTVALUE1).

Character length and limitations: Any positive integer

62 08 April 2009 Name-Value Pair API Developer Guide

User Selected Options Type Fields

Field Description

Express Checkout API Operations

DoExpressCheckoutPayment API

SHIPPINGCALCULATION MODE

INSURANCEOPTIONSELE

(Optional) Describes how the options that were presented to the user were determined. Is one of the following values:

z API - Callback z API - Flatrate

(Optional) The Yes/No option that you chose for insurance.

CTED

SHIPPINGOPTIONISDEF AULT

(Optional) Is true if the buyer chose the default shipping option. Character length and limitations: true or false

SHIPPINGOPTIONAMOUNT(Optional) The shipping amount that was chosen by the buyer

SHIPPINGOPTIONNAME (Optional) Is true if the buyer chose the default shipping option.

EbayItemPaymentDetailsItemType Fields

Field Description

L_EBAYITEMNUMBERn (Optional) Auction item number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).

Character length: 765 single-byte characters

L_EBAYITEMAUCTIONTX NIDn

(Optional) Auction transaction identification number. These parameters must be ordered sequentially beginning with 0 (for example

L_EBAYITEMAUCTIONTXNID0, L_EBAYITEMAUCTIONTXNID1). Character length: 255 single-byte characters

L_EBAYITEMORDERIDn (Optional) Auction order identification number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMORDERID0, L_EBAYITEMORDERID1).

Character length: 64 single-byte characters

DoExpressCheckoutPayment API

Completes an Express Checkout transaction. If you set up a billing agreement in your SetExpressCheckout API call, the billing

agreement is created when you call the DoExpressCheckoutPayment API operation.

z “DoExpressCheckoutPayment Request” on page 64 z “DoExpressCheckoutPayment Response” on page 71

Name-Value Pair API Developer Guide 08 April 2009 63

Express Checkout API Operations

DoExpressCheckoutPayment API

DoExpressCheckoutPayment Request

z DoExpressCheckout Request Fields z Payment Details Type Fields z eBay Item Payment Details Item Type Fields z Payment Details Item Type Fields z Address Fields

64 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

DoExpressCheckoutPayment API

DoExpressCheckoutPayment Request Fields

Field Description

METHOD (Required) Must be DoExpressCheckoutPayment.

TOKEN (Required) The timestamped token value that was returned by

SetExpressCheckout response and passed on GetExpressCheckoutDetails

request. Character length and limitations: 20 single-byte characters

PAYMENTACTION (Required) How you want to obtain payment:

z Authorization indicates that this payment is a basic authorization subject to

settlement with PayPal Authorization & Capture.

z Order indicates that this payment is is an order authorization subject to

settlement with PayPal Authorization & Capture.

z Sale indicates that this is a final sale for which you are requesting payment.

NOTE: You cannot set this value to Sale on SetExpressCheckout request and

then change this value to Authorization on the final PayPal Express Checkout API DoExpressCheckoutPayment request.

Character length and limit: Up to 13 single-byte alphabetic characters

PAYERID (Required) Unique PayPal customer account identification number as returned by

GetExpressCheckoutDetails response.Character length and limitations: 13

single-byte alphanumeric characters.

(Optional) Shipping options and insurance selected by the user.

RETURNFMFDETAILS (Optional) Flag to indicate whether you want the results returned by Fraud

Management Filters. By default, you do not receive this information.

z 0 - do not receive FMF details (default) z 1 - receive FMF details

Payment Details Type Fields

Field Description

AMT (Required) The total cost of the transaction 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.

If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases.

Set this field to 0 if the transaction does not include a one-time purchase; for example, when you set up a billing agreement for a recurring payment that is not immediately charged.

CURRENCYCODE (Optional) A three-character currency code. Default: USD.

Name-Value Pair API Developer Guide 08 April 2009 65

Express Checkout API Operations

DoExpressCheckoutPayment API

Field Description

ITEMAMT (Optional) Sum of cost of all items in this order.

NOTE: ITEMAMT is required if you specify L_AMTn.

SHIPPINGAMT (Optional) Total shipping costs for this order.

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

NOTE: If you specify a value for SHIPPINGAMT, you must also specify a value for

ITEMAMT.

INSURANCEAMT (Optional) Total shipping insurance costs for this order. The value must be a non-

negative currency amount or null if insurance options are offered.

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

SHIPPINGDISCOUNT (Optional) Shipping discount for this order, specified as a negative number.

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

INSURANCEOPTIONOFFE RED

Character length and limitations: true or false

HANDLINGAMT (Optional) Total handling costs for this order.

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

NOTE: If you specify a value for HANDLINGAMT, you must also specify a value for

ITEMAMT.

TAXAMT (Optional) Sum of tax for all items in this order.

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

NOTE: TAXAMT is required if you specify L_TAXAMTn

66 08 April 2009 Name-Value Pair API Developer Guide

Express Checkout API Operations

DoExpressCheckoutPayment API

Field Description

DESC (Optional) Description of items the customer is purchasing.

Character length and limitations: 127 single-byte alphanumeric characters

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

Character length and limitations: 256 single-byte alphanumeric characters

INVNUM (Optional) Your own invoice or tracking number.

Character length and limitations: 127 single-byte alphanumeric characters

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

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

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

transaction.

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

Name-Value Pair API Developer Guide 08 April 2009 67

Express Checkout API Operations

DoExpressCheckoutPayment API

Payment Details Item Type Fields

Field Description

L_NAMEn (Optional) Item name.

These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).

Character length and limitations: 127 single-byte characters

L_DESCn (Optional) Item description.

Character length and limitations: 127 single-byte characters

L_AMTn (Optional) Cost of item.

These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).

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

NOTE: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

L_NUMBERn (Optional) Item number.

These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).

Character length and limitations: 127 single-byte characters

L_QTYn (Optional) Item quantity.

These parameters must be ordered sequentially beginning with 0 (for example L_QTY0, L_QTY1).

Character length and limitations: Any positive integer

L_TAXAMTn (Optional) Item sales tax.

NOTE: 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 must be ordered sequentially beginning with 0 (for example

L_TAXAMT0, L_TAXAMT1).

L_ITEMWEIGHTVALUEn, L_ITEMWEGHTUNITn

(Optional) Item weight corresponds to the weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

Character length and limitations: Any positive integer

L_ITEMLENGTHVALUEn L_I

TEMLENGTHUNITn

(Optional) Item the shipping carrier as is without having to make an additional database query.

length corresponds to the length of the item. You can pass this data to

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMLENGTHVALUE0, L_ITEMLENGTHVALUE1).

Character length and limitations: Any positive integer

68 08 April 2009 Name-Value Pair API Developer Guide

Field Description

Express Checkout API Operations

DoExpressCheckoutPayment API

L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn

L_ITEMHEIGHTVALUEn L_I

TEMHEIGHTUNITn

(Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

Character length and limitations: Any positive integer

(Optional) Item the shipping carrier as is without having to make an additional database query.

These parameters must be ordered sequentially beginning with 0 (for example L_ITEMHEIGHTVALUE0, L_ITEMHEIGHTVALUE1).

Character length and limitations: Any positive integer

height corresponds to the height of the item. You can pass this data to

Name-Value Pair API Developer Guide 08 April 2009 69

Express Checkout API Operations

DoExpressCheckoutPayment API

User Selected Options Type Fields

Field Description

SHIPPINGCALCULATION MODE

INSURANCEOPTIONSELE

(Optional) Describes how the options that were presented to the user were determined. Is one of the following values:

z API - Callback z API - Flatrate

(Optional) The Yes/No option that you chose for insurance.

CTED

SHIPPINGOPTIONISDEF AULT

(Optional) Is true if the buyer chose the default shipping option. Character length and limitations: true or false

SHIPPINGOPTIONAMOUNT(Optional) The shipping amount that was chosen by the buyer

SHIPPINGOPTIONNAME (Optional) Is true if the buyer chose the default shipping option.

EbayItemPaymentDetailsItemType Fields

Field Description

L_EBAYITEMNUMBERn (Optional) Auction item number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).

Character length: 765 single-byte characters

L_EBAYITEMAUCTIONTX NIDn

(Optional) Auction transaction identification number. These parameters must be ordered sequentially beginning with 0 (for example

L_EBAYITEMAUCTIONTXNID0, L_EBAYITEMAUCTIONTXNID1). Character length: 255 single-byte characters

L_EBAYITEMORDERIDn (Optional) Auction order identification number.

These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMORDERID0, L_EBAYITEMORDERID1).

Character length: 64 single-byte characters

Address Fields

Field Description

NAME Person’s name associated with this shipping address. Required if using a

shipping address. Character length and limitations: 32 single-byte characters.

SHIPTOSTREET First street address. Required if using a shipping address.

Character length and limitations: 100 single-byte characters.

70 08 April 2009 Name-Value Pair API Developer Guide