Name-Value Pair API Developer Guide and Reference

Name-Value Pair API

Developer Guide and

Reference

Last updated: June 2008

PayPal Name-Value Pair API Developer Guide and Reference

Document Number: 100018.en_US-200806

© 2008 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners.

The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.

Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

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 and Reference

June 2008

3

Contents

4

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

SetExpressCheckout API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

SetExpressCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

SetExpressCheckout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

GetExpressCheckoutDetails API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

GetExpressCheckoutDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . 50

GetExpressCheckoutDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . 50

DoExpressCheckoutPayment API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

DoExpressCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . 57

DoExpressCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 5 GetTransactionDetails API . . . . . . . . . . . . . . . . . 67

GetTransactionDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

GetTransactionDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 6 MassPay API . . . . . . . . . . . . . . . . . . . . . . . . . 77

MassPay Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

MassPay Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapter 7 RefundTransaction API . . . . . . . . . . . . . . . . . . . 81

RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 8 TransactionSearch API . . . . . . . . . . . . . . . . . . . 83

TransactionSearch Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

June 2008


Contents

TransactionSearch Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 9 Recurring Payments and Reference Transactions API

Operations87

CreateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

CreateRecurringPaymentsProfile Request . . . . . . . . . . . . . . . . . . . . . . . 87

CreateRecurringPaymentsProfile Response . . . . . . . . . . . . . . . . . . . . . . 97

GetRecurringPaymentsProfileDetails API . . . . . . . . . . . . . . . . . . . . . . . . . . 98

GetRecurringPaymentsProfileDetails Request . . . . . . . . . . . . . . . . . . . . . 98

GetRecurringPaymentsProfileDetails Response . . . . . . . . . . . . . . . . . . . . 98

ManageRecurringPaymentsProfileStatus API . . . . . . . . . . . . . . . . . . . . . . . .105

ManageRecurringPaymentsProfileStatus Request . . . . . . . . . . . . . . . . . . .106

ManageRecurringPaymentsProfileStatus Response . . . . . . . . . . . . . . . . . .106

BillOutstandingAmount API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

BillOutstandingAmount Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

BillOutstandingAmount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

UpdateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

UpdateRecurringPaymentsProfile Request . . . . . . . . . . . . . . . . . . . . . . .108

UpdateRecurringPaymentsProfile Response . . . . . . . . . . . . . . . . . . . . . .113

SetCustomerBillingAgreement API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

SetCustomerBillingAgreement Request . . . . . . . . . . . . . . . . . . . . . . . . .114

SetCustomerBillingAgreement Response . . . . . . . . . . . . . . . . . . . . . . . .117

GetBillingAgreementCustomerDetails API . . . . . . . . . . . . . . . . . . . . . . . . . .117

GetBillingAgreementCustomerDetails Request . . . . . . . . . . . . . . . . . . . . .118

GetBillingAgreementCustomerDetails Response . . . . . . . . . . . . . . . . . . . .118

DoReferenceTransaction API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

DoReferenceTransaction Request. . . . . . . . . . . . . . . . . . . . . . . . . . . .120

DoReferenceTransaction Response. . . . . . . . . . . . . . . . . . . . . . . . . . .128

Chapter 10 DoNonReferencedCredit API . . . . . . . . . . . . . . . 135

DoNonReferencedCredit Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

DoNonReferencedCredit Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Chapter 11 Fraud Management Filters API Operations . . . . . . . . 139

Fraud Management Filters API Prerequisites . . . . . . . . . . . . . . . . . . . . . . . .139

ManagePendingTransactionStatus API . . . . . . . . . . . . . . . . . . . . . . . . . . .140

ManagePendingTransactionStatus Request. . . . . . . . . . . . . . . . . . . . . . .141


June 2008

5

6

Contents

ManagePendingTransactionStatus Response. . . . . . . . . . . . . . . . . . . . . .141

Chapter 12 GetBalance API . . . . . . . . . . . . . . . . . . . . . . 143

GetBalance Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

GetBalance Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Chapter 13 AddressVerify API . . . . . . . . . . . . . . . . . . . . . 145

AddressVerify Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

AddressVerify Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Chapter A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 149

General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151

Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155

SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .175

DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .177

Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .182

GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187

TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187

RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

Mass Pay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192

Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .202

GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .204

CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204

UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206

DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206

AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213

ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .213

Chapter B Country Codes . . . . . . . . . . . . . . . . . . . . . . 215

Chapter C State and Province Codes . . . . . . . . . . . . . . . . . 225

June 2008


Contents

Chapter D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 229

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

AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231

CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233


June 2008

7

Contents

8

June 2008


Preface

This Document

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

Name-Value Pair API.

Intended Audience

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

Revision History

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

T

ABLE

P.1 Revision History

Date

June 2008

April 2008

February 2008

January 2008

September 2007

August 2007

Description

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

Express Checkout Integration Guide.

Added Fraud Management Filters information. Changed recurring payments information.

Added that ther VERSION parameter must be 50.0 in the API call to use recurring payments. z z z z

Added billing agreement fields to SetExpressCheckout for recurring payments

Updated CreateRecurringPaymentsProfile for new recurring payments features.

Added new recurring payments APIs

Added DoNonReferencedCredit API z z z

Update eBay auctions for Express Checkout section

Added fields for the giropay payment method to Express Checkout APIs

Added Direct Payment error 10571.

Added recurring payments concepts, modified SetExpressCheckout,

DoExpressCheckoutPayment, DoReferenceTransaction, and added additional DoReferenceTransaction error codes.


June 2008

9

Revision History

T

ABLE

P.1 Revision History

Date

April 2007

February 2007

December 2006

October 2006

Description

Added Recurring Payments APIs: SetCustomerBillingAgreement,

GetBillingAgreementCustomerDetails, and

CreateRecurringPaymentsProfile.

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

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

CVV2.

Updates for bug fixes.

First public release.

10

June 2008


1

PayPal NVP API Overview

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

“Introducing the PayPal NVP API” on page 11

“Basic Steps” on page 12

z z

“Taking Your Application Live” on page 13

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

Accept PayPal in checkout on your website using Express Checkout.

Charge a credit card using Direct Payment.

Capture payments previously authorized through Express Checkout, Direct Payment, or

Website Payments Standard.

z z z z z

Reauthorize or void previous authorizations.

Pay one or more recipients using Mass Payment.

Issue full refunds or multiple partial refunds.

Search transactions using a start date or other criteria.

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:


June 2008

11

12

PayPal NVP API Overview

Basic Steps

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.

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.

N O T E

:

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:

June 2008



Taking Your Application Live

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

.

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.

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

.

I M P O R T A N T

:

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.

N O T E

:

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


June 2008

13

14


Technical Details

Modify Your Code

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

PayPal server values: z z

The server address in the URL. (See

“Posting Using HTTPS” on page 18

.)

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 at http://www.w3.org/Addressing/ .

NVP Format

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

An NVP string conforms to the following guidelines: z

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

FIRSTNAME=Robert

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

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

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:

June 2008



Technical Details

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

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

URL-Encoding Methods

Language

ASP.NET

Encode

Classic ASP

Java

PHP

ColdFusion

Decode

Encode

Decode

Encode

Decode

Encode

Decode

Encode

Decode

Method

System.Web.HttpUtility.UrlEncode(buffer,

Encoding.Default)

System.Web.HttpUtility.UrlDecode(buffer,

Encoding.Default)

Server.URLEncode

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

Internet.

java.net.URLEncoder.encode

java.net.URLDecoder.decode

urlencode() urldecode()

URLEncodedFormatstring [, charset ]

URLDecodeurlEncodedString[, 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

USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature&SUBJ

ECT=optionalThirdPartyEmailAddress&VERSION=3.2

The following parameters are always required:

USER

PWD

VERSION

N O T E

:

The examples show the required security parameters like this:

[requiredSecurityParameters]

Body Parameters

&METHOD=methodName&otherRequiredAndOptionalParameters


June 2008

15

16


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

PWD

VERSION=

<current version>

SIGNATURE

SUBJECT

(Required) Your PayPal API Username.

(Required) Your PayPal API Password.

(Required) Version number of the NVP API service, such as 51.0.

(Optional) Your PayPal API signature string.

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

(Optional) Email address of a PayPal account that has granted you permission to make this call.

Set this parameter only if you are calling an API on a different user’s behalf.


:

You must protect the values for USER, PWD, and SIGNATURE in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it.

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

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:

<form method=post action=https://api-3t.sandbox.paypal.com/nvp>



<input type=hidden name=USER value=xxxxxx.paypal.com>

<input type=hidden name=PWD value=abcdefg>

<input type=hidden name=SIGNATURE value=xxxxxxxxxxxxxxx>

...

</form>

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

June 2008



Technical Details

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

API Response Fields

ACK=Success&TIMESTAMP=date/timeOfResponse

&CORRELATIONID=debuggingToken&VERSION=3.200000

&BUILD=buildNumber

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

Each response includes the ACK field. If the ACK field’s value is Success or

SuccessWithWarning, you should process the API response fields. In a successful response, you can ignore all fields up to and including the BUILD field. The important fields begin after the BUILD field.

Error Responses

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

Format of an Error Response

Response Fields on

Error

ACK=Error&TIMESTAMP=date/timeOfResponse&

CORRELATIONID=debuggingToken&VERSION=3.200000&

BUILD=buildNumber&L_ERRORCODE0=errorCode&

L_SHORTMESSAGE0=shortMessage&

L_LONGMESSAGE0=longMessage&

L_SEVERITYCODE0=severityCode

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

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

ACK Parameter Values

The following table lists values for the ACK parameter.

ACK Parameter Values

Type of Response

Successful response

Error response

Value

Success

SuccessWithWarning

Failure

FailureWithWarning

Warning


June 2008

17


Posting Using HTTPS

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

June 2008


2

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

“DoAuthorization API” on page 23

“DoReauthorization API” on page 24

“DoVoid API” on page 25

DoCapture API

z z

“DoCapture Request” on page 20

DoCapture Response


June 2008

19

20

Authorization and Capture API Operation Reference

DoCapture API

DoCapture Request

DoCapture Request Fields

Field Description

METHOD

AUTHORIZATIONID

AMT

CURRENCYCODE

COMPLETETYPE

INVNUM

NOTE

(Required) Must be DoCapture.

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

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

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

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

N O T E

:

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.

(Optional) Your invoice number or other identification number that is displayed to the merchant and customer in his transaction history.

N O T E

:

This value on DoCapture will overwrite a value previously set on

DoAuthorization.

N O T E

:

The value is recorded only if the authorization you are capturing is an order authorization, not a basic authorization.

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

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

June 2008



DoCapture API

Field

SOFTDESCRIPTOR

Description

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

<PP * | PAYPAL *><Merchant descriptor as set in the Payment

Receiving Preferences><1 space><soft descriptor>

The soft descriptor can contain only the following characters: z

Alphanumeric characters z z z z

- (dash)

* (asterisk)

. (period)

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

The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools.

The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.

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

DoCapture Response Fields

Payer Information Fields

Ship To Address Fields

Payer Name Fields


June 2008

21

22


DoCapture API

Do Capture Response Fields


AUTHORIZATIONID

(See description) The authorization identification number you specified in the request.


PayerInfo Type Fields

Field

EMAIL

PAYERID

PAYERSTATUS

COUNTRYCODE

BUSINESS

Description

Email address of payer.

Character length and limitations: 127 single-byte characters.

Unique PayPal customer account identification number.

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

Status of payer. Valid values are: z z verified unverified

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

Payer’s country of residence in the form of ISO standard 3166 two-character country codes.

Character length and limitations: Two single-byte characters.

Payer’s business name.


Ship To Address Type Fields


ADDRESSSTATUS

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

Status of street address on file with PayPal.

Valid values are: z none z z

Confirmed

Unconfirmed

Person’s name associated with this address.


First street address.


Second street address.


Name of city.


June 2008



DoAuthorization API

Field

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

Payer Name Fields

Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Description

State or province.


Required for U.S. addresses only.

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


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

Description

Payer’s salutation.


Payer’s first name.


Payer’s middle name.


Payer’s last name


Payer’s suffix


DoAuthorization API

z z

DoAuthorization Request

DoAuthorization Response


June 2008

23

24


DoReauthorization API

DoAuthorization Request

DoAuthorization Request Fields


METHOD

TRANSACTIONID

AMT

TRANSACTIONENTITY

CURRENCYCODE

(Required) Must be DoAuthorization.

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

PayPal.


(Required) Amount to authorize.


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

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

DoAuthorization Response

DoAuthorization Response Fields


TRANSACTIONID

AMT

An authorization identification number.

The amount you specified in the request.

DoReauthorization API

z z

DoReauthorization Request

DoReauthorization Response

June 2008



DoVoid API

DoReauthorization Request

DoReauthorization Request Fields


METHOD

AUTHORIZATIONID

AMT

CURRENCYCODE

(Required) Must be DoReauthorization.

(Required) The value of a previously authorized transaction identification number returned by PayPal.


(Required) Amount to reauthorize.



DoReauthorization Response

DoReauthorization Response Fields


AUTHORIZATIONID

A new authorization identification number.

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

DoVoid API

z z

DoVoid Request

DoVoid Response


June 2008

25


DoVoid API

DoVoid Request

DoVoid Request Fields

Field

METHOD

AUTHORIZATIONID

NOTE

Description

(Required) Must be DoVoid.

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

PayPal product.

N O T E

:

If you are voiding a transaction that has been reauthorized, use the ID from the original authorization, and not the reauthorization.


(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


AUTHORIZATIONID

The authorization identification number you specified in the request.


26

June 2008


3

DoDirectPayment API

z z

DoDirectPayment Request

DoDirectPayment Response

DoDirectPayment Request

z z z z z z z z

DoDirectPayment Request Fields

Credit Card Fields


Payer Name Fields

Billing Address Fields

Payment Details Fields

Ebay Item Payment Details Fields



June 2008

27

28

DoDirectPayment API

DoDirectPayment Request

DoDirectPayment Request Fields


METHOD

PAYMENTACTION

IPADDRESS

RETURNFMFDETAILS

(Required) Must be DoDirectPayment.

(Optional) How you want to obtain payment: z z

Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture.

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

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

Default: Sale

N O T E

:

Order is not allowed for Direct Payment.

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

N O T E

:

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.

(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


CREDITCARDTYPE

ACCT

EXPDATE

(Required) Type of credit card.

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

Allowable values: z

Visa z z z z z

MasterCard

Discover

Amex

Maestro: See important note.

Solo: See important note.

N O T E

:

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

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

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

(See description) 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.

June 2008


Field

CVV2

STARTDATE

ISSUENUMBER

DoDirectPayment API


Description

(determined by account settings) 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, once a transaction has been completed, you must not store the value of CVV2.

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

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

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


June 2008

29

30

DoDirectPayment API



Field

EMAIL

PAYERID

PAYERSTATUS

COUNTRYCODE

BUSINESS

Description





Status of payer. Valid values are: z verified z unverified







Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Description







Payer’s last name


Payer’s suffix


Address Fields

Field

STREET

STREET2

CITY

Description

(Required) First street address.


(Optional) Second street address.


(Required) Name of city.


June 2008


Field

STATE

COUNTRYCODE

ZIP

PHONENUM

DoDirectPayment API


Description

(Required) State or province.


(Required) Country code.

Character limit: Two single-byte characters.

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


(Optional) Phone number.

Character length and limit: 20 single-byte characters.


June 2008

31

32

DoDirectPayment API


Payment Details Type Fields


AMT

CURRENCYCODE

ITEMAMT

SHIPPINGAMT

INSURANCEAMT

SHIPPINGDISCOUNT

(Required) Total amount of order, including shipping, handling, and tax.

N O T E

:

Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period

(.), and the optional thousands separator must be a comma (,).

N O T E

:

You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.

A three-character currency code. Default: USD.

(See description) Sum of cost of all items in this order.

Limitations: Must not exceed $10,000 USD in any currency. No currency symbol.

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

N O T E

:

ITEMAMT is required if you specify L_AMT

n

.

(Optional) Total shipping costs for this order.

N O T E

:

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.

N O T E

:

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

ITEMAMT.

(Optional) Total shipping insurance costs for this order.

N O T E

:



N O T E

:


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

N O T E

:



N O T E

:


June 2008


Field

HANDLINGAMT

TAXAMT

DESC

CUSTOM

INVNUM

BUTTONSOURCE

NOTIFYURL

DoDirectPayment API


Description

(Optional) Total handling costs for this order.

N O T E

:



N O T E

:

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

ITEMAMT.

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

N O T E

:



N O T E

:

TAXAMT is required if you specify L_TAXAMT

n

(Optional) Description of items the customer is purchasing.

Character length and limitations: 127 single-byte alphanumeric characters

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


(Optional) Your own invoice or tracking number.


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


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

N O T E

:

If you do not specify this value in the request, the notification URL from your

Merchant Profile is used, if one exists.

Character length and limitations: 2,048 single-byte alphanumeric characters


June 2008

33

34

DoDirectPayment API


Payment Details Item Type Fields


L_NAMEn

L_DESCn

L_AMTn

L_NUMBERn

L_QTYn

L_TAXAMTn

(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

(Optional) Item description.


(Optional) Cost of item


L_AMT0, L_AMT1).

N O T E

:



N O T E

:

If you specify a value for L_AMT

n

, you must specify a value for ITEMAMT.

(Optional) Item number.


L_NUMBER0, L_NUMBER1).


(Optional) Item quantity.


L_QTY0, L_QTY1).

Character length and limitations: Any positive integer

(Optional) Item sales tax.

N O T E

:




L_TAXAMT0, L_TAXAMT1).

EbayItemPaymentDetailsItemType Fields


L_EBAYITEMNUMBERn

(Optional) Auction item number.


L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).

Character length: 765 single-byte characters.

June 2008


DoDirectPayment API



L_EBAYITEMAUCTIONTX

NIDn

(Optional) Auction transaction identification number.


L_EBAYITEMAUCTIONTXNID0, L_EBAYITEMAUCTIONTXNID1).

Character length: 255 single-byte characters

L_EBAYITEMORDERIDn

(Optional) Auction order identification number.


L_EBAYITEMORDERID0, L_EBAYITEMORDERID1).



June 2008

35

36

DoDirectPayment API

DoDirectPayment Response

Ship To Address Fields

Field

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

SHIPTOPHONENUM

Description

(See description) Person’s name associated with this address. This field is required for shipping addresses but is optional for credit card billing addresses.








(Required) State or province for United States addresses.





Character limit: 2 single-byte characters.



DoDirectPayment Response

DoDirectPayment Response Fields

Field

TRANSACTIONID

Description

Unique transaction ID of the payment.

N O TE

:

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

TransactionID is your AuthorizationID for use with the Authorization &

Capture APIs.


AMT

AVSCODE

CVV2MATCH

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

DoDirectPaymentRequest for reference transactions with direct payments.

Address Verification System response code. See “AVS and CVV2 Response Codes” on page 231 for possible values.

Character limit: One single-byte alphanumeric character

Result of the CVV2 check by PayPal.

June 2008


Field

L_FMF

filter

ID

n

L_FMF

filter

NAME

n

DoDirectPayment API


Description

Filter ID, including the ID number, and the entry number, starting from 0.

The ID number is one of the following values: z

1 = AVS No Match z z

2 = AVS Partial Match

3 = AVS Unavailable/Unsupported z z z z

4 = Card Security Code (CSC) Mismatch

5 = Maximum Transaction Amount

6 = Unconfirmed Address

7 = Country Monitor z z z z z z z z z z

8 = Large Order Number

9 = Billing/Shipping Address Mismatch

10 = Risky ZIP Code

11 = Suspected Freight Forwarder Check

12 = Total Purchase Price Minimum

13 = IP Address Velocity

14 = Risky Email Address Domain Check

15 = Risky Bank Identification Number (BIN) Check

16 = Risky IP Address Range

17 = PayPal Fraud Model

Filter name, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.


June 2008

37

DoDirectPayment API


38

June 2008


4

Express Checkout API

Operations

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

“SetExpressCheckout API” on page 39

z z

“GetExpressCheckoutDetails API” on page 49

“DoExpressCheckoutPayment API” on page 57

SetExpressCheckout API

z z

“SetExpressCheckout Request” on page 39

“SetExpressCheckout Response” on page 49

SetExpressCheckout Request

z z z z z z

SetExpressCheckout Request Fields

Address Fields

“Payment Details Type Fields” on page 44

“Payment Details Item Type Fields” on page 47

“EbayItemPaymentDetailsItemType Fields” on page 47

Billing Agreement Details Fields


June 2008

39

40

Express Checkout API Operations

SetExpressCheckout API

SetExpressCheckout Request Fields


METHOD

TOKEN

AMT

(Required) Must be SetExpressCheckout.

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

SetExpressCheckout response.


(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. If the transaction does not include a one-time purchase, this field can be set to 0.



N O T E

:


CURRENCYCODE

MAXAMT

DESC

CUSTOM

INVNUM

(Optional) A three-character currency code. Default: USD. See “Currency Codes” on page 229 .

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



N O T E

:




(Optional) A free-form field for your own use, such as a tracking number or other value you want PayPal to return on GetExpressCheckoutDetails response and

DoExpressCheckoutPayment response.


(Optional) Your own unique invoice or tracking number. PayPal returns this value to you on DoExpressCheckoutPayment response.

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


June 2008




Field

RETURNURL

CANCELURL

Description

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

N O T E

:

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

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

PayPal to pay you.

N O T E

:

PayPal recommends that the value be the original page on which the customer chose to pay with PayPal or establish a billing agreement.

Character length and limitations: 2048 characters

REQCONFIRMSHIPPING

(Optional) The value 1 indicates that you require that the customer’s shipping address on file with PayPal be a confirmed address.

N O T E

:

Setting this field overrides the setting you have specified in your 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.



ALLOWNOTE

ADDRESSOVERRIDE

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



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




June 2008

41

42



Field

LOCALECODE

PAGESTYLE

HDRIMG

HDRBORDERCOLOR

HDRBACKCOLOR

PAYFLOWCOLOR

EMAIL

SOLUTIONTYPE

Description

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

DE

FR z z z z

IT

GB

ES

US

Any other value will default to US. See “Country Codes” on page 215 .

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


(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

(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

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


ASCII

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


ASCII

(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

(Optional) Type of checkout flow: z

Sole: Express Checkout for auctions z

Mark: normal Express Checkout

June 2008




Field

LANDINGPAGE

CHANNELTYPE

GIROPAYSUCCESSURL

GIROPAYCANCELURL

BANKTXNPENDINGURL

L_BILLINGTYPE

L_BILLINGAGREEMENT

DESCRIPTION

n

L_CUSTOM

n

L_PAYMENTTYPE

n n

Description

(Optional) Type of PayPal page to display: z

Billing: non-PayPal account z

Login: PayPal account login

(Optional) Type of channel: z z

Merchant: non-auction seller eBayItem: eBay auction

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

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


Germany.

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


Germany.

Type of billing agreement.

For recurring payments, this field is required and must be set to

RecurringPayments.

Description of goods or services associated with the billing agreement.

PayPal recommends that you provide a brief summary of the terms & conditions of the billing agreement.

Custom annotation field for your own use.

N O T E

:

This field is ignored for recurring payments.

Specifies type of PayPal payment you require for the billing agreement, which is one of the following values.

z z

Any

InstantOnly

N O T E

:

This field is ignored for recurring payments.


June 2008

43

44



Address Fields

Field

NAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRY

PHONENUM

Description

(Required) Person’s name associated with this shipping address.


















AMT

CURRENCYCODE

ITEMAMT


N O T E

:



N O T E

:






N O T E

:


n

.

June 2008




Field

SHIPPINGAMT

INSURANCEAMT

SHIPPINGDISCOUNT

HANDLINGAMT

TAXAMT

DESC

CUSTOM

INVNUM

Description


N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:



N O T E

:



N O T E

:



N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:


n








June 2008

45



Field

BUTTONSOURCE

NOTIFYURL

Description




N O T E

:




46

June 2008






L_NAMEn

L_DESCn

L_AMTn

L_NUMBERn

L_QTYn

L_TAXAMTn



L_NAME0, L_NAME1).






L_AMT0, L_AMT1).

N O T E

:



N O T E

:


n








L_QTY0, L_QTY1).



N O T E

:







L_EBAYITEMNUMBERn






June 2008

47




L_EBAYITEMAUCTIONTX

NIDn





L_EBAYITEMORDERIDn





48

June 2008



GetExpressCheckoutDetails API

Billing Agreement Details Fields


L_BILLINGTYPEn

L_BILLINGAGREEMENTD

ESCRIPTIONn

L_PAYMENTTYPEn

L_CUSTOMn

(Required) Type of billing agreement. For reference transactions, this field must be

MerchantInitiatedBilling, which requests PayPal to prompt the buyer to set up a billing agreement for recurring payments. For recurring payments, the value must be RecurringPayments.

N O T E

:

Other defined values are not valid.

(Optional) Description of goods or services associated with the 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.

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

Any

InstantOnly

(Optional) Custom annotation field for your own use.


SetExpressCheckout Response

SetExpressCheckout Response Fields


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.


GetExpressCheckoutDetails API

z z

“GetExpressCheckoutDetails Request” on page 50

“GetExpressCheckoutDetails Response” on page 50


June 2008

49



GetExpressCheckoutDetails Request

GetExpressCheckoutDetails Request Fields


METHOD

TOKEN

(Required) Must be GetExpressCheckoutDetails.

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

SetExpressCheckout response.


GetExpressCheckoutDetails Response

z z z z z z z

GetExpressCheckoutDetails Response Fields


Payer Name Fields



Item Details Fields

Ebay Item Details Fields

50

June 2008




GetExpressCheckoutDetails Response Fields


TOKEN

CUSTOM

INVNUM

PHONENUM

ADJUSTMENT

NOTE

REDIRECTREQUIRED

The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request.


A free-form field for your own use, as set by you in the Custom element of

SetExpressCheckout request.


Your own invoice or tracking number, as set by you in the element of the same name in SetExpressCheckout request .


Payer’s contact telephone number.

N O TE

:

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)

A discount or gift certificate offered by PayPal to the buyer. This amount will be represented by a negative amount. If the buyer has a negative PayPal account balance, PayPal adds the negative balance to the transaction amount, which is represented as a positive value.

The text entered by the buyer on the PayPal website if the ALLOWNOTE field was set to 1 in SetExpressCheckout.


Flag to indicate whether you need to redirect the customer to back to PayPal after completing the transaction.

N O TE

:

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

Payer Information Fields


EMAIL

PAYERID

PAYERSTATUS








June 2008

51



Field

COUNTRYCODE

BUSINESS

Description


Character length and limitations: Two single-byte characters



52

June 2008





Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Address Type Fields

Field

ADDRESSSTATUS

Description







Payer’s last name.Character length and limitations: 25 single-byte characters

Payer’s suffix.Character length and limitations: 12 single-byte characters

SHIPTONAME

SHIPTOSTREET

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

Description

Status of street address on file with PayPal

Valid values are: z z z none

Confirmed

Unconfirmed

(Required) Person’s name associated with this address.








(Optional) State or province.





(Required) Country code. See “Country Codes” on page 215 .

Character limit: Two single-byte characters


June 2008

53

54





AMT

CURRENCYCODE

ITEMAMT

SHIPPINGAMT

INSURANCEAMT

SHIPPINGDISCOUNT


N O T E

:



N O T E

:






N O T E

:


n

.


N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:



N O T E

:



N O T E

:


June 2008


Field

HANDLINGAMT

TAXAMT

DESC

CUSTOM

INVNUM

BUTTONSOURCE

NOTIFYURL



Description


N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:


n










N O T E

:





June 2008

55

56





L_NAMEn

L_DESCn

L_AMTn

L_NUMBERn

L_QTYn

L_TAXAMTn



L_NAME0, L_NAME1).






L_AMT0, L_AMT1).

N O T E

:



N O T E

:


n








L_QTY0, L_QTY1).



N O T E

:







L_EBAYITEMNUMBERn





June 2008



DoExpressCheckoutPayment API


L_EBAYITEMAUCTIONTX

NIDn





L_EBAYITEMORDERIDn





DoExpressCheckoutPayment API

z z

“DoExpressCheckoutPayment Request” on page 57

“DoExpressCheckoutPayment Response” on page 62

DoExpressCheckoutPayment Request

z z z z z

DoExpressCheckout Request Fields


Payment Details Item Fields

Ebay Item Payment Details Fields

Address Fields


June 2008

57

58



DoExpressCheckoutPayment Request Fields


METHOD

TOKEN

PAYMENTACTION

PAYERID

RETURNFMFDETAILS

(Required) Must be DoExpressCheckoutPayment.

(Required) The timestamped token value that was returned by

SetExpressCheckout response and passed on GetExpressCheckoutDetails request.


(Required) How you want to obtain payment: z


z z

Order indicates that this payment is is an order authorization subject to settlement with PayPal Authorization & Capture.


N O T E

:

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

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

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



z z

0 - do not receive FMF details (default)




AMT

CURRENCYCODE

ITEMAMT


N O T E

:



N O T E

:






N O T E

:


n

.

June 2008




Field

SHIPPINGAMT

INSURANCEAMT

SHIPPINGDISCOUNT

HANDLINGAMT

TAXAMT

DESC

CUSTOM

INVNUM

Description


N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:



N O T E

:



N O T E

:



N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:


n








June 2008

59



Field

BUTTONSOURCE

NOTIFYURL

Description




N O T E

:




60

June 2008






L_NAMEn

L_DESCn

L_AMTn

L_NUMBERn

L_QTYn

L_TAXAMTn



L_NAME0, L_NAME1).






L_AMT0, L_AMT1).

N O T E

:



N O T E

:


n








L_QTY0, L_QTY1).



N O T E

:







L_EBAYITEMNUMBERn






June 2008

61

62




L_EBAYITEMAUCTIONTX

NIDn





L_EBAYITEMORDERIDn





Address Fields

Field

NAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRY

PHONENUM

Description

(Required) Person’s name associated with this shipping address.
















DoExpressCheckoutPayment Response

z z

DoExpressCheckoutPayment Response Fields

Payment Information Fields

June 2008




DoExpressCheckoutPayment Response Fields


TOKEN

NOTE

The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request.


The text entered by the buyer on the PayPal website if the ALLOWNOTE field was set to 1 in SetExpressCheckout.


REDIRECTREQUIRED

L_FMF

L_FMF

filter filter

ID

n

NAME

n

Flag to indicate whether you need to redirect the customer to back to PayPal after completing the transaction.

N O TE

:

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

Filter ID, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.


Payment Information Fields


TRANSACTIONID

TRANSACTIONTYPE

PAYMENTTYPE

ORDERTIME


N O T E

:

If the PaymentAction of the request was Authorization or Order, this value is your AuthorizationID for use with the Authorization & Capture

APIs.

Character length and limitations:19 single-byte characters

The type of transaction


Valid values: z z cart express-checkout

Indicates whether the payment is instant or delayed.

Character length and limitations: Seven single-byte characters

Valid values: z none z z echeck instant

Time/date stamp of payment


June 2008

63



Field

AMT

CURRENCYCODE

FEEAMT

SETTLEAMT

TAXAMT

EXCHANGERATE

PAYMENTSTATUS

Description

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

Profile.

Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.

A three-character currency code.

PayPal fee amount charged for the transactionCharacter length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.

Amount deposited in your PayPal account after a currency conversion.

Tax charged on the transaction.


Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account.Character length and limitations: a decimal that does not exceed 17 characters, including decimal point

Status of the payment:Completed: The payment has been completed, and the funds have been added successfully to your account balance.

Pending: The payment is pending. See the PendingReason element for more information.

64

June 2008


Field

PENDINGREASON

REASONCODE



Description

The reason the payment is pending: z none: No pending reason z z address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.

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

z z z z intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.

multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.

verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.

other: The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service.

The reason for a reversal if TransactionType is reversal: z none: No reason code z z chargeback: A reversal has occurred on this transaction due to a chargeback by your customer.

guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee.

z z z buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer.

refund: A reversal has occurred on this transaction because you have given the customer a refund.

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


June 2008

65



66

June 2008


5

GetTransactionDetails API

z z

“GetTransactionDetails Request” on page 67

“GetTransactionDetails Response” on page 67

GetTransactionDetails Request

GetTransactionDetails Request Fields


METHOD

TRANSACTIONID

Must be GetTransactionDetails.

(Required) Unique identifier of a transaction.

N O T E

:

The details for some kinds of transactions cannot be retrieved with

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

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

GetTransactionDetails Response

N O T E

:

z z

All fields defined in the formal structure of GetTransactionDetailsResponse are not necessarily returned. Data are returned in a response only if PayPal has recorded data that corresponds to the field.

Receiver Information Fields

Payer Information Fields z z z z

Address Fields

Payer Name Fields

Payer Name Fields

Payment Information Fields z z z

Payment Item Information Fields

Subscription Fields

Subscriptions Terms Fields


June 2008

67

68

GetTransactionDetails API

GetTransactionDetails Response

Receiver Information Fields


RECEIVEREMAIL

RECEIVERID

Primary email address of the payment recipient (the seller).

If you are the recipient of the payment and the payment is sent to your non-primary email address, the value of Receiver is still your primary email address.


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



EMAIL

PAYERID

PAYERSTATUS

SHIPTOCOUNTRYCODE

PAYERBUSINESS












Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Description







Payer’s last name


Payer’s suffix


June 2008




Address Fields

Field

ADDRESSOWNER

ADDRESSSTATUS

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

Description

eBay company that maintains this address.

Valid values are: z eBay z

PayPal



Confirmed

Unconfirmed







Name of city.


State or province.






Expanded name of country.



SHIPTOPHONENUM



TRANSACTIONID




June 2008

69

70




PARENTTRANSACTIONID z

Parent or related transaction identification number. This field is populated for the following transaction types: z

Reversal. Capture of an authorized transaction.

z z z z z

Reversal. Reauthorization of a transaction.

Capture of an order. The value of ParentTransactionID is the original

OrderID.

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

OrderID.

Capture of an order authorization.

Void of an order. The value of ParentTransactionID is the original OrderID.

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

RECEIPTID

Receipt identification number

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

TRANSACTIONTYPE

PAYMENTTYPE

ORDERTIME

AMT

CURRENCYCODE

FEEAMT

SETTLEAMT


Valid values: z cart z express-checkout




Valid values: z z z none echeck instant

Time/date stamp of payment. For example: 2006-08-15T17:23:15Z.


Profile.





June 2008


Field

TAXAMT

EXCHANGERATE

PAYMENTSTATUS



Description




Status of the payment.

The status of the payment: z

None: No status z z

Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you.

Completed: The payment has been completed, and the funds have been added successfully to your account balance.

z z z z

Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element.

Expired: the authorization period for this payment has been reached.

Failed: The payment has failed. This happens only if the payment was made from your customer’s bank account.

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

z z z z

Refunded: You refunded the payment.

Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element.

Processed: A payment has been accepted.

Voided: An authorization for this transaction has been voided.


June 2008

71

72



Field

PENDINGREASON

REASONCODE

Description

N O T E

:

PendingReason is returned in the response only if PaymentStatus is

Pending.

The reason the payment is pending: z z z z z z z none: No pending reason address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.


intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.




The reason for a reversal if TransactionType is reversal: z z none: No reason code chargeback: A reversal has occurred on this transaction due to a chargeback by your customer.

z z z z guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee.

buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer.



June 2008




Payment Item Information Fields


INVNUM

CUSTOM

NOTE

SALESTAX

Invoice number you set in the original transaction.


Custom field you set in the original transaction.


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


Amount of tax charged on payment.

Payment Item Fields

Field

L_DESCn

L_NUMBERn

L_QTYn

L_AMTn

L_OPTIONSNAMEn

L_OPTIONSVALUEn

Description

Amount of tax charged on payment.


L_DESC0, L_DESC1).

Item number set by you. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_number variable. For example, item_number1, item_number2, and so forth.Character length and limitations: 127 single-byte alphanumeric characters



Quantity set by you or entered by the customer.

Character length and limitations: no limit

Cost of item.


L_AMT0, L_AMT1).

PayPal option names for an item in the shopping cart; each name corresponds to an option value. There can be multiple option names per item.

The option names are ordered sequentially beginning with 0 (for example,

L_OPTIONSNAMES0, L_OPTIONSNAME1).

PayPal option values corresponding to option names of an item in the shopping cart.

The option names are ordered sequentially beginning with 0 (for example,

L_OPTIONSVALUE0, L_OPTIONSVALUE1).

Subscription Fields

Field

SUBSCRIPTIONID

SUBSCRIPTIONDATE

Description

ID generated by PayPal for the subscriber.


Subscription start date


June 2008

73



Field

EFFECTIVEDATE

RETRYTIME

USERNAME

PASSWORD

RECURRENCES

REATTEMPT

RECURRING

Description

Date when the subscription modification will be effective

Date PayPal will retry a failed subscription payment..

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

Character length and limitations: 64 alphanumeric single-byte characters

Password generated by PayPal and given to subscriber to access the subscription. For security, the value of the password is hashed.

Character length and limitations: 128 alphanumeric single-byte characters

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

Character length and limitations: no limit.

Indicates whether reattempts should occur upon payment failures.

Indicates whether regular rate recurs.

1 = Yes.

Subscription Terms Fields


PERIOD

The amount subscriber is to be charged in one payment.Character length and limitations: no limit

The period of time that the subscriber will be charged.


74

June 2008





June 2008

75



76

June 2008


6

MassPay API

z z

“MassPay Request” on page 77

“MassPay Response” on page 79

MassPay Request

z z

MassPay Request Fields

MassPay Item Details Fields


June 2008

77

78

MassPay API

MassPay Request

MassPay Request Fields


METHOD

EMAILSUBJECT

CURRENCYCODE

RECEIVERTYPE

Must be MassPay.

(Optional) The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients.



(Optional) Indicates how you identify the recipients of payments in this call to

MassPay.

Must be EmailAddress or UserID

MassPay Item Type Fields


L_EMAILn

L_RECEIVERIDn

(See description) Email address of recipient.

N O T E

:

You must specify either L_EMAIL

n

or L_RECEIVERID

n

, but you must not mix the two in the group of MassPay items. Use only one or the other, but not both, in a single request.


L_EMAIL0, L_EMAIL1).

Character length and limitations: 127 single-byte characters maximum.

(See description) Unique PayPal customer account number. This value corresponds to the value of PayerID returned by GetTransactionDetails.

N O T E

:

You must specify either L_EMAIL

n

or L_RECEIVERID

n

, but you must not mix the two in the group of MassPay items. Use only one or the other, but not both, in a single request.


L_RECEIVERID0, L_RECEIVERID1).


L_AMTn

L_UNIQUEIDn

L_NOTEn

(Required) Payment amount.


L_AMT0, L_AMT1).

N O T E

:

You cannot mix currencies in a single MassPayRequest. A single request must include items that are of the same currency.

(Optional) Transaction-specific identification number for tracking in an accounting system.


L_UNIQUEID0, L_UNIQUEID1).

Character length and limitations: 30 single-byte characters. No whitespace allowed.

(Optional) Custom note for each recipient.

Character length and limitations: 4,000 single-byte alphanumeric characters.

June 2008


MassPay Response

The fields in the response are the standard response header fields.

MassPay API

MassPay Response


June 2008

79

MassPay API

MassPay Response

80

June 2008


7

RefundTransaction API

z z

“RefundTransaction Request” on page 81

“RefundTransaction Response” on page 81

RefundTransaction Request

RefundTransaction Request Fields


METHOD

TRANSACTIONID

REFUNDTYPE

AMT

NOTE

Must be RefundTransaction.

(Required) Unique identifier of a transaction.


(Required) Type of refund you are making: z

Other z z

Full

Partial

(See description) Refund amount.

Amount is required if RefundType is Partial.

N O T E

:

If RefundType is Full, do not set Amount.

(Optional) Custom memo about the refund.


RefundTransaction Response

RefundTransaction Response Fields


REFUNDTRANSACTIONID

Unique transaction ID of the refund.

Character length and limitations:17 single-byte characters.

FEEREFUNDAMT

Transaction fee refunded to original recipient of payment.

GROSSREFUNDAMT

Amount of money refunded to original payer.


June 2008

81

RefundTransaction API

RefundTransaction Response

Field

NETREFUNDAMT

Description

Amount subtracted from PayPal balance of original recipient of payment to make this refund.

82

June 2008


8

TransactionSearch API

z z

“TransactionSearch Request” on page 83

“TransactionSearch Response” on page 86

TransactionSearch Request

z z

“TransactionSearch Request Fields” on page 84

“Payer Name Fields” on page 86


June 2008

83

84

TransactionSearch API

TransactionSearch Request

TransactionSearch Request Fields


METHOD

STARTDATE

ENDDATE

EMAIL

RECEIVER

RECEIPTID

TRANSACTIONID

Must be TransactionSearch.

(Required) The earliest transaction date at which to start the search.

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

(Optional) The latest transaction date to be included in the search.

(Optional) Search by the buyer’s email address.


(Optional) Search by the receiver’s email address. If the merchant account has only one email, this is the primary email. Can also be a non-primary email.

(Optional) Search by the PayPal Account Optional receipt ID.

INVNUM

ACCT

AUCTIONITEMNUMBER

(Optional) Search by the transaction ID. The returned results are from the merchant’s transaction records.


(Optional) Search by invoice identification key, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased.

N O T E

:

No wildcards are allowed.


(Optional) Search by credit card number, as set by you for the original transaction.

This field searches the records for items sold by the merchant, not the items purchased.

N O T E

:

No wildcards are allowed.

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

(Optional) Search by auction item number of the purchased goods.

June 2008



TransactionSearch Request

Field

TRANSACTIONCLASS

AMT

STATUS

Description

(Optional) Search by classification of transaction.

Some kinds of possible classes of transactions are not searchable with this field. You cannot search for bank transfer withdrawals, for example.

z

All: all transaction classifications z z z z

Sent: only payments sent

Received: only payments received

MassPay: only mass payments

MoneyRequest: only money requests z z z z z z z z

FundsAdded: only funds added to balance

FundsWithdrawn: only funds withdrawn from balance

Referral: only transactions involving referrals

Fee: only transactions involving fees

Subscription: only transactions involving subscriptions

Dividend: only transactions involving dividends

Billpay: only transactions involving BillPay Transactions

Refund: only transactions involving funds z z z z z z

CurrencyConversions: only transactions involving currency conversions

BalanceTransfer: only transactions involving balance transfers

Reversal: only transactions involving BillPay reversals

Shipping: only transactions involving UPS shipping fees

BalanceAffecting: only transactions that affect the account balance

ECheck: only transactions involving eCheck

(Optional) Search by transaction amount.

N O T E

:


(Optional) Search by currency code.

(Optional) Search by transaction status: z z z z z

Pending: The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field.

Processing: The payment is being processed.

Success: The payment has been completed and the funds have been added successfully to your account balance.

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

Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer.


June 2008

85

86


TransactionSearch Response


Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Description







Payer’s last name


Payer’s suffix


TransactionSearch Response

TransactionSearch Response Fields


L_TIMESTAMPn

L_TIMEZONEn

L_TYPEn

L_EMAILn

The date and time (in UTC/GMT format) the transaction occurred.

The time zone of the transaction.

The type of the transaction.

The email address of either the payer or the payment recipient (the “payee”). If the payment amount is positive, this field is the recipient of the funds. If the payment is negative, this field is the paying customer.

L_NAMEn

L_TRANSACTIONIDn

L_STATUSn

L_AMTn

L_FEEAMTn

L_NETAMTn

Display name of the payer.

Seller’s transaction ID.

The status of the transaction.

The total gross amount charged, including any profile shipping cost and taxes.

The fee that PayPal charged for the transaction.

The net amount of the transaction.

June 2008


9

Recurring Payments and

Reference Transactions API

Operations

This chapter describes the PayPal API operations related to recurring payments and reference transactions: z z

“CreateRecurringPaymentsProfile API” on page 87

“GetRecurringPaymentsProfileDetails API” on page 98

z z z z z z

“ManageRecurringPaymentsProfileStatus API” on page 105

“BillOutstandingAmount API” on page 106

“UpdateRecurringPaymentsProfile API” on page 107

“SetCustomerBillingAgreement API” on page 113

“GetBillingAgreementCustomerDetails API” on page 117

“DoReferenceTransaction API” on page 120

CreateRecurringPaymentsProfile API

z z

“CreateRecurringPaymentsProfile Request” on page 87

“CreateRecurringPaymentsProfile Response” on page 97

CreateRecurringPaymentsProfile Request

z z z z z z z z

CreateRecurringPaymentsProfile Request

Recurring Payments Profile Details

Schedule Details

Billing Period Details

Activation Details

Ship To Address

Credit Card Details

Payer Information


June 2008

87

Recurring Payments and Reference Transactions API Operations

CreateRecurringPaymentsProfile API

z z

Payer Name

Billing Address

88

June 2008




CreateRecurringPaymentsProfile Request Fields


METHOD

TOKEN

(Required) Must be DoDirectPayment.

(See description) A timestamped token, the value of which was returned in the response to the first call to SetExpressCheckout. You can also use the token returned in the SetCustomerBillingAgreement response.

Call CreateRecurringPaymentsProfile once for each billing agreement included in SetExpressCheckout request and use the same token for each call.

Each CreateRecurringPaymentsProfile request creates a single recurring payments profile.

N O T E

:

Tokens expire after approximately 3 hours.

N O T E

:

If you include both Token and CreditCardDetails, the token is used and credit card details are ignored.

Recurring Payments Profile Details Fields


SUBSCRIBERNAME

PROFILESTARTDATE

PROFILEREFERENCE

(Optional) Full name of the person receiving the product or service paid for by the recurring payment.

If not present, the name in the buyer’s PayPal account is used.


(Required) The date when billing for this profile begins.

Must be a valid date, in UTC/GMT format.

N O T E

:

The profile may take up to 24 hours for activation.

(Optional) The merchant’s own unique reference or invoice number.


ScheduleDetails Fields

Field

DESC

MAXFAILEDPAYMENTS

Description

(Required) Description of the recurring payment.

N O T E

:

This field must match the corresponding billing agreement description included in the SetExpressCheckout request.


(Optional) The number of scheduled payments that can fail before the profile is automatically suspended. An IPN message is sent to the merchant when the specified number of failed payments is reached.

Character length and limitations: Number string representing an integer.


June 2008

89



Field

AUTOBILLAMT

Description

(Optional) This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments that have yet to be successfully paid.

Valid values: Must be NoAutoBill or AddToNextBilling.

90

June 2008




Billing Period Details Type


BILLINGPERIOD

(Required) Unit for billing during this subscription period.

One of the following values: z

Day z z z z

Week

SemiMonth

Month

Year

For SemiMonth, billing is done on the 1st and 15th of each month.

N O T E

:

The combination of BillingPeriod and BillingFrequency cannot exceed one year.

BILLINGFREQUENCY

(Required) Number of billing periods that make up one billing cycle.

The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing frequency is 52.

N O T E

:

If the billing period is SemiMonth., the billing frequency must be 1.

TOTALBILLINGCYCLES

(Optional) The number of billing cycles for payment period (either the regular payment period or the trial period).

z z z

For the trial period, the value must be greater than 0.

For the regular payment period, if no value is specified or the value is 0, the regular payment period continues until the profile is canceled or deactivated.

For the regular payment period, if the value is greater than 0, the regular payment period will expire after the trial period is finished and continue at the billing frequency for TotalBillingCycles cycles.

AMT

(Required) Billing amount for each billing cycle during this payment period. This amount does not include shipping and tax amounts.

N O T E

:

All amounts in the CreateRecurringPaymentsProfile request must have the same currency.


CURRENCYCODE

SHIPPINGAMT

(Required) A three-character currency code.

Default: USD

(Optional) Shipping amount for each billing cycle during this payment period.

N O T E

:

All amounts in the request must have the same currency.



June 2008

91



Field

TAXAMT

Description

(Optional) Tax amount for each billing cycle during this payment period.

N O T E

:



92

June 2008




Activation Details Type


INITAMT

(Optional) Initial non-recurring payment amount due immediately upon profile creation. Use an initial amount for enrolment or set-up fees.

N O T E

:

All amounts included in the request must have the same currency.


FAILEDINITAMTACTION

(Optional) By default, PayPal will suspend the pending profile in the event that the initial payment amount fails. You can override this default behavior by setting this field to ContinueOnFailure, which indicates that if the initial payment amount fails, PayPal should add the failed payment amount to the outstanding balance for this recurring payment profile.

When this flag is set to ContinueOnFailure, a success code will be returned to the merchant in the CreateRecurringPaymentsProfile response and the recurring payments profile will be activated for scheduled billing immediately. You should check your IPN messages or PayPal account for updates of the payment status.

If this field is not set or is set to CancelOnFailure, PayPal will create the recurring payment profile, but will place it into a pending status until the initial payment is completed. If the initial payment clears, PayPal will notify you by IPN that the pending profile has been activated. If the payment fails, PayPal will notify you by

IPN that the pending profile has been canceled.

Character length and limitations: ContinueOnFailure or CancelOnFailure.


Field

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

Description














June 2008

93



Field

SHIPTOCOUNTRYCODE

SHIPTOPHONENUM

Description





94

June 2008






CREDITCARDTYPE

ACCT

EXPDATE



Allowable values: z

Visa z z z z z

MasterCard

Discover

Amex



N O T E

:








Format: MMYYYY


CVV2

STARTDATE

ISSUENUMBER









Field

EMAIL

PAYERID

Description






June 2008

95



Field

PAYERSTATUS

COUNTRYCODE

BUSINESS

Description







96

June 2008





Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Description







Payer’s last name


Payer’s suffix


Address Fields

Field

STREET

STREET2

CITY

STATE

COUNTRYCODE

ZIP

PHONENUM

Description















CreateRecurringPaymentsProfile Response

CreateRecurringPaymentsProfile Response Fields


PROFILEID

A unique identifier for future reference to the details of this recurring payment.

Character length and limitations: Up to 14 single-byte alphanumeric characters.


June 2008

97

98


GetRecurringPaymentsProfileDetails API

Field

STATUS

Description

Status of the recurring payment profile.

z

ActiveProfile - The recurring payment profile has been successfully created and activated for scheduled payments according the billing instructions from the recurring payments profile.

z

PendingProfile - The system is in the process of creating the recurring payment profile. Please check your IPN messages for an update.

GetRecurringPaymentsProfileDetails API

z z

“GetRecurringPaymentsProfileDetails Request” on page 98

“GetRecurringPaymentsProfileDetails Response” on page 98

GetRecurringPaymentsProfileDetails Request

GetRecurringPaymentsProfileDetails Request Fields


METHOD

PROFILEID

(Required) Must be GetRecurringPaymentsProfileDetails.

(Required) Recurring payments profile ID returned in the

CreateRecurringPaymentsProfile response.

Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatability with previous versions of the

PayPal API.

GetRecurringPaymentsProfileDetails Response

z z z z z z z z

GetRecurringPaymentsProfileDetails Response Fields

Recurring Payments Profile Fields


Billing Period Fields

Recurring Payments Summary Fields

Credit Card Fields



June 2008




GetRecurringPaymentsProfileDetails Response Fields


PROFILEID

STATUS

DESC

AUTOBILLOUTAMT

MAXFAILEDPAYMENTS

Recurring payments profile ID returned in the


Status of the recurring payment profile.

z z z z z

ActiveProfile

PendingProfile

CancelledProfile

SuspendedProfile

ExpiredProfile

Description of the recurring payment.


This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments that have yet to be successfully paid.

Valid values: NoAutoBill or AddToNextBilling.

The number of scheduled payments that can fail before the profile is automatically suspended.


AGGREGATEAMOUNT

AGGREGATEOPTIONALAM

OUNT

Total amount collected thus far for scheduled payments.

Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period


Total amount collected thus far for optional payments.

Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period


FINALPAYMENTDUEDATE

Final scheduled payment due date before the profile expires.

Recurring Payments Profile Details Fields

Field

SUBSCRIBERNAME

Description

Full name of the person receiving the product or service paid for by the recurring payment.



PROFILESTARTDATE

The date when billing for this profile begins.

Must be a valid date, in UTC/GMT format.

N O T E

:

The profile may take up to 24 hours for activation.


June 2008

99



Field

PROFILEREFERENCE

Description

The merchant’s own unique reference or invoice number.


100

June 2008




Ship To Address Type Fields


ADDRESSSTATUS

SHIPTONAME

SHIPTOSTREET


Valid values are: z none z z

Confirmed

Unconfirmed





SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE



Name of city.


State or province.






Billing Period Details Type


BILLINGPERIOD

Unit for billing during this subscription period.

One of the following values: z z z z z

Day

Week

SemiMonth

Month

Year

For SemiMonth, billing is done on the 1st and 15th of each month.

N O T E

:

The combination of BillingPeriod and BillingFrequency cannot exceed one year.


June 2008

101

102



Field

TAXAMT

Description

BILLINGFREQUENCY

Number of billing periods that make up one billing cycle.

The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing frequency is 52.

N O T E

:

If the billing period is SemiMonth., the billing frequency must be 1.

TOTALBILLINGCYCLES

The number of billing cycles for payment period (either the regular payment period or the trial period).

z

For the trial period, the value must be greater than 0.

z z

For the regular payment period, if no value is specified or the value is 0, the regular payment period continues until the profile is canceled or deactivated.

For the regular payment period, if the value is greater than 0, the regular payment period will expire after the trial period is finished and continue at the billing frequency for TotalBillingCycles cycles.

AMT

SHIPPINGAMT

Billing amount for each billing cycle during this payment period. This amount does not include shipping and tax amounts.

N O T E

:

All amounts in the CreateRecurringPaymentsProfile request must have the same currency.


Shipping amount for each billing cycle during this payment period.

N O T E

:



Tax amount for each billing cycle during this payment period.

N O T E

:



June 2008




Recurring Payments Summary Details Fields


NEXTBILLINGDATE

The next scheduled billing date, in YYYY-MM-DD format.

NUMCYCYLECOMPLETED

The number of billing cycles completed in the current active subscription period. A billing cycle is considered completed when payment is collected or after retry attempts to collect payment for the current billing cycle have failed.

NUMCYCLESREMAINING

The number of billing cycles remaining in the current active subscription period.

OUTSTANDINGBALANCE

The current past due or outstanding balance for this profile.


FAILEDPAYMENTCOUNT

The total number of failed billing cycles for this profile.

LASTPAYMENTDATE

The date of the last successful payment received for this profile, in YYYY-MM-DD format.

LASTPAYMENTAMT

The amount of the last successful payment received for this profile.




CREDITCARDTYPE

ACCT

Type of credit card.


Allowable values: z z z z z z

Visa

MasterCard

Discover

Amex



N O T E

:

If the credit card type is Maestro or Solo, the currencyId must be GBP. In addition, either StartMonth and StartYear or IssueNumber must be specified.

Credit card number. Only the last 4 digits of the credit card number are returned.




June 2008

103



Field

EXPDATE

STARTDATE

ISSUENUMBER

Description

Credit card expiration date.


Format: MMYYYY


Month and year that Maestro or Solo card was issued, the MMYYYY format.


Issue number of Maestro or Solo card.Character length: two numeric digits maximum.

104

June 2008



ManageRecurringPaymentsProfileStatus API

Payer Info Type Fields

Field

FIRSTNAME

LASTNAME

Description





Payer’s last name.


Address Fields

Field

STREET

STREET2

CITY

STATE

COUNTRYCODE

ZIP

PHONENUM

Description





Name of city.


State or province.


Country code.




Phone number.


ManageRecurringPaymentsProfileStatus API

z z

“ManageRecurringPaymentsProfileStatus Request” on page 106

“ManageRecurringPaymentsProfileStatus Response” on page 106


June 2008

105

106


BillOutstandingAmount API

ManageRecurringPaymentsProfileStatus Request

ManageRecurringPaymentsProfileStatus Request Fields


METHOD

PROFILEID

ACTION

NOTE

Must be ManageRecurringPaymentsProfileStatus.




PayPal API.

(Required) The action to be performed to the recurring payments profile. Must be one of the following: z z z

Cancel - Only profiles in Active or Suspended state can be canceled.

Suspend - Only profiles in Active state can be suspended.

Reactivate - Only profiles in a suspended state can be reactivated.

(Optional) The reason for the change in status. For profiles created using Express

Checkout, this message will be included in the email notification to the buyer when the status of the profile is successfully changed, and can also be seen by both you and the buyer on the Status History page of the PayPal account.

ManageRecurringPaymentsProfileStatus Response

ManageRecurringPaymentsProfileStatus Response Fields


PROFILEID



For each action, an error is returned if the recurring payments profile has a status that is not compatible with the action. Errors are returned in the following cases: z

Cancel - Profile status is not Active or Suspended.

z z

Suspend - Profile status is not Active.

Reactivate - Profile status is not Suspended.

BillOutstandingAmount API

z z

“BillOutstandingAmount Request” on page 107

“BillOutstandingAmount Response” on page 107

June 2008



UpdateRecurringPaymentsProfile API

BillOutstandingAmount Request

BillOutstandingAmount Request Fields


METHOD

PROFILEID

AMT

NOTE

(Required) Must be BillOutstandingAmount.




PayPal API.

N O T E

:

The profile must have a status of either Active or Suspended.

(Optional) The amount to bill. The amount must be less than or equal to the current outstanding balance of the profile. If no value is specified, PayPal will attempt to bill the entire outstanding balance amount.


(Optional) The reason for the non-scheduled payment. For profiles created using

Express Checkout, this message will be included in the email notification to the buyer for the non-scheduled payment transaction, and can also be seen by both you and the buyer on the Status History page of the PayPal account.

BillOutstandingAmount Response

BillOutstandingAmount Response Fields


PROFILEID



An error is returned if the profile specified in the BillOutstandingAmount request has a status of canceled or expired.

UpdateRecurringPaymentsProfile API

z z

“UpdateRecurringPaymentsProfile Request” on page 108

“UpdateRecurringPaymentsProfile Response” on page 113


June 2008

107



UpdateRecurringPaymentsProfile Request

z z z z z

UpdateRecurringPaymentsProfile Request Fields


Credit Card Fields


Address Fields

108

June 2008




UpdateRecurringPaymentsProfile Request Fields


METHOD

PROFILEID

NOTE

DESC

Must be UpdateRecurringPaymentsProfile.




PayPal API.

(Optional) The reason for the update to the recurring payments profile. This message will be included in the email notification to the buyer for the recurring payments profile update. This note can also be seen by both you and the buyer on the Status

History page of the PayPal account.

(Optional) Description of the recurring payment.


SUBSCRIBERNAME

PROFILEREFERENCE

(Optional) Full name of the person receiving the product or service paid for by the recurring payment.



(Optional) The merchant’s own unique reference or invoice number.


(Optional) The number of additional billing cycles to add to this profile.

ADDITIONALBILLINGCY

CLES

AMT

SHIPPINGAMT

(Optional) Billing amount for each cycle in the subscription period, not including shipping and tax amounts.

N O T E

:

For recurring payments with Express Checkout, the payment amount can be increased by no more than 20% every 180 days (starting when the profile is created).


(Optional) Shipping amount for each billing cycle during the regular payment period.

N O T E

:




June 2008

109



Field

TAXAMT

OUTSTANDINGAMT

AUTOBILLOUTAMT

MAXFAILEDPAYMENTS

Description

(Optional) Tax amount for each billing cycle during the regular payment period.

N O T E

:



(Optional) The current past due or outstanding amount for this profile. You can only decrease the outstanding amount—it cannot be increased.


(Optional) This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle.

Valid values: Must be NoAutoBill or AddToNextBilling.

(Optional) The number of failed payments allowed before the profile is automatically suspended. The specified value cannot be less than the current number of failed payments for this profile.


110

June 2008





Field

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

SHIPTOPHONENUM

Description



















CREDITCARDTYPE

ACCT



Allowable values: z

Visa z z z z z

MasterCard

Discover

Amex



N O T E

:







June 2008

111



Field

EXPDATE

CVV2

STARTDATE

ISSUENUMBER

Description



Format: MMYYYY









112

June 2008



SetCustomerBillingAgreement API


Field

FIRSTNAME

LASTNAME

Description

(Optional) Email address of payer.


(Required) Payer’s first name.


(Required) Payer’s last name.


Address Fields

Field

STREET

STREET2

CITY

STATE

COUNTRYCODE

ZIP

PHONENUM

Description















UpdateRecurringPaymentsProfile Response

UpdateRecurringPaymentsProfile Response Fields


PROFILEID



An error is returned if the profile specified in the BillOutstandingAmount request has a status of canceled or expired.

SetCustomerBillingAgreement API


June 2008

113



z z

“SetCustomerBillingAgreement Request” on page 114

“SetCustomerBillingAgreement Response” on page 117

SetCustomerBillingAgreement Request

z z

SetCustomerBillingAgreement Request Fields

Billing Agreement Details Fields

114

June 2008




SetCustomerBillingAgreement Request Fields


METHOD

RETURNURL

CANCELURL

LOCALECODE

PAGESTYLE

HDRIIMG

HDRBORDERCOLOR

Must be SetCustomerBillingAgreement.

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

N O T E

:

PayPal recommends that the value be the final review page on which the customer confirms the billing agreement.


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

PayPal to pay you.

N O T E

:

PayPal recommends that the value be the original page on which the customer chose to pay with PayPal or establish a billing agreement.


(Optional) Locale of pages displayed by PayPal during checkout.

Character length and limitations: Any two-character country code.

The following two-character country codes are supported by PayPal: z z

AU

DE z z z z z

FR

IT

GB

ES

US

Any other value will default to US. See “Country Codes” on page 215 .

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


(Optional) A URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored on a secure (https) server.


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

Character length and limitations: Six character HTML hexadecimal color code in

ASCII.


June 2008

115



Field

HDRBACKCOLOR

PAYFLOWCOLOR

EMAIL

Description

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


ASCII.

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


ASCII.

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

116

June 2008



GetBillingAgreementCustomerDetails API

Billing Agreement Details Fields


BILLINGTYPE

BILLINGAGREEMENTDES

CRIPTION

PAYMENTTYPE

BILLINGAGREEMENTCUS

TOM

(Required) Type of billing agreement. For reference transactions, this field must be

MerchantInitiatedBilling, which requests PayPal to prompt the buyer to set up a billing agreement for recurring payments. For recurring payments, the value must be RecurringPayments.

N O T E

:

Other defined values are not valid.

(Optional) Description of goods or services associated with the 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”.


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

Any

InstantOnly

(Optional) Custom annotation field for your own use.


SetCustomerBillingAgreement Response

SetCustomerBillingAgreement Response Fields


TOKEN

A unique time-stamped token, which uniquely identifies this transaction for subsequent API calls.

N O TE

:

The token expires after three hours.


GetBillingAgreementCustomerDetails API

z z

“GetBillingAgreementCustomerDetails Request” on page 118

“GetBillingAgreementCustomerDetails Response” on page 118


June 2008

117



GetBillingAgreementCustomerDetails Request

GetBillingAgreementCustomerDetails Request Fields


METHOD

TOKEN

(Required) Must be GetBillingAgreementCustomerDetails.

(Required) The time-stamped token returned in the

SetCustomerBillingAgreement response.

N O T E

:

The token expires after three hours.


GetBillingAgreementCustomerDetails Response

z z z z

GetBillingAgreementCustomerDetails Response


Payer Name Fields


118

June 2008




GetBillingAgreementCustomerDetails Response Fields



EMAIL



PAYERID

PAYERSTATUS

SHIPTOCOUNTRYCODE

PAYERBUSINESS



Status of payer. Valid values are: z z verified unverified







Field

SALUTATION

FIRSTNAME

MIDDLENAME

LASTNAME

SUFFIX

Description







Payer’s last name


Payer’s suffix




(Required) Status of street address on file with PayPal.


Confirmed

Unconfirmed


June 2008

119

120


DoReferenceTransaction API

Field

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

Description

(Required) Person’s name associated with this address.








(Optional) State or province.





(Required) Country code. Character limit: Two single-byte characters.

DoReferenceTransaction API

z z

“DoReferenceTransaction Request” on page 120

“DoReferenceTransaction Response” on page 128

DoReferenceTransaction Request

z z z z z z z z

DoReferenceTransaction Request Fields



Payment Item Details Fields

Ebay Payment Detail Item Fields

Credit Card Fields



June 2008




DoReferenceTransaction Request Fields


METHOD

REFERENCEID

PAYMENTACTION

RETURNFMFDETAILS

SOFTDESCRIPTOR

(Required) Must be DoReferenceTransaction.

(Required) Create a new transaction based on a credit card charge with

DoDirectPayment API TransactionID.

(Optional) How you want to obtain payment: z z





z z

0 - do not receive FMF details (default)


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

<PP * | PAYPAL *><Merchant descriptor as set in the Payment

Receiving Preferences><1 space><soft descriptor>

The soft descriptor can contain only the following characters: z

Alphanumeric characters z z z z

- (dash)

* (asterisk)

. (period)

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

The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools.

The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.

The soft descriptor is passed in as JanesFlowerGifts LLC

The resulting descriptor string on the credit card would be:

PAYPAL *EBAY JanesFlow


June 2008

121

122




Field

SHIPTONAME

SHIPTOSTREET

SHIPTOSTREET2

SHIPTOCITY

SHIPTOSTATE

SHIPTOZIP

SHIPTOCOUNTRYCODE

SHIPTOPHONENUM

Description



















AMT

CURRENCYCODE

ITEMAMT


N O T E

:



N O T E

:






N O T E

:


n

.

June 2008




Field

SHIPPINGAMT

INSURANCEAMT

SHIPPINGDISCOUNT

HANDLINGAMT

TAXAMT

DESC

CUSTOM

INVNUM

Description


N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:



N O T E

:



N O T E

:



N O T E

:



N O T E

:


ITEMAMT.


N O T E

:



N O T E

:


n








June 2008

123



Field

BUTTONSOURCE

NOTIFYURL

Description




N O T E

:




124

June 2008






L_NAMEn

L_DESCn

L_AMTn

L_NUMBERn

L_QTYn

L_TAXAMTn



L_NAME0, L_NAME1).






L_AMT0, L_AMT1).

N O T E

:



N O T E

:


n








L_QTY0, L_QTY1).



N O T E

:







L_EBAYITEMNUMBERn






June 2008

125




L_EBAYITEMAUCTIONTX

NIDn





L_EBAYITEMORDERIDn





126

June 2008






CREDITCARDTYPE

ACCT

EXPDATE



Allowable values: z

Visa z z z z z

MasterCard

Discover

Amex



N O T E

:








Format: MMYYYY


CVV2

STARTDATE

ISSUENUMBER









Field

FIRSTNAME

LASTNAME

Description








June 2008

127



Address Fields

Field

STREET

STREET2

CITY

STATE

COUNTRYCODE

ZIP

PHONENUM

Description















DoReferenceTransaction Response

z z

DoReferenceTransaction Response Fields

Payment Information Fields

128

June 2008




DoReferenceTransaction Response Fields for Express Checkout


AVSCODE

CVV2MATCH

BILLINGAGREEMENTID

Address Verification System response code. See “AVS and CVV2 Response Codes” on page 231 for possible values.

Character limit: One single-byte alphanumeric character

Result of the CVV2 check by PayPal.

L_FMF

L_FMF

filter filter

ID

n

NAME

n

Returned if the value of ReferenceID in the request is a billing agreement identification number.

Filter ID, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.




TRANSACTIONID

TRANSACTIONTYPE

PAYMENTTYPE

ORDERTIME

AMT

CURRENCYCODE


N O T E

:

If the PaymentAction of the request was Authorization or Order, this value is your AuthorizationID for use with the Authorization & Capture

APIs.




Valid values: z cart z express-checkout



Valid values: z z z none echeck instant

Time/date stamp of payment


Profile.




June 2008

129

130



Field

FEEAMT

SETTLEAMT

TAXAMT

EXCHANGERATE

PAYMENTSTATUS

PENDINGREASON

Description






Status of the payment:Completed: The payment has been completed, and the funds have been added successfully to your account balance.

Pending: The payment is pending. See the PendingReason element for more information.

The reason the payment is pending: z z z z z z z none: No pending reason address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.


intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.




June 2008


Field

REASONCODE



Description

The reason for a reversal if TransactionType is reversal: z none: No reason code z z chargeback: A reversal has occurred on this transaction due to a chargeback by your customer.

guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee.

z z z buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer.




June 2008

131



132

June 2008





June 2008

133



134

June 2008


10

DoNonReferencedCredit API

z z

“DoNonReferencedCredit Request” on page 135

“DoNonReferencedCredit Response” on page 138

DoNonReferencedCredit Request

z z z z

DoNonReferencedCredit Request Fields

Credit Card Fields


Address Fields


June 2008

135

136

DoNonReferencedCredit API

DoNonReferencedCredit Request

DoNonReferencedCredit Request Fields


METHOD

AMT

NETAMT

SHIPPINGAMT

(Required) Must be DoNonReferencedCredit.

(Required) Total of order, including shipping, handling, and tax.



Amount = NetAmount + ShippingAmount + TaxAmount

(Optional) Total amount of all items in this transaction.


Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are

AUD, CAD, EUR, GBP, JPY, and USD.

(Optional) Total shipping costs in this transaction.

Limitations: Value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

TAXAMT

CURRENCYCODE

NOTE


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

The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

(Required) Currency code. Default: USD.


(Optional) Field used by merchant to record why this credit was issued to a buyer.

Similar to a “memo” field. Freeform text. String field.



CREDITCARDTYPE



Allowable values: z z z z z z

Visa

MasterCard

Discover

Amex



N O T E

:



June 2008


Field

ACCT

EXPDATE

CVV2

STARTDATE

ISSUENUMBER


DoNonReferencedCredit Request

Description






Format: MMYYYY










June 2008

137

138


DoNonReferencedCredit Response


Field

FIRSTNAME

LASTNAME

Description







Address Fields

Field

STREET

STREET2

CITY

STATE

COUNTRYCODE

ZIP

PHONENUM

Description















DoNonReferencedCredit Response

DoNonReferencedCredit Response Fields


TRANSACTIONID

CURRENCYCODE

Unique identifier of a transaction.


Currency code.


June 2008


11

Fraud Management Filters API

Operations

This chapter describes the PayPal API operations and prerequisites related to Fraud

Management Filters: z z

“Fraud Management Filters API Prerequisites” on page 139

“ManagePendingTransactionStatus API” on page 140

Fraud Management Filters API Prerequisites

If your website already uses PayPal APIs and you want to use Fraud Management Filters, you must manage pending payments. To manage these payments, you must ensure that your website meets the following criteria: z

You must handle the SuccessWithWarning acknowledgement status in the response to all of the following API operations:

– DoDirectPayment

– DoExpressCheckoutPayment

– DoReferenceTransaction

<ack>

<__value__>

<m__value>SuccessWithWarning</m__value>

</__value__>

</ack>

<correlationID>9be3aa0887b0a</correlationID>

<errors>

<com.paypal.soap.api.ErrorType>

<shortMessage>Payment Pending your review in Fraud Management

Filters</shortMessage>

<longMessage></longMessage>

<errorCode>

<m__value>11610</m__value>

</errorCode>

<severityCode>

<__value__>

<m__value>Warning</m__value>

</__value__>

</severityCode>

<____hashCodeCalc>false</____hashCodeCalc>

</com.paypal.soap.api.ErrorType>

</errors>


June 2008

139

140

Fraud Management Filters API Operations

ManagePendingTransactionStatus API

z z z z


:

You may lose payment transactions if you do not handle

SuccessWithWarning acknowledgements.

You must handle Pending in the PaymentStatus of a response as representing a successful payment.

You must capture and evaluate the return code associated with a SuccessWithWarning acknowledgement.

If you process authorizations or orders, you must be able to analyze the short message associated with a capture failure, because a payment cannot be captured until it is taken out of the pending state. Thus, a capture failure may occur because the transaction was pended or it may occur for some valid reason.

Your shipping process must not allow shipping before the payment has been accepted.

z

N O T E

:

Pending payments are held 30 days unless explicitly denied or accepted. After 30 days, a pending payment is automatically reversed.

If you use Direct Payment Recurring Billing (for Pro merchants), your subscription creation process must handle a SuccessWithWarning acknowledgement and associated return codes. Specifically, it must handle the situation in which only the first payment is pended; payments thereafter will not be placed in pending.

If you do not want to manage pending payments; for example, if your shipping process would require substantial rework, you can still use FMF to flag or deny riskier payments, which provides you with additional risk review options, without changing your site.

ManagePendingTransactionStatus API

z z

“ManagePendingTransactionStatus Request” on page 141

“ManagePendingTransactionStatus Response” on page 141

June 2008




ManagePendingTransactionStatus Request

ManagePendingTransactionStatus Request Fields


METHOD

TRANSACTIONID

ACTION

Must be ManagePendingTransactionStatus.

The transaction ID of the payment transaction.

The operation you want to perform on the transaction, which is one of the following actions: z z

Accept - accepts the payment

Deny - rejects the payment

ManagePendingTransactionStatus Response

ManagePendingTransactionStatus Response Fields


TRANSACTIONID

STATUS

The transaction ID of the transaction whose payment has been denied or accepted.

The status of the transaction, which is one of the following values: z z

Pending

Processing z z z z z z

Completed

Denied

Reversed

Display Only

Partially Refunded

Created Refunded


June 2008

141



142

June 2008


12

GetBalance API

z z

“GetBalance Request” on page 143

“GetBalance Response” on page 143

GetBalance Request

GetBalance Request Fields


METHOD

(Required) Must be GetBalance.

RETURNALLCURRENCIES

(Optional) Whether to return all currencies, which is one of the following values: z z

0 - Return only the balance for the primary currency holding

1 - Return the balance for each currency holding

N O T E

:

You can only include this field with API VERSION 51 and later; prior versions return only the balance for the primary currency holding.

GetBalance Response

GetBalance Response Fields


L_AMTn

L_CURRENTYCODEn

The available balance and associated currency code for the primary currency holding.

The currency code associated with the holding, such as USD.


June 2008

143

GetBalance API

GetBalance Response

144

June 2008


13

AddressVerify API

z z

“AddressVerify Request” on page 146

“AddressVerify Response” on page 146


June 2008

145

146

AddressVerify API

AddressVerify Request

AddressVerify Request

AddressVerify Request Fields


METHOD

EMAIL

STREET

ZIP

(Required) Must be AddressVerify.

(Required) Email address of a PayPal member to verify.

Maximum string length: 255 single-byte characters

Input mask: ?@?.??

(Required) First line of the billing or shipping postal address to verify.

To pass verification, the value of Street must match the first three single-byte characters of a postal address on file for the PayPal member.

Street

Maximum string length: 35 single-byte characters.

Alphanumeric plus - , . ‘ # \

Whitespace and case of input value are ignored.

(Required) Postal code to verify.

To pass verification, the value of Zip must match the first five single-byte characters of the postal code of the verified postal address for the verified PayPal member.

Maximum string length: 16 single-byte characters.

Whitespace and case of input value are ignored.

AddressVerify Response

AddressVerify Response Fields


CONFIRMATIONCODE

STREETMATCH

None: The request value of the Email element does not match any email address on file at PayPal.

Confirmed: If the response value of the StreetMatch element is Matched, the entire postal address is confirmed.

Unconfirmed: PayPal responds that the postal address is unconfirmed.

N O TE

:

The values Confirmed and Unconfirmed both indicate that the member email address passed verification.

None: The request value of the Email element does not match any email address on file at PayPal. No comparison of other request values was made.

Matched: The request value of the Street element matches the first three singlebyte characters of a postal address on file for the PayPal member.

Unmatched: The request value of the Street element does not match any postal address on file for the PayPal member.

June 2008


Field

ZIPMATCH

COUNTRYCODE

TOKEN

AddressVerify API

AddressVerify Response

Description

None: The request value of the Street element was unmatched. No comparison of the Zip element was made.

Matched: The request value of the Zip element matches the ZIP code of the postal address on file for the PayPal member.

Unmatched: The request value of the Zip element does not match the ZIP code of the postal address on file for the PayPal member.

Two-character country code (ISO 3166) on file for the PayPal email address. See

“Country Codes” on page 215 .

The token contains encrypted information about the member’s email address and postal address. If you pass the value of the token in the HTML variable address_api_token of Buy Now buttons, PayPal prevents the buyer from using an email address or postal address other than those that PayPal verified with this API call.

The token is valid for 24 hours.



June 2008

147

AddressVerify API

AddressVerify Response

148

June 2008


A

API Error Codes

z z z z z z z z z z z z z z z z z z

“General API Errors” on page 150

“Validation Errors” on page 151

“Direct Payment API Errors” on page 155

“SetExpressCheckout API Errors” on page 167

“GetExpressCheckoutDetails API Errors” on page 175

“DoExpressCheckoutPayment API Errors” on page 177

“Authorization and Capture API Errors” on page 182

“TransactionSearch API Errors” on page 187

“RefundTransaction API Errors” on page 189

“Mass Pay API Errors” on page 192

“Recurring Payments Errors” on page 194

“SetCustomerBillingAgreement Errors” on page 202

“GetBillingAgreementCustomerDetails Errors” on page 204

“CreateBillingAgreement Errors” on page 204

“UpdateBillingAgreement Errors” on page 206

“DoReferenceTransaction Errors” on page 206

“AddressVerify API Errors” on page 213

“ManagePendingTransactionStatus API Errors” on page 213

June 2008

149

150

API Error Codes

General API Errors

General API Errors

T

ABLE

A.1 General API Errors

T

ABLE

A.1

Error

Code Short Message

10002 Authentication/Authoriza tion Failed



10002 Internal Error





10002 Restricted account

Long Message Correcting This Error

Username/Password is incorrect This error can be caused by an incorrect

API username, an incorrect API password, or an invalid API signature.

Make sure that all three of these values are correct. For your security, PayPal does not report exactly which of these three values might be in error.

You do not have permission to make this API call

Account is locked or inactive

Internal Error

Internal Error

Account is not verified

This call is not defined in the database!

Token is not valid

Account is restricted Your PayPal merchant account has been restricted. Contact your PayPal account manager for resolution.




10002 Restricted account

Token is not valid

API access is disabled for this account

Client certificate is disabled

Account is restricted

June 2008

API Error Codes

Validation Errors

81104

81105

81106

81107

81108

81109

81110

81111

81001

81002

81003

81004

81100

81101

81102

81103

81112

81113

81114

81115

81116

81117

81118

81119

81120

Validation Errors

T

ABLE

A.2 Validation Errors

T

ABLE

A.2

Error Code

81000

Short Message

Missing Parameter

Invalid Parameter

Unspecified Method

Unspecified Method

Unspecified Method

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Long Message

Required Parameter Missing : Unable to identify parameter

A Parameter is Invalid : Unable to identify parameter

Method Specified is not Supported

No Method Specified

No Request Received

OrderTotal (Amt) : Required parameter missing

MaxAmt : Required parameter missing

ReturnURL: Required parameter missing

NotifyURL : Required parameter missing

CancelURL : Required parameter missing

ShipToStreet : Required parameter missing

ShipToStreet2 : Required parameter missing

ShipToCity : Required parameter missing

ShipToState : Required parameter missing

ShipToZip : Required parameter missing

Country : Required parameter missing

ReqConfirmShipping : Required parameter missing

NoShipping : Required parameter missing

AddrOverride : Required parameter missing

LocaleCode : Required parameter missing

PaymentAction : Required parameter missing

Email : Required parameter missing

Token : Required parameter missing

PayerID : Required parameter missing

ItemAmt : Required parameter missing

ShippingAmt : Required parameter missing

June 2008

151

152

API Error Codes

Validation Errors

T

ABLE

A.2

81143

81144

81145

81146

81147

81148

81149

81150

81135

81136

81137

81138

81139

81140

81141

81142

81127

81128

81129

81130

81131

81132

81133

81134

Error Code

81121

81122

81123

81124

81125

81126

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Short Message

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Missing Parameter

Long Message

HandlingTotal Amt : Required parameter missing

TaxAmt : Required parameter missing

IPAddress : Required parameter missing

ShipToName : Required parameter missing

L_Amt : Required parameter missing

Amt : Required parameter missing

L_TaxAmt : Required parameter missing

AuthorizationID : Required parameter missing

CompleteType : Required parameter missing

CurrencyCode : Required parameter missing

TransactionID : Required parameter missing

TransactionEntity : Required parameter missing

Acct : Required parameter missing

ExpDate : Required parameter missing

FirstName : Required parameter missing

LastName : Required parameter missing

Street : Required parameter missing

Street2 : Required parameter missing

City : Required parameter missing

State : Required parameter missing

Zip : Required parameter missing

CountryCode : Required parameter missing

RefundType : Required parameter missing

StartDate : Required parameter missing

EndDate : Required parameter missing

MPID : Required parameter missing

CreditCardType : Required parameter missing

User : Required parameter missing

Pwd : Required parameter missing

Version : Required parameter missing

June 2008

T

ABLE

A.2

81227

81229

81230

81232

81234

81235

81236

81237

81219

81220

81221

81222

81223

81224

81225

81226

81208

81209

81210

81211

81212

81213

81214

81215

Error Code

81200

81201

81203

81205

81206

81207

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Short Message

Missing Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

API Error Codes

Validation Errors

Long Message

Amt : Invalid parameter

MaxAmt : Invalid parameter

NotifyURL : Invalid parameter

ShipToStreet : Invalid parameter

ShipToStreet2 : Invalid parameter

ShipToCity : Invalid parameter

ShipToState : Invalid parameter

ShipToZip : Invalid parameter

Country : Invalid parameter

ReqConfirmShipping : Invalid parameter

Noshipping : Invalid parameter

AddrOverride : Invalid parameter

LocaleCode : Invalid parameter

PaymentAction : Invalid parameter

ItemAmt : Invalid parameter

ShippingAmt : Invalid parameter

HandlingTotal Amt : Invalid parameter

TaxAmt : Invalid parameter

IPAddress : Invalid parameter

ShipToName : Invalid parameter

L_Amt : Invalid parameter

Amt : Invalid parameter

L_TaxAmt : Invalid parameter

CompleteType : Invalid parameter

CurrencyCode : Invalid parameter

TransactionEntity : Invalid parameter

ExpDate : Invalid parameter

FirstName : Invalid parameter

LastName : Invalid parameter

Street : Invalid parameter

June 2008

153

API Error Codes

Validation Errors

T

ABLE

A.2

Error Code

81238

81239

81243

81244

81245

81247

81248

81249

81250

81251

Short Message

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Invalid Parameter

Internal Error

Long Message

Street2 : Invalid parameter

City : Invalid parameter

RefundType : Invalid parameter

StartDate : Invalid parameter

EndDate : Invalid parameter

CreditCardType : Invalid parameter

Username : Invalid parameter

Password : Invalid parameter

Version : Invalid parameter

Internal Service Error

154

June 2008

API Error Codes

Direct Payment API Errors

Direct Payment API Errors

T

ABLE

A.3 DirectPayment API Errors

T

ABLE

A.3

Error


10102 PaymentAction of Order

Temporarily Unavailable

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






10432 Invalid argument

10500

10501

Invalid Configuration


Long Message

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

PaymentAction.

Order total is missing.

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

Item total is invalid.

Shipping total is invalid.

Handling total is invalid.

Tax total is invalid.

Invoice ID value exceeds maximum allowable length.

This transaction cannot be processed due to an invalid merchant configuration.


Corrective Action

Occurs when you have not agreed to the billing agreement.

Occurs when the billing agreement is disabled or inactive.

June 2008

155

156

API Error Codes


T

ABLE

A.3

Error


10502 Invalid Data

10504

10505

10507 Invalid Configuration

10508

10509 Invalid Data

10510 Invalid Data

10511 Invalid Data

10512

10513

10519

10520

10521

10523

Invalid Data

Gateway Decline

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Internal Error

Long Message

This transaction cannot be processed. Please use a valid credit card.

This transaction cannot be processed. Please enter a valid

Credit Card Verification Number.

This transaction cannot be processed.


The credit card used is expired.

The CVV provided is invalid. The CVV is between 3-4 digits long.

The transaction was refused because the

AVS response returned the value of N, and the merchant account is not able to accept such transactions.

Your PayPal account is restricted - contact PayPal for more information.

This transaction cannot be processed. Please contact PayPal

Customer Service.

This transaction cannot be processed. Please enter a valid credit card expiration date.


The credit card type is not supported. Try another card type.


The expiration date must be a two-digit month and four-digit year.

You must submit an IP address of the buyer with each API call.

The credit card type entered is not currently supported by PayPal.

The merchant selected a value for the

PaymentAction field that is not supported.

The first name of the buyer is required for this merchant.

This transaction cannot be processed. Please enter a first name.

This transaction cannot be processed. Please enter a last name.

Please enter a credit card.


This transaction cannot be processed. Please enter a valid credit card.


The last name of the buyer is required for this merchant.

The credit card field was blank.

The total amount and item amounts do not match.

The credit card entered is invalid.

None - this is a PayPal internal error.

June 2008

API Error Codes


T

ABLE

A.3

Error


10525 Invalid Data

10526 Invalid Data

10527 Invalid Data

10534 Gateway Decline


10536 Invalid Data

10537 Filter Decline



10540 Invalid Data


10542 Invalid Data

Long Message

This transaction cannot be processed. The amount to be charged is zero.

This transaction cannot be processed. The currency is not supported at this time.

This transaction cannot be processed. Please enter a valid credit card number and type.





The merchant entered a amount of zero.

The currency code entered is not supported.


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





The transaction cannot be processed due to an invalid address.


This transaction cannot be processed. Please enter a valid email address.

The merchant entered an invoice ID that is already associated with a transaction by the same merchant. By default, the invoice ID must be unique for all transactions. To change this setting, log into PayPal or contact customer service.

The transaction was declined by the country filter managed by the merchant.

To accept this transaction, change your risk settings on PayPal.

The transaction was declined by the maximum amount filter managed by the merchant. To accept this transaction, change your risk settings on PayPal.

The transaction was declined by PayPal.

Contact PayPal for more information.

The transaction was declined by PayPal because of an invalid address.

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

The email address provided by the buyer is in an invalid format.

June 2008

157

158

API Error Codes


T

ABLE

A.3

Error




10546

10547 Internal Error





10553

10554

10555

Gateway Decline

Gateway Decline

Filter Decline

Filter Decline

Long Message





This transaction cannot be processed. The merchant’s account is not able to process transactions.

This transaction cannot be processed. The merchan’s account is not able to process transactions.









The transaction was declined by PayPal because of possible fraudulent activity.


The transaction was declined by PayPal because of possible fraudulent activity on the IP address. Contact PayPal for more information.


The merchant account attempting the transaction is not a business account at

PayPal. Check your account settings.

The merchant account attempting the transaction is not able to process Direct

Payment transactions. Contact PayPal for more information.

Access to Direct Payment was disabled for your account. Contact PayPal for more information.

The merchant account attempting the transaction does not have a confirmed email address with PayPal. Check your account settings.

The merchant attempted a transaction where the amount exceeded the upper limit for that merchant.

The transaction was declined because of a merchant risk filter for AVS.

Specifically, the merchant has set to decline transaction when the AVS returned a no match (AVS = N).


Specifically, the merchant has set to decline transaction when the AVS returned a partial match.

June 2008

API Error Codes


T

ABLE

A.3

Error



Long Message




Specifically, the merchant has set to decline transaction when the AVS was unsupported.

10561

10562

10563

10564

10565

10567

10701

10702

Invalid Data

Invalid Data

Invalid Data

Gateway Decline

Merchant country unsupported

10566 Credit card type unsupported

Invalid Data

10571 Transaction approved, but with invalid Card

Security Code (CSC) format.

Invalid Data

Invalid Data

There’s an error with this transaction. Please enter complete billing address.

This transaction cannot be processed. Please enter a valid credit card expiration year.

This transaction cannot be processed. Please enter a valid credit card expiration month.


The merchant country is not supported.

The credit card type is not supported.


This transaction was approved, although the Card Security Code

(CSC) had too few, too many, or invalid characters. Based on your account profile settings, the invalid CSC was not given to the card issuer for its approval process.

There’s an error with this transaction. Please enter a valid billing address.

There’s an error with this transaction. Please enter a valid address1 in the billing address.

There was a problem processing this transaction.

If you want to require valid CVV values, change the risk control settings in your account profile.

There was a problem with a particular field in the address. The long error message will tell you what field is invalid.


June 2008

159

160

API Error Codes


T

ABLE

A.3

Error


10703 Invalid Data

10704 Invalid Data

10705 Invalid Data

10706 Invalid Data

10707 Invalid Data

10708 Invalid Data

10709 Invalid Data

10709 Invalid Data

10710 Invalid Data

10710 Invalid Data

Long Message

There’s an error with this transaction. Please enter a valid address2 in the billing address.

There’s an error with this transaction. Please enter a valid city in the billing address.

There’s an error with this transaction. Please enter a valid state in the billing address.

There’s an error with this transaction. Please enter a valid postal code in the billing address.

There’s an error with this transaction. Please enter a valid country in the billing address.

There’s an error with this transaction. Please enter a complete billing address.

There’s an error with this transaction. Please enter an address1 in the billing address.


There’s an error with this transaction. Please enter a city in the billing address.













June 2008

API Error Codes


T

ABLE

A.3

Error


10711 Invalid Data

10712 Invalid Data

10713

10713

10714

10715

10716

10717

10718

10719

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Long Message

There’s an error with this transaction. Please enter your state in the billing address.

There’s an error with this transaction. Please enter your five digit postal code in the billing address.

There’s an error with this transaction. Please enter a country in the billing address.


There’s an error with this transaction. Please enter a valid billing address.



There’s an error with this transaction. Please enter a valid postal code in the billing address.

There’s an error with this transaction. Please enter a valid city and state in the billing address.

There’s an error with this transaction. Please enter a valid shipping address.












June 2008

161

162

API Error Codes


T

ABLE

A.3

Error


10720 Invalid Data

10721 Invalid Data

10722 Invalid Data

10723 Invalid Data

10724 Invalid Data

10725 Invalid Data

10726 Invalid Data

10726 Invalid Data

10727 Invalid Data

10727 Invalid Data

Long Message

There’s an error with this transaction. Please enter a valid address1 in the shipping address.

There’s an error with this transaction. Please enter a valid address2 in the shipping address.

There’s an error with this transaction. Please enter a valid city in the shipping address.

There’s an error with this transaction. Please enter a valid state in the shipping address.

There’s an error with this transaction. Please enter your five digit postal code in the shipping address.

There’s an error with this transaction. Please enter a valid country in the shipping address.

There’s an error with this transaction. Please enter a complete shipping address.

There’s an error with this transaction. Please enter a complete shipping address.

There’s an error with this transaction. Please enter an address1 in the shipping address.

There’s an error with this transaction. Please enter an address1 in the shipping address.












June 2008

API Error Codes


T

ABLE

A.3

Error


10728 Invalid Data

10728 Invalid Data

10729

10730

10731

10731

10732

10733

10734

10735

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Long Message

There’s an error with this transaction. Please enter a city in the shipping address.

There’s an error with this transaction. Please enter a city in the shipping address.

There’s an error with this transaction. Please enter your state in the shipping address.


There’s an error with this transaction. Please enter a country in the shipping address.

There’s an error with this transaction. Please enter a country in the shipping address.

There’s an error with this transaction. Please enter a valid shipping address.















June 2008

163

164

API Error Codes


T

ABLE

A.3

Error


10736 Invalid Data

10744 Invalid Data

10745 Invalid Data

10746 Invalid Data

10747 Invalid Data

10748 Invalid Data

10750 Invalid Data

10751 Invalid Data



10755 Invalid Data

Long Message

There’s an error with this transaction. Please enter a valid city and state in the shipping address.

This transaction cannot be processed. Please enter a valid country code in the billing address.

This transaction cannot be processed. Please enter a valid country code in the shipping address.

This transaction cannot be processed. Please use a valid country on the billing address.


This transaction cannot be processed without a Credit Card

Verification Number.





This transaction cannot be processed due to an unsupported currency.






The merchant entered an IP address that was in an invalid format. The IP address must be in a format such as

123.456.123.456.

The merchant’s configuration requires a

CVV to be entered, but no CVV was provided with this transaction. Contact

PayPal if you wish to change this setting.


The merchant provided an address either in the United States or Canada, but the state provided is not a valid state in either country.

The transaction was declined by the issuing bank, not PayPal. The merchant should attempt another card.



The currency code entered by the merchant is not supported.

June 2008

API Error Codes


T

ABLE

A.3

Error


10756

10758

10759

10760

10761

Gateway Decline


Gateway Decline


Gateway Decline

Long Message

The transaction cannot be processed. The country and billing address associated with this credit card do not match.

There’s been an error due to invalid API username and/or password.


This transaction cannot be processed. The country listed for your business address is not currently supported.

This transaction cannot be processed. Please check the status of your first transaction before placing another order.

10762

10763

Gateway Decline

Invalid Data

10764 This transaction cannot be processed at this time.

Please try again later.

11610 Payment Pending your review in Fraud

Management Filters

11611 Transaction blocked by your settings in FMF

11612 Could not process your request to accept/deny the transaction




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

Payment Pending your review in

Fraud Management Filters

Transaction blocked by your settings in FMF

Could not process your request to accept/deny the transaction




The API username or password is incorrect for this merchant.



The merchant’s country of residence listed in their PayPal account is not currently supported to allow Direct

Payment transactions.

The transaction was declined because

PayPal is currently processing a transaction by the same buyer for the same amount. Can occur when a buyer submits multiple, identical transactions in quick succession.

The CVV provide is invalid. The CVV is between 3-4 digits long.




The transaction was rejected by PayPal because of excessive failures over a short period of time for this credit card.


June 2008

165

API Error Codes


T

ABLE

A.3

Error





15005 Processor Decline



15008 Invalid Data

Long Message











The transaction was declined because the merchant does not have a valid commercial entity agreement on file with PayPal. Contact PayPal for more information.

The transaction was declined because the CVV entered does not match the credit card.



The transaction was declined by the issuing bank because of an expired credit card. The merchant should attempt another card.

This transaction has been completed, but the total of items in the cart did not match the total of all items.

166

June 2008

API Error Codes

SetExpressCheckout API Errors

SetExpressCheckout API Errors

T

ABLE

A.4 SetExpressCheckout API Errors

T

ABLE

A.4

Error

Code

10001

10001

10004

10004

10004

10007

10010

10102

10103

10400

10401

Short Message

ButtonSource value truncated.

Internal Error

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



Permission denied

Long Message

The transaction could not be loaded

Internal Error


The transaction id is not valid

Invalid value for request billing address parameter.

Invalid Invoice

PaymentAction of Order


Please use another Solution

Type.


Non-ASCII invoice id is not supported.

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

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

OrderTotal is missing.

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


Order total is invalid.

Correcting This Error...

June 2008

167

168

API Error Codes


T

ABLE

A.4

Error

Code

10402

10404

10405

10407

10409

10410

10411

Short Message

Authorization only is not allowed for merchant.




You’re not authorized to access this info.

Invalid token

This Express Checkout session has expired.

Long Message

This merchant account is not permitted to set PaymentAction to

Authorization. Please contact

Customer Service.

ReturnURL is missing.

CancelURL is missing.

Invalid buyer email address

(BuyerEmail).

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

Invalid token.

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


If you receive this error, you must return your customer to

PayPal to approve the use of

PayPal again. Display an error message to inform the customer that the transaction expired, and provide a button to return to PayPal. In this situation, you are effectively restarting the entire checkout process. (Do not reuse the expired token value on

SetExpressCheckout request.) However, because you already know the final

OrderTotal, be sure to update the value for that element if appropriate. You might also want to update the values for ReturnURL and

CancelURL, if necessary.

June 2008

API Error Codes


T

ABLE

A.4

Error

Code

10412

10413

10415

10418

10425

10426

Short Message

Duplicate invoice

Long Message

Payment has already been made for this InvoiceID.


PayPal checks that

InvoiceID values are unique for any particular merchant. If you send an InvoiceID value already associated with another transaction in the

PayPal system, PayPal returns error code 10412.

You might not be able to correct this error during an actual checkout. If you get this error, research why might occur and modify your implementation of Express

Checkout to ensure that you generate unique invoice identification numbers.



The totals of the cart item amounts do not match order amounts.

A successful transaction has already been completed for this token.

PayPal allows a token only once for a successful transaction.

Handling this error

If you determine that your customers are clicking your

“Place Order” button twice,

PayPal recommends that you disable the button after your customer has clicked it.


Express Checkout has been disabled for this merchant.



Express Checkout has been disabled for this merchant. Please contact

Customer Service.


June 2008

169

170

API Error Codes


T

ABLE

A.4

Error

Code

10427

10428

10429

10430

10431

10432

10433

10434

10436

10437

Short Message











Long Message




Item amount is missing.

Item amount is invalid.


Value of Order Description has been truncated.

Value of Custom element has been truncated.

PageStyle value exceeds maximum allowable length.

cpp-header-image value exceeds maximum allowable length.


June 2008

API Error Codes


T

ABLE

A.4

Error

Code

10438

10439

10440

10441

10442

10457

10458

10459

10460

10461

10462

10463

10464

10465

10467

Short Message





ButtonSource value truncated

Error occurred in communicating to eBay










Long Message




The NotifyURL element value exceeds maximum allowable length.

The ButtonSource element value exceeds maximum allowable length.

eBay API creation error eBay API unknown failure eBay API failure

Parsing error

Item number invalid, removed, or unavailable

Order not found eBay user password incorrect eBay user invalid

Item ID and Transaction ID mismatch

Duplicate Item ID


June 2008

171

172

API Error Codes


T

ABLE

A.4

Error

Code

10468

10469

10470

10471

10472

10473

10474

Short Message


PaymentAction of Order


Wowo flag is off for

ExpressO feature




Invalid Data

10475

10476

10477

10478

10479

10480

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Long Message

Duplicate Order ID

Express Auctions is unavailable

Solution Type passed as Sole while

ExpressO feature is turned off

ReturnURL is missing

CancelURL is missing

Multiple Order IDs are not supported


Invalid Data


The country code in the shipping address must match the buyer's country of residence

This transaction cannot be completed with PaymentAction of Sale

Maximum number of billing agreements exceeded

More than one billing agreement specified for reference transaction

Recurring payments profile description must be provided if the billing agreement type is recurring payments

Billing agreement types cannot be mixed in the same request

Invalid billing agreement type


June 2008

API Error Codes


T

ABLE

A.4

Error

Code

10537

10538

10539

10725

10727

10728

10729

10730

10731

10736

10800

11547

11601

11602

11801

Short Message

Risk Control Country Filter

Failure

Risk Control Max Amount

Failure

Payment declined by your

Risk Controls settings:

PayPal Risk Model.

Shipping Address Country

Error

Shipping Address1 Empty

Shipping Address City

Empty

Shipping Address State

Empty

Shipping Address Postal

Code Empty


Empty

Shipping Address Invalid

City State Postal Code

Invalid Data

Long Message

The transaction was refused because the country was prohibited as a result of your Country Monitor Risk

Control Settings.

The transaction was refused because the maximum amount was excceeded as a result of your Maximum

Amount Risk Control Settings.

Payment declined by your Risk

Controls settings: PayPal Risk

Model.

There was an error in the Shipping

Address Country field

The field Shipping Address1 is required

The field Shipping Address City is required

The field Shipping Address State is required

The field Shipping Address Postal

Code is required

The field Shipping Address Country is required

A match of the Shipping Address

City, State, and Postal Code failed.

Your request is too long. Check

URLs and other long strings.

Recurring payments temporarily unavailable.


Recurring payments temporarily unavailable; try again later

Request for billing address failed


Invalid Data

Billing address request is not enabled for merchant

Feature not yet available

You cannot pass both new and deprecated parameter address fields.

June 2008

173

174

API Error Codes


T

ABLE

A.4

Error

Code

11802

11803

11804

11805

11806

11807

11810

11811

11812

11813

11814

11815

Short Message

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Long Message

You cannot pass both the new and deprecated Custom parameter.

You cannot pass both the new and deprecated Invoice ID parameter.

You cannot pass both the new and deprecated order description.

You cannot pass both the new and deprecated order total or amount parameters.

You cannot pass both the new and deprecated

ProfileAddressChangeDate parameter.

You cannot pass both the new and deprecated ShippingMethod parameter.

Invalid Insurance Amount.



Invalid Data

Invalid Shipping Discount.

The value of Description parameter has been truncated.

Invalid callback URL.


Invalid data


Invalid value for AllowNote.

Item sales tax is invalid.


June 2008

API Error Codes

GetExpressCheckoutDetails API Errors

GetExpressCheckoutDetails API Errors

T

ABLE

A.5 GetExpressCheckoutDetails API Errors

T

ABLE

A.5

Error

Code

10001

10001

10001

10001

10004

10004

10004

10004

10004

10007

10007

10007

10408

Short Message

Internal Error

Internal Error





Invalid transaction type

Long Message

Internal Error

Transaction failed due to internal error







Permission denied

Permission denied

Permission denied

Express Checkout token is missing.

You can not get the details for this type of transaction




You do not have permission to get the details of this transaction




June 2008

175

API Error Codes

GetExpressCheckoutDetails API Errors

T

ABLE

A.5

Error

Code

10409

10410

10411

Short Message


Invalid token


Long Message


Invalid token.



176

June 2008

API Error Codes

DoExpressCheckoutPayment API Errors

DoExpressCheckoutPayment API Errors

T

ABLE

A.6 Errors

T

ABLE

A.6

Error

Code

10001

10001

10001

10001

10004

10004

10007

10406

10408

10409

10410

10411

10412

Short Message

Internal Error

Internal Error


Internal Error



Permission denied




Invalid token


Duplicate invoice

Long Message


Warning an internal error has occurred. The transaction id may not be correct


Internal Error



You do not have permissions to make this API call

The PayerID value is invalid.



Invalid token.


Payment has already been made for this InvoiceID.


June 2008

177

178

API Error Codes


T

ABLE

A.6

Error

Code

10413

10414

10415

10416

10417

10418

10419

10420

10421

Short Message


Long Message



z z z z

ItemTotal

ShippingTotal

HandlingTotal

TaxTotal

If you get this error, research why it might have occurred and modify your implementation of Express Checkout to ensure proper addition of the values.




Transaction cannot complete.

The amount exceeds the maximum amount for a single transaction.

A successful transaction has already been completed for this token.

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

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



Express Checkout

PayerID is missing.


This Express Checkout session belongs to a different customer.

Express Checkout PayerID is missing.

Express Checkout

PaymentAction is missing.

This Express Checkout session belongs to a different customer. Token value mismatch.

Instruct the customer that PayPal is unable to process the payment and redisplay alternative payment methods with which the customer can pay.

Verify that your programs are properly associating the Tokens and PayerIDs.

June 2008

API Error Codes


T

ABLE

A.6

Error

Code

10422

10424

Short Message

Customer must choose new funding sources.


Long Message

The customer must return to

PayPal to select new funding sources.

Shipping address is invalid.


If you receive this error message,

PayPal recommends that you return your customer to PayPal to review and approve new valid funding sources.

Although this error is rare, you should consider trapping the error to display a message to the customer describing what happened, along with a button or hyperlink to return to PayPal.

10426

10427

10428

10429

10431

10432

10433

10434















Value of OrderDescription element has been truncated.


June 2008

179

180

API Error Codes


T

ABLE

A.6

Error

Code

10435

10441

10442

10443

10444

10445

10446

10474

10537

10538

Short Message




Long Message

The customer has not yet confirmed payment for this

Express Checkout session.



This transaction cannot be completed with

PaymentAction of Order.



This transaction cannot be processed at this time.


Unconfirmed email

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

Invalid Data

Risk Control Country

Filter Failure


Failure


A confirmed email is required to make this API call.

This transaction cannot be processed. The country code in the shipping address must match the buyer’s country of residence.

The transaction was refused because the country was prohibited as a result of your

Country Monitor Risk Control

Settings.

The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk

Control Settings.


The buyer selects the country of residence when they sign up for their

PayPal account. The country of residence is displayed after the dash in the title on the Account Overview page.

June 2008

API Error Codes


T

ABLE

A.6

Error

Code

10539

10725

10727

10728

10729

10730

10731

10736

11610

11611

11612

11820

Short Message



PayPal Risk Model.


Error

Long Message



Model.

There was an error in the

Shipping Address Country field

Shipping Address1 Empty The field Shipping Address1 is required


Empty

The field Shipping Address

City is required


Empty


Code Empty


State is required


Postal Code is required


Empty




Country is required

A match of the Shipping

Address City, State, and Postal

Code failed.

Payment Pending your review in Fraud Management Filters

Payment Pending your review in Fraud

Management Filters






Invalid Order URL.


June 2008

181

182

API Error Codes

Authorization and Capture API Errors

Authorization and Capture API Errors

T

ABLE

A.7 Authorization & Capture API Error Messages

T

ABLE

A.7

Error

Code

10001

10001

10004

10007

10009

10010

10202

10600

10601

10602

Short

Message

Internal Error

Internal Error

Internal Error

Permission denied

Long Message

Internal Error


Invalid argument

You do not have permissions to make this

API call


Invalid argument

Returned By API

Call...

Transaction refused


Exceed max

Authorization voided.

Authorization expired.

Authorization completed.

Transaction would exceed user’s monthly maximum

DoAuthorization

DoCapture

Authorization is voided.

DoAuthorization

DoCapture

DoReauthorization

DoVoid

Authorization has expired.

DoAuthorization

DoCapture

DoReauthorization

DoVoid

Authorization has already been completed.

DoAuthorization

DoCapture

DoReauthorization

DoVoid

Correcting This

Error...

Retry the request at a later time or close order.

Close the order or authorization.



June 2008

API Error Codes


T

ABLE

A.7

Error

Code

10603

10604

10605

Short

Message

The buyer is restricted.

Authorization must include both buyer and seller.

Unsupported currency.

Long Message

The buyer account is restricted.

Returned By API

Call...

DoAuthorization

DoCapture

DoReauthorization

DoVoid

DoAuthorization Authorization transaction cannot be unilateral. It must include both buyer and seller to make an auth.

Currency is not supported.

DoAuthorization

DoCapture

10606

10607

10608

10609

10610

10611

10612

Buyer cannot pay.

Auth&Capture unavailable.

Funding source missing.

Invalid transactionID.

Amount limit exceeded.

Not enabled.

No more settlement.

Transaction rejected, please contact the buyer.

Authorization & Capture feature unavailable.

The funding source is missing.

DoAuthorization

DoCapture

DoReauthorization

DoAuthorization

DoCapture

DoReauthorization

DoVoid

DoAuthorization

DoCapture

DoReauthorization

Transaction id is invalid.

DoAuthorization

DoCapture

DoReauthorization

DoVoid

Amount specified exceeds allowable limit.

DoAuthorization

DoCapture

DoReauthorization

Authorization & Capture feature is not enabled for the merchant. Contact customer service.

Maxmimum number of allowable settlements has been reached. No more settlement for the authorization.

DoAuthorization

DoCapture

DoReauthorization

DoCapture

Correcting This

Error...

Contact the buyer.

Review the order to ensure customer and seller are both PayPal members.

Retry the request with a

PayPal-supported currency.

Contact the buyer.

Contact PayPal Customer

Service.

Contact the buyer.

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

Reattempt the request with a lower amount.

Contact PayPal Customer

Service.

Close the order.

June 2008

183

184

API Error Codes


T

ABLE

A.7

Error

Code

10613

10614

10615

10616

10617

10618

10619

10620

10621

10622

Short

Message

Currency mismatch.

Cannot void reauth.

Cannot reauth reauth.

Long Message

Currency of capture must be the same as currency of authorization.

You can void only the original authorization, not a reauthorization.

You can reauthorize only the original authorization, not a reauthorization.

Maximum number of reauthorization allowed for the auth is reached.

Returned By API

Call...

DoCapture

DoVoid

DoReauthorization

DoReauthorization Maximum number of reauthorization allowed for the auth is reached.

Reauthorization not allowed.

Transaction already voided or expired.

Reauthorization is not allowed inside honor period.

Transaction has already been voided or expired.


DoReauthorization

DoAuthorization

DoCapture

DoReauthorization

DoVoid

DoCapture Invoice ID value exceeds maximum allowable length.

Order has already been voided, expired, or completed.

Order has expired.

Order has already been voided, expired, or completed.

Order has expired.

DoAuthorization

DoCapture

DoVoid

Order is voided. Order is voided.

DoAuthorization

DoCapture

DoVoid

DoAuthorization

DoCapture

DoVoid

Correcting This

Error...

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

Void the authorization.

Capture the reauthorization.

Capture or close the authorization

Capture the authorization or reauthorize outside of honor period.


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

Close this order.

Close this order.

Close this order.

June 2008

API Error Codes


T

ABLE

A.7

Error

Code

10623

10624

Short

Message

Maximum number of authorization allowed for the order is reached.

Duplicate invoice


Long Message


Returned By API

Call...

DoAuthorization

DoCapture

DoReauthorization

DoVoid

Payment has already been made for this

Invoice ID.


DoAuthorization

DoAuthorization

DoCapture

DoReauthorization

10626

10627

10628

10629

10630



Reauthorization not allowed.

Item amount is invalid. to risk model.

The invoice ID field is not supported for basic authorizations.

This transaction cannot be processed at this time.


Reauthorization is not allowed for this type of authorization.


DoCapture

DoReauthorization

DoAuthorization

DoReauthorization

DoVoid

DoAuthorization

DoCapture

DoReauthorization

DoVoid

DoReauthorization

DoAuthorization

DoCapture

Correcting This

Error...

Capture this order.

Review the invoice ID and reattempt the request.

Reattempt the request with a lower amount.

Contact the buyer.

The Invoice ID field can only be used with

DoCapture.

Retry the request at a later time.

Use DoAuthorization to authorize the an order.

Check the item amount to ensure that it is not zero or negative.

June 2008

185

API Error Codes


T

ABLE

A.7

Error

Code

11094

Short

Message

This authorization cannot be voided, reauthorized, or captured against.

Long Message

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

Returned By API

Call...

Correcting This

Error...

186

June 2008

GetTransactionDetails API Errors

T

ABLE

A.8 GetTransactionDetails API Errors

T

ABLE

A.8

Error Code

10001

Short Message

Internal Error

Long Message

Internal Error

API Error Codes

GetTransactionDetails API Errors

TransactionSearch API Errors

T

ABLE

A.9 TransactionSearch API Errors

T

ABLE

A.9

Error

Code

10001

10001

10003

10004

10004

10004

10004

Short Message

Internal Error







Long Message

Internal Error


Start date is a required parameter

Start date is invalid

End date is invalid

Currency is not supported

Transaction class is not supported

June 2008

187

188

API Error Codes

TransactionSearch API Errors

T

ABLE

A.9

Error

Code

10004

10004

10004

10004

10004

10004

10004

10007

10007

11002

Short Message








Permission denied

Permission denied

Search warning

Long Message

Receipt id is not valid

Payer email is invalid

Auction item id is not valid

Receiver email is invalid

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

Receiver can only be specified for payments you’ve received


You do not have permission to search for this transaction


The number of results were truncated. Please change your search parameters if you wish to see all your results.

June 2008

API Error Codes

RefundTransaction API Errors

RefundTransaction API Errors

T

ABLE

A.10 RefundTransaction API Errors

T

ABLE

A.10

Error


10001

10001

10001

10001

10004

10004

10004

10004

10004

10004

10004

Internal Error

Internal Error

Long Message

Internal Error

Warning an internal error has occurred.

The transaction id may not be correct




Internal Error








Internal Error

The partial refund amount must be a positive amount

You can not specify a partial amount with a full refund

A transaction id is required

The partial refund amount must be a positive amount

You can not specify a partial amount with a full refund

A transaction id is required

Transaction class is not supported

June 2008

189

190

API Error Codes


T

ABLE

A.10

Error


10004

10007


Permission denied

10007

10009

Permission denied

Transaction refused

Long Message


You do not have permission to refund this transaction


You do not have a verified ACH


This error can be caused by insufficient funds in your

PayPal balance to cover the amount of the refund and either your not having yet verified the bank account associated with your PayPal account or your not having any bank account associated with your PayPal account at all.

Ensure that you have sufficient funds in your PayPal balance and that you have verified the associated bank account.

10009

10009

10009

10009

10009

10009

10009

10009

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Transaction refused

The partial refund amount must be less than or equal to the original transaction amount

The partial refund amount must be less than or equal to the remaining amount

The partial refund amount is not valid

Because a complaint case exists on this transaction, only a refund of the full or full remaining amount of the transaction can be issued

You are over the time limit to perform a refund on this transaction

Can not do a full refund after a partial refund


The partial refund must be the same currency as the original transaction

June 2008

API Error Codes


T

ABLE

A.10

Error


10009

10009

10009

10009

10009

10009

10011

11001

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Transaction refused

Long Message

This transaction has already been fully refunded


You can not refund this type of transaction

You can not do a partial refund on this transaction

The account for the counterparty is locked or inactive

You can not refund this type of transaction

Invalid transaction id value Transaction refused because of an invalid transaction id value

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


June 2008

191

192

API Error Codes

Mass Pay API Errors

Mass Pay API Errors

T

ABLE

A.11 MassPay API Errors

T

ABLE

A.11

Error

Code

10001

10001

10001

10001

10001

10002

10004

10004

10004

10004

10004

10004

Short Message

Invalid account number.

Long Message

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

Check the number or attempt with another card.

Internal Error

Internal Error

Internal Error





The masspay receiver_type is not a recognizable type

The user account is locked

The number of input records is greater than maximum allowed

Account locked




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

The note string length exceeds the maximum limit of 4000 characters




The amount is missing

The currency is missing

Currency is not supported

June 2008

API Error Codes

Mass Pay API Errors

T

ABLE

A.11

Error

Code

10004

10004

10004

10004

10004

10004

10007

10301

10303

10304

10305

Short Message







Permission denied

User not allowed

Restricted account

Unconfirmed email

Limit Exceeded

10306

10307

10308

Limit Exceeded

Receive only account

Long Message

The amount is not a valid number

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

~1

The amount is less than or equal to zero

The unique id string length exceeds the maximum limit of 30 characters

The unique id string contains a space as a character



The user is not allowed to send money through Mass Pay


The user account has unconfirmed email

The user account needs to have its sending limit removed in order to make a mass payment.

The user’s international account needs to have its sending limit removed in order to make a mass payment

The user account is receive only and therefore cannot send payments out

There is some configuration error

10309

Masspay server configuration error

Masspay server unavailable The mass pay server is unavailable

June 2008

193

API Error Codes

Recurring Payments Errors

T

ABLE

A.11

Error

Code

10310

10311

10312

10313

10314

Short Message

Unable to create payment

Unable to submit payment

Masspay server error

Masspay Invalid Data

Masspay input parse error

10317

10320

10321

10327

Masspay Invalid Email

Internal Error

Insufficient funds

Masspay Invalid UserID

Long Message

Unable to create payments for masspay

Unable to submit payments for masspay

The masspay server has reported errors

The masspay input file includes invalid data

The input to the masspay server is incorrect. Please make sure that you are using a correctly formatted input.

The masspay input file includes invalid Email

Internal Error

The account does not have sufficient funds to do this masspay

The masspay input file includes invalid UserID

Recurring Payments Errors

The following table lists errors for the following APIs that handle recurring payments profiles: z z z z z

CreateRecurringPaymentsProfile

GetRecurringPaymentsProfileDetails

ManageRecurringPaymentsProfileStatus

UpdateRecurringPaymentsProfile

BillOutstandingAmount

194

June 2008

API Error Codes


T

ABLE

A.12 Recurring Payments Errors

T

ABLE

A.12

Error

Code

10001

Short Message

Invalid account number

10478

10501

10502

10504

10505

10507

10508

10509

10510

10511

Invalid Data


Invalid Data

Invalid Data

Gateway Decline


Invalid Data

Invalid Data

Invalid Data

Invalid Data

Long Message

The transaction failed as a result of invalid credit card number. Check the number or attempt with another credit card.

Recurring payments profile description must be provided if the billing agreement type is recurring payments.






Additional Information

Occurs when the billing agreement is disabled or inactive.

The credit card used is expired.

This transaction cannot be processed. Please contact PayPal

Customer Service.

This transaction cannot be processed. Please enter a valid credit card expiration date.


The credit card type is not supported. Try another card type.


The CVV provided is invalid.

The CVV is between 3-4 digits long.

The transaction was refused because the AVS response returned the value of N, and the merchant account is not able to accept such transactions.

Your PayPal account is restricted

- contact PayPal for more information.

The expiration date must be a two-digit month and four-digit year.

You must submit an IP address of the buyer with each API call.

The credit card type entered is not currently supported by

PayPal.

The merchant selected an value for the PaymentAction field that is not supported.

June 2008

195

196

API Error Codes


T

ABLE

A.12

Error

Code

10512

Short Message

Invalid Data

10513 Invalid Data

10535 Gateway decline



10561

10565

10709

10710

10711

10712

Invalid Data

Merchant country unsupported

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Long Message

This transaction cannot be processed. Please enter a first name.

This transaction cannot be processed. Please enter a last name.


This transaction cannot be processed. The merchant’s account is not able to process transactions.


The first name of the buyer is required for this merchant.

The last name of the buyer is required for this merchant.


The merchant account attempting the transaction is not a business account at PayPal.

Check your account settings.

Access to Direct Payment was disabled for your account.


There’s an error with this transaction. Please enter complete billing address.

The merchant country is not supported.



There’s an error with this transaction. Please enter your state in the billing address.


There was a problem with a particular field in the address.

The long error message will tell you what field is invalid.







June 2008

API Error Codes


T

ABLE

A.12

Error

Code

10713

10744

10748

10751

10752

10760

11089

11501

11502

11503

11504

11505

Short Message

Invalid Data

Invalid Data

Invalid Data

Invalid Data

Gateway Decline


Long Message


This transaction cannot be processed. Please enter a valid country code in the billing address.


Verification Number.



This transaction cannot be processed. The country listed for your business address is not currently supported.






The merchant’s configuration requires a CVV to be entered, but no CVV was provided with this transaction. Contact PayPal if you wish to change this setting.

The merchant provided an address either in the United

States or Canada, but the state provided is not a valid state in either country.


The merchant’s country of residence listed in their PayPal account is not currently supported to allow Direct

Payment transactions.

Transaction Refused.

Invalid merchant country

Account is locked or inactive.

The merchant’s country is currently not supported

Missing token

The token is missing or is invalid

The token is missing or is invalid One or more subscription detail fields are missing from the request.

Missing subscription details Missing subscription details One or more schedule detail fields are missing from the request.

Missing schedule details

Start date should be greater than current date

Missing schedule details

Subscription start date should be greater than current date

June 2008

197

198

API Error Codes


T

ABLE

A.12

Error

Code

11506

11507

11508

11509

11510

11511

11512

11513

11514

11515

11516

11517

11518

11519

11520

11521

11522

11523

11524

Short Message

Invalid max failed payments

Invalid trial amount

Invalid trial total billing cycles

Invalid trial billing period

Invalid trial amount

Invalid currency for trial amount

Invalid trial shipping amount

Invalid currency for trial shipping amount

Invalid profile status

Invalid currency for trial tax amount

Invalid billing frequency

Long Message

Max failed payments, if supplied, must be >= 0

Trial amount must be >= 0

Trial total billing cycles must be >

0

Trial billing period must be one of

Day, Week, Month, SemiMonth, or

Year

Trial amount must be >= 0

This currency is currently not supported for trial amount.

Trial shipping amount must be >=

0

This currency is currently not supported for trial shipping amount

The profile status is invalid.

This currency is currently not supported for trial tax amount

Billing Frequency must be > 0 and be less than or equal to one year


Currency must be USD.

If a trial shipping amount is supplied, it must be >= 0.



The combination of billing frequency and billing period cannot exceed one year.

Invalid total billing cycles Total billing cycles must be >= 0 (0 means continuous)

Invalid billing period

Invalid amount

Billing period must be one of Day,

Week, Month, SemiMonth, or Year

Bill amount must be greater than 0

Invalid currency for amount This currency is currently not supported for amount

Invalid shipping amount Shipping amount must be >= 0

Invalid currency for shipping amount

Invalid tax amount

Invalid currency for tax amount

This currency is currently not supported for shipping amount

Tax amount must be >= 0

This currency is currently not supported for tax amount




June 2008

API Error Codes


T

ABLE

A.12

Error

Code

11531

11543

11544

11545

11546

11547

11548

11549

11550

11551

11552

11553

11554

Short Message

Invalid profile status

Invalid payer country

Invalid period status

Denied

Denied

This feature is not available at this time

Invalid currency code

Start Date is required

Start Date should be valid

Profile ID is missing from the request

Invalid profile ID

Invalid action value provided

Note is missing from the request

Long Message

The profile status must be one of

(A)ctive, (C)ancelled, or e(X)pired

The payer’s country is currently not supported

The trial period status must be one of (A)ctive or (C)ancelled

Payer’s account is denied

Merchant account is denied

Recurring payments feature is not currently available; try again later

Invalid currency code, all currency codes much match

Subscription start date is required

Subscription start date should be valid

Profile ID is missing from the request

The profile ID is invalid

Invalid action value provided

Note is missing from the request


11555

11556 Invalid profile status for suspend action; profile should be active

11557

11558

11560

11561

Invalid profile status for cancel action; profile should be active or suspended

Invalid profile status for suspend action; profile should be active

Invalid profile status for reactivate action; profile should be suspended

Invalid activation type

Invalid initial amount

Invalid profile status for reactivate action; profile should be suspended

The activation type is invalid

The activation type is invalid

The initial amount is invalid

June 2008

199

200

API Error Codes


T

ABLE

A.12

Error

Code

11562

11564

11567

11568

11569

11570

11571

11576

11577

11578

11579

11581

11582

11583

11584

11585

11586

Short Message

Invalid auto bill type

The number of failed payments should be greater than the current number of failed payments

The time of the update is too close to the billing date

Invalid currency for delinquent amount

Cannot increase delinquent amount

The maximum number of failed payments should be greater than the current number of failed payments

The total amount cannot exceed 120% increment per

180 days

Bill amount is greater than outstanding balance

Another outstanding payment is scheduled

Bill outstanding amount not processed because of scheduled payment

Long Message

The auto bill type is invalid

The number of failed payments should be greater than the current number of failed payments

The time of the update is too close to the billing date

Invalid currency for delinquent amount

Cannot increase delinquent amount

The maximum number of failed payments should be greater than the current number of failed payments

The total amount cannot exceed

120% increment per 180 days

Bill amount is greater than outstanding balance

Another outstanding payment is scheduled

Recurring payment scheduled within 24 hours, so we are not processing the bill outstanding amount

Payment is failing

Invalid Data

Inactive profile

Missing Token or buyer credit card

Payment is failing

Profile description is invalid.

No payment in queue No scheduled payment has been found.

DPRP feature is unavailable DPRP feature is unavailable

Profile is not active

Missing token or payment source

DPRP is disabled DPRP is disabled for this merchant.


June 2008

API Error Codes


T

ABLE

A.12

Error

Code

11587

11590

15004

Short Message

Billing Address is Partial

Profile update is not required

Gateway Decline

Long Message

Billing Address is Partial

Based on your input request, profile already up to date.




June 2008

201

202

API Error Codes

SetCustomerBillingAgreement Errors

SetCustomerBillingAgreement Errors

T

ABLE

A.13 SetCustomerBillingAgreement Errors

T

ABLE

A.13

Error

Code

10004

10404

10004

10405

10407

Short Message






10436

Long Message

Invalid argument; BillingType input field is set to None

ReturnURL is missing.

Invalid value for request billing address parameter.

CancelURL is missing.


ReturnURL tag has no content

CancelURL tag has no content

Invalid buyer email address

(BuyerEmail).

PageStyle value exceeds maximum allowable length.

Invalid BuyerEmail (badly formatted or violates SMTP protocol defined email address format) or BuyerEmail is passed as an empty tag.

PageStyle tag is too long

10437

10438





cpp-header-border-color value exceeds maximum allowable length.

cpp_header_image tag is too long; maximum length is 127 cpp_header_border_color tag is too long; maximum length is 6

June 2008

API Error Codes

SetCustomerBillingAgreement Errors

T

ABLE

A.13

Error

Code

10439

10440

10471

10472

10476

10477

11452

Short Message







Merchant not enabled for reference transactions

11453

11601

11602

Long Message

cpp-header-back-color value exceeds maximum allowable length.

cpp-payflow-color value exceeds maximum allowable length.

ReturnURL is invalid.

CancelURL is invalid.


cpp_header_back_color tag is too long; maximum length is 6 cpp_payflow_color tag is too long; maximum length is 6

ReturnURL tag contains invalid

URL

CancelURL tag contains invalid

URL

Reference transactions temporarily unavailable.




Reference transaction feature not currently available; try again later

This merchant is not enabled for

Mark reference transaction.

Warning only

Feature not enabled because system is running in standin mode. Warning only

Billing address request is not enabled for merchant

Feature not yet available

June 2008

203

204

API Error Codes

GetBillingAgreementCustomerDetails Errors

GetBillingAgreementCustomerDetails Errors

T

ABLE

A.14 GetBillingAgreementCustomerDetails Errors

T

ABLE

A.14

Error

Code

10408

10409

Short Message

Missing token


10410

10411

Invalid token


Long Message

Token is missing


Invalid token



Token is missing

Token belongs to a different merchant

Token invalid

Token expired

CreateBillingAgreement Errors

T

ABLE

A.15 CreateBillingAgreement Errors

T

ABLE

A.15

Error

Code

10408

10409

10410

10411

11455

11456

10408

Short Message

Missing token


Invalid token


Buyer did not accept billing agreement

A successful Billing

Agreement has already been created for this token.

Missing token

Long Message

Token is missing


Invalid token


Buyer did not accept billing agreement


Token is missing


Token is missing


Token invalid

Token expired

Buyer has not agreed to the billing agreement.

Token has already been used to create a billing agreement

Token is missing

June 2008

API Error Codes

CreateBillingAgreement Errors

T

ABLE

A.15

Error

Code

10409

Short Message


10410

10411

Invalid token


Long Message


Invalid token




Token invalid

Token expired

June 2008

205

206

API Error Codes

UpdateBillingAgreement Errors

UpdateBillingAgreement Errors

T

ABLE

A.16 UpdateBillingAgreement Errors

T

ABLE

A.16

Error

Code

10001

10004

10201

10204

10209

10209

10211

11451

11451

11452

Short Message

Internal Error


Billing Agreement was cancelled

User’s account is closed or restricted

Disabled

Disabled

Invalid billing agreement

ID

Billing Agreement Id or transaction Id is not valid



Long Message

Internal Error

Invalid argument; description field or custom field is empty and the status is active



Check the description and custom fields of the billing agreement. Either the description or custom field is empty and the status is active or the contents of one of these fields exceeds the maximum field length.

Billing agreement has been cancelled


Preapproved Payments not enabled.


Merchant pull is not enabled for the country or merchant is not enabled for merchant pull

Account number mismatch for the API caller and the account the billing agreement belongs to.

Invalid transaction or billing agreement ID; could not find

Billing Agreement in database




ReferenceID field is empty.

Reference id refers to an invalid transaction.


Mark reference transaction

DoReferenceTransaction Errors

June 2008

API Error Codes

DoReferenceTransaction Errors

T

ABLE

A.17 All Reference Transactions-Related API Errors

T

ABLE

A.17

Error

Code

10001

10002

10004

10009

Short Message

Internal Error

Authentication/Authorizati on Failed


Transaction refused

10010

10201

10202

10203

10204

10205

10206

10207

10209

10210

10211

10212

Long Message

Internal Error

Invalid payment type argument


Invalid Invoice

Agreement canceled

Exceed max

Action required


Risk

Duplicate

Retry

Disabled

No Funding

Profile preference setting

The account for the counterparty is locked or inactive

Non-ASCII invoice id is not supported


Transaction would exceed user’s monthly maximum

Transaction failed, action required by user


Transaction refused due to risk model

Transaction was already processed

Transaction failed but user has alternate funding source


Merchant is locked/close/restricted

Non-ASCII characters are used in InvoiceID field

Billing agreement is not active

Transaction would exceed the monthly limit

Retry the transaction with an alternate funding source.

Merchants is not enabled for preapproved payments (PAP); applies only to legacy PAP billing agreements

Payee has no funding sources.

Transaction failed because has no funding sources

Invalid MP ID

A profile preference is set to automatically deny certain transactions

Invalid MP ID

A profile preference is set that automatically denies this kind of transaction

June 2008

207

208

API Error Codes


T

ABLE

A.17

Error

Code

10213

10214

10215

10216

10400

10401

10402

10406

10412

10413

10414

10417

Short Message

Invalid Soft Descriptor

Long Message

The soft descriptor passed in contains invalid characters


Soft descriptor format error.

Soft Descriptor truncated The soft descriptor was truncated


Duplicate invoice

Transaction refused because a confirmed address is not available

TotalOrder amount is missing Transaction refused because of an invalid argument. See additional error messages for details.


Authorization only is not allowed for merchant.

Order total is missing.

Order total is invalid.

TotalOrder amount is invalid

This merchant account is not permitted to set PaymentAction? to

Authorization. Please contact

Customer Service.

The PayerID? value is invalid.

Merchant is not eligible for auth settlement

Merchant account number is invalid

Payment has already been made for this InvoiceID?.


Payment already made for the invoice

Total of cart items does not match order total






Amount exceeds the max amount for a single txn

Account not associated with a usable funding source

June 2008

API Error Codes


T

ABLE

A.17

Error

Code

10417

10418

10420

10426

10427

10428

10429

10429

10430

10431

Short Message


Long Message




Credit card or Billing Agreement is required to complete payment

Currencies in the shopping cart must be the same










PaymentAction? tag is missing.





Item sales tax is invalid

Item amount is missing.


PaymentAction? tag is missing.

ItemTotal amount is invalid.

ShippingTotal amount is invalid.

HandlingTotal amount is invalid

TaxTotal amount is invalid.

PaymentDetailsItem.Tax field is invalid. Warning only; API executes

PaymentDetailsItem.Amount field is missing. Warning only;

API executes

PaymentDetailsItem.Amount field is invalid. Warning only;

API executes

June 2008

209

210

API Error Codes


T

ABLE

A.17

Error

Code

10432

10433

10434

10441

10442

Short Message






10504

10527

10537

10538

10539

10546

Long Message


Value of OrderDescription element has been truncated.




InvoiceID field is too long; maximum length is 256

OrderDescription field is too long; maximum length is 127.

Warning only; API executes

Custom field is too long; maximum length is 256.

Warning only; API executes

NotifyURL field is too long; maximum length for notify URL is 2048

The cvv2 is invalid.

Invalid Data

Risk Control Country Filter

Failure


Failure



PayPal Risk Model.

Gateway Decline





The transaction was refused because the country was prohibited as a result of your Country Monitor

Risk Control Settings.

The transaction was refused because the maximum amount was excused as a result of your

Maximum Amount Risk Control

Settings.



Model.


ButtonSource field is too long; maximum length is 32. Warning only; API executes

CVV2 field is invalid.

CreditCardNumber and/or

CreditCardType is invalid

Transaction refused due to country monitor risk control

Transaction refused due to max amount risk control

Transaction declined by Risk

Control settings: PayPal Risk model

IP fraud models failed.

June 2008

API Error Codes


T

ABLE

A.17

Error

Code

10560

10567

10600

10601

10621

10622

10623

10725

10727

10728

10729

10730

10731

10736

10747

10748

10755

Short Message

Invalid Data

Invalid Data

Long Message

The issue number of the credit card is invalid.

A Start Date or Issue Number is required.


IssueNumber is invalid.

None of Start date or issue number is specified (only applies to Switch and Solo credit cards)

Authorization voided

Authorization expired.

Order has expired.

Order is voided.

Authorization voided.

Authorization has expired

Order has expired.

Order is voided.




Error

There was an error in the Shipping

Address Country field

Shipping Address1 Empty The field Shipping Address1 is required


Empty

The field Shipping Address City is required


Empty


Code Empty


Empty



Invalid Data

The field Shipping Address State is required

The field Shipping Address Postal

Code is required


Country is required

A match of the Shipping Address

City, State, and Postal Code failed.

Invalid Data

Unsupported Currency.

This transaction cannot be processed without a valid IP address.


Verification number.

This transaction cannot be processed due to an unsupported currency.

Shipping address error in country field

Shipping address error in address1 field

Shipping address error in city field

Shipping address error in state field

Shipping address error in postal code

Country code is empty in shipping address

Match of shipping address, city, state, and postal code failed.

IPAddress field is invalid.

CVV2 field is missing.

June 2008

211

212

API Error Codes


T

ABLE

A.17

Error

Code

11302

11451

11451

11451

11451

11452

11453

11453

11454

11459

11610

11611

11612

18014

Short Message

Cannot pay self








Warning: Could not send email to the buyer

Invalid Data

Long Message

The transaction was refused because you cannot send money to yourself.




Cannot pay self. Merchant is referencing own transaction.

Invalid reference id






Warning: Could not send email to the buyer

Reference transaction is not associated with a billing agreement.

Reference id either not found or could not be decrypted

Reference id either not found or could not be decrypted


Mark reference transaction

Feature wired off

Feature not supported in standin

The shipping address must match the user’s address in the PayPal account.

Payment Pending your review in

Fraud Management Filters

Failed to send email to buyer.

This error is not fatal and generates a warning.

The shipping address on file does not match the requested shipping address.

Payment Pending your review in Fraud

Management Filters



Gateway Decline





Verification number.

June 2008

API Error Codes

AddressVerify API Errors

AddressVerify API Errors

T

ABLE

A.18 AddressVerify API Errors

T

ABLE

A.18

Error Code Short Message


10004

10004

10009



The API is disabled.

Long Message

Invalid email format

Invalid street format

Invalid zip format

The Address API is currently disabled

ManagePendingTransactionStatus API Errors

T

ABLE

A.19 ManagePendingTransactionStatus API Errors

T

ABLE

A.19

Error Code Short Message

11614

11614


The transaction has already been Accepted/Denied and the status cannot be changed

Long Message


The transaction has already been Accepted/Denied and the status cannot be changed

June 2008

213

API Error Codes

ManagePendingTransactionStatus API Errors

214

June 2008

B

Country Codes

T

ABLE

B.1 Country Codes

T

ABLE

B.1

Country

AFGHANISTAN

ÅLAND ISLANDS

ALBANIA

ALGERIA

AMERICAN SAMOA

ANDORRA

ANGOLA

ANGUILLA

ANTARCTICA

ANTIGUA AND BARBUDA

ARGENTINA

ARMENIA

ARUBA

AUSTRALIA

AUSTRIA

AZERBAIJAN

BAHAMAS

BAHRAIN

BANGLADESH

BARBADOS

BELARUS

BELGIUM

June 2008

Code

AW

AU

AT

AZ

AQ

AG

AR

AM

AS

AD

AO

AI

AF

AX

AL

DZ

BS

BH

BD

BB

BY

BE

215

216

Country Codes

T

ABLE

B.1

Country

BELIZE

BENIN

BERMUDA

BHUTAN

BOLIVIA

BOSNIA AND HERZEGOVINA

BOTSWANA

BOUVET ISLAND

BRAZIL

BRITISH INDIAN OCEAN TERRITORY

BRUNEI DARUSSALAM

BULGARIA

BURKINA FASO

BURUNDI

CAMBODIA

CAMEROON

CANADA

CAPE VERDE

CAYMAN ISLANDS

CENTRAL AFRICAN REPUBLIC

CHAD

CHILE

CHINA

CHRISTMAS ISLAND

COCOS (KEELING) ISLANDS

COLOMBIA

COMOROS

CONGO

June 2008

Code

TD

CL

CN

CX

CA

CV

KY

CF

CC

CO

KM

CG

BF

BI

KH

CM

BR

IO

BN

BG

BO

BA

BW

BV

BZ

BJ

BM

BT

T

ABLE

B.1

Country

CONGO, THE DEMOCRATIC REPUBLIC OF THE

COOK ISLANDS

COSTA RICA

COTE D'IVOIRE

CROATIA

CUBA

CYPRUS

CZECH REPUBLIC

DENMARK

DJIBOUTI

DOMINICA

DOMINICAN REPUBLIC

ECUADOR

EGYPT

EL SALVADOR

EQUATORIAL GUINEA

ERITREA

ESTONIA

ETHIOPIA

FALKLAND ISLANDS (MALVINAS)

FAROE ISLANDS

FIJI

FINLAND

FRANCE

FRENCH GUIANA

FRENCH POLYNESIA

FRENCH SOUTHERN TERRITORIES

GABON

June 2008

Code

FO

FJ

FI

FR

ER

EE

ET

FK

GF

PF

TF

GA

EC

EG

SV

GQ

DK

DJ

DM

DO

HR

CU

CY

CZ

CD

CK

CR

CI

Country Codes

217

218

Country Codes

T

ABLE

B.1

Country

GAMBIA

GEORGIA

GERMANY

GHANA

GIBRALTAR

GREECE

GREENLAND

GRENADA

GUADELOUPE

GUAM

GUATEMALA

GUERNSEY

GUINEA

GUINEA-BISSAU

GUYANA

HAITI

HEARD ISLAND AND MCDONALD ISLANDS

HOLY SEE (VATICAN CITY STATE)

HONDURAS

HONG KONG

HUNGARY

ICELAND

INDIA

INDONESIA

IRAN, ISLAMIC REPUBLIC OF

IRAQ

IRELAND

ISLE OF MAN

June 2008

Code

HU

IS

IN

ID

HM

VA

HN

HK

IR

IQ

IE

IM

GN

GW

GY

HT

GP

GU

GT

GG

GI

GR

GL

GD

GM

GE

DE

GH

T

ABLE

B.1

Country

ISRAEL

ITALY

JAMAICA

JAPAN

JERSEY

JORDAN

KAZAKHSTAN

KENYA

KIRIBATI

KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF

KOREA, REPUBLIC OF

KUWAIT

KYRGYZSTAN

LAO PEOPLE'S DEMOCRATIC REPUBLIC

LATVIA

LEBANON

LESOTHO

LIBERIA

LIBYAN ARAB JAMAHIRIYA

LIECHTENSTEIN

LITHUANIA

LUXEMBOURG

MACAO

MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF

MADAGASCAR

MALAWI

MALAYSIA

MALDIVES

Code

LT

LU

MO

MK

LS

LR

LY

LI

MG

MW

MY

MV

KG

LA

LV

LB

KI

KP

KR

KW

JE

JO

KZ

KE

IL

IT

JM

JP

June 2008

Country Codes

219

220

Country Codes

T

ABLE

B.1

Country

MALI

MALTA

MARSHALL ISLANDS

MARTINIQUE

MAURITANIA

MAURITIUS

MAYOTTE

MEXICO

MICRONESIA, FEDERATED STATES OF

MOLDOVA, REPUBLIC OF

MONACO

MONGOLIA

MONTSERRAT

MOROCCO

MOZAMBIQUE

MYANMAR

NAMIBIA

NAURU

NEPAL

NETHERLANDS

NETHERLANDS ANTILLES

NEW CALEDONIA

NEW ZEALAND

NICARAGUA

NIGER

NIGERIA

NIUE

NORFOLK ISLAND

June 2008

Code

AN

NC

NZ

NI

NA

NR

NP

NL

NE

NG

NU

NF

MS

MA

MZ

MM

FM

MD

MC

MN

MR

MU

YT

MX

ML

MT

MH

MQ

T

ABLE

B.1

Country

NORTHERN MARIANA ISLANDS

NORWAY

OMAN

PAKISTAN

PALAU

PALESTINIAN TERRITORY, OCCUPIED

PANAMA

PAPUA NEW GUINEA

PARAGUAY

PERU

PHILIPPINES

PITCAIRN

POLAND

PORTUGAL

PUERTO RICO

QATAR

REUNION

ROMANIA

RUSSIAN FEDERATION

RWANDA

SAINT HELENA

SAINT KITTS AND NEVIS

SAINT LUCIA

SAINT PIERRE AND MIQUELON

SAINT VINCENT AND THE GRENADINES

SAMOA

SAN MARINO

SAO TOME AND PRINCIPE

June 2008

Code

SH

KN

LC

PM

RE

RO

RU

RW

VC

WS

SM

ST

PL

PT

PR

QA

PY

PE

PH

PN

PW

PS

PA

PG

MP

NO

OM

PK

Country Codes

221

222

Country Codes

T

ABLE

B.1

Country

SAUDI ARABIA

SENEGAL

SERBIA AND MONTENEGRO

SEYCHELLES

SIERRA LEONE

SINGAPORE

SLOVAKIA

SLOVENIA

SOLOMON ISLANDS

SOMALIA

SOUTH AFRICA

SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS

SPAIN

SRI LANKA

SUDAN

SURINAME

SVALBARD AND JAN MAYEN

SWAZILAND

SWEDEN

SWITZERLAND

SYRIAN ARAB REPUBLIC

TAIWAN, PROVINCE OF CHINA

TAJIKISTAN

TANZANIA, UNITED REPUBLIC OF

THAILAND

TIMOR-LESTE

TOGO

TOKELAU

Code

SY

TW

TJ

TZ

SJ

SZ

SE

CH

TH

TL

TG

TK

ES

LK

SD

SR

SB

SO

ZA

GS

SL

SG

SK

SI

SA

SN

CS

SC

June 2008

T

ABLE

B.1

Country

TONGA

TRINIDAD AND TOBAGO

TUNISIA

TURKEY

TURKMENISTAN

TURKS AND CAICOS ISLANDS

TUVALU

UGANDA

UKRAINE

UNITED ARAB EMIRATES

UNITED KINGDOM

UNITED STATES

UNITED STATES MINOR OUTLYING ISLANDS

URUGUAY

UZBEKISTAN

VANUATU

VENEZUELA

VIET NAM

VIRGIN ISLANDS, BRITISH

VIRGIN ISLANDS, U.S.

WALLIS AND FUTUNA

WESTERN SAHARA

YEMEN

ZAMBIA

ZIMBABWE

Code

UM

UY

UZ

VU

UA

AE

GB

US

TM

TC

TV

UG

TO

TT

TN

TR

WF

EH

YE

ZM

ZW

VE

VN

VG

VI

Country Codes

June 2008

223

Country Codes

224

June 2008

C

State and Province Codes

T

ABLE

C.1 State and Province Codes

T

ABLE

C.1

Canadian Province or U.S. State

Alberta

British Columbia

Manitoba

New Brunswick

Newfoundland and Labrador

Northwest Territories

Nova Scotia

Nunavut

Ontario

Prince Edward Island

Quebec

Saskatchewan

Yukon

Alabama

Alaska

American Samoa

Arizona

Arkansas

California

Colorado

Connecticut

Delaware

June 2008

Abbreviation

YT

AL

AK

AS

ON

PE

QC

SK

NL

NT

NS

NU

AB

BC

MB

NB

AZ

AR

CA

CO

CT

DE

225

226

State and Province Codes

T

ABLE

C.1


Massachusetts

Michigan

Minnesota

Mississippi

Missouri

Montana

Nebraska

Nevada

New Hampshire

New Jersey

New Mexico

New York

District of Columbia

Federated States of Micronesia

Florida

Georgia

Guam

Hawaii

Idaho

Illinois

Indiana

Iowa

Kansas

Kentucky

Louisiana

Maine

Marshall Islands

Maryland

June 2008

Abbreviation

MO

MT

NE

NV

MA

MI

MN

MS

NH

NJ

NM

NY

LA

ME

MH

MD

IN

IA

KS

KY

GU

HI

ID

IL

DC

FM

FL

GA

T

ABLE

C.1


North Carolina

North Dakota

Northern Mariana Islands

Ohio

Oklahoma

Oregon

Palau

Pennsylvania

Puerto Rico

Rhode Island

South Carolina

South Dakota

Tennessee

Texas

Utah

Vermont

Virgin Islands

Virginia

Washington

West Virginia

Wisconsin

Wyoming

Armed Forces Americas

Armed Forces

Armed Forces Pacific

June 2008


Abbreviation

TN

TX

UT

VT

PR

RI

SC

SD

OK

OR

PW

PA

NC

ND

MP

OH

WI

WY

AA

AE

AP

VI

VA

WA

WV

227


228

June 2008

D

Currency Codes

T

ABLE

D.1 Currency Codes

T

ABLE

D.1

ISO-4217 Code

PLN

SEK

SGD

USD

HUF

JPY

NOK

NZD

DKK

EUR

GBP

HKD

AUD

CAD

CHF

CZK

Currency

Australian Dollar

Canadian Dollar

Swiss Franc

Czech Koruna

Danish Krone

Euro

Pound Sterling

Hong Kong Dollar

Hungarian Forint

Japanese Yen

Norwegian Krone

New Zealand Dollar

Polish Zloty

Swedish Krona

Singapore Dollar

U.S. Dollar

June 2008

229

Currency Codes

230

June 2008

E

AVS and CVV2 Response Codes

z z

“AVS Response Codes” on page 231

“CVV2 Response Codes” on page 233

AVS Response Codes

z z

AVS Response Codes for Visa, Mastercard, Discover, and American Express

AVS Response Codes for Maestro and Solo

June 2008

231

232

AVS and CVV2 Response Codes

AVS Response Codes

T

ABLE

E.1 AVS Response Codes for Visa, MasterCard, Discover, and American Express

T

ABLE

E.1

AVS Code

A

B

C

D

E

I

N

F

G

P

R

S

X

Y

U

W

Z

All others

Meaning

Address

International “A”

International “N”

International “X”

Not allowed for MOTO

(Internet/Phone) transactions

UK-specific “X”

Global Unavailable

International Unavailable

No

Postal (International “Z”)

Retry

Service not Supported

Unavailable

Whole ZIP

Exact match

Yes

ZIP

Error

Matched Details

Address only (no ZIP)

Address only (no ZIP)

None

N

OT E

:

N O TE

:

The transaction is declined.

Address and Postal Code

Not applicable

N

OT E

:

N O TE

:


Address and Postal Code

Not applicable

Not applicable

None

N

OT E

:

N O TE

:


Postal Code only (no Address)

Not applicable

Not applicable

Not applicable

Nine-digit ZIP code (no Address)

Address and nine-digit ZIP code

Address and five-digit ZIP

Five-digit ZIP code (no Address)

Not applicable

T

ABLE

E.2 AVS Response Codes for Maestro and Solo

T

ABLE

E.2

AVS Code

0

1

Meaning

All the address information matched.

None of the address information matched.

Matched Details

All information matched

None

N

O T E

:

N O T E

:


June 2008


CVV2 Response Codes

T

ABLE

E.2

AVS Code

2

3

4

Null

Meaning

Part of the address information matched.

The merchant did not provide AVS information. Not processed.

Address not checked, or acquirer had no response. Service not available.

No AVS response was obtained.

Default value of field.

Matched Details

Partial

Not applicable

Not applicable

Not applicable

CVV2 Response Codes

z z

CVV2 Response Codes for Visa, MasterCard, Discover, and American Express

CVV2 Response Codes for Maestro and Solo

T

ABLE

E.3 CVV2 Response Codes for Visa, MasterCard, Discover, and American Express

T

ABLE

E.3

CVV2 Code

P

S

M

N

U

X

Meaning

Match

No match

Not processed

Service not supported

Service not available

No response

Matched Details

CVV2CSC

None

Not applicable

Not applicable

Not applicable

Not applicable

T

ABLE

E.4 CVV2 Response Codes for Maestro and Solo

T

ABLE

E.4

1

2

CVV2 Code

0

Meaning

Matched

No match

The merchant has not implemented

CVV2 code handling

Matched Details

CVV2

None

Not applicable

June 2008

233


CVV2 Response Codes

T

ABLE

E.4

CVV2 Code

3

4

All others

Meaning

Merchant has indicated that CVV2 is not present on card

Service not available

Error

Matched Details

Not applicable

Not applicable

Not applicable

234

June 2008

No results