SOAP API Developer

Reference

Last updated: June 2008

 PayPal SOAP API Developer Reference

Document Number: 100002.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 1 PayPal SOAP API Overview . . . . . . . . . . . . . . . . . 13

Services Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
PayPal WSDL/XSD Schema Definitions. . . . . . . . . . . . . . . . . . . . . . . . . 14
API Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SOAP RequesterCredentials: Username, Password, Signature, and Subject . . . . . 16
SOAP Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
SOAP Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
SOAP Message Style: doc-literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
SOAP Request Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Request Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Response Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
CorrelationID for Reporting Problems to PayPal . . . . . . . . . . . . . . . . . . . . 22
PayPal SOAP API Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Character Encoding, Data Types and Formats, and Currencies . . . . . . . . . . . . 23

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

DoCapture API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
DoCapture Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
DoAuthorization API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
DoAuthorization Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoAuthorization Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoReauthorization API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoReauthorization Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
DoReauthorization Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
DoVoid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

SOAP API Developer Reference June 2008 3

 Contents

DoVoid Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
DoVoid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 3 DoDirectPayment API . . . . . . . . . . . . . . . . . . . . 35

DoDirectPayment Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
DoDirectPayment Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 4 Express Checkout API Operations . . . . . . . . . . . . . 51

SetExpressCheckout API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
SetExpressCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
SetExpressCheckout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
GetExpressCheckoutDetails API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
GetExpressCheckoutDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . 65
GetExpressCheckoutDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . 66
DoExpressCheckoutPayment API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
DoExpressCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . 75
DoExpressCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 5 GetTransactionDetails API . . . . . . . . . . . . . . . . . 87

GetTransactionDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
GetTransactionDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 6 MassPay API . . . . . . . . . . . . . . . . . . . . . . . . . 99

MassPay Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
MassPay Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Chapter 7 RefundTransaction API . . . . . . . . . . . . . . . . . . 103

RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Chapter 8 TransactionSearch API . . . . . . . . . . . . . . . . . . 107

TransactionSearch Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
TransactionSearch Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

4 June 2008 SOAP API Developer Reference

 Contents

Chapter 9 Recurring Payments and Reference Transactions API

Operations113
CreateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
CreateRecurringPaymentsProfile Request . . . . . . . . . . . . . . . . . . . . . . . 114
CreateRecurringPaymentsProfile Response . . . . . . . . . . . . . . . . . . . . . .125
GetRecurringPaymentsProfileDetails API . . . . . . . . . . . . . . . . . . . . . . . . . .125
GetRecurringPaymentsProfileDetails Request . . . . . . . . . . . . . . . . . . . . .126
GetRecurringPaymentsProfileDetails Response . . . . . . . . . . . . . . . . . . . .127
ManageRecurringPaymentsProfileStatus API . . . . . . . . . . . . . . . . . . . . . . . .136
ManageRecurringPaymentsProfileStatus Request . . . . . . . . . . . . . . . . . . .137
ManageRecurringPaymentsProfileStatus Response . . . . . . . . . . . . . . . . . .137
BillOutstandingAmount API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
BillOutstandingAmount Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
BillOutstandingAmount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
UpdateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
UpdateRecurringPaymentsProfile Request . . . . . . . . . . . . . . . . . . . . . . .141
UpdateRecurringPaymentsProfile Response . . . . . . . . . . . . . . . . . . . . . .147
SetCustomerBillingAgreement API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
SetCustomerBillingAgreement Request . . . . . . . . . . . . . . . . . . . . . . . . .148
SetCustomerBillingAgreement Response . . . . . . . . . . . . . . . . . . . . . . . .151
GetBillingAgreementCustomerDetails API . . . . . . . . . . . . . . . . . . . . . . . . . .151
GetBillingAgreementCustomerDetails Request . . . . . . . . . . . . . . . . . . . . .152
GetBillingAgreementCustomerDetails Response . . . . . . . . . . . . . . . . . . . .152
DoReferenceTransaction API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
DoReferenceTransaction Request. . . . . . . . . . . . . . . . . . . . . . . . . . . .156
DoReferenceTransaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . .166

Chapter 10 DoNonReferencedCredit API . . . . . . . . . . . . . . . 171

DoNonReferencedCredit Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
DoNonReferencedCredit Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

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

Fraud Management Filters API Prerequisites . . . . . . . . . . . . . . . . . . . . . . . .177
ManagePendingTransactionStatus API . . . . . . . . . . . . . . . . . . . . . . . . . . .178
ManagePendingTransactionStatus Request. . . . . . . . . . . . . . . . . . . . . . .179
ManagePendingTransactionStatus Response . . . . . . . . . . . . . . . . . . . . . .179

SOAP API Developer Reference June 2008 5

 Contents

Chapter 12 GetBalance API . . . . . . . . . . . . . . . . . . . . . . 181

GetBalance Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
GetBalance Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

Chapter 13 AddressVerify API . . . . . . . . . . . . . . . . . . . . . 183

AddressVerify Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
AddressVerify Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184

Chapter A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 187

General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .213
DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .215
Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
Mass Pay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .242
CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .251

Chapter B Country Codes . . . . . . . . . . . . . . . . . . . . . . 253

Chapter C State and Province Codes . . . . . . . . . . . . . . . . . 263

Chapter D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 267

6 June 2008 SOAP API Developer Reference

 Contents

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

AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271

SOAP API Developer Reference June 2008 7

 Contents

8 June 2008 SOAP API Developer Reference

 Contents

SOAP API Developer Reference June 2008 9

 Contents

10 June 2008 SOAP API Developer Reference

 Preface

This Document
This document describes the PayPal SOAP Application Programming Interface (API) and
service.

Intended Audience
This document is written for programmers familiar with application programming standards
such as the Simple Object Access Protocol (SOAP), the Web Services Description Language
(WSDL), and XML Schema Definition (XSD) language.

Revision History
Revision history for PayPal SOAP API Developer Reference.

TABLE P.1 Revision History

Date Description

June 2008 Rearranged material, added error codes, and moved some material to the
Express Checkout Integration Guide.

April 2008 Added Fraud Management Filters information. Changed recurring payments
information.

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

January 2008 z Added billing agreement fields to SetExpressCheckout for recurring

payments
z Updated CreateRecurringPaymentsProfile for new recurring payments
features.
z Added new recurring payments APIs
z Added new DoNonReferencedCredit API

September 2007 z Update eBay auctions for Express Checkout section

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

SOAP API Developer Reference June 2008 11

 Revision History

TABLE P.1 Revision History

Date Description

August 2007 Updated DoCapture, DoReferenceTransaction and related error codes.

May 2007 Added Recurring Payments APIs: SetCustomerBillingAgreement,

GetBillingAgreementCustomerDetails, and
CreateRecurringPaymentsProfile.

March 2007 Minor bug fixes including adding Switch/Solo codes to AVS Response Codes
and CVV2 Response Codes in Direct Payment API chapter.

February 2007 Minor bug fixes.

December 2006 Minor bug fixes.

October 2006 Book renamed SOAP API Developer Reference. Former books for the SOAP
SDKs now included in this one volume.

June 2006 CardNumber field added to TransactionSearch API. Significantly improved

error messages for Direct Payment API. Minor change to one Mass Pay API
error message.

March 2006 Updated for new API credential: API signatures. New SOAP service endpoint
for signatures.
Miscellaneous minor corrections throughout.

January 2006 Additional error messages for Authorization & Capture APIs and Express
Checkout APIs.

December 2005 Removed erroneous description that stated that the SetExpressCheckoutRequest
field cpp-header-image must be URL-encoded.

12 June 2008 SOAP API Developer Reference

 1 PayPal SOAP API Overview

The PayPal SOAP API provides programmatic access to PayPal features and services.
Developers can build custom applications, tools, and services that correspond to the same
services and tools available through the main PayPal website, https://www.paypal.com/.
Typical applications include searching for transactions, paying en masse, and making
refunds.The API is based on open standards known collectively as “Web Services,” which
include the Simple Object Access Protocol (SOAP), Web Services Definition Language
(WSDL), and the XML Schema Definition language (XSD). These standards are supported by
a wide range of development tools on a variety of platforms.

Services Architecture
Like many web services, PayPal SOAP is a combination of client-side and server-side
schemas, hardware and software servers, and core services.

PayPal SOAP High-level Diagram

In an object-oriented processing model, the interface to SOAP requests/responses is an object

in your application’s native programming language. Your third-party SOAP client generates
business-object interfaces and network stubs from PayPal-provided WSDL and XSD files that
specify the PayPal SOAP message structure, its contents, and the PayPal API service bindings.

SOAP API Developer Reference June 2008 13

 PayPal SOAP API Overview
Services Architecture

A business application works with data in the form of object properties to send and receive
data by calling object methods. The SOAP client handles the details of building the SOAP
request, sending it to the PayPal service, and converting the response back to an object.

PayPal WSDL/XSD Schema Definitions

The PayPal Web Services schema and its underlying eBay Business Language (eBL) base and
core components are required for developing applications with the PayPal Web Services API.
The following are the locations of the WSDL and XSD files.

Location of PayPal WSDL and XSD Files

Development and Test with the PayPal Sandbox API Service

PayPal Schema https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl

eBL Base Components and https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd

Component Types https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd

Production with Live PayPal Web Services API Service

PayPal Schema https://www.paypal.com/wsdl/PayPalSvc.wsdl

eBL Base Components and http://www.paypal.com/wsdl/eBLBaseComponents.xsd

Component Types http://www.paypal.com/wsdl/CoreComponentTypes.xsd

API Concepts and Terminology

Here are some basic concepts and terminology relating to PayPal’s API service and security
authentication.

14 June 2008 SOAP API Developer Reference

 PayPal SOAP API Overview
Services Architecture

Basic PayPal API Set-up Concepts and Terminology

Term Definition
API Calls PayPal Application Programming Interface services, by which companies can make payments,
search transactions, refund payments, view transaction information, and other business
functions.
API Certificate Mututally exclusive with API Signature. A PayPal-generated unique digital certificate file that
you download from the PayPal website and use on the client computer to encrypt the HTTPS
requests of your API calls to PayPal’s API server.
An API certificate is suitable if you have complete control over your own web server.
API Signature Mututally exclusive with API Signature. A PayPal-generated unique digital signature (a line of
text, or hash) that you copy from PayPal’s website and include in your API calls. An alternative
to API Certificate security.
Your digital signature, your API username, and your API password all together are called three-
token authentication, because you include each of them as a programatic token in your API calls.
An API signature is suitable for use with Microsoft Windows web servers or other shared web
server configurations, such as those used by web hosting services.
API Username A PayPal-generated identifying account name and password that you use specifically for making
and Password API calls. You include your API username and password with every API call. The API username
and password are different from your PayPal login username (email address) and password.
Subject An indicator in an API call of the account for whom the call is being made. This is the
authorization programmatic aspect of third-party authorization. The value of the Subject field is the third-
party’s Paypal email address.
First-Party A company makes API calls itself from its own server to PayPal's server. The company has its
Access own API certificate or API signature, username, and password.
Example:
A staff programmer for a merchant's company obtains a PayPal-issued API certificate file and
makes API calls for the company from the company's own web server.
Third-Party Another person or company makes API calls on the your behalf. You grant the third-party your
Access permission to make API calls for you.
Example:
A web hosting service has its own API certificate, API username, and API password. Its
customers, who are merchants that use PayPal, give the hosting service their permission to make
API calls on their behalf. The hosting service includes a merchant's PayPal email address in the
"Subject" field of an API call.

Security
The PayPal SOAP API service is protected to ensure that only authorized PayPal members use
it. There are four levels of security:
1. A required API username (Username field) and API password (Password field)
2. A third required authentication mechanism, which is either one of the following:

SOAP API Developer Reference June 2008 15

 PayPal SOAP API Overview
Services Architecture

– Client-side request signing via a PayPal-issued API Certificate

– Request authentication via an an API Signature included in the request (Signature field)
3. An optional third-party authorization to make the API call on some other account’s behalf
(the optional Subject field).
4. Secure Sockets Layer (SSL) data transport
A failure of authenticated security at any one of these levels denies access to the PayPal SOAP
API service.

SOAP RequesterCredentials: Username, Password, Signature, and Subject

For the security of your business, PayPal must verify that merchants or third-party developers
are permitted to initiate a transaction before they make one. PayPal authenticates each request.
If the request cannot be authenticated, a SOAP security fault is returned.
In the SOAP request header, your SOAP client must set the Username, Password elements
to pass an API username/password combination. In addition, you can set the Signature or
Subject elements to specify your API signature string and an optional third-party account
email address for authentication. The following is a partial example of the
RequesterCredentials elements required for all SOAP requests. For a correlation of these
elements to the generic structure of an entire SOAP request, see “Request Structure” on
page 18.

<SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”>
<Username>api_username</Username>
<Password>api_password</Password>
<Signature>api_signature</Signature>
<Subject>authorizing_account_emailaddress</Subject>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
where:

RequesterCredentials Authentication Elements in SOAP Header

Element Value Description

<Username> api_username Your API username, which is auto-generated by PayPal when you
apply for a digital certificate to use the PayPal SOAP API. You can
see this value on https://www.paypal.com/in your Profile under
API Access > API Certificate Information.

<Password> api_password Your API password, which you specify when you apply for a digital
certificate to use the PayPal SOAP API.

16 June 2008 SOAP API Developer Reference

 PayPal SOAP API Overview
SOAP Service Endpoints

Element Value Description

<Signature> api_signature Your API signature, if you use one instead of an API Certificate.

<Subject> authorizing_ The email address of a third-party for whom you are sending
account_ requests to the PayPal SOAP API. Your API username must have
emailaddress been granted permission by this third-party to make any particular
PayPal API request.

SOAP Service Endpoints

Depending on your chosen authentication mechanism, your SOAP requests must be processed
by different service endpoints.
SOAP Service Endpoints
Authentication
Mechanism Live Production Endpoint Test (Sandbox) Endpoint
API Signature https://api-3t.paypal.com/2.0/ https://api-3t.sandbox.paypal.com/2.0/
API Certificate https://api.paypal.com/2.0/ https://api.sandbox.paypal.com/2.0/

SOAP Implementation
This section contains information about the PayPal SOAP implementation.

SOAP Message Style: doc-literal

PayPal uses doc-literal SOAP messaging, not rpc-encoding. With doc-literal, a
single service interface call passes an XML document in the request to the PayPal API server,
which responds with an XML document instance.

SOAP Request Envelope

The following diagram illustrates the contents of a PayPal SOAP request envelope.
All PayPal APIs are based on two core structures: AbstractRequestType and
AbstractResponseType.

SOAP API Developer Reference June 2008 17

 PayPal SOAP API Overview
SOAP Implementation

Diagram of SOAP Request Envelope

Request Structure
The following is an annotated description of the SOAP request structure required by the
PayPal SOAP API.

General Structure of PayPal API SOAP Request

<?xml version=”1.0” encoding=”UTF-8”?>

<SOAP-ENV:Envelope xmlns:xsi= ” http://www.w3.org/2001/XMLSchema-instance”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”
><SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”>
<Username>api_username</Username>
<Password>api_password</Password>

18 June 2008 SOAP API Developer Reference

 PayPal SOAP API Overview
SOAP Implementation

<Signature/>
<Subject/>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<specific_api_name_Req xmlns=”urn:ebay:api:PayPalAPI”>
<specific_api_name_Request>
<Version xmlns=urn:ebay:apis:eBLBaseComponents”>service_version
</Version>
<required_or_optional_fields xsi:type=”some_type_here”>data
</required_or_optional_fields>
</specific_api_name_Request>
</specific_api_name_Req>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Annotation of Generic SOAP Request

Lines Comment

12, 13 The <Username> and <Password> fields are part of the PayPal SOAP API
<RequesterCredentials> security authentication mechanism you must construct for
every SOAP request header. For details, see “SOAP RequesterCredentials: Username,
Password, Signature, and Subject” on page 16.

14 The <Signature> element should include your API signature string if that is the kind of API
credential you are using. For more details, see “RequesterCredentials Authentication Elements
in SOAP Header” on page 16.

15 The <Subject> element can specify a third-party PayPal account by whom you are
authorized to make this request. For more details, see “RequesterCredentials Authentication
Elements in SOAP Header” on page 16.

19 through 27 The SOAP request for every PayPal API follows this element naming pattern. The API’s
specific name is appended with Req, and in this element the specific_api_name_Request is
nested. Each specific_api_name_Request has a corresponding
specific_api_name_RequestType.

22 The number of the PayPal SOAP API version is required on each SOAP request.
This version number is the value of ns:version in
https://www.paypal.com/wsdl/PalPalSvc.wsdl

24 For details about required and optional elements and values for specific requests, see the
description of individual APIs.

Response Structure
The following is an annotated description of the structure of a SOAP response from the PayPal
API where response is Success:

SOAP API Developer Reference June 2008 19

 PayPal SOAP API Overview
SOAP Implementation

<?xml version=”1. 0”?>

<SOAP-ENV:Envelope
xmlns:SOAP-ENV= ”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”
xmlns:cc=”urn:ebay:apis:CoreComponentTypes”
xmlns:wsu=”http://schemas.xmlsoap.org/ws/2002/07/utility”
xmlns:saml=”urn:oasis:names:tc:SAML:1.0:assertion”
xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”
xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xmlns:ebl=”urn:ebay:apis:eBLBaseComponents”
xmlns:ns=”urn:ebay:api:PayPalAPI”>
<SOAP-ENV:Header>
<Security
xmlns=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xsi:type=”wsse:SecurityType”
/>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials
xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”
/>
</RequesterCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body id=”_0”>
<specific_api_name_Response xmlns=”urn:ebay:api:PayPalAPI”>
<Timestamp xmlns=”urn:ebay:api:PayPalAPI”> dateTime_in_UTC/GMT
</TIMESTAMP>
<Ack xmlns=”urn:ebay:apis:eBLBaseComponents”>Success</Ack>
<Version xmlns=”urn:ebay:apis:eBLBaseComponents”>
serviceVersion
</Version>
<CorrelationId xmlns=”urn:ebay:apis:eBLBaseComponents”>
applicationCorrelation
</CorrelationID>
<Build xmlns=”urn:ebay:apis:eBLBaseComponents”>
api_build_number
</Build>
<elements_for_specific_api_response> data
</elements_for_specific_api_response>
</specific_api_name_Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

20 June 2008 SOAP API Developer Reference

 PayPal SOAP API Overview
SOAP Implementation

Annotation of Generic SOAP Response

Lines Comment

22 and 31 The specific_api_name_Response start and end elements.

23 Each API response contains a timestamp with its date and time in UTC/GMT.

24 The <Ack> element contains the string Success after the corresponding request has been
successfully processed.
In the case of errors, Ack is set to a value other than Success, and the response body contains
an <Errors> element with information to help you troubleshoot the cause of the error. See
“Error Responses” on page 21.

26 The <CorrelationID> element contains information about the PayPal application that
processed the request.
Use the value of this element if you need to troubleshoot a problem with one of your requests.

27 through 30 The different PayPal APIs return different structures depending on their response definitions.
For detailed information, see the description of the individual APIs.
NOTE: Because a field is defined in the formal structure of an API response does not mean
that that field is necessarily returned. Data are returned in a response only if PayPal
has recorded data that corresponds to the field.

Error Responses
If a request is malformed or some other error, the body of the SOAP response contains an
<Errors> element with other elements that can help you troubleshoot the cause of the error.
The most important of these additional elements are as follows:
z ShortMessage
z LongMessage
z ErrorCode

SOAP API Developer Reference June 2008 21

 PayPal SOAP API Overview
SOAP Implementation

The following example shows the error response if your API username and password do not
match a legitimate API username and password on file with PayPal.

Example of SOAP Error Response: Bad Username or Password

<?xml version="1.0" encoding="UTF-8"?>

< S O A P - EN V: En ve l op e de ta ils
n ot show n >
<S OAP-ENV:Header>... details not shown.</SOAP-ENV:Header>
<SOAP-ENV:Body id="_0">
<GetTransactionDetailsResponse xmlns="urn:ebay:api:PayPalAPI">
<Timestamp xmlns="urn:ebay:apis:eBLBaseComponents">
2005-02-09T21:51:26Z
</Timestamp>
<Ack xmlns="urn:ebay:apis:eBLBaseComponents">Failure</Ack>
<Errors
xmlns="urn:ebay:apis:eBLBaseComponents"
xsi:type="ebl:ErrorType">
<ShortMessage xsi:type="xs:string">
Authentication/Authorization Failed
</ShortMessage>
<LongMessage xsi:type="xs:string">
Username/Password is incorrect
</LongMessage>
<ErrorCode xsi:type="xs:token">10002</ErrorCode>
<SeverityCode xmlns="urn:ebay:apis:eBLBaseComponents">
Error </SeverityCode>
</Errors>
<CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents">
debugging_info
</CorrelationID>
<Version xmlns="urn:ebay:apis:eBLBaseComponents">
1.000000
</Version>
<Build xmlns="urn:ebay:apis:eBLBaseComponents">1.0006</Build>..
other elements in response.</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

CorrelationID for Reporting Problems to PayPal

The value returned in CorrelationID is important for PayPal to determine the precise cause
of any error you might encounter. If you have to troubleshoot a problem with your requests,
we suggest that you capture the value of CorrelationID so you can report it to PayPal.

22 June 2008 SOAP API Developer Reference

 PayPal SOAP API Overview
PayPal SOAP API Definitions

PayPal SOAP API Definitions

The PayPal SOAP API comprises individual API definitions for specific business functions.
As a foundation, the API relies on eBay Business Language (eBL) base and core components.
The core eBL structures AbstractRequestType and AbstractResponseType are the
basis of the SOAP request and response of each PayPal API. AbstractResponseType is
also the framework for error messages common across all PayPal APIs.
PayPal has made some schema design decisions that can affect how businesses design their
own applications.
z Enumerations: Enumerations are defined directly in the PayPal API schema.
z Troubleshooting information: The PayPal API returns information about elements that
trigger errors.
z Backward compatibility: The PayPal API is versioned so that business applications are
backward compatible when new elements are introduced to the server-side schema.
NOTE: eBL defines many structures that are specific to processing auctions. PayPal’s SOAP
schema includes these definitions to maintain compatibility with eBay’s SOAP and
for possible future joint use of SOAP across both eBay and PayPal. The material in
this book focuses only on those SOAP definitions pertinent to use of the PayPal SOAP
API.

Character Encoding, Data Types and Formats, and Currencies

This section details allowed character encoding and character sets, date data types, and
formats.
UTF-8 Character Encoding
The PayPal SOAP API service assumes that all data in SOAP requests is in Unicode,
specifically, the Unicode (or UCS) Transformation Format, 8-bit encoding form (UTF-8).
In SOAP responses, the service always returns data in UTF-8.
Date/Time Formats
The PayPal SOAP API schema defines date/time values as Coordinated Universal Time
(UTC/GMT), using ISO 8601 format, and of type ns:dateTime. An example date/time
stamp is 2006-08-24T05:38:48Z
Core Currency Amount Data Type
The core currency amount data type is call BasicAmountType and is derived from string, and
all currency amount fields have the following structure:
1. The currencyID attribute is required.
2. The amount must have two decimal places.
3. The decimal separator must be a period (“.”).

SOAP API Developer Reference June 2008 23

 PayPal SOAP API Overview
PayPal SOAP API Definitions

4. You must not use any thousands separator.

5. BasicAmountType has a data type of ebl:CurrencyCodeType, which defines a large
number of different currency codes. However, for your processing to succeed, you must set
currencyCode to a valid currency code. Some APIs support only a subset of currencies.

Here is an example. (The field name Amount is an example; actual field names can vary
depending on the specific API.)

<Amount currencyID=”currencyCode”>3.00</Amount>

24 June 2008 SOAP API Developer Reference

 2 Authorization and Capture API
Operation Reference

This chapter describes the PayPal API operations related to delayed payment settlement:
z “DoCapture API” on page 25
z “DoAuthorization API” on page 31
z “DoReauthorization API” on page 32
z “DoVoid API” on page 33

DoCapture API
z “DoCapture Request” on page 26
z DoCapture Response

SOAP API Developer Reference June 2008 25

 Authorization and Capture API Operation Reference
DoCapture API

DoCapture API Diagram

DoCapture Request
DoCapture Request Fields
Field Description
AuthorizationID xs:string
(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.
Amount ebl:BasicAmountType
(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 (,).
CompleteType ebl:CompleteCodeType
(Required) The value Complete indicates that this the last capture you intend to
make.
The value NotComplete indicates that you intend to make additional captures.
NOTE: If Complete, any remaining amount of the original authorized transaction is
automatically voided and all remaining open authorizations are voided.
Character length and limits: 12 single-byte alphanumeric characters.

26 June 2008 SOAP API Developer Reference

 Authorization and Capture API Operation Reference
DoCapture API

Field Description
InvoiceID xs:string
(Optional) Your invoice number or other identification number that is displayed to the
merchant and customer in his transaction history.
NOTE: This value on DoCapture will overwrite a value previously set on
DoAuthorization.
NOTE: The value is recorded only if the authorization you are capturing is an order
authorization, not a basic authorization.
Character length and limits: 127 single-byte alphanumeric characters.
Note xs:string
(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.
SoftDescriptor xs:string
(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 - (dash)
z * (asterisk)
z . (period)
z {space}

If you use any other characters (such as “,”), an error code is returned.
The soft descriptor does not include the phone number, which can be toggled between
the merchant’s customer service number and PayPal’s customer service number.
The maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8
characters are used by the PayPal prefix shown in the data format. Thus, the
maximum length of the soft descriptor passed in the API request is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
z The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools.
z The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
z The soft descriptor is passed in as JanesFlowerGifts LLC.

The resulting descriptor string on the credit card would be:

PAYPAL *EBAY JanesFlow

SOAP API Developer Reference June 2008 27

 Authorization and Capture API Operation Reference
DoCapture API

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

28 June 2008 SOAP API Developer Reference

 Authorization and Capture API Operation Reference
DoCapture API

DoCapture Response Fields

Field Description
AuthorizationID xs:string
(See description) The authorization identification number you specified in the
request.
Character length and limits: 19 single-byte characters maximum.
PaymentInfo ebl:PaymentInfoType
Information about the payment.

PayerInfoType Fields
Field Description
Payer ebl:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters.
PayerID ebl:UserIDType
Unique PayPal customer account identification number.
Character length and limitations:13 single-byte alphanumeric characters.
PayerStatus ebl:PayPalUserStatusCodeType
Status of payer. Valid values are:
z verified
z unverified

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

PayerName ebl:PersonNameType
First and last name of payer.
PayerCountry ebl:CountryCodeType
Payer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: Two single-byte characters.
PayerBusiness xs:string
Payer’s business name.
Character length and limitations: 127 single-byte characters.
Address xs:string
Payer’s shipping address information.

SOAP API Developer Reference June 2008 29

 Authorization and Capture API Operation Reference
DoCapture API

AddressType Fields
Field Description
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal.
Valid values are:
z none
z Confirmed
z Unconfirmed

Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
State or province.
Character length and limitations: 40 single-byte characters.
Required for U.S. addresses only.
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCode
Country code. Character limit: Two single-byte characters.

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters.
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.

30 June 2008 SOAP API Developer Reference

 Authorization and Capture API Operation Reference
DoAuthorization API

Field Description
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters.
LastName ebl:NameType
Payer’s last name
Character length and limitations: 25 single-byte characters.
Suffix ebl:SuffixType
Payer’s suffix
Character length and limitations: 12 single-byte characters.

DoAuthorization API
z DoAuthorization Request
z DoAuthorization Response

SOAP API Developer Reference June 2008 31

 Authorization and Capture API Operation Reference
DoReauthorization API

DoAuthorization API Diagram

DoAuthorization Request
DoAuthorization Request Fields
Field Description
TransactionID xs:string
(Required) The value of the order’s transaction identification number returned by
PayPal.
Character length and limits: 19 single-byte characters maximum.
Amount ebl:BasicAmountType
(Required) Amount to authorize.
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 (,).
TransactionEntity ebl:TransactionEntityType
(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.

DoAuthorization Response
DoAuthorization Response Fields
Field Description
TransactionID xs:string
An authorization identification number.
Amount ebl:BasicAmountType
The amount you specified in the request.

DoReauthorization API

32 June 2008 SOAP API Developer Reference

 Authorization and Capture API Operation Reference
DoVoid API

z DoReauthorization Request
z DoReauthorization Response

DoReauthorization API Diagram

DoReauthorization Request
DoReauthorization Request Fields
Field Description
AuthoriztionID xs:string
(Required) The value of a previously authorized transaction identification number
returned by PayPal.
Character length and limits: 19 single-byte characters maximum.
Amount ebl:BasicAmountType
(Required) Amount to reauthorize.
Limitations: Value is a positive number which cannot exceed $10,000 USD in any
currency. No currency symbol. Must have two decimal places, decimal separator
must be a period (.), and the optional thousands separator must be a comma (,).

DoReauthorization Response
DoReauthorization Response Fields
Field Description
AuthoriztionID xs:string
A new authorization identification number.
Character length and limits:19 single-byte characters maximum.

DoVoid API
z DoVoid Request
z DoVoid Response

SOAP API Developer Reference June 2008 33

 Authorization and Capture API Operation Reference
DoVoid API

DoVoid API Diagram

DoVoid Request
DoVoid Request Fields
Field Description
AuthorizationID xs:string
(Required) The value of the original authorization identification number returned by a
PayPal product.
NOTE: If you are voiding a transaction that has been reauthorized, use the ID from
the original authorization, and not the reauthorization.
Character length and limits: 19 single-byte characters.
Note xs:string
(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
DoVoidResponse Fields
Field Description
AuthorizationID xs:string
The authorization identification number you specified in the request.
Character length and limits: 19 single-byte characters.

34 June 2008 SOAP API Developer Reference

 3 DoDirectPayment API

z DoDirectPayment Request
z DoDirectPayment Response

SOAP API Developer Reference June 2008 35

 DoDirectPayment API
DoDirectPayment Request

DoDirectPayment API Diagram

DoDirectPayment Request
z DoDirectPayment Request Fields
z Credit Card Fields

36 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Request

z Payer Information Fields

z Payer Name Fields
z Billing Address Fields
z Payment Details Fields
z Ebay Item Payment Details Fields
z Ship To Address Fields

SOAP API Developer Reference June 2008 37

 DoDirectPayment API
DoDirectPayment Request

DoDirectPayment Request Fields

Field Description
PaymentAction ebl:PaymentActionCodeType
(Optional) How you want to obtain payment:
z Authorization indicates that this payment is a basic authorization subject to
settlement with PayPal Authorization & Capture.
z Sale indicates that this is a final sale for which you are requesting payment.

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

Default: Sale
NOTE: Order is not allowed for Direct Payment.
CreditCard ebl:CreditCardDetailsType
(Required) Information about the credit card to be charged.
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the credit card to be charged.
IPAddress xs:string
(Required) IP address of the payer’s browser.
NOTE: PayPal records this IP addresses as a means to detect possible fraud.
Character length and limitations: 15 single-byte characters, including periods, for
example: 255.255.255.255.
MerchantSessionId xs:string
(Optional) Your customer session identification token.
NOTE: PayPal records this optional session identification token as an additional
means to detect possible fraud.
Character length and limitations: 64 single-byte numeric characters.
ReturnFMFDetails xs:boolean
(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

38 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Request

CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Required) Type of credit card.
Character length and limitations: Up to ten single-byte alphabetic characters.
Allowable values:
z Visa
z MasterCard
z Discover
z Amex
z Maestro: See important note.
z Solo: See important note.

NOTE: 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.
CreditCardNumber xs:string
(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.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: Two single-byte numeric characters, including
leading zero.
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: Four single-byte numeric characters.
CVV2 xs:string
(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.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro or Solo card was issued.
Character length: Two-digit, zero-filled if necessary.
StartYear xs:int
(Optional) Year that Maestro or Solo card was issued.
Character length: Four digits.

SOAP API Developer Reference June 2008 39

 DoDirectPayment API
DoDirectPayment Request

Field Description
IssueNumber xs:int
(Optional) Issue number of Maestro or Solo card.Character length: two numeric
digits maximum.

40 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Request

PayerInfoType Fields
Field Description
Payer ebl:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters.
PayerID ebl:UserIDType
Unique PayPal customer account identification number.
Character length and limitations:13 single-byte alphanumeric characters.
PayerStatus ebl:PayPalUserStatusCodeType
Status of payer. Valid values are:
z verified
z unverified

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

PayerName ebl:PersonNameType
First and last name of payer.
PayerCountry ebl:CountryCodeType
Payer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: Two single-byte characters.
PayerBusiness xs:string
Payer’s business name.
Character length and limitations: 127 single-byte characters.
Address xs:string
Payer’s shipping address information.

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters.
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters.
LastName ebl:NameType
Payer’s last name
Character length and limitations: 25 single-byte characters.

SOAP API Developer Reference June 2008 41

 DoDirectPayment API
DoDirectPayment Request

Field Description
Suffix ebl:SuffixType
Payer’s suffix
Character length and limitations: 12 single-byte characters.

42 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Request

PaymentDetailsType Fields
Field Description
OrderTotal ebl:BasicAmountType
(Required) Total amount of order, including shipping, handling, and tax.
NOTE: 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 (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ItemTotal ebl:BasicAmountType
(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 (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

SOAP API Developer Reference June 2008 43

 DoDirectPayment API
DoDirectPayment Request

Field Description
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
OrderDescription xs:string
(Optional) Description of items the customer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction.
NOTE: If you do not specify this value in the request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ebl:AddressType
(Optional) Address the order will be shipped to.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.

44 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Request

PaymentDetailsItemType Fields
Field Description
Name xs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
(Optional) Cost of item
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:string
(Optional) Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
EbayItemPayment eBl:ebayItemPaymentDetailsItemType
DetailsItem (Optional) Information relating to an auction sale on eBay.

EbayItemPaymentDetailsItemType Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters.

SOAP API Developer Reference June 2008 45

 DoDirectPayment API
DoDirectPayment Request

Field Description
AuctionTransaction xs:string
ID (Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters.

46 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Response

AddressType Fields
Field Description
Name xs:string
(See description) Person’s name associated with this address. This field is
required for shipping addresses but is optional for credit card billing
addresses.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Required) State or province for United States addresses.
Character length and limitations: 40 single-byte characters.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCodeType
(Required) Country code.
Character limit: 2 single-byte characters.
Phone xs:string
(Optional) Phone number.
Character length and limit: 20 single-byte characters.

DoDirectPayment Response

SOAP API Developer Reference June 2008 47

 DoDirectPayment API
DoDirectPayment Response

DoDirectPayment Response Fields

Field Description
TransactionID xs:string
Unique transaction ID of the payment.
NOTE: If the PaymentAction of the request was Authorization, the value of
TransactionID is your AuthorizationID for use with the Authorization &
Capture APIs.
Character length and limitations: 19 single-byte characters.
Amount ebl:BasicAmountType
This value is the amount of the payment as specified by you on
DoDirectPaymentRequest for reference transactions with direct payments.
AVSCode xs:string
Address Verification System response code. See “AVS and CVV2 Response Codes”
on page 269 for possible values.
Character limit: One single-byte alphanumeric character
CVV2Code xs:string
Result of the CVV2 check by PayPal.
FMFDetails ebl:FMFDetailsType
Fraud filter details.

FMFDetailsType Fields
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.

48 June 2008 SOAP API Developer Reference

 DoDirectPayment API
DoDirectPayment Response

RiskFilterListType Fields
Field Description
ID xs:int
Filter ID, which is one of the following values:
z 1 = AVS No Match
z 2 = AVS Partial Match
z 3 = AVS Unavailable/Unsupported
z 4 = Card Security Code (CSC) Mismatch
z 5 = Maximum Transaction Amount
z 6 = Unconfirmed Address
z 7 = Country Monitor
z 8 = Large Order Number
z 9 = Billing/Shipping Address Mismatch
z 10 = Risky ZIP Code
z 11 = Suspected Freight Forwarder Check
z 12 = Total Purchase Price Minimum
z 13 = IP Address Velocity
z 14 = Risky Email Address Domain Check
z 15 = Risky Bank Identification Number (BIN) Check
z 16 = Risky IP Address Range
z 17 = PayPal Fraud Model

Name xs:string
Filter name
Description xs:string
Filter description

SOAP API Developer Reference June 2008 49

 DoDirectPayment API
DoDirectPayment Response

50 June 2008 SOAP API Developer Reference

 4 Express Checkout API
Operations

This chapter describes the PayPal API operations related to Express Checkout transactions:
z “SetExpressCheckout API” on page 51
z “GetExpressCheckoutDetails API” on page 64
z “DoExpressCheckoutPayment API” on page 74

SetExpressCheckout API
z “SetExpressCheckout Request” on page 52
z “SetExpressCheckout Response” on page 64

SOAP API Developer Reference June 2008 51

 Express Checkout API Operations
SetExpressCheckout API

SetExpressCheckout API Diagram

SetExpressCheckout Request
z SetExpressCheckout Request Fields
z Address Fields
z “PaymentDetailsType Fields” on page 59
z “PaymentDetailsItemType Fields” on page 62

52 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
SetExpressCheckout API

z “EbayItemPaymentDetailsItemType Fields” on page 62

z Billing Agreement Details Fields

SOAP API Developer Reference June 2008 53

 Express Checkout API Operations
SetExpressCheckout API

SetExpressCheckoutRequestDetailsType Fields
Field Description
Token ebl:ExpressCheckoutTokenType
(Optional) A timestamped token, the value of which was returned by
SetExpressCheckout response.
Character length and limitations: 20 single-byte characters
OrderTotal cc:BasicAmountType
This field is deprecated.
(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.
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 (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
MaxAmount cc:BasicAmountType
(Optional) The expected maximum total amount of the complete order, including
shipping cost and tax charges.
If the transaction does not include a one-time purchase, this field is ignored.
Limitations: Must not exceed $10,000 USD in any currency. No currency symbol.
Must have two decimal places, decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
OrderDescription xs:string
This field is deprecated.
(Optional) Description of items the customer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
This field is deprecated.
(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
response.
Character length and limitations: 256 single-byte alphanumeric characters

54 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
SetExpressCheckout API

Field Description
InvoiceID xs:string
This field is deprecated.
(Optional) Your own unique invoice or tracking number. PayPal returns this value to
you on response.
If the transaction does not include a one-time purchase, this field is ignored.
Character length and limitations: 127 single-byte alphanumeric characters
ReturnURL xs:string
(Required) URL to which the customer’s browser is returned after choosing to pay
with PayPal.
NOTE: PayPal recommends that the value be the final review page on which the
customer confirms the order and payment or billing agreement.
Character length and limitations: 2048 characters
CancelURL xs:string
(Required) URL to which the customer is returned if he does not approve the use of
PayPal to pay you.
NOTE: PayPal recommends that the value be the original page on which the
customer chose to pay with PayPal or establish a billing agreement.
Character length and limitations: 2048 characters
Address ebl:AddressType
This field is deprecated.
(Optional) Customer’s shipping address.
If you include a shipping address and set the AddressOverride element on the
request, PayPal returns this same address in
GetExpressCheckoutDetailsResponse.
ReqConfirmShipping xs:string
(Optional) The value 1 indicates that you require that the customer’s shipping address
on file with PayPal be a confirmed address.
NOTE: Setting this field overrides the setting you have specified in your Merchant
Account Profile.
Character length and limitations: One single-byte numeric character.
Allowable values: 0, 1
NoShipping xs:string
(Optional) The value 1 indicates that on the PayPal pages, no shipping address fields
should be displayed whatsoever.
Character length and limitations: One single-byte numeric character.
Allowable values: 0, 1

SOAP API Developer Reference June 2008 55

 Express Checkout API Operations
SetExpressCheckout API

Field Description
AllowNote xs:string
(Optional) The value 1 indicates that the customer may enter a note to the merchant
on the PayPal page during checkout. The note is returned in the
GetExpressCheckoutDetails response and the DoExpressCheckoutPayment
response.
Character length and limitations: One single-byte numeric character.
Allowable values: 0, 1
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the payment.
AddressOverride xs:string
(Optional) The value 1 indicates that the PayPal pages should display the shipping
address set by you in this SetExpressCheckout request, not the shipping address on
file with PayPal for this customer.
Displaying the PayPal street address on file does not allow the customer to edit that
address.
Character length and limitations: One single-byte numeric character.
Allowable values: 0, 1
LocaleCode xs:string
(Optional) Locale of pages displayed by PayPal during Express Checkout.
Character length and limitations: Any two-character country code.
The following two-character country codes are supported by PayPal:
z AU
z DE
z FR
z IT
z GB
z ES
z US

Any other value will default to US. See “Country Codes” on page 253.
PageStyle xs:string
(Optional) Sets the Custom Payment Page Style for payment pages associated with
this button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name you chose
when adding or editing the page style from the Profile subtab of the My Account
tab of your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters.
cpp-header-image xs:string
(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

56 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
SetExpressCheckout API

Field Description
cpp-header-border- xs:string
color (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
cpp-header-back- xs:string
color (Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitation: Six character HTML hexadecimal color code in
ASCII
cpp-payflow-color xs:string
(Optional) Sets the background color for the payment page. By default, the color is
white.
Character length and limitation: Six character HTML hexadecimal color code in
ASCII
PaymentAction ebl:PaymentActionCodeType
(Optional) How you want to obtain payment:
z Sale indicates that this is a final sale for which you are requesting payment.
z Authorization indicates that this payment is a basic authorization subject to
settlement with PayPal Authorization & Capture.
z Order indicates that this payment is an order authorization subject to settlement
with PayPal Authorization & Capture.
If the transaction does not include a one-time purchase, this field is ignored.
NOTE: You cannot set this value to Sale in SetExpressCheckout request and then
change this value to Authorization or Order on the final API
DoExpressCheckoutPayment request. If the value is set to
Authorization or Order in SetExpressCheckout, the value may be set
to Sale or the same value (either Authorization or Order) in
DoExpressCheckoutPayment.
Character length and limit: Up to 13 single-byte alphabetic characters
Default value: Sale
BuyerEmail ebl:EmailAddressType
(Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion of the PayPal login page.
Character length and limit: 127 single-byte alphanumeric characters
SolutionType ebl:SolutionTypeType
(Optional) Type of checkout flow:
z Sole: Express Checkout for auctions
z Mark: normal Express Checkout

SOAP API Developer Reference June 2008 57

 Express Checkout API Operations
SetExpressCheckout API

Field Description
LandingPage ebl:LandingPageType
(Optional) Type of PayPal page to display:
z Billing: non-PayPal account
z Login: PayPal account login

ChannelType ebl:ChannelType
(Optional) Type of channel:
z Merchant: non-auction seller
z eBayItem: eBay auction

giropaySuccessURL xs:string
(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.
giropayCancelURL xs:string
(Optional) The URL on the merchant site to redirect to after a successful giropay
payment.
Use this field only if you are using giropay or bank transfer payment methods in
Germany.
BanktxnPendingURL xs:string
(Optional) The URL on the merchant site to transfer to after a bank transfer payment.
Use this field only if you are using giropay or bank transfer payment methods in
Germany.
BillingAgreement ns:BillingAgreementDetailsType
Details (See description) Billing agreement details for recurring payments. You can include
up to 10 billing agreements per SetExpressCheckout request.

58 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
SetExpressCheckout API

AddressType Fields
Field Description
Name xs:string
(Required) Person’s name associated with this shipping address.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Required) State or province for United States addresses.
Character length and limitations: 40 single-byte characters.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCodeType
(Required) Country code.
Character limit: 2 single-byte characters.
Phone xs:string
(Optional) Phone number.
Character length and limit: 20 single-byte characters.

PaymentDetailsType Fields
Field Description
OrderTotal ebl:BasicAmountType
(Required) Total amount of order, including shipping, handling, and tax.
NOTE: 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 (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

SOAP API Developer Reference June 2008 59

 Express Checkout API Operations
SetExpressCheckout API

Field Description
ItemTotal ebl:BasicAmountType
(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 (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

60 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
SetExpressCheckout API

Field Description
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
OrderDescription xs:string
(Optional) Description of items the customer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction.
NOTE: If you do not specify this value in the request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ebl:AddressType
(Optional) Address the order will be shipped to.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.

SOAP API Developer Reference June 2008 61

 Express Checkout API Operations
SetExpressCheckout API

PaymentDetailsItemType Fields
Field Description
Name xs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
(Optional) Cost of item
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:string
(Optional) Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
EbayItemPayment eBl:ebayItemPaymentDetailsItemType
DetailsItem (Optional) Information relating to an auction sale on eBay.

EbayItemPaymentDetailsItemType Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters.

62 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
SetExpressCheckout API

Field Description
AuctionTransaction xs:string
ID (Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters.

SOAP API Developer Reference June 2008 63

 Express Checkout API Operations
GetExpressCheckoutDetails API

BillingAgreementDetails Fields
Field Description
BillingType ns:BillingCodeType
(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.
NOTE: Other defined values are not valid.
BillingAgreement xs:string
Description (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.
PaymentType ns:MerchantPullPaymentCodeType
(Optional) Specifies type of PayPal payment you require for the billing agreement.
z Any
z InstantOnly

BillingAgreement xs:string
Custom (Optional) Custom annotation field for your own use.
Character length and limitations: 256 single-byte alphanumeric bytes.

SetExpressCheckout Response
SetExpressCheckoutResponseDetailsType Fields
Field Description
Token xs:string
A timestamped token by which you identify to PayPal that you are processing this
payment with Express Checkout.
The token expires after three hours.If you set the token in the
SetExpressCheckout request, the value of the token in the response is identical to
the value in the request.
Character length and limitations: 20 single-byte characters

GetExpressCheckoutDetails API
z “GetExpressCheckoutDetails Request” on page 65
z “GetExpressCheckoutDetails Response” on page 66

64 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
GetExpressCheckoutDetails API

GetExpressCheckoutDetails API Diagram

GetExpressCheckoutDetails Request

SOAP API Developer Reference June 2008 65

 Express Checkout API Operations
GetExpressCheckoutDetails API

GetExpressCheckoutDetailsType Request Fields

Field Description
Token xs:string
(Required) A timestamped token, the value of which was returned by
SetExpressCheckout response.
Character length and limitations: 20 single-byte characters

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

66 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
GetExpressCheckoutDetails API

GetExpressCheckoutDetailsResponseType Fields
Field Description
Token xs:string
The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
PayerInfo ebl:PayerInfoType
Information about the payer.
Custom xs:string
A free-form field for your own use, as set by you in the Custom element of
SetExpressCheckout request.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
Your own invoice or tracking number, as set by you in the element of the same name
in SetExpressCheckout request .
Character length and limitations: 127 single-byte alphanumeric characters
ContactPhone xs:string
Payer’s contact telephone number.
NOTE: PayPal returns a contact telephone number only if your Merchant account
profile settings require that the buyer enter one.
Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers)
or +XXX XXXXXXXX (for international numbers)
PaymentDetails ebl:PaymentDetailsType
Information about the payment.
PayPalAdjustment cc:BasicAmountType
A discount or gift certificate offered by PayPal to the buyer. This amount will be
represented by a negative amount. If the buyer has a negative PayPal account
balance, PayPal adds the negative balance to the transaction amount, which is
represented as a positive value.
Note xs:string
The text entered by the buyer on the PayPal website if the AllowNote field was set
to 1 in SetExpressCheckout.
Character length and limitations: 255 single-byte characters
RedirectRequired xs:boolean
Flag to indicate whether you need to redirect the customer to back to PayPal after
completing the transaction.
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.

SOAP API Developer Reference June 2008 67

 Express Checkout API Operations
GetExpressCheckoutDetails API

PayerInfoType Fields
Field Description
Payer ebl:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
Unique PayPal customer account identification number.
Character length and limitations:13 single-byte alphanumeric characters.
PayerStatus ebl:PayPalUserStatusCodeType
Status of payer. Valid values are:
z verified
z unverified

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

PayerName ebl:PersonNameType
First and last name of payer.
PayerCountry ebl:CountryCode Type
Payer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: Two single-byte characters
PayerBusiness xs:string
Payer’s business name.
Character length and limitations: 127 single-byte characters
Address xs:string
Payer’s shipping address information.

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
Payer’s last name.Character length and limitations: 25 single-byte characters

68 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
GetExpressCheckoutDetails API

Field Description
Suffix ebl:SuffixType
Payer’s suffix.Character length and limitations: 12 single-byte characters

SOAP API Developer Reference June 2008 69

 Express Checkout API Operations
GetExpressCheckoutDetails API

AddressType Fields
Field Description
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal
Valid values are:
z none
z Confirmed
z Unconfirmed

Name xs:string
(Required) Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
(Optional) State or province.
Character length and limitations: 40 single-byte characters
Required for U.S. addresses only.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCode
(Required) Country code. See “Country Codes” on page 253.
Character limit: Two single-byte characters

70 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
GetExpressCheckoutDetails API

PaymentDetailsType Fields
Field Description
OrderTotal ebl:BasicAmountType
(Required) Total amount of order, including shipping, handling, and tax.
NOTE: 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 (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ItemTotal ebl:BasicAmountType
(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 (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

SOAP API Developer Reference June 2008 71

 Express Checkout API Operations
GetExpressCheckoutDetails API

Field Description
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
OrderDescription xs:string
(Optional) Description of items the customer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction.
NOTE: If you do not specify this value in the request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ebl:AddressType
(Optional) Address the order will be shipped to.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.

72 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
GetExpressCheckoutDetails API

PaymentDetailsItemType Fields
Field Description
Name xs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
(Optional) Cost of item
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:string
(Optional) Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
EbayItemPayment eBl:ebayItemPaymentDetailsItemType
DetailsItem (Optional) Information relating to an auction sale on eBay.

EbayItemPaymentDetailsItemType Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters.

SOAP API Developer Reference June 2008 73

 Express Checkout API Operations
DoExpressCheckoutPayment API

Field Description
AuctionTransaction xs:string
ID (Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters.

DoExpressCheckoutPayment API
z “DoExpressCheckoutPayment Request” on page 75
z “DoExpressCheckoutPayment Response” on page 80

74 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
DoExpressCheckoutPayment API

DoExpressCheckoutPayment API Diagram (to be updated)

DoExpressCheckoutPayment Request
z DoExpressCheckout Request Fields
z Payment Details Fields
z Payment Details Item Fields
z Ebay Item Payment Details Fields
z Address Fields

SOAP API Developer Reference June 2008 75

 Express Checkout API Operations
DoExpressCheckoutPayment API

DoExpressCheckoutPaymentRequestType Fields
Field Description
Token xs:string
(Required) The timestamped token value that was returned by
SetExpressCheckout response and passed on GetExpressCheckoutDetails
request.
Character length and limitations: 20 single-byte characters
PaymentAction ebl:PaymentActionCodeType
(Required) How you want to obtain payment:
z Authorization indicates that this payment is a basic authorization subject to
settlement with PayPal Authorization & Capture.
z Order indicates that this payment is is an order authorization subject to
settlement with PayPal Authorization & Capture.
z Sale indicates that this is a final sale for which you are requesting payment.

NOTE: You cannot set this value to Sale on SetExpressCheckout request and
then change this value to Authorization on the final PayPal Express
Checkout API DoExpressCheckoutPayment request.
Character length and limit: Up to 13 single-byte alphabetic characters
PayerID ebl:UserIDType
(Required) Unique PayPal customer account identification number as returned by
GetExpressCheckoutDetails response.Character length and limitations: 13
single-byte alphanumeric characters.
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the payment.
ReturnFMFDetails xs:boolean
(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

PaymentDetailsType Fields
Field Description
OrderTotal ebl:BasicAmountType
(Required) Total amount of order, including shipping, handling, and tax.
NOTE: 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 (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

76 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
DoExpressCheckoutPayment API

Field Description
ItemTotal ebl:BasicAmountType
(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 (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

SOAP API Developer Reference June 2008 77

 Express Checkout API Operations
DoExpressCheckoutPayment API

Field Description
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
OrderDescription xs:string
(Optional) Description of items the customer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction.
NOTE: If you do not specify this value in the request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ebl:AddressType
(Optional) Address the order will be shipped to.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.

78 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
DoExpressCheckoutPayment API

PaymentDetailsItemType Fields
Field Description
Name xs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
(Optional) Cost of item
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:string
(Optional) Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
EbayItemPayment eBl:ebayItemPaymentDetailsItemType
DetailsItem (Optional) Information relating to an auction sale on eBay.

EbayItemPaymentDetailsItemType Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters.

SOAP API Developer Reference June 2008 79

 Express Checkout API Operations
DoExpressCheckoutPayment API

Field Description
AuctionTransaction xs:string
ID (Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters.

AddressType Fields
Field Description
Name xs:string
(Required) Person’s name associated with this shipping address.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Required) State or province for United States addresses.
Character length and limitations: 40 single-byte characters.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCodeType
(Required) Country code.
Character limit: 2 single-byte characters.
Phone xs:string
(Optional) Phone number.
Character length and limit: 20 single-byte characters.

DoExpressCheckoutPayment Response
z DoExpressCheckoutPayment Response Fields

80 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
DoExpressCheckoutPayment API

z Payment Information Fields

z Fraud Management Filters Fields
z Risk Filter List Fields

SOAP API Developer Reference June 2008 81

 Express Checkout API Operations
DoExpressCheckoutPayment API

DoExpressCheckoutPaymentResponseDetailsType Fields
Field Description
Token xs:string
The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
PaymentInfo ebl:PaymentInfoType
Information about the payment.
Note xs:string
The text entered by the buyer on the PayPal website if the AllowNote field was set
to 1 in SetExpressCheckout.
Character length and limitations: 255 single-byte characters
RedirectRequired xs:boolean
Flag to indicate whether you need to redirect the customer to back to PayPal after
completing the transaction.
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.
FMFDetails ebl:FMFDetailsType
Fraud filter details.

PaymentInfoType Fields
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
NOTE: 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
TransactionType ns:PaymentTransactionCodeType
The type of transaction
Character length and limitations:15 single-byte characters
Valid values:
z cart
z express-checkout

82 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
DoExpressCheckoutPayment API

Field Description
PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed.
Character length and limitations: Seven single-byte characters
Valid values:
z none
z echeck
z instant

PaymentDate xs:dateTime
Time/date stamp of payment
GrossAmount ebl:BasicAmountType
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.
FeeAmount ebl:BasicAmountType
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.
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.
ExchangeRate xs:string
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
PaymentStatus ebl:PendingStatusCodeType
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.

SOAP API Developer Reference June 2008 83

 Express Checkout API Operations
DoExpressCheckoutPayment API

Field Description
PendingReason ebl:PendingStatusCodeType
The reason the payment is pending:
z none: No pending reason
z address: The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
z echeck: The payment is pending because it was made by an eCheck that has not
yet cleared.
z intl: The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
z multi-currency: You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
z verify: The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
z other: The payment is pending for a reason other than those listed above. For
more information, contact PayPal customer service.
ReasonCode ebl:ReasonCodeType
The reason for a reversal if TransactionType is reversal:
z none: No reason code
z chargeback: A reversal has occurred on this transaction due to a chargeback by
your customer.
z guarantee: A reversal has occurred on this transaction due to your customer
triggering a money-back guarantee.
z buyer-complaint: A reversal has occurred on this transaction due to a
complaint about the transaction from your customer.
z refund: A reversal has occurred on this transaction because you have given the
customer a refund.
z other: A reversal has occurred on this transaction due to a reason not listed
above.

84 June 2008 SOAP API Developer Reference

 Express Checkout API Operations
DoExpressCheckoutPayment API

FMFDetailsType Fields
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.

RiskFilterListType Fields
Field Description
ID xs:int
Filter ID, which is one of the following values:
z 1 = AVS No Match
z 2 = AVS Partial Match
z 3 = AVS Unavailable/Unsupported
z 4 = Card Security Code (CSC) Mismatch
z 5 = Maximum Transaction Amount
z 6 = Unconfirmed Address
z 7 = Country Monitor
z 8 = Large Order Number
z 9 = Billing/Shipping Address Mismatch
z 10 = Risky ZIP Code
z 11 = Suspected Freight Forwarder Check
z 12 = Total Purchase Price Minimum
z 13 = IP Address Velocity
z 14 = Risky Email Address Domain Check
z 15 = Risky Bank Identification Number (BIN) Check
z 16 = Risky IP Address Range
z 17 = PayPal Fraud Model

Name xs:string
Filter name
Description xs:string
Filter description

SOAP API Developer Reference June 2008 85

 Express Checkout API Operations
DoExpressCheckoutPayment API

86 June 2008 SOAP API Developer Reference

 5 GetTransactionDetails API

z “GetTransactionDetails Request” on page 88

z “GetTransactionDetails Response” on page 89

SOAP API Developer Reference June 2008 87

 GetTransactionDetails API
GetTransactionDetails Request

GetTransactionDetails API Diagram

GetTransactionDetails Request

88 June 2008 SOAP API Developer Reference

 GetTransactionDetails API
GetTransactionDetails Response

GetTransactionDetails Request Fields

Field Description
TransactionID xs:string
(Required) Unique identifier of a transaction.
NOTE: 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
NOTE: 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.
z GetTransactionDetails Response Fields
z Payment Details Fields
z Receiver Information Fields
z Payer Information Fields
z Address Fields
z Payer Name Fields
z Payer Name Fields
z Payment Information Fields
z Payment Item Information Fields
z Subscription Fields
z Subscriptions Terms Fields

SOAP API Developer Reference June 2008 89

 GetTransactionDetails API
GetTransactionDetails Response

GetTransactionDetailsResponse Fields
Field Description
PaymentTransaction Wrapper structure.
Details

PaymentTransactionDetails Fields
Field Description
ReceiverInfo ebl:ReceiverInfoType
PayerInfo ebl:PayerInfoType
PaymentInfo ebl:PaymentInfoType
PaymentItemInfo ebl:PaymentItemInfoType

ReceiverInfoType Fields
Field Description
Business xs:string
Details about a single transaction.
Receiver xs:string
Primary email address of the payment recipient (the seller).
If you are the recipient of the payment and the payment is sent to your non-primary
email address, the value of Receiver is still your primary email address.
Character length and limitations: 127 single-byte alphanumeric characters
ReceiverID xs:string
Unique account ID of the payment recipient (the seller). This value is the same as the
value of the recipient's referral ID.

PayerInfoType Fields
Field Description
Payer ebl:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters.
PayerID ebl:UserIDType
Unique PayPal customer account identification number.
Character length and limitations:13 single-byte alphanumeric characters.
PayerStatus ebl:PayPalUserStatusCodeType
Status of payer. Valid values are:
z verified
z unverified

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

90 June 2008 SOAP API Developer Reference

 GetTransactionDetails API
GetTransactionDetails Response

Field Description
PayerName ebl:PersonNameType
First and last name of payer.
PayerCountry ebl:CountryCodeType
Payer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: Two single-byte characters.
PayerBusiness xs:string
Payer’s business name.
Character length and limitations: 127 single-byte characters.
Address xs:string
Payer’s shipping address information.

SOAP API Developer Reference June 2008 91

 GetTransactionDetails API
GetTransactionDetails Response

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters.
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters.
LastName ebl:NameType
Payer’s last name
Character length and limitations: 25 single-byte characters.
Suffix ebl:SuffixType
Payer’s suffix
Character length and limitations: 12 single-byte characters.

AddressType Fields
Field Description
AddressOwner ebl:AddressOwnerTypeCode
eBay company that maintains this address.
Valid values are:
z eBay
z PayPal

AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal.
Valid values are:
z none
z Confirmed
z Unconfirmed

Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters.

92 June 2008 SOAP API Developer Reference

 GetTransactionDetails API
GetTransactionDetails Response

Field Description
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
State or province.
Character length and limitations: 40 single-byte characters.
Required for U.S. addresses only.
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ns:Country
Country code. Character limit: Two single-byte characters.
CountryName xs:string
Expanded name of country.
Character length and limitations: 64 single-byte alphanumeric characters
Phone xs:string
Country code. Character limit: Two single-byte characters.

SOAP API Developer Reference June 2008 93

 GetTransactionDetails API
GetTransactionDetails Response

PaymentInfoType Fields
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
ParentTransactionID xs:string
z Parent or related transaction identification number. This field is populated for the
following transaction types:
z Reversal. Capture of an authorized transaction.
z Reversal. Reauthorization of a transaction.
z Capture of an order. The value of ParentTransactionID is the original
OrderID.
z Authorization of an order. The value of ParentTransactionID is the original
OrderID.
z Capture of an order authorization.
z Void of an order. The value of ParentTransactionID is the original OrderID.

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

ReceiptID xs:string
Receipt identification number
Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
TransactionType ns:PaymentTransactionCodeType
The type of transaction
Valid values:
z cart
z express-checkout

Character length and limitations:15 single-byte characters

PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed.
Character length and limitations: Seven single-byte characters
Valid values:
z none
z echeck
z instant

PaymentDate xs:dateTime
Time/date stamp of payment. For example: 2006-08-15T17:23:15Z.
GrossAmount ebl:BasicAmountType
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.

94 June 2008 SOAP API Developer Reference

 GetTransactionDetails API
GetTransactionDetails Response

Field Description
FeeAmount ebl:BasicAmountType
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.
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.
ExchangeRate xs:string
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
PaymentStatus ebl:PendingStatusCodeType
Status of the payment.
The status of the payment:
z None: No status
z Canceled-Reversal: This means a reversal has been canceled. For example,
you won a dispute with the customer, and the funds for the transaction that was
reversed have been returned to you.
z Completed: The payment has been completed, and the funds have been added
successfully to your account balance.
z Denied: You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the PendingReason
element.
z Expired: the authorization period for this payment has been reached.
z Failed: The payment has failed. This happens only if the payment was made
from your customer’s bank account.
z Pending: The payment is pending. See the PendingReason field for more
information.
z Refunded: You refunded the payment.
z Reversed: A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
z Processed: A payment has been accepted.
z Voided: An authorization for this transaction has been voided.

SOAP API Developer Reference June 2008 95

 GetTransactionDetails API
GetTransactionDetails Response

Field Description
PendingReason ebl:PendingStatusCodeType
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
The reason the payment is pending:
z none: No pending reason
z address: The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
z echeck: The payment is pending because it was made by an eCheck that has not
yet cleared.
z intl: The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
z multi-currency: You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
z verify: The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
z other: The payment is pending for a reason other than those listed above. For
more information, contact PayPal customer service.
ReasonCode ebl:ReasonCodeType
The reason for a reversal if TransactionType is reversal:
z none: No reason code
z chargeback: A reversal has occurred on this transaction due to a chargeback by
your customer.
z guarantee: A reversal has occurred on this transaction due to your customer
triggering a money-back guarantee.
z buyer-complaint: A reversal has occurred on this transaction due to a
complaint about the transaction from your customer.
z refund: A reversal has occurred on this transaction because you have given the
customer a refund.
z other: A reversal has occurred on this transaction due to a reason not listed
above.

96 June 2008 SOAP API Developer Reference

 GetTransactionDetails API
GetTransactionDetails Response

PaymentItemInfoType Fields
Field Description
InvoiceID xs:string
Invoice number you set in the original transaction.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
Custom field you set in the original transaction.
Character length and limitations: 127 single-byte alphanumeric characters
Memo xs:string
Memo entered by your customer in PayPal Website Payments note field.
Character length and limitations: 255 single-byte alphanumeric characters
SalesTax xs:string
Amount of tax charged on payment.
PaymentItem ebl:PaymentItemType
Amount of tax charged on payment.
Subscription ebl:SubscriptionInfoType
Subscription information
Auction ebl:AuctionInfoType
Subscription information

PaymentItemType Fields
Field Description
Name xs:string
Amount of tax charged on payment.
Number xs:string
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 xs:string
Quantity set by you or entered by the customer.
Character length and limitations: no limit
Amount ebl:BasicAmountType
Cost of item.
Options ns:OptionType
name: xs:string
value: xs:string
PayPal item options for shopping cart.

SOAP API Developer Reference June 2008 97

 GetTransactionDetails API
GetTransactionDetails Response

SubscriptionInfoType Fields
Field Description
SubscriptionID xs:string
ID generated by PayPal for the subscriber.
Character length and limitations: no limit
SubscriptionDate xs:dateTime
Subscription start date
EffectiveDate xs:dateTime
Date when the subscription modification will be effective
RetryTime xs:dateTime
Date PayPal will retry a failed subscription payment..
UserName xs:string
Username generated by PayPal and given to subscriber to access the subscription.
Character length and limitations: 64 alphanumeric single-byte characters
Password xs:string
Password generated by PayPal and given to subscriber to access the subscription. For
security, the value of the password is hashed.
Character length and limitations: 128 alphanumeric single-byte characters
Recurrences xs:string
The number of payment installments that will occur at the regular rate.
Character length and limitations: no limit.
reattempt xs:string
Indicates whether reattempts should occur upon payment failures.
recurring xs:string
Indicates whether regular rate recurs.
1 = Yes.
SubscriptionTermsTy
pe

SubscriptionTermsType Fields
Field Description
Amount eb:BasicAmountType
The amount subscriber is to be charged in one payment.Character length and
limitations: no limit
Period xs:string
The period of time that the subscriber will be charged.
Character length and limitations: no limit

98 June 2008 SOAP API Developer Reference

 6 MassPay API

z “MassPay Request” on page 99

z “MassPay Response” on page 101

MassPay API Diagram

MassPay Request
z MassPay Request Fields
z MassPay Item Details Fields

SOAP API Developer Reference June 2008 99

 MassPay API
MassPay Request

MassPay Request Fields

Field Description
EmailSubject xs:string
(Optional) The subject line of the email that PayPal sends when the transaction is
completed. The subject line is the same for all recipients.
Character length and limitations: 255 single-byte alphanumeric characters.
MassPayItem ebl:MassPayItemType
(Required) Details of each payment.
NOTE: A single MassPayRequest can include up to 250 MassPayItems.
ReceiverType ebl:ReceiverInfoCodeType
(Optional) Indicates how you identify the recipients of payments in this call to
MassPay.
Must be EmailAddress or UserID

MassPayItemType Fields
Field Description
ReceiverEmail ebl:EmailAddressType
(See description) Email address of recipient.
NOTE: You must specify either ReceiverEmail or ReceiverID, 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.
Character length and limitations: 127 single-byte characters maximum.
ReceiverID xs:string
(See description) Unique PayPal customer account number. This value corresponds to
the value of PayerID returned by GetTransactionDetails.
NOTE: You must specify either ReceiverEmail or ReceiverID, 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.
Character length and limitations: 17 single-byte characters maximum.
Amount ebl:BasicAmountType
(Required) Payment amount.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
NOTE: You cannot mix currencies in a single MassPayRequest. A single request
must include items that are of the same currency.
UniqueId xs:string
(Optional) Transaction-specific identification number for tracking in an accounting
system.
Character length and limitations: 30 single-byte characters. No whitespace allowed.

100 June 2008 SOAP API Developer Reference

 MassPay API
MassPay Response

Field Description
Note xs:string
(Optional) Custom note for each recipient.
Character length and limitations: 4,000 single-byte alphanumeric characters.

MassPay Response
The elements returned are the same as for AbstractResponseType.

SOAP API Developer Reference June 2008 101

 MassPay API
MassPay Response

102 June 2008 SOAP API Developer Reference

 7 RefundTransaction API

z “RefundTransaction Request” on page 104

z “RefundTransaction Response” on page 104

SOAP API Developer Reference June 2008 103

 RefundTransaction API
RefundTransaction Request

RefundTransaction API Diagram

RefundTransaction Request
RefundTransaction Request Fields
Field Description
TransactionID xs:string
(Required) Unique identifier of a transaction.
Character length and limitations: 17 single-byte alphanumeric characters.
RefundType ebl:RefundPurposeTypeCodeType
(Required) Type of refund you are making:
z Other
z Full
z Partial

Amount ebl:BasicAmountType
(See description) Refund amount.
Amount is required if RefundType is Partial.
NOTE: If RefundType is Full, do not set Amount.
Memo xs:string
(Optional) Custom memo about the refund.
Character length and limitations: 255 single-byte alphanumeric characters.

RefundTransaction Response
RefundTransactionResponse Fields
Field Description
RefundTransactionID xs:string
Unique transaction ID of the refund.
Character length and limitations:17 single-byte characters.

104 June 2008 SOAP API Developer Reference

 RefundTransaction API
RefundTransaction Response

Field Description
FeeRefundAmount ebl:BasicAmountType
Transaction fee refunded to original recipient of payment.
GrossRefundAmount ebl:BasicAmountType
Amount of money refunded to original payer.
NetRefundAmount ebl:BasicAmountType
Amount subtracted from PayPal balance of original recipient of payment to make this
refund.

SOAP API Developer Reference June 2008 105

 RefundTransaction API
RefundTransaction Response

106 June 2008 SOAP API Developer Reference

 8 TransactionSearch API

z “TransactionSearch Request” on page 107

z “TransactionSearch Response” on page 110

TransactionSearch API Diagram

TransactionSearch Request
z “TransactionSearch Request Fields” on page 108
z “PayerName Fields” on page 110

SOAP API Developer Reference June 2008 107

 TransactionSearch API
TransactionSearch Request

TransactionSearch Request Fields

Field Description
StartDate xs:dateTime
STARTDATE (Required) The earliest transaction date at which to start the search.
No wildcards are allowed. The value must be in UTC/GMT format.
EndDate xs:dateTime
(Optional) The latest transaction date to be included in the search.
Payer xs:string
ebl:EmailAddressType
(Optional) Search by the buyer’s email address.
Character length and limitations: 127 single-byte alphanumeric characters.
Receiver ebl:EmailAddressType
(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.
ReceiptID xs:string
(Optional) Search by the PayPal Account Optional receipt ID.
TransactionID ebl:TransactionID
(Optional) Search by the transaction ID. The returned results are from the merchant’s
transaction records.
Character length and limitations: 19 single-byte characters maximum.
InvoiceID xs:string
(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.
NOTE: No wildcards are allowed.
Character length and limitations: 127 single-byte characters maximum.
CardNumber xs:string
(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.
NOTE: 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.
PayerName ebl:PersonNameType
Search by the buyer’s name:
AuctionItemNumber xs:string
(Optional) Search by auction item number of the purchased goods.

108 June 2008 SOAP API Developer Reference

 TransactionSearch API
TransactionSearch Request

Field Description
TransactionClass ePaymentTransactionClassCodeType
(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 Sent: only payments sent
z Received: only payments received
z MassPay: only mass payments
z MoneyRequest: only money requests
z FundsAdded: only funds added to balance
z FundsWithdrawn: only funds withdrawn from balance
z Referral: only transactions involving referrals
z Fee: only transactions involving fees
z Subscription: only transactions involving subscriptions
z Dividend: only transactions involving dividends
z Billpay: only transactions involving BillPay Transactions
z Refund: only transactions involving funds
z CurrencyConversions: only transactions involving currency conversions
z BalanceTransfer: only transactions involving balance transfers
z Reversal: only transactions involving BillPay reversals
z Shipping: only transactions involving UPS shipping fees
z BalanceAffecting: only transactions that affect the account balance
z ECheck: only transactions involving eCheck

Amount ebl:BasicAmountType
(Optional) Search by transaction amount.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
CurrencyCode xs:token
(Optional) Search by currency code.
Status ebl:PaymentTransactionStatusCodeType
(Optional) Search by transaction status:
z Pending: The payment is pending. The specific reason the payment is pending is
returned by the GetTransactionDetails API PendingReason field.
z Processing: The payment is being processed.
z Success: The payment has been completed and the funds have been added
successfully to your account balance.
z Denied: You denied the payment. This happens only if the payment was
previously pending.
z Reversed: A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer.

SOAP API Developer Reference June 2008 109

 TransactionSearch API
TransactionSearch Response

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters.
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters.
LastName ebl:NameType
Payer’s last name
Character length and limitations: 25 single-byte characters.
Suffix ebl:SuffixType
Payer’s suffix
Character length and limitations: 12 single-byte characters.

TransactionSearch Response
TransactionSearch Response Fields
Field Description
Timestamp xs:dateTime
The date and time (in UTC/GMT format) the transaction occurred.
Timezone xs:string
The time zone of the transaction.
Type xs:string
The type of the transaction.
Payer ebl:EmailAddressType
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.
PayerDisplayName xs:string
Display name of the payer.
TransactionID xs:string
Seller’s transaction ID.

110 June 2008 SOAP API Developer Reference

 TransactionSearch API
TransactionSearch Response

Field Description
Status xs:string
The status of the transaction.
GrossAmount ebl:BasicAmountType
The total gross amount charged, including any profile shipping cost and taxes.
FeeAmount ebl:BasicAmountType
The fee that PayPal charged for the transaction.
NetAmount ebl:BasicAmountType
The net amount of the transaction.

SOAP API Developer Reference June 2008 111

 TransactionSearch API
TransactionSearch Response

112 June 2008 SOAP API Developer Reference

 9 Recurring Payments and
Reference Transactions API

Operations

This chapter describes the PayPal API operations related to recurring payments and reference
transactions:
z “CreateRecurringPaymentsProfile API” on page 113
z “GetRecurringPaymentsProfileDetails API” on page 125
z “ManageRecurringPaymentsProfileStatus API” on page 136
z “BillOutstandingAmount API” on page 138
z “UpdateRecurringPaymentsProfile API” on page 140
z “SetCustomerBillingAgreement API” on page 147
z “GetBillingAgreementCustomerDetails API” on page 151
z “DoReferenceTransaction API” on page 155

CreateRecurringPaymentsProfile API
z “CreateRecurringPaymentsProfile Request” on page 114
z “CreateRecurringPaymentsProfile Response” on page 125

SOAP API Developer Reference June 2008 113

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

CreateRecurringPaymentsProfile API Diagram

CreateRecurringPaymentsProfile Request
z CreateRecurringPaymentsProfile Request
z Recurring Payments Profile Details
z Schedule Details
z Billing Period Details
z Activation Details

114 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

z Ship To Address
z Credit Card Details
z Payer Information
z Payer Name
z Billing Address

SOAP API Developer Reference June 2008 115

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

CreateRecurringPaymentsProfile Request Fields

Field Description
Token xs:string
(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.
NOTE: Tokens expire after approximately 3 hours.
NOTE: If you include both Token and CreditCardDetails, the token is used and
credit card details are ignored.
CreditCard ns:CreditCardDetailsType
(See description) Credit card information for recurring payments using direct
payments.
NOTE: If you include both Token and CreditCardDetails, the token is used and
credit card details are ignored.
RecurringPayments ns:RecurringPaymentsProfileDetails
ProfileDetails (Required) You can include up to 10 recurring payments profiles per request. The
order of the profile details must match the order of the billing agreement details
specified in the SetExpressCheckout request.
ScheduleDetails ns:ScheduleDetailsType
(Required)

RecurringPaymentsProfileDetails Type Fields

Field Description
SubscriberName xs:string
(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.
Character length and limitations: 32 single-byte characters.
SubscriberShipping ns:AddressType
Address (Optional) The subscriber’s shipping address associated with this profile, if
applicable. If not specified, the ship to address from buyer’s PayPal account is used.
NOTE: Shipping Address is optional, but if you include it, certain fields are required.
BillingStartdate xs:dateTime
(Required) The date when billing for this profile begins.
Must be a valid date, in UTC/GMT format.
NOTE: The profile may take up to 24 hours for activation.

116 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

Field Description
ProfileReference xs:string
(Optional) The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters.

SOAP API Developer Reference June 2008 117

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

ScheduleDetails Type Fields

Field Description
Description xs:string
(Required) Description of the recurring payment.
NOTE: This field must match the corresponding billing agreement description
included in the SetExpressCheckout request.
Character length and limitations: 127 single-byte alphanumeric characters
ActivationDetails ns:ActivationDetailsType
(Optional)
TrialPeriod ns:BillingPeriodDetailsType
(Optional) The trial period for this schedule.
PaymentPeriod ns:BillingPeriodDetailsType
(Required) The regular payment period for this schedule.
MaxFailedPayments xs:int
(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.
AutoBillOutstanding ns:AutoBillType
Amount (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.

BillingPeriodDetails Type
Field Description
BillingPeriod ns:BillingPeriodType
(Required) Unit for billing during this subscription period.
One of the following values:
z Day
z Week
z SemiMonth
z Month
z Year

For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE: The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

118 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

Field Description
BillingFrequency xs:int
(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.
NOTE: If the billing period is SemiMonth., the billing frequency must be 1.
TotalBillingCycles xs:int
(Optional) 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 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.
z 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.
Amount cc:BasicAmountType
(Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
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.
ShippingAmount cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
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.
TaxAmount cc:BasicAmountType
(Optional) Tax amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
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.

SOAP API Developer Reference June 2008 119

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

ActivationDetails Type
Field Description
InitialAmount cc:BasicAmountType
(Optional) Initial non-recurring payment amount due immediately upon profile
creation. Use an initial amount for enrolment or set-up fees.
NOTE: All amounts included in the request must have the same currency.
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.
FailedInitialAmount ns:FailedPaymentAction
Action (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.

AddressType Fields
Field Description
Name xs:string
(See description) Person’s name associated with this address. This field is
required for shipping addresses but is optional for credit card billing
addresses.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.

120 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

Field Description
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Required) State or province for United States addresses.
Character length and limitations: 40 single-byte characters.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCodeType
(Required) Country code.
Character limit: 2 single-byte characters.
Phone xs:string
(Optional) Phone number.
Character length and limit: 20 single-byte characters.

SOAP API Developer Reference June 2008 121

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Required) Type of credit card.
Character length and limitations: Up to ten single-byte alphabetic characters.
Allowable values:
z Visa
z MasterCard
z Discover
z Amex
z Maestro: See important note.
z Solo: See important note.

NOTE: 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.
CreditCardNumber xs:string
(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.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: Two single-byte numeric characters, including
leading zero.
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: Four single-byte numeric characters.
CVV2 xs:string
(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.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro or Solo card was issued.
Character length: Two-digit, zero-filled if necessary.
StartYear xs:int
(Optional) Year that Maestro or Solo card was issued.
Character length: Four digits.

122 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

Field Description
IssueNumber xs:int
(Optional) Issue number of Maestro or Solo card.Character length: two numeric
digits maximum.

SOAP API Developer Reference June 2008 123

 Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API

PayerInfoType Fields
Field Description
Payer ebl:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters.
PayerID ebl:UserIDType
Unique PayPal customer account identification number.
Character length and limitations:13 single-byte alphanumeric characters.
PayerStatus ebl:PayPalUserStatusCodeType
Status of payer. Valid values are:
z verified
z unverified

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

PayerName ebl:PersonNameType
First and last name of payer.
PayerCountry ebl:CountryCodeType
Payer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: Two single-byte characters.
PayerBusiness xs:string
Payer’s business name.
Character length and limitations: 127 single-byte characters.
Address xs:string
Payer’s shipping address information.

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters.
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters.
LastName ebl:NameType
Payer’s last name
Character length and limitations: 25 single-byte characters.

124 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

Field Description
Suffix ebl:SuffixType
Payer’s suffix
Character length and limitations: 12 single-byte characters.

CreateRecurringPaymentsProfile Response
CreateRecurringPaymentsProfile Response Fields
Field Description
ProfileID xs:string
A unique identifier for future reference to the details of this recurring payment.
Character length and limitations: Up to 14 single-byte alphanumeric characters.
ProfileStatus ns:RecurringPaymentsProfileStatusType
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 “GetRecurringPaymentsProfileDetails Request” on page 126
z “GetRecurringPaymentsProfileDetails Response” on page 127

SOAP API Developer Reference June 2008 125

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

GetRecurringPaymentsProfileDetails API Diagram

GetRecurringPaymentsProfileDetails Request

126 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

GetRecurringPaymentsProfileDetails Request Fields

Field Description
ProfileID xs:string
(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 GetRecurringPaymentsProfileDetails Response Fields
z Recurring Payments Profile Fields
z Ship To Address Fields
z Billing Period Fields
z Recurring Payments Summary Fields
z Credit Card Fields
z Payer Information Fields

SOAP API Developer Reference June 2008 127

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

GetRecurringPaymentsProfileDetails Response Fields

Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
ProfileStatus ns:RecurringPaymentsProfileStatusType
Status of the recurring payment profile.
z ActiveProfile
z PendingProfile
z CancelledProfile
z SuspendedProfile
z ExpiredProfile

Description xs:string
Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters.
AutoBillOutstanding ns:AutoBillType
Amount 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.
MaxFailedPayments xs:int
The number of scheduled payments that can fail before the profile is automatically
suspended.
Character length and limitations: Number string representing an integer.
RecurringPayments ns:RecurringPaymentsProfileDetailsType
ProfileDetails Buyer information for this recurring payments profile.
CurrentRecurring ns:BillingPeriodDetailsType
PaymentsPeriod This field is not returned if the profile is canceled or expired:
Details of the current subscription period.
RecurringPayments ns:RecurringPaymentsSummaryDetailsType
Summary Payment summary for this recurring payments profile.
AggregateAmount ns:AmountType
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
(.), and the optional thousands separator must be a comma (,).

128 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

Field Description
AggregateOptionalAm ns:AmountType
ount 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
(.), and the optional thousands separator must be a comma (,).
FinalPaymentDueDate ns:DateTime
Final scheduled payment due date before the profile expires.
CreditCard ns:CreditCardDetailsType
If this is a recurring payments profile using direct payments, this field contains the
credit card information for this profile.
NOTE: Only the last four digits of the credit card account number are returned, and
the CVV2 value is not returned.

SOAP API Developer Reference June 2008 129

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

RecurringPaymentsProfileDetails Type Fields

Field Description
SubscriberName xs:string
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.
Character length and limitations: 32 single-byte characters.
SubscriberShipping ns:AddressType
Address The subscriber’s shipping address associated with this profile, if applicable. If not
specified, the ship to address from buyer’s PayPal account is used.
NOTE: Shipping Address is optional, but if you include it, certain fields are required.
BillingStartdate xs:dateTime
The date when billing for this profile begins.
Must be a valid date, in UTC/GMT format.
NOTE: The profile may take up to 24 hours for activation.
ProfileReference xs:string
The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters.

AddressType Fields
Field Description
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal.
Valid values are:
z none
z Confirmed
z Unconfirmed

Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters.

130 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

Field Description
StateOrProvince xs:string
State or province.
Character length and limitations: 40 single-byte characters.
Required for U.S. addresses only.
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCode
Country code. Character limit: Two single-byte characters.

SOAP API Developer Reference June 2008 131

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

BillingPeriodDetails Type
Field Description
BillingPeriod ns:BillingPeriodType
Unit for billing during this subscription period.
One of the following values:
z Day
z Week
z SemiMonth
z Month
z Year

For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE: The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
BillingFrequency xs:int
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.
NOTE: If the billing period is SemiMonth., the billing frequency must be 1.
TotalBillingCycles xs:int
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 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.
z 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.
Amount cc:BasicAmountType
Billing amount for each billing cycle during this payment period. This amount does
not include shipping and tax amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
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.

132 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

Field Description
ShippingAmount cc:BasicAmountType
Shipping amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
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.
TaxAmount cc:BasicAmountType
Tax amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
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.

SOAP API Developer Reference June 2008 133

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

RecurringPaymentsSummaryDetailsType Fields
Field Description
NextBillingDate xs:dateTime
The next scheduled billing date, in YYYY-MM-DD format.
NumberCycles xs:int
Completed 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.
NumberCycles xs:int
Remaining The number of billing cycles remaining in the current active subscription period.
OutstandingBalance cc:BasicAmountType
The current past due or outstanding balance for this 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.
FailedPaymentCount xs:int
The total number of failed billing cycles for this profile.
LastPaymentDate xs:dateTime
The date of the last successful payment received for this profile, in YYYY-MM-DD
format.
LastPaymentAmount cc:BasicAmountType
The amount of the last successful payment received for this 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.

134 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API

CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
Type of credit card.
Character length and limitations: Up to ten single-byte alphabetic characters.
Allowable values:
z Visa
z MasterCard
z Discover
z Amex
z Maestro: See important note.
z Solo: See important note.

NOTE: 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.
CreditCardNumber xs:string
Credit card number. Only the last 4 digits of the credit card number are returned.
Character length and limitations: numeric characters only. No spaces or punctutation.
Must conform with modulo and length required by each credit card type.
ExpMonth xs:int
Credit card expiration month.
Character length and limitations: Two single-byte numeric characters, including
leading zero.
ExpYear xs:int
Credit card expiration year.
Character length and limitations: Four single-byte numeric characters.
CardOwner ns:PayerInfoType
Details about the owner of the credit card.
StartMonth xs:int
Month that Maestro or Solo card was issued.
Character length: Two-digit, zero-filled if necessary.
StartYear xs:int
Year that Maestro or Solo card was issued.
Character length: Four digits.
IssueNumber xs:int
Issue number of Maestro or Solo card.Character length: two numeric digits
maximum.

SOAP API Developer Reference June 2008 135

 Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API

PayerInfoType Fields
Field Description
Payer ns:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters.
FirstName ns:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.
LastName ns:PersonNameType
Payer’s last name.
Character length and limitations: 25 single-byte characters.
Address ns:AddressType
Payer’s billing address information.

ManageRecurringPaymentsProfileStatus API
z “ManageRecurringPaymentsProfileStatus Request” on page 137
z “ManageRecurringPaymentsProfileStatus Response” on page 137

136 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API

ManageRecurringPaymentsProfileStatus API Diagram

ManageRecurringPaymentsProfileStatus Request
ManageRecurringPaymentsProfileStatus Request Fields
Field Description
ProfileID xs:string
(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.
Action ns:StatusChangeActionType
(Required) The action to be performed to the recurring payments profile. Must be one
of the following:
z Cancel - Only profiles in Active or Suspended state can be canceled.
z Suspend - Only profiles in Active state can be suspended.
z Reactivate - Only profiles in a suspended state can be reactivated.

Note xs:string
(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

SOAP API Developer Reference June 2008 137

 Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API

ManageRecurringPaymentsProfileStatus Response Fields

Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
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 Suspend - Profile status is not Active.
z Reactivate - Profile status is not Suspended.

BillOutstandingAmount API
z “BillOutstandingAmount Request” on page 139
z “BillOutstandingAmount Response” on page 139

138 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API

BillOutstandingAmount API Diagram

BillOutstandingAmount Request
BillOutstandingAmount Request Fields
Field Description
ProfileID xs:string
(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.
NOTE: The profile must have a status of either Active or Suspended.
Amount cc:BasicAmountType
(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.
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.
Note xs:string
(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

SOAP API Developer Reference June 2008 139

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

BillOutstandingAmount Response Fields

Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
An error is returned if the profile specified in the BillOutstandingAmount
request has a status of canceled or expired.

UpdateRecurringPaymentsProfile API
z “UpdateRecurringPaymentsProfile Request” on page 141
z “UpdateRecurringPaymentsProfile Response” on page 147

140 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

UpdateRecurringPaymentsProfile API Diagram

UpdateRecurringPaymentsProfile Request
z UpdateRecurringPaymentsProfile Request Fields
z Ship To Address Fields
z Credit Card Fields
z Payer Information Fields

SOAP API Developer Reference June 2008 141

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

UpdateRecurringPaymentsProfile Request Fields

Field Description
ProfileID xs:string
(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.
Note xs:string
(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.
Description xs:string
(Optional) Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters.
SubscriberName xs:string
(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.
Character length and limitations: 32 single-byte characters.
SubscriberShipping ns:AddressType
Address (Optional) The subscriber’s shipping address associated with this profile, if
applicable. If not specified, the ship to address from buyer’s PayPal account is used.
NOTE: Shipping Address is optional, but if you update any of the address fields, you
must enter all of them. For example, if you want to update the subsriber’s
street address, you must specify all of the fields listed in
ShipTo: AddressType, not just the field for the street address.
ProfileReference xs:string
(Optional) The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters.
AdditionalBilling xs:int
Cycles (Optional) The number of additional billing cycles to add to this profile.

142 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

Field Description
Amount cc:BasicAmountType
(Optional) Billing amount for each cycle in the subscription period, not including
shipping and tax amounts.
NOTE: 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).
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.
ShippingAmount cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during the regular payment period.
NOTE: All amounts in the request must have the same currency.
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.
TaxAmount cc:BasicAmountType
(Optional) Tax amount for each billing cycle during the regular payment period.
NOTE: All amounts in the request must have the same currency.
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.
OutstandingBalance cc:BasicAmountType
(Optional) The current past due or outstanding amount for this profile. You can only
decrease the outstanding amount—it cannot be increased.
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.
AutoBillOutstanding ns:AutoBillType
Amount (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.
MaxFailedPayments xs:int
(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.
Character length and limitations: Number string representing an integer.

SOAP API Developer Reference June 2008 143

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

Field Description
CreditCard ns:CreditCardDetailsType
(Optional)
NOTE: Only enter credit card details for recurring payments with direct payments.
NOTE: Credit card billing address is optional, but if you update any of the address
fields, you must enter all of them. For example, if you want to update the
street address, you must specify all of the address fields listed in
CreditCardDetailsType, not just the field for the street address.
Credit card information for this profile, if applicable.

144 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

AddressType Fields
Field Description
Name xs:string
(See description) Person’s name associated with this address. This field is
required for shipping addresses but is optional for credit card billing
addresses.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Required) State or province for United States addresses.
Character length and limitations: 40 single-byte characters.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCodeType
(Required) Country code.
Character limit: 2 single-byte characters.
Phone xs:string
(Optional) Phone number.
Character length and limit: 20 single-byte characters.

SOAP API Developer Reference June 2008 145

 Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API

CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Required) Type of credit card.
Character length and limitations: Up to ten single-byte alphabetic characters.
Allowable values:
z Visa
z MasterCard
z Discover
z Amex
z Maestro: See important note.
z Solo: See important note.

NOTE: 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.
CreditCardNumber xs:string
(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.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: Two single-byte numeric characters, including
leading zero.
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: Four single-byte numeric characters.
CVV2 xs:string
(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.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro or Solo card was issued.
Character length: Two-digit, zero-filled if necessary.
StartYear xs:int
(Optional) Year that Maestro or Solo card was issued.
Character length: Four digits.

146 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API

Field Description
IssueNumber xs:int
(Optional) Issue number of Maestro or Solo card.Character length: two numeric
digits maximum.

PayerInfoType Fields
Field Description
Payer ns:EmailAddressType
(Optional) Email address of payer.
Character length and limitations: 127 single-byte characters.
FirstName ns:PersonNameType
(Required) Payer’s first name.
Character length and limitations: 25 single-byte characters.
LastName ns:PersonNameType
(Required) Payer’s last name.
Character length and limitations: 25 single-byte characters.
Address ns:AddressType
(Required) Payer’s billing address information.

UpdateRecurringPaymentsProfile Response
UpdateRecurringPaymentsProfile Response Fields
Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
An error is returned if the profile specified in the BillOutstandingAmount
request has a status of canceled or expired.

SetCustomerBillingAgreement API
z “SetCustomerBillingAgreement Request” on page 148
z “SetCustomerBillingAgreement Response” on page 151

SOAP API Developer Reference June 2008 147

 Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API

SetCustomerBillingAgreement API Diagram

SetCustomerBillingAgreement Request
z SetCustomerBillingAgreement Request Fields
z Billing Agreement Details Fields

148 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API

SetCustomerBillingAgreement Request Fields

Field Description
BillingAgreement ns:BillingAgreementDetailsType
Details (Required)
ReturnURL xs:string
(Required) URL to which the customer’s browser is returned after choosing to pay
with PayPal.
NOTE: PayPal recommends that the value be the final review page on which the
customer confirms the billing agreement.
Character length and limitations: no limit.
CancelURL xs:string
(Required) URL to which the customer is returned if he does not approve the use of
PayPal to pay you.
NOTE: PayPal recommends that the value be the original page on which the
customer chose to pay with PayPal or establish a billing agreement.
Character length and limitations: no limit.
LocaleCode xs:string
(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 AU
z DE
z FR
z IT
z GB
z ES
z US

Any other value will default to US. See “Country Codes” on page 253.
PageStyle xs:string
(Optional) Sets the Custom Payment Page Style for payment pages associated with
this button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name you chose
when adding or editing the page style from the Profile subtab of the My Account
tab of your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters.
cpp-header-image xs:string
(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.
Character length and limitations: 127 single-byte alphanumeric characters.

SOAP API Developer Reference June 2008 149

 Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API

Field Description
cpp-header-border xs:string
(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.
cpp-header-back- xs:string
color (Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitation: Six character HTML hexadecimal color code in
ASCII.
cpp-payflow-color xs:string
(Optional) Sets the background color for the payment page.
Character length and limitation: Six character HTML hexadecimal color code in
ASCII.
BuyerEmail ns:EmailAddressType
(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.

150 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API

BillingAgreementDetails Fields
Field Description
BillingType ns:BillingCodeType
(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.
NOTE: Other defined values are not valid.
BillingAgreement xs:string
Description (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.
PaymentType ns:MerchantPullPaymentCodeType
(Optional) Specifies type of PayPal payment you require for the billing agreement.
z Any
z InstantOnly

BillingAgreement xs:string
Custom (Optional) Custom annotation field for your own use.
Character length and limitations: 256 single-byte alphanumeric bytes.

SetCustomerBillingAgreement Response
SetCustomerBillingAgreement Response Fields
Field Description
Token xs:string
A unique time-stamped token, which uniquely identifies this transaction for
subsequent API calls.
NOTE: The token expires after three hours.
Character length and limitations: 20 single-byte characters.

GetBillingAgreementCustomerDetails API
z “GetBillingAgreementCustomerDetails Request” on page 152
z “GetBillingAgreementCustomerDetails Response” on page 152

SOAP API Developer Reference June 2008 151

 Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API

GetBillingAgreementCustomerDetails API Diagram

GetBillingAgreementCustomerDetails Request
GetBillingAgreementCustomerDetails Request Fields
Field Description
Token xs:string
(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE: The token expires after three hours.
Character length and limitations: 20 single-byte characters.

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

152 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API

GetBillingAgreementCustomerDetails Response Fields

Field Description
PayerInfo ns:PayerInfoType

PayerInfoType Fields
Field Description
Payer ebl:EmailAddressType
Email address of payer.
Character length and limitations: 127 single-byte characters.
PayerID ebl:UserIDType
Unique PayPal customer account identification number.
Character length and limitations:13 single-byte alphanumeric characters.
PayerStatus ebl:PayPalUserStatusCodeType
Status of payer. Valid values are:
z verified
z unverified

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

PayerName ebl:PersonNameType
First and last name of payer.
PayerCountry ebl:CountryCodeType
Payer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: Two single-byte characters.
PayerBusiness xs:string
Payer’s business name.
Character length and limitations: 127 single-byte characters.
Address xs:string
Payer’s shipping address information.

PayerName Fields
Field Description
Salutation xs:string
Payer’s salutation.
Character length and limitations: 20 single-byte characters.
FirstName ebl:PersonNameType
Payer’s first name.
Character length and limitations: 25 single-byte characters.

SOAP API Developer Reference June 2008 153

 Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API

Field Description
MiddleName ebl:NameUser
Payer’s middle name.
Character length and limitations: 25 single-byte characters.
LastName ebl:NameType
Payer’s last name
Character length and limitations: 25 single-byte characters.
Suffix ebl:SuffixType
Payer’s suffix
Character length and limitations: 12 single-byte characters.

154 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

AddressType Fields
Field Description
AddressStatus ebl:AddressStatusTypeCode
(Required) Status of street address on file with PayPal.
Valid values are:
z none
z Confirmed
z Unconfirmed

Name xs:string
(Required) Person’s name associated with this address.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Optional) State or province.
Character length and limitations: 40 single-byte characters.
Required for U.S. addresses only.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCode
(Required) Country code. Character limit: Two single-byte characters.

DoReferenceTransaction API
z “DoReferenceTransaction Request” on page 156
z “DoReferenceTransaction Response” on page 166

SOAP API Developer Reference June 2008 155

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

DoReferenceTransaction API Diagram

DoReferenceTransaction Request
z DoReferenceTransaction Request Fields
z Ship To Address Fields
z Payment Details Fields
z Payment Item Details Fields
z Ebay Payment Detail Item Fields

156 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

z Credit Card Fields

z Payer Information Fields

SOAP API Developer Reference June 2008 157

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

DoReferenceTransaction Request Fields

Field Description
ReferenceID xs:string
(Required) Create a new transaction based on a credit card charge with
DoDirectPayment API TransactionID.
PaymentAction xs:string
(Optional) How you want to obtain payment:
z Authorization indicates that this payment is a basic authorization subject to
settlement with PayPal Authorization & Capture.
z Sale indicates that this is a final sale for which you are requesting payment.

PaymentDetails ebl:PaymentDetailsType
(Required) Information about the payment. See
MerchantSessionId xs:string
(Optional) Your customer session identification token.
NOTE: PayPal records this optional session identification token as an additional
means to detect possible fraud.
Character length and limitations: 64 single-byte numeric characters.
ReturnFMFDetails xs:boolean
(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

158 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description
SoftDescriptor xs:string
(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 - (dash)
z * (asterisk)
z . (period)
z {space}

If you use any other characters (such as “,”), an error code is returned.The soft
descriptor does not include the phone number, which can be toggled between the
merchant’s customer service number and PayPal’s customer service number.The
maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8
characters are used by the PayPal prefix shown in the data format. Thus, the
maximum length of the soft descriptor passed in the API request is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
z The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools.
z The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
z The soft descriptor is passed in as JanesFlowerGifts LLC

The resulting descriptor string on the credit card would be:

PAYPAL *EBAY JanesFlow

SOAP API Developer Reference June 2008 159

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

AddressType Fields
Field Description
Name xs:string
(See description) Person’s name associated with this address. This field is
required for shipping addresses but is optional for credit card billing
addresses.
Character length and limitations: 32 single-byte characters.
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters.
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters.
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters.
StateOrProvince xs:string
(Required) State or province for United States addresses.
Character length and limitations: 40 single-byte characters.
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters.
Country ebl:CountryCodeType
(Required) Country code.
Character limit: 2 single-byte characters.
Phone xs:string
(Optional) Phone number.
Character length and limit: 20 single-byte characters.

PaymentDetailsType Fields
Field Description
OrderTotal ebl:BasicAmountType
(Required) Total amount of order, including shipping, handling, and tax.
NOTE: 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 (,).
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

160 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description
ItemTotal ebl:BasicAmountType
(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 (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.

SOAP API Developer Reference June 2008 161

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
OrderDescription xs:string
(Optional) Description of items the customer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction.
NOTE: If you do not specify this value in the request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte alphanumeric characters

ShipToAddress ebl:AddressType
(Optional) Address the order will be shipped to.

PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.

162 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

PaymentDetailsItemType Fields
Field Description
Name xs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
(Optional) Cost of item
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:string
(Optional) Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator
must be a period (.), and the optional thousands separator must be a comma
(,). Equivalent to nine characters maximum for USD.
NOTE: You must set the currencyID attribute to one of the three-character currency
codes for any of the supported PayPal currencies.
EbayItemPayment eBl:ebayItemPaymentDetailsItemType
DetailsItem (Optional) Information relating to an auction sale on eBay.

EbayItemPaymentDetailsItemType Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters.

SOAP API Developer Reference June 2008 163

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description
AuctionTransaction xs:string
ID (Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters.

164 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Required) Type of credit card.
Character length and limitations: Up to ten single-byte alphabetic characters.
Allowable values:
z Visa
z MasterCard
z Discover
z Amex
z Maestro: See important note.
z Solo: See important note.

NOTE: 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.
CreditCardNumber xs:string
(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.

ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: Two single-byte numeric characters, including
leading zero.

ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: Four single-byte numeric characters.
CVV2 xs:string
(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.

CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.

StartMonth xs:int
(Optional) Month that Maestro or Solo card was issued.
Character length: Two-digit, zero-filled if necessary.

SOAP API Developer Reference June 2008 165

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description

StartYear xs:int
(Optional) Year that Maestro or Solo card was issued.
Character length: Four digits.
IssueNumber xs:int
(Optional) Issue number of Maestro or Solo card.Character length: two numeric
digits maximum.

PayerInfoType Fields
Field Description
Payer ns:EmailAddressType
(Optional) Email address of payer.
Character length and limitations: 127 single-byte characters.
FirstName ns:PersonNameType
(Required) Payer’s first name.
Character length and limitations: 25 single-byte characters.
LastName ns:PersonNameType
(Required) Payer’s last name.
Character length and limitations: 25 single-byte characters.
Address ns:AddressType
(Required) Payer’s billing address information.

DoReferenceTransaction Response
z DoReferenceTransaction Response Fields
z Payment Information Fields
z Fraud Management Filter Fields
z Risk Filter List Fields

166 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

DoReferenceTransaction Response Fields for Express Checkout

Field Description
PaymentInfo ns:PaymentInfoType
AVSCode xs:string
Address Verification System response code. See “AVS and CVV2 Response Codes”
on page 269 for possible values.
Character limit: One single-byte alphanumeric character
CVV2Code xs:string
Result of the CVV2 check by PayPal.
BillingAgreementID xs:string
Returned if the value of ReferenceID in the request is a billing agreement
identification number.
FMFDetails ebl:FMFDetailsType
Fraud filter details.

PaymentInfoType Fields
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
NOTE: 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
TransactionType ns:PaymentTransactionCodeType
The type of transaction
Character length and limitations:15 single-byte characters
Valid values:
z cart
z express-checkout

PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed.
Character length and limitations: Seven single-byte characters
Valid values:
z none
z echeck
z instant

PaymentDate xs:dateTime
Time/date stamp of payment

SOAP API Developer Reference June 2008 167

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description
GrossAmount ebl:BasicAmountType
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.
FeeAmount ebl:BasicAmountType
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.
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.
ExchangeRate xs:string
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
PaymentStatus ebl:PendingStatusCodeType
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.

168 June 2008 SOAP API Developer Reference

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

Field Description
PendingReason ebl:PendingStatusCodeType
The reason the payment is pending:
z none: No pending reason
z address: The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
z echeck: The payment is pending because it was made by an eCheck that has not
yet cleared.
z intl: The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
z multi-currency: You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
z verify: The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
z other: The payment is pending for a reason other than those listed above. For
more information, contact PayPal customer service.
ReasonCode ebl:ReasonCodeType
The reason for a reversal if TransactionType is reversal:
z none: No reason code
z chargeback: A reversal has occurred on this transaction due to a chargeback by
your customer.
z guarantee: A reversal has occurred on this transaction due to your customer
triggering a money-back guarantee.
z buyer-complaint: A reversal has occurred on this transaction due to a
complaint about the transaction from your customer.
z refund: A reversal has occurred on this transaction because you have given the
customer a refund.
z other: A reversal has occurred on this transaction due to a reason not listed
above.

SOAP API Developer Reference June 2008 169

 Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API

FMFDetailsType Fields
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.

RiskFilterListType Fields
Field Description
ID xs:int
Filter ID, which is one of the following values:
z 1 = AVS No Match
z 2 = AVS Partial Match
z 3 = AVS Unavailable/Unsupported
z 4 = Card Security Code (CSC) Mismatch
z 5 = Maximum Transaction Amount
z 6 = Unconfirmed Address
z 7 = Country Monitor
z 8 = Large Order Number
z 9 = Billing/Shipping Address Mismatch
z 10 = Risky ZIP Code
z 11 = Suspected Freight Forwarder Check
z 12 = Total Purchase Price Minimum
z 13 = IP Address Velocity
z 14 = Risky Email Address Domain Check
z 15 = Risky Bank Identification Number (BIN) Check
z 16 = Risky IP Address Range
z 17 = PayPal Fraud Model

Name xs:string
Filter name
Description xs:string
Filter description

170 June 2008 SOAP API Developer Reference

 10 DoNonReferencedCredit API

z “DoNonReferencedCredit Request” on page 171

z “DoNonReferencedCredit Response” on page 175

DoNonReferencedCredit API Diagram

DoNonReferencedCredit Request
z DoNonReferencedCredit Request Fields
z Credit Card Fields

SOAP API Developer Reference June 2008 171

 DoNonReferencedCredit API
DoNonReferencedCredit Request

z Payer Information Fields

z Address Fields

172 June 2008 SOAP API Developer Reference

 DoNonReferencedCredit API
DoNonReferencedCredit Request

DoNonReferencedCredit Request Fields

Field Description
Amount ns:BasicAmountType
(Required) Total of order, including shipping, handling, and tax.
Limitations: Must not exceed $10,000 USD in any currency. No currency symbol.
Must have two decimal places, decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
Amount = NetAmount + ShippingAmount + TaxAmount
NetAmount ns:BasicAmountType
(Optional) Total amount of all items in this transaction.
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 (,). The only valid currencies are
AUD, CAD, EUR, GBP, JPY, and USD.
ShippingAmount ns:BasicAmountType
(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.
TaxAmount ns:BasicAmountType
(Optional) Sum of tax for all items in this order.
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.
Comment xs:string
(Optional) Field used by merchant to record why this credit was issued to a buyer.
Similar to a “memo” field. Freeform text. String field.
CreditCard ebl:CreditCardDetailsType
(Required) Information about the credit card to be charged.

SOAP API Developer Reference June 2008 173

 DoNonReferencedCredit API
DoNonReferencedCredit Request

CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Required) Type of credit card.
Character length and limitations: Up to ten single-byte alphabetic characters.
Allowable values:
z Visa
z MasterCard
z Discover
z Amex
z Maestro: See important note.
z Solo: See important note.

NOTE: 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.
CreditCardNumber xs:string
(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.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: Two single-byte numeric characters, including
leading zero.
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: Four single-byte numeric characters.
CVV2 xs:string
(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.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro or Solo card was issued.
Character length: Two-digit, zero-filled if necessary.
StartYear xs:int
(Optional) Year that Maestro or Solo card was issued.
Character length: Four digits.

174 June 2008 SOAP API Developer Reference

 DoNonReferencedCredit API
DoNonReferencedCredit Response

Field Description
IssueNumber xs:int
(Optional) Issue number of Maestro or Solo card.Character length: two numeric
digits maximum.

PayerInfoType Fields
Field Description
Payer ns:EmailAddressType
(Optional) Email address of payer.
Character length and limitations: 127 single-byte characters.
FirstName ns:PersonNameType
(Required) Payer’s first name.
Character length and limitations: 25 single-byte characters.
LastName ns:PersonNameType
(Required) Payer’s last name.
Character length and limitations: 25 single-byte characters.
Address ns:AddressType
(Required) Payer’s billing address information.

DoNonReferencedCredit Response
DoNonReferencedCredit Response Fields
Field Description
TransactionID ns:TransactionId
Unique identifier of a transaction.
Character length and limitations: 17 single-byte alphanumeric characters.
Amount ns:BasicAmountType
Total of order, including shipping, handling, and tax.
Limitations: Must not exceed $10,000 USD in any currency. No currency symbol.
Must have two decimal places, decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).

SOAP API Developer Reference June 2008 175

 DoNonReferencedCredit API
DoNonReferencedCredit Response

176 June 2008 SOAP API Developer Reference

 11 Fraud Management Filters API
Operations

This chapter describes the PayPal API operations and prerequisites related to Fraud
Management Filters:
z “Fraud Management Filters API Prerequisites” on page 177
z “ManagePendingTransactionStatus API” on page 178

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
For example, one of these APIs could return a SuccessWithWarning status indicating
that the transaction was pended, as follows:

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

SOAP API Developer Reference June 2008 177

 Fraud Management Filters API Operations
ManagePendingTransactionStatus API

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

IMPORTANT: You may lose payment transactions if you do not handle

SuccessWithWarning acknowledgements.
z You must handle Pending in the PaymentStatus of a response as representing a
successful payment.
z You must capture and evaluate the return code associated with a SuccessWithWarning
acknowledgement.
z 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.
z Your shipping process must not allow shipping before the payment has been accepted.
NOTE: Pending payments are held 30 days unless explicitly denied or accepted. After 30
days, a pending payment is automatically reversed.
z 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 “ManagePendingTransactionStatus Request” on page 179
z “ManagePendingTransactionStatus Response” on page 179

178 June 2008 SOAP API Developer Reference

 Fraud Management Filters API Operations
ManagePendingTransactionStatus API

ManagePendingTransactionStatus Request
ManagePendingTransactionStatus Request Fields
Field Description
TransactionID The transaction ID of the payment transaction.
Action The operation you want to perform on the transaction, which is one of the following
actions:
z Accept - accepts the payment
z Deny - rejects the payment

ManagePendingTransactionStatus Response
ManagePendingTransactionStatus Response Fields
Field Description
TransactionID The transaction ID of the transaction whose payment has been denied or accepted.
Status The status of the transaction, which is one of the following values:
z Pending
z Processing
z Completed
z Denied
z Reversed
z Display Only
z Partially Refunded
z Created Refunded

SOAP API Developer Reference June 2008 179

 Fraud Management Filters API Operations
ManagePendingTransactionStatus API

180 June 2008 SOAP API Developer Reference

 12 GetBalance API

z “GetBalance Request” on page 181

z “GetBalance Response” on page 181

GetBalance API Diagram

GetBalance Request
GetBalance Request Fields
Field Description
ReturnAllCurrencies xs:string
(Optional) Whether to return all currencies, which is one of the following values:
z 0 - Return only the balance for the primary currency holding
z 1 - Return the balance for each currency holding

NOTE: 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
Field Description
Balance ebl:BasicAmountType
The available balance and associated currency code for the primary currency holding.
BalanceTimeStamp xs:dateTime
The time that the balance was reported.

SOAP API Developer Reference June 2008 181

 GetBalance API
GetBalance Response

Field Description
BalanceHoldings ebl:BasicAmountType
The available balance and associated currency code for each currency held, including
the primary currency. The first currency is the primary currency.

182 June 2008 SOAP API Developer Reference

 13 AddressVerify API

z “AddressVerify Request” on page 184

z “AddressVerify Response” on page 184

SOAP API Developer Reference June 2008 183

 AddressVerify API
AddressVerify Request

AddressVerify API Diagram

AddressVerify Request
AddressVerify Request Fields
Field Description
Email ebl:EmailAddressType
(Required) Email address of a PayPal member to verify.
Maximum string length: 255 single-byte characters
Input mask: ?@?.??
Street xs:string
(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.
Zip xs:string
(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

184 June 2008 SOAP API Developer Reference

 AddressVerify API
AddressVerify Response

AddressVerify Response Fields

Field Description
ConfirmationCode ebl:AddressStatuscodeType
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.
NOTE: The values Confirmed and Unconfirmed both indicate that the member
email address passed verification.
StreetMatch ebl:MatchStatusCodeType
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 single-
byte 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.
ZipMatch ebl:MatchStatusCodeType
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.
CountryCode ebl:CountryCodeType
Two-character country code (ISO 3166) on file for the PayPal email address. See
“Country Codes” on page 253.
PayPalToken xs:string
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.
Character length and limitations: 94 single-byte characters.

SOAP API Developer Reference June 2008 185

 AddressVerify API
AddressVerify Response

186 June 2008 SOAP API Developer Reference

A API Error Codes

z “General API Errors” on page 188

z “Validation Errors” on page 189
z “Direct Payment API Errors” on page 193
z “SetExpressCheckout API Errors” on page 205
z “GetExpressCheckoutDetails API Errors” on page 213
z “DoExpressCheckoutPayment API Errors” on page 215
z “Authorization and Capture API Errors” on page 220
z “TransactionSearch API Errors” on page 225
z “RefundTransaction API Errors” on page 227
z “Mass Pay API Errors” on page 230
z “Recurring Payments Errors” on page 232
z “SetCustomerBillingAgreement Errors” on page 240
z “GetBillingAgreementCustomerDetails Errors” on page 242
z “CreateBillingAgreement Errors” on page 242
z “UpdateBillingAgreement Errors” on page 244
z “DoReferenceTransaction Errors” on page 244
z “AddressVerify API Errors” on page 251
z “ManagePendingTransactionStatus API Errors” on page 251

June 2008 187

 API Error Codes
General API Errors

General API Errors

TABLE A.1 General API Errors

Error
Code Short Message Long Message Correcting This Error
10002 Authentication/Authoriza Username/Password is incorrect This error can be caused by an incorrect
tion Failed API username, an incorrect API
password, or an invalid API signature.
Make sure that all three of these values
are correct. For your security, PayPal
does not report exactly which of these
three values might be in error.
10002 Authentication/Authoriza You do not have permission to
tion Failed make this API call
10002 Authentication/Authoriza Account is locked or inactive
tion Failed
10002 Internal Error Internal Error
10002 Authentication/Authoriza Internal Error
tion Failed
10002 Authentication/Authoriza Account is not verified
tion Failed
10002 Authentication/Authoriza This call is not defined in the
tion Failed database!
10002 Authentication/Authoriza Token is not valid
tion Failed
10002 Restricted account Account is restricted Your PayPal merchant account has been
restricted. Contact your PayPal account
manager for resolution.
10002 Authentication/Authoriza Token is not valid
tion Failed
10002 Authentication/Authoriza API access is disabled for this
tion Failed account
10002 Authentication/Authoriza Client certificate is disabled
tion Failed
10002 Restricted account Account is restricted

188 June 2008

 API Error Codes
Validation Errors

Validation Errors
TABLE A.2 Validation Errors

Error Code Short Message Long Message

81000 Missing Parameter Required Parameter Missing : Unable to identify
parameter
81001 Invalid Parameter A Parameter is Invalid : Unable to identify parameter
81002 Unspecified Method Method Specified is not Supported
81003 Unspecified Method No Method Specified
81004 Unspecified Method No Request Received
81100 Missing Parameter OrderTotal (Amt) : Required parameter missing
81101 Missing Parameter MaxAmt : Required parameter missing
81102 Missing Parameter ReturnURL: Required parameter missing
81103 Missing Parameter NotifyURL : Required parameter missing
81104 Missing Parameter CancelURL : Required parameter missing
81105 Missing Parameter ShipToStreet : Required parameter missing
81106 Missing Parameter ShipToStreet2 : Required parameter missing
81107 Missing Parameter ShipToCity : Required parameter missing
81108 Missing Parameter ShipToState : Required parameter missing
81109 Missing Parameter ShipToZip : Required parameter missing
81110 Missing Parameter Country : Required parameter missing
81111 Missing Parameter ReqConfirmShipping : Required parameter missing
81112 Missing Parameter NoShipping : Required parameter missing
81113 Missing Parameter AddrOverride : Required parameter missing
81114 Missing Parameter LocaleCode : Required parameter missing
81115 Missing Parameter PaymentAction : Required parameter missing
81116 Missing Parameter Email : Required parameter missing
81117 Missing Parameter Token : Required parameter missing
81118 Missing Parameter PayerID : Required parameter missing
81119 Missing Parameter ItemAmt : Required parameter missing
81120 Missing Parameter ShippingAmt : Required parameter missing

June 2008 189

 API Error Codes
Validation Errors

Error Code Short Message Long Message

81121 Missing Parameter HandlingTotal Amt : Required parameter missing
81122 Missing Parameter TaxAmt : Required parameter missing
81123 Missing Parameter IPAddress : Required parameter missing
81124 Missing Parameter ShipToName : Required parameter missing
81125 Missing Parameter L_Amt : Required parameter missing
81126 Missing Parameter Amt : Required parameter missing
81127 Missing Parameter L_TaxAmt : Required parameter missing
81128 Missing Parameter AuthorizationID : Required parameter missing
81129 Missing Parameter CompleteType : Required parameter missing
81130 Missing Parameter CurrencyCode : Required parameter missing
81131 Missing Parameter TransactionID : Required parameter missing
81132 Missing Parameter TransactionEntity : Required parameter missing
81133 Missing Parameter Acct : Required parameter missing
81134 Missing Parameter ExpDate : Required parameter missing
81135 Missing Parameter FirstName : Required parameter missing
81136 Missing Parameter LastName : Required parameter missing
81137 Missing Parameter Street : Required parameter missing
81138 Missing Parameter Street2 : Required parameter missing
81139 Missing Parameter City : Required parameter missing
81140 Missing Parameter State : Required parameter missing
81141 Missing Parameter Zip : Required parameter missing
81142 Missing Parameter CountryCode : Required parameter missing
81143 Missing Parameter RefundType : Required parameter missing
81144 Missing Parameter StartDate : Required parameter missing
81145 Missing Parameter EndDate : Required parameter missing
81146 Missing Parameter MPID : Required parameter missing
81147 Missing Parameter CreditCardType : Required parameter missing
81148 Missing Parameter User : Required parameter missing
81149 Missing Parameter Pwd : Required parameter missing
81150 Missing Parameter Version : Required parameter missing

190 June 2008

 API Error Codes
Validation Errors

Error Code Short Message Long Message

81200 Missing Parameter Amt : Invalid parameter
81201 Invalid Parameter MaxAmt : Invalid parameter
81203 Invalid Parameter NotifyURL : Invalid parameter
81205 Invalid Parameter ShipToStreet : Invalid parameter
81206 Invalid Parameter ShipToStreet2 : Invalid parameter
81207 Invalid Parameter ShipToCity : Invalid parameter
81208 Invalid Parameter ShipToState : Invalid parameter
81209 Invalid Parameter ShipToZip : Invalid parameter
81210 Invalid Parameter Country : Invalid parameter
81211 Invalid Parameter ReqConfirmShipping : Invalid parameter
81212 Invalid Parameter Noshipping : Invalid parameter
81213 Invalid Parameter AddrOverride : Invalid parameter
81214 Invalid Parameter LocaleCode : Invalid parameter
81215 Invalid Parameter PaymentAction : Invalid parameter
81219 Invalid Parameter ItemAmt : Invalid parameter
81220 Invalid Parameter ShippingAmt : Invalid parameter
81221 Invalid Parameter HandlingTotal Amt : Invalid parameter
81222 Invalid Parameter TaxAmt : Invalid parameter
81223 Invalid Parameter IPAddress : Invalid parameter
81224 Invalid Parameter ShipToName : Invalid parameter
81225 Invalid Parameter L_Amt : Invalid parameter
81226 Invalid Parameter Amt : Invalid parameter
81227 Invalid Parameter L_TaxAmt : Invalid parameter
81229 Invalid Parameter CompleteType : Invalid parameter
81230 Invalid Parameter CurrencyCode : Invalid parameter
81232 Invalid Parameter TransactionEntity : Invalid parameter
81234 Invalid Parameter ExpDate : Invalid parameter
81235 Invalid Parameter FirstName : Invalid parameter
81236 Invalid Parameter LastName : Invalid parameter
81237 Invalid Parameter Street : Invalid parameter

June 2008 191

 API Error Codes
Validation Errors

Error Code Short Message Long Message

81238 Invalid Parameter Street2 : Invalid parameter
81239 Invalid Parameter City : Invalid parameter
81243 Invalid Parameter RefundType : Invalid parameter
81244 Invalid Parameter StartDate : Invalid parameter
81245 Invalid Parameter EndDate : Invalid parameter
81247 Invalid Parameter CreditCardType : Invalid parameter
81248 Invalid Parameter Username : Invalid parameter
81249 Invalid Parameter Password : Invalid parameter
81250 Invalid Parameter Version : Invalid parameter
81251 Internal Error Internal Service Error

192 June 2008

 API Error Codes
Direct Payment API Errors

Direct Payment API Errors

TABLE A.3 DirectPayment API Errors

Error
Code Short Message Long Message Corrective Action
10102 PaymentAction of Order PaymentAction of Order is
Temporarily Unavailable temporarily unavailable. Please
try later or use other
PaymentAction.
10401 Transaction refused Order total is missing.
because of an invalid
argument. See additional
error messages for details.
10418 Transaction refused The currencies of the shopping
because of an invalid cart amounts must be the same.
argument. See additional
error messages for details.
10426 Transaction refused Item total is invalid.
because of an invalid
argument. See additional
error messages for details.
10427 Transaction refused Shipping total is invalid.
because of an invalid
argument. See additional
error messages for details.
10428 Transaction refused Handling total is invalid.
because of an invalid
argument. See additional
error messages for details.
10429 Transaction refused Tax total is invalid.
because of an invalid
argument. See additional
error messages for details.
10432 Invalid argument Invoice ID value exceeds
maximum allowable length.
10500 Invalid Configuration This transaction cannot be Occurs when you have not agreed to the
processed due to an invalid billing agreement.
merchant configuration.
10501 Invalid Configuration This transaction cannot be Occurs when the billing agreement is
processed due to an invalid disabled or inactive.
merchant configuration.

June 2008 193

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10502 Invalid Data This transaction cannot be The credit card used is expired.
processed. Please use a valid
credit card.
10504 Invalid Data This transaction cannot be The CVV provided is invalid. The CVV
processed. Please enter a valid is between 3-4 digits long.
Credit Card Verification Number.
10505 Gateway Decline This transaction cannot be The transaction was refused because the
processed. AVS response returned the value of N,
and the merchant account is not able to
accept such transactions.
10507 Invalid Configuration This transaction cannot be Your PayPal account is restricted -
processed. Please contact PayPal contact PayPal for more information.
Customer Service.
10508 Invalid Data This transaction cannot be The expiration date must be a two-digit
processed. Please enter a valid month and four-digit year.
credit card expiration date.
10509 Invalid Data This transaction cannot be You must submit an IP address of the
processed. buyer with each API call.
10510 Invalid Data The credit card type is not The credit card type entered is not
supported. Try another card type. currently supported by PayPal.
10511 Invalid Data This transaction cannot be The merchant selected a value for the
processed. PaymentAction field that is not
supported.
10512 Invalid Data This transaction cannot be The first name of the buyer is required
processed. Please enter a first for this merchant.
name.
10513 Invalid Data This transaction cannot be The last name of the buyer is required
processed. Please enter a last for this merchant.
name.
10519 Invalid Data Please enter a credit card. The credit card field was blank.
10520 Invalid Data This transaction cannot be The total amount and item amounts do
processed. not match.
10521 Invalid Data This transaction cannot be The credit card entered is invalid.
processed. Please enter a valid
credit card.
10523 Internal Error This transaction cannot be None - this is a PayPal internal error.
processed.

194 June 2008

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10525 Invalid Data This transaction cannot be The merchant entered a amount of zero.
processed. The amount to be
charged is zero.
10526 Invalid Data This transaction cannot be The currency code entered is not
processed. The currency is not supported.
supported at this time.
10527 Invalid Data This transaction cannot be The credit card entered is invalid.
processed. Please enter a valid
credit card number and type.
10534 Gateway Decline This transaction cannot be The credit card entered is currently
processed. Please enter a valid restricted by PayPal. Contact PayPal for
credit card number and type. more information.
10535 Gateway Decline This transaction cannot be The credit card entered is invalid.
processed. Please enter a valid
credit card number and type.
10536 Invalid Data This transaction cannot be The merchant entered an invoice ID that
processed. 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.
10537 Filter Decline This transaction cannot be The transaction was declined by the
processed. country filter managed by the merchant.
To accept this transaction, change your
risk settings on PayPal.
10538 Filter Decline This transaction cannot be The transaction was declined by the
processed. maximum amount filter managed by the
merchant. To accept this transaction,
change your risk settings on PayPal.
10539 Filter Decline This transaction cannot be The transaction was declined by PayPal.
processed. Contact PayPal for more information.
10540 Invalid Data The transaction cannot be The transaction was declined by PayPal
processed due to an invalid because of an invalid address.
address.
10541 Gateway Decline This transaction cannot be The credit card entered is currently
processed. Please enter a valid restricted by PayPal. Contact PayPal for
credit card number and type. more information.
10542 Invalid Data This transaction cannot be The email address provided by the buyer
processed. Please enter a valid is in an invalid format.
email address.

June 2008 195

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10544 Gateway Decline This transaction cannot be The transaction was declined by PayPal.
processed. Contact PayPal for more information.
10545 Gateway Decline This transaction cannot be The transaction was declined by PayPal
processed. because of possible fraudulent activity.
Contact PayPal for more information.
10546 Gateway Decline This transaction cannot be The transaction was declined by PayPal
processed. because of possible fraudulent activity
on the IP address. Contact PayPal for
more information.
10547 Internal Error This transaction cannot be None - this is a PayPal internal error.
processed.
10548 Invalid Configuration This transaction cannot be The merchant account attempting the
processed. The merchant’s transaction is not a business account at
account is not able to process PayPal. Check your account settings.
transactions.
10549 Invalid Configuration This transaction cannot be The merchant account attempting the
processed. The merchan’s transaction is not able to process Direct
account is not able to process Payment transactions. Contact PayPal
transactions. for more information.
10550 Invalid Configuration This transaction cannot be Access to Direct Payment was disabled
processed. for your account. Contact PayPal for
more information.
10552 Invalid Configuration This transaction cannot be The merchant account attempting the
processed. transaction does not have a confirmed
email address with PayPal. Check your
account settings.
10553 Gateway Decline This transaction cannot be The merchant attempted a transaction
processed. where the amount exceeded the upper
limit for that merchant.
10554 Filter Decline This transaction cannot be The transaction was declined because of
processed. a merchant risk filter for AVS.
Specifically, the merchant has set to
decline transaction when the AVS
returned a no match (AVS = N).
10555 Filter Decline This transaction cannot be The transaction was declined because of
processed. a merchant risk filter for AVS.
Specifically, the merchant has set to
decline transaction when the AVS
returned a partial match.

196 June 2008

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10556 Filter Decline This transaction cannot be The transaction was declined because of
processed. a merchant risk filter for AVS.
Specifically, the merchant has set to
decline transaction when the AVS was
unsupported.
10561 Invalid Data There’s an error with this
transaction. Please enter
complete billing address.
10562 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration year.
10563 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration month.
10564 Gateway Decline This transaction cannot be There was a problem processing this
processed. transaction.
10565 Merchant country The merchant country is not
unsupported supported.
10566 Credit card type The credit card type is not
unsupported supported.
10567 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
10571 Transaction approved, but This transaction was approved, If you want to require valid CVV values,
with invalid Card although the Card Security Code change the risk control settings in your
Security Code (CSC) (CSC) had too few, too many, or account profile.
format. invalid characters. Based on your
account profile settings, the
invalid CSC was not given to the
card issuer for its approval
process.
10701 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
billing address. message will tell you what field is
invalid.
10702 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
address1 in the billing address. message will tell you what field is
invalid.

June 2008 197

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10703 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
address2 in the billing address. message will tell you what field is
invalid.
10704 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
city in the billing address. message will tell you what field is
invalid.
10705 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
state in the billing address. message will tell you what field is
invalid.
10706 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
postal code in the billing address. message will tell you what field is
invalid.
10707 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
country in the billing address. message will tell you what field is
invalid.
10708 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
complete billing address. message will tell you what field is
invalid.
10709 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter an field in the address. The long error
address1 in the billing address. message will tell you what field is
invalid.
10709 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter an field in the address. The long error
address1 in the billing address. message will tell you what field is
invalid.
10710 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a city in field in the address. The long error
the billing address. message will tell you what field is
invalid.
10710 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a city in field in the address. The long error
the billing address. message will tell you what field is
invalid.

198 June 2008

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10711 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
state in the billing address. message will tell you what field is
invalid.
10712 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
five digit postal code in the message will tell you what field is
billing address. invalid.
10713 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
country in the billing address. message will tell you what field is
invalid.
10713 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
country in the billing address. message will tell you what field is
invalid.
10714 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
billing address. message will tell you what field is
invalid.
10715 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
state in the billing address. message will tell you what field is
invalid.
10716 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
five digit postal code in the message will tell you what field is
billing address. invalid.
10717 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
postal code in the billing address. message will tell you what field is
invalid.
10718 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
city and state in the billing message will tell you what field is
address. invalid.
10719 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
shipping address. message will tell you what field is
invalid.

June 2008 199

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10720 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
address1 in the shipping address. message will tell you what field is
invalid.
10721 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
address2 in the shipping address. message will tell you what field is
invalid.
10722 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
city in the shipping address. message will tell you what field is
invalid.
10723 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
state in the shipping address. message will tell you what field is
invalid.
10724 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
five digit postal code in the message will tell you what field is
shipping address. invalid.
10725 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
country in the shipping address. message will tell you what field is
invalid.
10726 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
complete shipping address. message will tell you what field is
invalid.
10726 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
complete shipping address. message will tell you what field is
invalid.
10727 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter an field in the address. The long error
address1 in the shipping address. message will tell you what field is
invalid.
10727 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter an field in the address. The long error
address1 in the shipping address. message will tell you what field is
invalid.

200 June 2008

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10728 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a city in field in the address. The long error
the shipping address. message will tell you what field is
invalid.
10728 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a city in field in the address. The long error
the shipping address. message will tell you what field is
invalid.
10729 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
state in the shipping address. message will tell you what field is
invalid.
10730 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
five digit postal code in the message will tell you what field is
shipping address. invalid.
10731 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
country in the shipping address. message will tell you what field is
invalid.
10731 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a field in the address. The long error
country in the shipping address. message will tell you what field is
invalid.
10732 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
shipping address. message will tell you what field is
invalid.
10733 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
state in the shipping address. message will tell you what field is
invalid.
10734 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
five digit postal code in the message will tell you what field is
shipping address. invalid.
10735 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter your field in the address. The long error
five digit postal code in the message will tell you what field is
shipping address. invalid.

June 2008 201

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10736 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
city and state in the shipping message will tell you what field is
address. invalid.
10744 Invalid Data This transaction cannot be There was a problem with a particular
processed. Please enter a valid field in the address. The long error
country code in the billing message will tell you what field is
address. invalid.
10745 Invalid Data This transaction cannot be There was a problem with a particular
processed. Please enter a valid field in the address. The long error
country code in the shipping message will tell you what field is
address. invalid.
10746 Invalid Data This transaction cannot be There was a problem with a particular
processed. Please use a valid field in the address. The long error
country on the billing address. message will tell you what field is
invalid.
10747 Invalid Data This transaction cannot be The merchant entered an IP address that
processed. was in an invalid format. The IP address
must be in a format such as
123.456.123.456.
10748 Invalid Data This transaction cannot be The merchant’s configuration requires a
processed without a Credit Card CVV to be entered, but no CVV was
Verification Number. provided with this transaction. Contact
PayPal if you wish to change this setting.
10750 Invalid Data There’s an error with this There was a problem with a particular
transaction. Please enter a valid field in the address. The long error
state in the shipping address. message will tell you what field is
invalid.
10751 Invalid Data There’s an error with this The merchant provided an address either
transaction. Please enter a valid in the United States or Canada, but the
state in the billing address. state provided is not a valid state in
either country.
10752 Gateway Decline This transaction cannot be The transaction was declined by the
processed. issuing bank, not PayPal. The merchant
should attempt another card.
10754 Gateway Decline This transaction cannot be The transaction was declined by PayPal.
processed. Contact PayPal for more information.
10755 Invalid Data This transaction cannot be The currency code entered by the
processed due to an unsupported merchant is not supported.
currency.

202 June 2008

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
10756 Gateway Decline The transaction cannot be None - this is a PayPal internal error.
processed. The country and
billing address associated with
this credit card do not match.
10758 Invalid Configuration There’s been an error due to The API username or password is
invalid API username and/or incorrect for this merchant.
password.
10759 Gateway Decline This transaction cannot be The transaction was declined by PayPal.
processed. Please enter a valid Contact PayPal for more information.
credit card number and type.
10760 Invalid Configuration This transaction cannot be The merchant’s country of residence
processed. The country listed for listed in their PayPal account is not
your business address is not currently supported to allow Direct
currently supported. Payment transactions.
10761 Gateway Decline This transaction cannot be The transaction was declined because
processed. Please check the PayPal is currently processing a
status of your first transaction transaction by the same buyer for the
before placing another order. same amount. Can occur when a buyer
submits multiple, identical transactions
in quick succession.
10762 Gateway Decline This transaction cannot be The CVV provide is invalid. The CVV is
processed. between 3-4 digits long.
10763 Invalid Data This transaction cannot be None - this is a PayPal internal error.
processed.
10764 This transaction cannot be This transaction cannot be The transaction was declined by PayPal.
processed at this time. processed at this time. Please try Contact PayPal for more information.
Please try again later. again later.
11610 Payment Pending your Payment Pending your review in
review in Fraud Fraud Management Filters
Management Filters
11611 Transaction blocked by Transaction blocked by your
your settings in FMF settings in FMF
11612 Could not process your Could not process your request to
request to accept/deny the accept/deny the transaction
transaction
15001 Gateway Decline This transaction cannot be The transaction was rejected by PayPal
processed. because of excessive failures over a
short period of time for this credit card.
Contact PayPal for more information.

June 2008 203

 API Error Codes
Direct Payment API Errors

Error
Code Short Message Long Message Corrective Action
15002 Gateway Decline This transaction cannot be The transaction was declined by PayPal.
processed. Contact PayPal for more information.
15003 Invalid Configuration This transaction cannot be The transaction was declined because
processed. the merchant does not have a valid
commercial entity agreement on file
with PayPal. Contact PayPal for more
information.
15004 Gateway Decline This transaction cannot be The transaction was declined because
processed. Please enter a valid the CVV entered does not match the
Credit Card Verification Number. credit card.
15005 Processor Decline This transaction cannot be The transaction was declined by the
processed. issuing bank, not PayPal. The merchant
should attempt another card.
15006 Processor Decline This transaction cannot be The transaction was declined by the
processed. Please enter a valid issuing bank, not PayPal. The merchant
credit card number and type. should attempt another card.
15007 Processor Decline This transaction cannot be The transaction was declined by the
processed. Please use a valid issuing bank because of an expired
credit card. credit card. The merchant should attempt
another card.
15008 Invalid Data This transaction has been
completed, but the total of items
in the cart did not match the total
of all items.

204 June 2008

 API Error Codes
SetExpressCheckout API Errors

SetExpressCheckout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10001 ButtonSource value The transaction could not be loaded
truncated.
10001 Internal Error Internal Error
10004 Transaction refused because Transaction refused because of an
of an invalid argument. See invalid argument. See additional
additional error messages for error messages for details.
details.
10004 Transaction refused because The transaction id is not valid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Invalid value for request billing
of an invalid argument. See address parameter.
additional error messages for
details.
10007 Permission denied You do not have permission to make
this API call
10010 Invalid Invoice Non-ASCII invoice id is not
supported.
10102 PaymentAction of Order PaymentAction of Order is
Temporarily Unavailable temporarily unavailable. Please try
later or use other PaymentAction.
10103 Please use another Solution Your Solution Type is temporarily
Type. unavailable. If possible, please use
another Solution Type.
10400 Transaction refused because OrderTotal is missing.
of an invalid argument. See
additional error messages for
details
10401 Transaction refused because Order total is invalid.
of an invalid argument. See
additional error messages for
details

June 2008 205

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10402 Authorization only is not This merchant account is not
allowed for merchant. permitted to set PaymentAction to
Authorization. Please contact
Customer Service.
10404 Transaction refused because ReturnURL is missing.
of an invalid argument. See
additional error messages for
details.
10405 Transaction refused because CancelURL is missing.
of an invalid argument. See
additional error messages for
details.
10407 Transaction refused because Invalid buyer email address
of an invalid argument. See (BuyerEmail).
additional error messages for
details.
10409 You’re not authorized to Express Checkout token was issued
access this info. for a merchant account other than
yours.
10410 Invalid token Invalid token.
10411 This Express Checkout This Express Checkout session has If you receive this error, you
session has expired. expired. Token value is no longer must return your customer to
valid. 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.

206 June 2008

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10412 Duplicate invoice Payment has already been made for PayPal checks that
this InvoiceID. 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.
10413 Transaction refused because The totals of the cart item amounts
of an invalid argument. See do not match order amounts.
additional error messages for
details
10415 Transaction refused because A successful transaction has already PayPal allows a token only
of an invalid argument. See been completed for this token. once for a successful
additional error messages for transaction.
details. 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.
10418 Transaction refused because The currencies of the shopping cart
of an invalid argument. See amounts must be the same.
additional error messages for
details
10425 Express Checkout has been Express Checkout has been disabled
disabled for this merchant. for this merchant. Please contact
Customer Service.
10426 Transaction refused because Item total is invalid.
of an invalid argument. See
additional error messages for
details

June 2008 207

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10427 Transaction refused because Shipping total is invalid.
of an invalid argument. See
additional error messages for
details
10428 Transaction refused because Handling total is invalid.
of an invalid argument. See
additional error messages for
details
10429 Transaction refused because Tax total is invalid.
of an invalid argument. See
additional error messages for
details
10430 Transaction refused because Item amount is missing.
of an invalid argument. See
additional error messages for
details
10431 Transaction refused because Item amount is invalid.
of an invalid argument. See
additional error messages for
details
10432 Transaction refused because Invoice ID value exceeds maximum
of an invalid argument. See allowable length.
additional error messages for
details
10433 Transaction refused because Value of Order Description has been
of an invalid argument. See truncated.
additional error messages for
details
10434 Transaction refused because Value of Custom element has been
of an invalid argument. See truncated.
additional error messages for
details
10436 Transaction refused because PageStyle value exceeds maximum
of an invalid argument. See allowable length.
additional error messages for
details.
10437 Transaction refused because cpp-header-image value exceeds
of an invalid argument. See maximum allowable length.
additional error messages for
details.

208 June 2008

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10438 Transaction refused because cpp-header-image value exceeds
of an invalid argument. See maximum allowable length.
additional error messages for
details.
10439 Transaction refused because cpp-header-image value exceeds
of an invalid argument. See maximum allowable length.
additional error messages for
details.
10440 Transaction refused because cpp-header-image value exceeds
of an invalid argument. See maximum allowable length.
additional error messages for
details.
10441 Transaction refused because The NotifyURL element value
of an invalid argument. See exceeds maximum allowable length.
additional error messages for
details
10442 ButtonSource value The ButtonSource element value
truncated exceeds maximum allowable length.
10457 Error occurred in eBay API creation error
communicating to eBay
10458 Error occurred in eBay API unknown failure
communicating to eBay
10459 Error occurred in eBay API failure
communicating to eBay
10460 Error occurred in Parsing error
communicating to eBay
10461 Error occurred in Item number invalid, removed, or
communicating to eBay unavailable
10462 Error occurred in Order not found
communicating to eBay
10463 Error occurred in eBay user password incorrect
communicating to eBay
10464 Error occurred in eBay user invalid
communicating to eBay
10465 Error occurred in Item ID and Transaction ID
communicating to eBay mismatch
10467 Error occurred in Duplicate Item ID
communicating to eBay

June 2008 209

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10468 Transaction refused because Duplicate Order ID
of an invalid argument. See
additional error messages for
details
10469 PaymentAction of Order Express Auctions is unavailable
Temporarily Unavailable
10470 Wowo flag is off for Solution Type passed as Sole while
ExpressO feature ExpressO feature is turned off
10471 Transaction refused because ReturnURL is missing
of an invalid argument. See
additional error messages for
details
10472 Transaction refused because CancelURL is missing
of an invalid argument. See
additional error messages for
details
10473 Error occurred in Multiple Order IDs are not supported
communicating to eBay
10474 Invalid Data This transaction cannot be processed.
The country code in the shipping
address must match the buyer's
country of residence
10475 Transaction refused because This transaction cannot be completed
of an invalid argument. See with PaymentAction of Sale
additional error messages for
details
10476 Invalid Data Maximum number of billing
agreements exceeded
10477 Invalid Data More than one billing agreement
specified for reference transaction
10478 Invalid Data Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments
10479 Invalid Data Billing agreement types cannot be
mixed in the same request
10480 Invalid Data Invalid billing agreement type

210 June 2008

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
10537 Risk Control Country Filter The transaction was refused because
Failure the country was prohibited as a result
of your Country Monitor Risk
Control Settings.
10538 Risk Control Max Amount The transaction was refused because
Failure the maximum amount was excceeded
as a result of your Maximum
Amount Risk Control Settings.
10539 Payment declined by your Payment declined by your Risk
Risk Controls settings: Controls settings: PayPal Risk
PayPal Risk Model. Model.
10725 Shipping Address Country There was an error in the Shipping
Error Address Country field
10727 Shipping Address1 Empty The field Shipping Address1 is
required
10728 Shipping Address City The field Shipping Address City is
Empty required
10729 Shipping Address State The field Shipping Address State is
Empty required
10730 Shipping Address Postal The field Shipping Address Postal
Code Empty Code is required
10731 Shipping Address Country The field Shipping Address Country
Empty is required
10736 Shipping Address Invalid A match of the Shipping Address
City State Postal Code City, State, and Postal Code failed.
10800 Invalid Data Your request is too long. Check
URLs and other long strings.
11547 Recurring payments Recurring payments temporarily
temporarily unavailable; try unavailable.
again later
11601 Request for billing address Billing address request is not enabled
failed for merchant
11602 Request for billing address Feature not yet available
failed
11801 Invalid Data You cannot pass both new and
deprecated parameter address fields.

June 2008 211

 API Error Codes
SetExpressCheckout API Errors

Error
Code Short Message Long Message Correcting This Error...
11802 Invalid Data You cannot pass both the new and
deprecated Custom parameter.
11803 Invalid Data You cannot pass both the new and
deprecated Invoice ID parameter.
11804 Invalid Data You cannot pass both the new and
deprecated order description.
11805 Invalid Data You cannot pass both the new and
deprecated order total or amount
parameters.
11806 Invalid Data You cannot pass both the new and
deprecated
ProfileAddressChangeDate
parameter.
11807 Invalid Data You cannot pass both the new and
deprecated ShippingMethod
parameter.
11810 Transaction refused because Invalid Insurance Amount.
of an invalid argument. See
additional error messages for
details
11811 Transaction refused because Invalid Shipping Discount.
of an invalid argument. See
additional error messages for
details
11812 Invalid Data The value of Description parameter
has been truncated.
11813 Transaction refused because Invalid callback URL.
of an invalid argument. See
additional error messages for
details
11814 Invalid data Invalid value for AllowNote.
11815 Transaction refused because Item sales tax is invalid.
of an invalid argument. See
additional error messages for
details

212 June 2008

 API Error Codes
GetExpressCheckoutDetails API Errors

GetExpressCheckoutDetails API Errors

TABLE A.5 GetExpressCheckoutDetails API Errors

Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal error
10001 ButtonSource value The transaction could not be loaded
truncated.
10001 ButtonSource value The transaction could not be loaded
truncated.
10004 Transaction refused because Transaction refused because of an
of an invalid argument. See invalid argument. See additional error
additional error messages for messages for details.
details.
10004 Transaction refused because The transaction id is not valid
of an invalid argument. See
additional error messages for
details.
10004 Invalid transaction type You can not get the details for this type
of transaction
10004 Transaction refused because The transaction could not be loaded
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because The transaction id is not valid
of an invalid argument. See
additional error messages for
details.
10007 Permission denied You do not have permission to make
this API call
10007 Permission denied You do not have permission to get the
details of this transaction
10007 Permission denied You do not have permission to make
this API call
10408 Express Checkout token is Express Checkout token is missing.
missing.

June 2008 213

 API Error Codes
GetExpressCheckoutDetails API Errors

Error
Code Short Message Long Message Correcting This Error...
10409 You’re not authorized to Express Checkout token was issued for
access this info. a merchant account other than yours.
10410 Invalid token Invalid token.
10411 This Express Checkout This Express Checkout session has
session has expired. expired. Token value is no longer
valid.

214 June 2008

 API Error Codes
DoExpressCheckoutPayment API Errors

DoExpressCheckoutPayment API Errors

TABLE A.6 Errors

Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Transaction failed due to
internal error
10001 Internal Error Warning an internal error has
occurred. The transaction id
may not be correct
10001 ButtonSource value The transaction could not be
truncated. loaded
10001 Internal Error Internal Error
10004 Transaction refused Transaction refused because of
because of an invalid an invalid argument. See
argument. See additional additional error messages for
error messages for details. details.
10004 Transaction refused The transaction id is not valid
because of an invalid
argument. See additional
error messages for details.
10007 Permission denied You do not have permissions to
make this API call
10406 Transaction refused The PayerID value is invalid.
because of an invalid
argument. See additional
error messages for details.
10408 Express Checkout token is Express Checkout token is
missing. missing.
10409 You’re not authorized to Express Checkout token was
access this info. issued for a merchant account
other than yours.
10410 Invalid token Invalid token.
10411 This Express Checkout This Express Checkout session
session has expired. has expired. Token value is no
longer valid.
10412 Duplicate invoice Payment has already been
made for this InvoiceID.

June 2008 215

 API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code Short Message Long Message Correcting This Error...
10413 Transaction refused The totals of the cart item z ItemTotal
because of an invalid amounts do not match order z ShippingTotal
argument. See additional amounts. z HandlingTotal
error messages for details. z TaxTotal
If you get this error, research why it
might have occurred and modify your
implementation of Express Checkout to
ensure proper addition of the values.
10414 Transaction refused The amount exceeds the
because of an invalid maximum amount for a single
argument. See additional transaction.
error messages for details.
10415 Transaction refused A successful transaction has
because of an invalid already been completed for
argument. See additional this token.
error messages for details.
10416 Transaction refused You have exceeded the
because of an invalid maximum number of payment
argument. See additional attempts for this token.
error messages for details.
10417 Transaction cannot The transaction cannot Instruct the customer that PayPal is
complete. complete successfully. Instruct unable to process the payment and
the customer to use an redisplay alternative payment methods
alternative payment method. with which the customer can pay.
10418 Transaction refused The currencies of the shopping
because of an invalid cart amounts must be the same.
argument. See additional
error messages for details.
10419 Express Checkout Express Checkout PayerID is
PayerID is missing. missing.
10420 Transaction refused Express Checkout
because of an invalid PaymentAction is missing.
argument. See additional
error messages for details.
10421 This Express Checkout This Express Checkout session Verify that your programs are properly
session belongs to a belongs to a different associating the Tokens and PayerIDs.
different customer. customer. Token value
mismatch.

216 June 2008

 API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code Short Message Long Message Correcting This Error...
10422 Customer must choose The customer must return to
new funding sources. PayPal to select new funding
sources.
10424 Transaction refused Shipping address is invalid. If you receive this error message,
because of an invalid PayPal recommends that you return
argument. See additional your customer to PayPal to review and
error messages for details. 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 Transaction refused Item total is invalid.
because of an invalid
argument. See additional
error messages for details.
10427 Transaction refused Shipping total is invalid.
because of an invalid
argument. See additional
error messages for details.
10428 Transaction refused Handling total is invalid.
because of an invalid
argument. See additional
error messages for details.
10429 Transaction refused Tax total is invalid.
because of an invalid
argument. See additional
error messages for details.
10431 Item amount is invalid. Item amount is invalid.
10432 Transaction refused Invoice ID value exceeds
because of an invalid maximum allowable length.
argument. See additional
error messages for details.
10433 Transaction refused Value of OrderDescription
because of an invalid element has been truncated.
argument. See additional
error messages for details.
10434 Transaction refused Value of Custom element has
because of an invalid been truncated.
argument. See additional
error messages for details.

June 2008 217

 API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code Short Message Long Message Correcting This Error...
10435 Transaction refused The customer has not yet
because of an invalid confirmed payment for this
argument. See additional Express Checkout session.
error messages for details.
10441 Transaction refused The NotifyURL element value
because of an invalid exceeds maximum allowable
argument. See additional length.
error messages for details.
10442 ButtonSource value The ButtonSource element
truncated. value exceeds maximum
allowable length.
10443 Transaction refused This transaction cannot be
because of an invalid completed with
argument. See additional PaymentAction of Order.
error messages for details.
10444 Transaction refused The transaction currency
because of an invalid specified must be the same as
argument. See additional previously specified.
error messages for details.
10445 This transaction cannot be This transaction cannot be
processed at this time. processed at this time. Please
Please try again later. try again later.
10446 Unconfirmed email A confirmed email is required
to make this API call.
10474 Invalid Data This transaction cannot be The buyer selects the country of
processed. The country code in residence when they sign up for their
the shipping address must PayPal account. The country of
match the buyer’s country of residence is displayed after the dash in
residence. the title on the Account Overview page.
10537 Risk Control Country The transaction was refused
Filter Failure because the country was
prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control Max Amount The transaction was refused
Failure because the maximum amount
was excceeded as a result of
your Maximum Amount Risk
Control Settings.

218 June 2008

 API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code Short Message Long Message Correcting This Error...
10539 Payment declined by your Payment declined by your Risk
Risk Controls settings: Controls settings: PayPal Risk
PayPal Risk Model. Model.
10725 Shipping Address Country There was an error in the
Error Shipping Address Country
field
10727 Shipping Address1 Empty The field Shipping Address1 is
required
10728 Shipping Address City The field Shipping Address
Empty City is required
10729 Shipping Address State The field Shipping Address
Empty State is required
10730 Shipping Address Postal The field Shipping Address
Code Empty Postal Code is required
10731 Shipping Address Country The field Shipping Address
Empty Country is required
10736 Shipping Address Invalid A match of the Shipping
City State Postal Code Address City, State, and Postal
Code failed.
11610 Payment Pending your Payment Pending your review
review in Fraud in Fraud Management Filters
Management Filters
11611 Transaction blocked by Transaction blocked by your
your settings in FMF settings in FMF
11612 Could not process your Could not process your request
request to accept/deny the to accept/deny the transaction
transaction
11820 Transaction refused Invalid Order URL.
because of an invalid
argument. See additional
error messages for details

June 2008 219

 API Error Codes
Authorization and Capture API Errors

Authorization and Capture API Errors

TABLE A.7 Authorization & Capture API Error Messages

Error Short Returned By API Correcting This

Code Message Long Message Call... Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to
internal error
10004 Internal Error Invalid argument
10007 Permission You do not have
denied permissions to make this
API call
10009 Transaction Account is locked or Retry the request at a
refused inactive later time or close order.
10010 Transaction Invalid argument
refused because
of an invalid
argument. See
additional error
messages for
details.
10202 Exceed max Transaction would DoAuthorization
exceed user’s monthly DoCapture
maximum
10600 Authorization Authorization is voided. DoAuthorization Close the order or
voided. DoCapture authorization.
DoReauthorization
DoVoid
10601 Authorization Authorization has DoAuthorization Close the order or
expired. expired. DoCapture authorization.
DoReauthorization
DoVoid
10602 Authorization Authorization has already DoAuthorization Close the order or
completed. been completed. DoCapture authorization.
DoReauthorization
DoVoid

220 June 2008

 API Error Codes
Authorization and Capture API Errors

Error Short Returned By API Correcting This

Code Message Long Message Call... Error...
10603 The buyer is The buyer account is DoAuthorization Contact the buyer.
restricted. restricted. DoCapture
DoReauthorization
DoVoid
10604 Authorization Authorization transaction DoAuthorization Review the order to
must include cannot be unilateral. It ensure customer and
both buyer and must include both buyer seller are both PayPal
seller. and seller to make an members.
auth.
10605 Unsupported Currency is not DoAuthorization Retry the request with a
currency. supported. DoCapture PayPal-supported
currency.
10606 Buyer cannot Transaction rejected, DoAuthorization Contact the buyer.
pay. please contact the buyer. DoCapture
DoReauthorization
10607 Auth&Capture Authorization & Capture DoAuthorization Contact PayPal Customer
unavailable. feature unavailable. DoCapture Service.
DoReauthorization
DoVoid
10608 Funding source The funding source is DoAuthorization Contact the buyer.
missing. missing. DoCapture
DoReauthorization
10609 Invalid Transaction id is invalid. DoAuthorization Check the validity of the
transactionID. DoCapture authorization ID and
DoReauthorization reattempt the request.
DoVoid
10610 Amount limit Amount specified DoAuthorization Reattempt the request
exceeded. exceeds allowable limit. DoCapture with a lower amount.
DoReauthorization
10611 Not enabled. Authorization & Capture DoAuthorization Contact PayPal Customer
feature is not enabled for DoCapture Service.
the merchant. Contact DoReauthorization
customer service.
10612 No more Maxmimum number of DoCapture Close the order.
settlement. allowable settlements has
been reached. No more
settlement for the
authorization.

June 2008 221

 API Error Codes
Authorization and Capture API Errors

Error Short Returned By API Correcting This

Code Message Long Message Call... Error...
10613 Currency Currency of capture must DoCapture Ensure that the currencies
mismatch. be the same as currency are the same, and retry
of authorization. the request.
10614 Cannot void You can void only the DoVoid Void the authorization.
reauth. original authorization,
not a reauthorization.
10615 Cannot reauth You can reauthorize only DoReauthorization Capture the
reauth. the original authorization, reauthorization.
not a reauthorization.
10616 Maximum Maximum number of DoReauthorization Capture or close the
number of reauthorization allowed authorization
reauthorization for the auth is reached.
allowed for the
auth is reached.
10617 Reauthorization Reauthorization is not DoReauthorization Capture the authorization
not allowed. allowed inside honor or reauthorize outside of
period. honor period.
10618 Transaction Transaction has already DoAuthorization Close the order or
already voided been voided or expired. DoCapture authorization.
or expired. DoReauthorization
DoVoid
10619 Invoice ID value Invoice ID value exceeds DoCapture Check the length of the
exceeds maximum allowable invoice ID and reattempt
maximum length. the request.
allowable
length.
10620 Order has Order has already been DoAuthorization Close this order.
already been voided, expired, or DoCapture
voided, expired, completed. DoVoid
or completed.
10621 Order has Order has expired. DoAuthorization Close this order.
expired. DoCapture
DoVoid
10622 Order is voided. Order is voided. DoAuthorization Close this order.
DoCapture
DoVoid

222 June 2008

 API Error Codes
Authorization and Capture API Errors

Error Short Returned By API Correcting This

Code Message Long Message Call... Error...
10623 Maximum Maximum number of DoAuthorization Capture this order.
number of authorization allowed for DoCapture
authorization the order is reached. DoReauthorization
allowed for the
DoVoid
order is reached.
10624 Duplicate Payment has already DoAuthorization Review the invoice ID
invoice been made for this and reattempt the request.
Invoice ID.
10625 Transaction The amount exceeds the DoAuthorization Reattempt the request
refused because maximum amount for a DoCapture with a lower amount.
of an invalid single transaction. DoReauthorization
argument. See
additional error
messages for
details.
10626 Risk Transaction refused due DoAuthorization Contact the buyer.
to risk model. DoCapture
DoReauthorization
10627 Transaction The invoice ID field is DoAuthorization The Invoice ID field can
refused because not supported for basic DoReauthorization only be used with
of an invalid authorizations. DoVoid DoCapture.
argument. See
additional error
messages for
details.
10628 This transaction This transaction cannot DoAuthorization Retry the request at a
cannot be be processed at this time. DoCapture later time.
processed at this Please try again later. DoReauthorization
time. Please try
DoVoid
again later.
10629 Reauthorization Reauthorization is not DoReauthorization Use DoAuthorization to
not allowed. allowed for this type of authorize the an order.
authorization.
10630 Item amount is Item amount is invalid. DoAuthorization Check the item amount to
invalid. DoCapture ensure that it is not zero
or negative.

June 2008 223

 API Error Codes
Authorization and Capture API Errors

Error Short Returned By API Correcting This

Code Message Long Message Call... Error...
11094 This This authorization can
authorization only be handled through
cannot be the marketplace which
voided, created it. It cannot
reauthorized, or directly be voided,
captured against. reauthorized, or captured
against.

224 June 2008

 API Error Codes
GetTransactionDetails API Errors

GetTransactionDetails API Errors

TABLE A.8 GetTransactionDetails API Errors

Error Code Short Message Long Message

10001 Internal Error Internal Error

TransactionSearch API Errors

TABLE A.9 TransactionSearch API Errors

Error
Code Short Message Long Message
10001 Internal Error Internal Error
10001 ButtonSource value The transaction could not be loaded
truncated.
10003 Transaction refused because Start date is a required parameter
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Start date is invalid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because End date is invalid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Currency is not supported
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Transaction class is not supported
of an invalid argument. See
additional error messages for
details.

June 2008 225

 API Error Codes
TransactionSearch API Errors

Error
Code Short Message Long Message
10004 Transaction refused because Receipt id is not valid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Payer email is invalid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Auction item id is not valid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Receiver email is invalid
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because You can not search for a transaction id and a receipt id
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because Receiver can only be specified for payments you’ve received
of an invalid argument. See
additional error messages for
details.
10004 Transaction refused because The transaction id is not valid
of an invalid argument. See
additional error messages for
details.
10007 Permission denied You do not have permission to search for this transaction
10007 Permission denied You do not have permission to make this API call
11002 Search warning The number of results were truncated. Please change your search
parameters if you wish to see all your results.

226 June 2008

 API Error Codes
RefundTransaction API Errors

RefundTransaction API Errors

TABLE A.10 RefundTransaction API Errors

Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Warning an internal error has occurred.
The transaction id may not be correct
10001 ButtonSource value The transaction could not be loaded
truncated.
10001 Internal Error Internal Error
10004 Transaction refused The partial refund amount must be a
because of an invalid positive amount
argument. See additional
error messages for details.
10004 Transaction refused You can not specify a partial amount
because of an invalid with a full refund
argument. See additional
error messages for details.
10004 Transaction refused A transaction id is required
because of an invalid
argument. See additional
error messages for details.
10004 Transaction refused The partial refund amount must be a
because of an invalid positive amount
argument. See additional
error messages for details.
10004 Transaction refused You can not specify a partial amount
because of an invalid with a full refund
argument. See additional
error messages for details.
10004 Transaction refused A transaction id is required
because of an invalid
argument. See additional
error messages for details.
10004 Transaction refused Transaction class is not supported
because of an invalid
argument. See additional
error messages for details.

June 2008 227

 API Error Codes
RefundTransaction API Errors

Error
Code Short Message Long Message Correcting This Error...
10004 Transaction refused The transaction id is not valid
because of an invalid
argument. See additional
error messages for details.
10007 Permission denied You do not have permission to refund
this transaction
10007 Permission denied You do not have permissions to make
this API call
10009 Transaction refused 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 Transaction refused The partial refund amount must be less
than or equal to the original transaction
amount
10009 Transaction refused The partial refund amount must be less
than or equal to the remaining amount
10009 Transaction refused The partial refund amount is not valid
10009 Transaction refused Because a complaint case exists on this
transaction, only a refund of the full or
full remaining amount of the
transaction can be issued
10009 Transaction refused You are over the time limit to perform a
refund on this transaction
10009 Transaction refused Can not do a full refund after a partial
refund
10009 Transaction refused Account is locked or inactive
10009 Transaction refused The partial refund must be the same
currency as the original transaction

228 June 2008

 API Error Codes
RefundTransaction API Errors

Error
Code Short Message Long Message Correcting This Error...
10009 Transaction refused This transaction has already been fully
refunded
10009 Transaction refused Account is restricted
10009 Transaction refused You can not refund this type of
transaction
10009 Transaction refused You can not do a partial refund on this
transaction
10009 Transaction refused The account for the counterparty is
locked or inactive
10009 Transaction refused You can not refund this type of
transaction
10011 Invalid transaction id value Transaction refused because of an
invalid transaction id value
11001 Transaction refused Transaction class is not supported
because of an invalid
argument. See additional
error messages for details.

June 2008 229

 API Error Codes
Mass Pay API Errors

Mass Pay API Errors

TABLE A.11 MassPay API Errors

Error
Code Short Message Long Message
10001 Invalid account number. The transaction failed as a result of an invalid credit card number.
Check the number or attempt with another card.
10001 Internal Error Internal Error
10001 Internal Error The transaction could not be loaded
10001 ButtonSource value truncated. The transaction could not be loaded
10001 Transaction refused because of The masspay receiver_type is not a recognizable type
an invalid argument. See
additional error messages for
details.
10002 Account locked The user account is locked
10004 Transaction refused because of The number of input records is greater than maximum allowed
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of The number of input records is less than or equal to zero
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of The note string length exceeds the maximum limit of 4000
an invalid argument. See characters
additional error messages for
details.
10004 Transaction refused because of The amount is missing
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of The currency is missing
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of Currency is not supported
an invalid argument. See
additional error messages for
details.

230 June 2008

 API Error Codes
Mass Pay API Errors

Error
Code Short Message Long Message
10004 Transaction refused because of The amount is not a valid number
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of The amount exceeds the max limit of a single mass pay item
an invalid argument. See ~1
additional error messages for
details.
10004 Transaction refused because of The amount is less than or equal to zero
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of The unique id string length exceeds the maximum limit of 30
an invalid argument. See characters
additional error messages for
details.
10004 Transaction refused because of The unique id string contains a space as a character
an invalid argument. See
additional error messages for
details.
10004 Transaction refused because of The transaction id is not valid
an invalid argument. See
additional error messages for
details.
10007 Permission denied You do not have permissions to make this API call
10301 User not allowed The user is not allowed to send money through Mass Pay
10303 Restricted account Account is restricted
10304 Unconfirmed email The user account has unconfirmed email
10305 Limit Exceeded The user account needs to have its sending limit removed in order to
make a mass payment.
10306 Limit Exceeded The user’s international account needs to have its sending limit
removed in order to make a mass payment
10307 Receive only account The user account is receive only and therefore cannot send payments
out
10308 Masspay server configuration There is some configuration error
error
10309 Masspay server unavailable The mass pay server is unavailable

June 2008 231

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message
10310 Unable to create payment Unable to create payments for masspay
10311 Unable to submit payment Unable to submit payments for masspay
10312 Masspay server error The masspay server has reported errors
10313 Masspay Invalid Data The masspay input file includes invalid data
10314 Masspay input parse error The input to the masspay server is incorrect. Please make sure that
you are using a correctly formatted input.
10317 Masspay Invalid Email The masspay input file includes invalid Email
10320 Internal Error Internal Error
10321 Insufficient funds The account does not have sufficient funds to do this masspay
10327 Masspay Invalid UserID 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 CreateRecurringPaymentsProfile
z GetRecurringPaymentsProfileDetails
z ManageRecurringPaymentsProfileStatus
z UpdateRecurringPaymentsProfile
z BillOutstandingAmount

232 June 2008

 API Error Codes
Recurring Payments Errors

TABLE A.12 Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
10001 Invalid account number The transaction failed as a result of
invalid credit card number. Check
the number or attempt with another
credit card.
10478 Invalid Data Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments.
10501 Invalid Configuration This transaction cannot be Occurs when the billing
processed due to an invalid agreement is disabled or
merchant configuration. inactive.
10502 Invalid Data This transaction cannot be The credit card used is expired.
processed. Please use a valid credit
card.
10504 Invalid Data This transaction cannot be The CVV provided is invalid.
processed. Please enter a valid The CVV is between 3-4 digits
Credit Card Verification Number. long.
10505 Gateway Decline This transaction cannot be The transaction was refused
processed. because the AVS response
returned the value of N, and the
merchant account is not able to
accept such transactions.
10507 Invalid Configuration This transaction cannot be Your PayPal account is restricted
processed. Please contact PayPal - contact PayPal for more
Customer Service. information.
10508 Invalid Data This transaction cannot be The expiration date must be a
processed. Please enter a valid two-digit month and four-digit
credit card expiration date. year.
10509 Invalid Data This transaction cannot be You must submit an IP address
processed. of the buyer with each API call.
10510 Invalid Data The credit card type is not The credit card type entered is
supported. Try another card type. not currently supported by
PayPal.
10511 Invalid Data This transaction cannot be The merchant selected an value
processed. for the PaymentAction field that
is not supported.

June 2008 233

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
10512 Invalid Data This transaction cannot be The first name of the buyer is
processed. Please enter a first required for this merchant.
name.
10513 Invalid Data This transaction cannot be The last name of the buyer is
processed. Please enter a last required for this merchant.
name.
10535 Gateway decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
10548 Invalid Configuration This transaction cannot be The merchant account
processed. The merchant’s account attempting the transaction is not
is not able to process transactions. a business account at PayPal.
Check your account settings.
10550 Invalid Configuration This transaction cannot be Access to Direct Payment was
processed. disabled for your account.
Contact PayPal for more
information.
10561 Invalid Data There’s an error with this
transaction. Please enter complete
billing address.
10565 Merchant country The merchant country is not
unsupported supported.
10709 Invalid Data There’s an error with this There was a problem with a
transaction. Please enter an particular field in the address.
address1 in the billing address. The long error message will tell
you what field is invalid.
10710 Invalid Data There’s an error with this There was a problem with a
transaction. Please enter a city in particular field in the address.
the billing address. The long error message will tell
you what field is invalid.
10711 Invalid Data There’s an error with this There was a problem with a
transaction. Please enter your state particular field in the address.
in the billing address. The long error message will tell
you what field is invalid.
10712 Invalid Data There’s an error with this There was a problem with a
transaction. Please enter your five particular field in the address.
digit postal code in the billing The long error message will tell
address. you what field is invalid.

234 June 2008

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
10713 Invalid Data There’s an error with this There was a problem with a
transaction. Please enter a country particular field in the address.
in the billing address. The long error message will tell
you what field is invalid.
10744 Invalid Data This transaction cannot be There was a problem with a
processed. Please enter a valid particular field in the address.
country code in the billing address. The long error message will tell
you what field is invalid.
10748 Invalid Data This transaction cannot be The merchant’s configuration
processed without a Credit Card requires a CVV to be entered,
Verification Number. but no CVV was provided with
this transaction. Contact PayPal
if you wish to change this
setting.
10751 Invalid Data There’s an error with this The merchant provided an
transaction. Please enter a valid address either in the United
state in the billing address. States or Canada, but the state
provided is not a valid state in
either country.
10752 Gateway Decline This transaction cannot be The transaction was declined by
processed. the issuing bank, not PayPal. The
merchant should attempt another
card.
10760 Invalid Configuration This transaction cannot be The merchant’s country of
processed. The country listed for residence listed in their PayPal
your business address is not account is not currently
currently supported. supported to allow Direct
Payment transactions.
11089 Transaction Refused. Account is locked or inactive.
11501 Invalid merchant country The merchant’s country is Missing token
currently not supported
11502 The token is missing or is The token is missing or is invalid One or more subscription detail
invalid fields are missing from the
request.
11503 Missing subscription details Missing subscription details One or more schedule detail
fields are missing from the
request.
11504 Missing schedule details Missing schedule details
11505 Start date should be greater Subscription start date should be
than current date greater than current date

June 2008 235

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
11506 Invalid max failed Max failed payments, if supplied,
payments must be >= 0
11507 Invalid trial amount Trial amount must be >= 0
11508 Invalid trial total billing Trial total billing cycles must be >
cycles 0
11509 Invalid trial billing period Trial billing period must be one of
Day, Week, Month, SemiMonth, or
Year
11510 Invalid trial amount Trial amount must be >= 0
11511 Invalid currency for trial This currency is currently not Currency must be USD.
amount supported for trial amount.
11512 Invalid trial shipping Trial shipping amount must be >= If a trial shipping amount is
amount 0 supplied, it must be >= 0.
11513 Invalid currency for trial This currency is currently not Currency must be USD.
shipping amount supported for trial shipping amount
11514 Invalid profile status The profile status is invalid.
11515 Invalid currency for trial tax This currency is currently not Currency must be USD.
amount supported for trial tax amount
11516 Invalid billing frequency Billing Frequency must be > 0 and The combination of billing
be less than or equal to one year frequency and billing period
cannot exceed one year.
11517 Invalid total billing cycles Total billing cycles must be >= 0 (0
means continuous)
11518 Invalid billing period Billing period must be one of Day,
Week, Month, SemiMonth, or Year
11519 Invalid amount Bill amount must be greater than 0
11520 Invalid currency for amount This currency is currently not Currency must be USD.
supported for amount
11521 Invalid shipping amount Shipping amount must be >= 0
11522 Invalid currency for This currency is currently not Currency must be USD.
shipping amount supported for shipping amount
11523 Invalid tax amount Tax amount must be >= 0
11524 Invalid currency for tax This currency is currently not Currency must be USD.
amount supported for tax amount

236 June 2008

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
11531 Invalid profile status The profile status must be one of
(A)ctive, (C)ancelled, or e(X)pired
11543 Invalid payer country The payer’s country is currently
not supported
11544 Invalid period status The trial period status must be one
of (A)ctive or (C)ancelled
11545 Denied Payer’s account is denied
11546 Denied Merchant account is denied
11547 This feature is not available Recurring payments feature is not
at this time currently available; try again later
11548 Invalid currency code Invalid currency code, all currency
codes much match
11549 Start Date is required Subscription start date is required
11550 Start Date should be valid Subscription start date should be
valid
11551 Profile ID is missing from Profile ID is missing from the
the request request
11552 Invalid profile ID The profile ID is invalid
11553 Invalid action value Invalid action value provided
provided
11554 Note is missing from the Note is missing from the request
request
11555
11556 Invalid profile status for Invalid profile status for suspend
cancel action; profile action; profile should be active
should be active or
suspended
11557 Invalid profile status for Invalid profile status for reactivate
suspend action; profile action; profile should be suspended
should be active
11558 Invalid profile status for The activation type is invalid
reactivate action; profile
should be suspended
11560 Invalid activation type The activation type is invalid
11561 Invalid initial amount The initial amount is invalid

June 2008 237

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
11562 Invalid auto bill type The auto bill type is invalid
11564 The number of failed The number of failed payments
payments should be greater should be greater than the current
than the current number of number of failed payments
failed payments
11567 The time of the update is The time of the update is too close
too close to the billing date to the billing date
11568 Invalid currency for Invalid currency for delinquent
delinquent amount amount
11569 Cannot increase delinquent Cannot increase delinquent amount
amount
11570 The maximum number of The maximum number of failed
failed payments should be payments should be greater than
greater than the current the current number of failed
number of failed payments payments
11571 The total amount cannot The total amount cannot exceed
exceed 120% increment per 120% increment per 180 days
180 days
11576 Bill amount is greater than Bill amount is greater than
outstanding balance outstanding balance
11577 Another outstanding Another outstanding payment is
payment is scheduled scheduled
11578 Bill outstanding amount not Recurring payment scheduled
processed because of within 24 hours, so we are not
scheduled payment processing the bill outstanding
amount
11579 Payment is failing Payment is failing
11581 Invalid Data Profile description is invalid.
11582 No payment in queue No scheduled payment has been
found.
11583 DPRP feature is unavailable DPRP feature is unavailable
11584 Inactive profile Profile is not active
11585 Missing Token or buyer Missing token or payment source
credit card
11586 DPRP is disabled DPRP is disabled for this
merchant.

238 June 2008

 API Error Codes
Recurring Payments Errors

Error
Code Short Message Long Message Additional Information
11587 Billing Address is Partial Billing Address is Partial
11590 Profile update is not Based on your input request,
required profile already up to date.
15004 Gateway Decline This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.

June 2008 239

 API Error Codes
SetCustomerBillingAgreement Errors

SetCustomerBillingAgreement Errors
TABLE A.13 SetCustomerBillingAgreement Errors

Error
Code Short Message Long Message Additional Information
10004 Transaction refused Invalid argument; BillingType
because of an invalid input field is set to None
argument. See additional
error messages for details.
10404 Transaction refused ReturnURL is missing. ReturnURL tag has no content
because of an invalid
argument. See additional
error messages for details.
10004 Transaction refused Invalid value for request billing
because of an invalid address parameter.
argument. See additional
error messages for details.
10405 Transaction refused CancelURL is missing. CancelURL tag has no content
because of an invalid
argument. See additional
error messages for details.
10407 Transaction refused Invalid buyer email address Invalid BuyerEmail (badly
because of an invalid (BuyerEmail). formatted or violates SMTP
argument. See additional protocol defined email address
error messages for details. format) or BuyerEmail is passed
as an empty tag.
10436 Transaction refused PageStyle value exceeds maximum PageStyle tag is too long
because of an invalid allowable length.
argument. See additional
error messages for details.
10437 Transaction refused cpp-header-image value exceeds cpp_header_image tag is too
because of an invalid maximum allowable length. long; maximum length is 127
argument. See additional
error messages for details.
10438 Transaction refused cpp-header-border-color value cpp_header_border_color tag is
because of an invalid exceeds maximum allowable too long; maximum length is 6
argument. See additional length.
error messages for details.

240 June 2008

 API Error Codes
SetCustomerBillingAgreement Errors

Error
Code Short Message Long Message Additional Information
10439 Transaction refused cpp-header-back-color value cpp_header_back_color tag is
because of an invalid exceeds maximum allowable too long; maximum length is 6
argument. See additional length.
error messages for details.
10440 Transaction refused cpp-payflow-color value exceeds cpp_payflow_color tag is too
because of an invalid maximum allowable length. long; maximum length is 6
argument. See additional
error messages for details.
10471 Transaction refused ReturnURL is invalid. ReturnURL tag contains invalid
because of an invalid URL
argument. See additional
error messages for details.
10472 Transaction refused CancelURL is invalid. CancelURL tag contains invalid
because of an invalid URL
argument. See additional
error messages for details.
10476 Transaction refused
because of an invalid
argument. See additional
error messages for details.
10477 Transaction refused
because of an invalid
argument. See additional
error messages for details.
11452 Merchant not enabled for Merchant not enabled for reference This merchant is not enabled for
reference transactions transactions Mark reference transaction.
Warning only
11453 Reference transactions Reference transaction feature not Feature not enabled because
temporarily unavailable. currently available; try again later system is running in standin
mode. Warning only
11601 Request for billing address Billing address request is not
failed enabled for merchant
11602 Request for billing address Feature not yet available
failed

June 2008 241

 API Error Codes
GetBillingAgreementCustomerDetails Errors

GetBillingAgreementCustomerDetails Errors
TABLE A.14 GetBillingAgreementCustomerDetails Errors

Error
Code Short Message Long Message Additional Information
10408 Missing token Token is missing Token is missing
10409 You’re not authorized to Express Checkout token was Token belongs to a different
access this info. issued for a merchant account merchant
other than yours.
10410 Invalid token Invalid token Token invalid
10411 This Express Checkout This Express Checkout session has Token expired
session has expired. expired. Token value is no longer
valid.

CreateBillingAgreement Errors
TABLE A.15 CreateBillingAgreement Errors

Error
Code Short Message Long Message Additional Information
10408 Missing token Token is missing Token is missing
10409 You’re not authorized to Express Checkout token was Token belongs to a different
access this info. issued for a merchant account merchant
other than yours.
10410 Invalid token Invalid token Token invalid
10411 This Express Checkout This Express Checkout session has Token expired
session has expired. expired. Token value is no longer
valid.
11455 Buyer did not accept billing Buyer did not accept billing Buyer has not agreed to the
agreement agreement billing agreement.
11456 A successful Billing Transaction refused because of an Token has already been used to
Agreement has already invalid argument. See additional create a billing agreement
been created for this token. error messages for details.
10408 Missing token Token is missing Token is missing

242 June 2008

 API Error Codes
CreateBillingAgreement Errors

Error
Code Short Message Long Message Additional Information
10409 You’re not authorized to Express Checkout token was Token belongs to a different
access this info. issued for a merchant account merchant
other than yours.
10410 Invalid token Invalid token Token invalid
10411 This Express Checkout This Express Checkout session has Token expired
session has expired. expired. Token value is no longer
valid.

June 2008 243

 API Error Codes
UpdateBillingAgreement Errors

UpdateBillingAgreement Errors
TABLE A.16 UpdateBillingAgreement Errors

Error
Code Short Message Long Message Additional Information
10001 Internal Error Internal Error
10004 Transaction refused Invalid argument; description field Check the description and
because of an invalid or custom field is empty and the custom fields of the billing
argument. See additional status is active agreement. Either the description
error messages for details. or custom field is empty and the
status is active or the contents of
one of these fields exceeds the
maximum field length.
10201 Billing Agreement was Billing Agreement was cancelled Billing agreement has been
cancelled cancelled
10204 User’s account is closed or User’s account is closed or
restricted restricted
10209 Disabled Preapproved Payments not Merchant pull is not enabled for
enabled. the country or merchant is not
enabled for merchant pull
10209 Disabled Preapproved Payments not Account number mismatch for
enabled. the API caller and the account
the billing agreement belongs to.
10211 Invalid billing agreement Invalid transaction or billing
ID agreement ID; could not find
Billing Agreement in database
11451 Billing Agreement Id or Billing Agreement Id or ReferenceID field is empty.
transaction Id is not valid transaction Id is not valid
11451 Billing Agreement Id or Billing Agreement Id or Reference id refers to an invalid
transaction Id is not valid transaction Id is not valid transaction.
11452 Merchant not enabled for Merchant not enabled for reference This merchant is not enabled for
reference transactions transactions Mark reference transaction

DoReferenceTransaction Errors

244 June 2008

 API Error Codes
DoReferenceTransaction Errors

TABLE A.17 All Reference Transactions-Related API Errors

Error
Code Short Message Long Message Additional Information
10001 Internal Error Internal Error
10002 Authentication/Authorizati
on Failed
10004 Transaction refused Invalid payment type argument
because of an invalid
argument. See additional
error messages for details.
10009 Transaction refused The account for the counterparty is Merchant is
locked or inactive locked/close/restricted
10010 Invalid Invoice Non-ASCII invoice id is not Non-ASCII characters are used
supported in InvoiceID field
10201 Agreement canceled Billing Agreement was cancelled Billing agreement is not active
10202 Exceed max Transaction would exceed user’s Transaction would exceed the
monthly maximum monthly limit
10203 Action required Transaction failed, action required
by user
10204 User’s account is closed or User’s account is closed or
restricted restricted
10205 Risk Transaction refused due to risk
model
10206 Duplicate Transaction was already processed
10207 Retry Transaction failed but user has Retry the transaction with an
alternate funding source alternate funding source.
10209 Disabled Preapproved Payments not Merchants is not enabled for
enabled. preapproved payments (PAP);
applies only to legacy PAP
billing agreements
10210 No Funding Transaction failed because has no Payee has no funding sources.
funding sources
10211 Invalid MP ID Invalid MP ID
10212 Profile preference setting A profile preference is set to A profile preference is set that
automatically deny certain automatically denies this kind of
transactions transaction

June 2008 245

 API Error Codes
DoReferenceTransaction Errors

Error
Code Short Message Long Message Additional Information
10213 Invalid Soft Descriptor The soft descriptor passed in
contains invalid characters
10214 Soft descriptor format error.
10215 Soft Descriptor truncated The soft descriptor was truncated
10216 Transaction refused because a
confirmed address is not
available
10400 Transaction refused Order total is missing. TotalOrder amount is missing
because of an invalid
argument. See additional
error messages for details.
10401 Transaction refused Order total is invalid. TotalOrder amount is invalid
because of an invalid
argument. See additional
error messages for details.
10402 Authorization only is not This merchant account is not Merchant is not eligible for auth
allowed for merchant. permitted to set PaymentAction? to settlement
Authorization. Please contact
Customer Service.
10406 Transaction refused The PayerID? value is invalid. Merchant account number is
because of an invalid invalid
argument. See additional
error messages for details.
10412 Duplicate invoice Payment has already been made Payment already made for the
for this InvoiceID?. invoice
10413 Transaction refused The totals of the cart item amounts Total of cart items does not
because of an invalid do not match order amounts. match order total
argument. See additional
error messages for details.
10414 Transaction refused The amount exceeds the maximum Amount exceeds the max
because of an invalid amount for a single transaction. amount for a single txn
argument. See additional
error messages for details.
10417 Transaction cannot The transaction cannot complete Account not associated with a
complete. successfully. Instruct the customer usable funding source
to use an alternative payment
method.

246 June 2008

 API Error Codes
DoReferenceTransaction Errors

Error
Code Short Message Long Message Additional Information
10417 Transaction cannot The transaction cannot complete Credit card or Billing Agreement
complete. successfully. Instruct the customer is required to complete payment
to use an alternative payment
method.
10418 Transaction refused The currencies of the shopping cart Currencies in the shopping cart
because of an invalid amounts must be the same. must be the same
argument. See additional
error messages for details.
10420 Transaction refused PaymentAction? tag is missing. PaymentAction? tag is missing.
because of an invalid
argument. See additional
error messages for details.
10426 Transaction refused Item total is invalid. ItemTotal amount is invalid.
because of an invalid
argument. See additional
error messages for details.
10427 Transaction refused Shipping total is invalid. ShippingTotal amount is invalid.
because of an invalid
argument. See additional
error messages for details.
10428 Transaction refused Handling total is invalid. HandlingTotal amount is invalid
because of an invalid
argument. See additional
error messages for details.
10429 Transaction refused Tax total is invalid. TaxTotal amount is invalid.
because of an invalid
argument. See additional
error messages for details.
10429 Transaction refused Item sales tax is invalid PaymentDetailsItem.Tax field is
because of an invalid invalid. Warning only; API
argument. See additional executes
error messages for details.
10430 Transaction refused Item amount is missing. PaymentDetailsItem.Amount
because of an invalid field is missing. Warning only;
argument. See additional API executes
error messages for details.
10431 Transaction refused Item amount is invalid. PaymentDetailsItem.Amount
because of an invalid field is invalid. Warning only;
argument. See additional API executes
error messages for details.

June 2008 247

 API Error Codes
DoReferenceTransaction Errors

Error
Code Short Message Long Message Additional Information
10432 Transaction refused Invoice ID value exceeds InvoiceID field is too long;
because of an invalid maximum allowable length. maximum length is 256
argument. See additional
error messages for details.
10433 Transaction refused Value of OrderDescription element OrderDescription field is too
because of an invalid has been truncated. long; maximum length is 127.
argument. See additional Warning only; API executes
error messages for details.
10434 Transaction refused Value of Custom element has been Custom field is too long;
because of an invalid truncated. maximum length is 256.
argument. See additional Warning only; API executes
error messages for details.
10441 Transaction refused The NotifyURL element value NotifyURL field is too long;
because of an invalid exceeds maximum allowable maximum length for notify URL
argument. See additional length. is 2048
error messages for details.
10442 ButtonSource value The ButtonSource element value ButtonSource field is too long;
truncated. exceeds maximum allowable maximum length is 32. Warning
length. only; API executes
10504 The cvv2 is invalid. This transaction cannot be CVV2 field is invalid.
processed. Please enter a valid
Credit Card Verification Number.
10527 Invalid Data This transaction cannot be CreditCardNumber and/or
processed. Please enter a valid CreditCardType is invalid
credit card number and type.
10537 Risk Control Country Filter The transaction was refused Transaction refused due to
Failure because the country was prohibited country monitor risk control
as a result of your Country Monitor
Risk Control Settings.
10538 Risk Control Max Amount The transaction was refused Transaction refused due to max
Failure because the maximum amount was amount risk control
excused as a result of your
Maximum Amount Risk Control
Settings.
10539 Payment declined by your Payment declined by your Risk Transaction declined by Risk
Risk Controls settings: Controls settings: PayPal Risk Control settings: PayPal Risk
PayPal Risk Model. Model. model
10546 Gateway Decline This transaction cannot be IP fraud models failed.
processed.

248 June 2008

 API Error Codes
DoReferenceTransaction Errors

Error
Code Short Message Long Message Additional Information
10560 Invalid Data The issue number of the credit card IssueNumber is invalid.
is invalid.
10567 Invalid Data A Start Date or Issue Number is None of Start date or issue
required. number is specified (only applies
to Switch and Solo credit cards)
10600 Authorization voided Authorization voided.
10601 Authorization expired. Authorization has expired
10621 Order has expired. Order has expired.
10622 Order is voided. Order is voided.
10623 Maximum number of Maximum number of authorization
authorization allowed for allowed for the order is reached.
the order is reached.
10725 Shipping Address Country There was an error in the Shipping Shipping address error in
Error Address Country field country field
10727 Shipping Address1 Empty The field Shipping Address1 is Shipping address error in
required address1 field
10728 Shipping Address City The field Shipping Address City is Shipping address error in city
Empty required field
10729 Shipping Address State The field Shipping Address State is Shipping address error in state
Empty required field
10730 Shipping Address Postal The field Shipping Address Postal Shipping address error in postal
Code Empty Code is required code
10731 Shipping Address Country The field Shipping Address Country code is empty in
Empty Country is required shipping address
10736 Shipping Address Invalid A match of the Shipping Address Match of shipping address, city,
City State Postal Code City, State, and Postal Code failed. state, and postal code failed.
10747 Invalid Data This transaction cannot be IPAddress field is invalid.
processed without a valid IP
address.
10748 Invalid Data This transaction cannot be CVV2 field is missing.
processed without a Credit Card
Verification number.
10755 Unsupported Currency. This transaction cannot be
processed due to an unsupported
currency.

June 2008 249

 API Error Codes
DoReferenceTransaction Errors

Error
Code Short Message Long Message Additional Information
11302 Cannot pay self The transaction was refused Cannot pay self. Merchant is
because you cannot send money to referencing own transaction.
yourself.
11451 Billing Agreement Id or Billing Agreement Id or Invalid reference id
transaction Id is not valid transaction Id is not valid
11451 Billing Agreement Id or Billing Agreement Id or Reference transaction is not
transaction Id is not valid transaction Id is not valid associated with a billing
agreement.
11451 Billing Agreement Id or Billing Agreement Id or Reference id either not found or
transaction Id is not valid transaction Id is not valid could not be decrypted
11451 Billing Agreement Id or Billing Agreement Id or Reference id either not found or
transaction Id is not valid transaction Id is not valid could not be decrypted
11452 Merchant not enabled for Merchant not enabled for reference This merchant is not enabled for
reference transactions transactions Mark reference transaction
11453 Reference transactions Reference transaction feature not Feature wired off
temporarily unavailable. currently available; try again later
11453 Reference transactions Reference transaction feature not Feature not supported in standin
temporarily unavailable. currently available; try again later
11454 Warning: Could not send Warning: Could not send email to Failed to send email to buyer.
email to the buyer the buyer This error is not fatal and
generates a warning.
11459 Invalid Data The shipping address must match The shipping address on file
the user’s address in the PayPal does not match the requested
account. shipping address.
11610 Payment Pending your Payment Pending your review in
review in Fraud Fraud Management Filters
Management Filters
11611 Transaction blocked by Transaction blocked by your
your settings in FMF settings in FMF
11612 Could not process your Could not process your request to
request to accept/deny the accept/deny the transaction
transaction
18014 Gateway Decline This transaction cannot be This transaction cannot be
processed. processed without a Credit Card
Verification number.

250 June 2008

 API Error Codes
AddressVerify API Errors

AddressVerify API Errors

TABLE A.18 AddressVerify API Errors

Error Code Short Message Long Message

10004 Transaction refused because Invalid email format
of an invalid argument. See
additional error messages
for details.
10004 Transaction refused because Invalid street format
of an invalid argument. See
additional error messages
for details.
10004 Transaction refused because Invalid zip format
of an invalid argument. See
additional error messages
for details.
10009 The API is disabled. The Address API is currently disabled

ManagePendingTransactionStatus API Errors

TABLE A.19 ManagePendingTransactionStatus API Errors

Error Code Short Message Long Message

11614 Could not process your request Could not process your request to accept/deny the transaction
to accept/deny the transaction
11614 The transaction has already The transaction has already been Accepted/Denied and the
been Accepted/Denied and the status cannot be changed
status cannot be changed

June 2008 251

 API Error Codes
ManagePendingTransactionStatus API Errors

252 June 2008

B Country Codes

TABLE B.1 Country Codes

Country Code

AFGHANISTAN AF

ÅLAND ISLANDS AX

ALBANIA AL

ALGERIA DZ

AMERICAN SAMOA AS

ANDORRA AD

ANGOLA AO

ANGUILLA AI

ANTARCTICA AQ

ANTIGUA AND BARBUDA AG

ARGENTINA AR

ARMENIA AM

ARUBA AW

AUSTRALIA AU

AUSTRIA AT

AZERBAIJAN AZ

BAHAMAS BS

BAHRAIN BH

BANGLADESH BD

BARBADOS BB

BELARUS BY

BELGIUM BE

BELIZE BZ

BENIN BJ

June 2008 253

 Country Codes

Country Code

BERMUDA BM

BHUTAN BT

BOLIVIA BO

BOSNIA AND HERZEGOVINA BA

BOTSWANA BW

BOUVET ISLAND BV

BRAZIL BR

BRITISH INDIAN OCEAN TERRITORY IO

BRUNEI DARUSSALAM BN

BULGARIA BG

BURKINA FASO BF

BURUNDI BI

CAMBODIA KH

CAMEROON CM

CANADA CA

CAPE VERDE CV

CAYMAN ISLANDS KY

CENTRAL AFRICAN REPUBLIC CF

CHAD TD

CHILE CL

CHINA CN

CHRISTMAS ISLAND CX

COCOS (KEELING) ISLANDS CC

COLOMBIA CO

COMOROS KM

CONGO CG

CONGO, THE DEMOCRATIC REPUBLIC OF THE CD

COOK ISLANDS CK

254 June 2008

 Country Codes

Country Code

COSTA RICA CR

COTE D'IVOIRE CI

CROATIA HR

CUBA CU

CYPRUS CY

CZECH REPUBLIC CZ

DENMARK DK

DJIBOUTI DJ

DOMINICA DM

DOMINICAN REPUBLIC DO

ECUADOR EC

EGYPT EG

EL SALVADOR SV

EQUATORIAL GUINEA GQ

ERITREA ER

ESTONIA EE

ETHIOPIA ET

FALKLAND ISLANDS (MALVINAS) FK

FAROE ISLANDS FO

FIJI FJ

FINLAND FI

FRANCE FR

FRENCH GUIANA GF

FRENCH POLYNESIA PF

FRENCH SOUTHERN TERRITORIES TF

GABON GA

GAMBIA GM

GEORGIA GE

June 2008 255

 Country Codes

Country Code

GERMANY DE

GHANA GH

GIBRALTAR GI

GREECE GR

GREENLAND GL

GRENADA GD

GUADELOUPE GP

GUAM GU

GUATEMALA GT

GUERNSEY GG

GUINEA GN

GUINEA-BISSAU GW

GUYANA GY

HAITI HT

HEARD ISLAND AND MCDONALD ISLANDS HM

HOLY SEE (VATICAN CITY STATE) VA

HONDURAS HN

HONG KONG HK

HUNGARY HU

ICELAND IS

INDIA IN

INDONESIA ID

IRAN, ISLAMIC REPUBLIC OF IR

IRAQ IQ

IRELAND IE

ISLE OF MAN IM

ISRAEL IL

ITALY IT

256 June 2008

 Country Codes

Country Code

JAMAICA JM

JAPAN JP

JERSEY JE

JORDAN JO

KAZAKHSTAN KZ

KENYA KE

KIRIBATI KI

KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KP

KOREA, REPUBLIC OF KR

KUWAIT KW

KYRGYZSTAN KG

LAO PEOPLE'S DEMOCRATIC REPUBLIC LA

LATVIA LV

LEBANON LB

LESOTHO LS

LIBERIA LR

LIBYAN ARAB JAMAHIRIYA LY

LIECHTENSTEIN LI

LITHUANIA LT

LUXEMBOURG LU

MACAO MO

MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MK

MADAGASCAR MG

MALAWI MW

MALAYSIA MY

MALDIVES MV

MALI ML

MALTA MT

June 2008 257

 Country Codes

Country Code

MARSHALL ISLANDS MH

MARTINIQUE MQ

MAURITANIA MR

MAURITIUS MU

MAYOTTE YT

MEXICO MX

MICRONESIA, FEDERATED STATES OF FM

MOLDOVA, REPUBLIC OF MD

MONACO MC

MONGOLIA MN

MONTSERRAT MS

MOROCCO MA

MOZAMBIQUE MZ

MYANMAR MM

NAMIBIA NA

NAURU NR

NEPAL NP

NETHERLANDS NL

NETHERLANDS ANTILLES AN

NEW CALEDONIA NC

NEW ZEALAND NZ

NICARAGUA NI

NIGER NE

NIGERIA NG

NIUE NU

NORFOLK ISLAND NF

NORTHERN MARIANA ISLANDS MP

NORWAY NO

258 June 2008

 Country Codes

Country Code

OMAN OM

PAKISTAN PK

PALAU PW

PALESTINIAN TERRITORY, OCCUPIED PS

PANAMA PA

PAPUA NEW GUINEA PG

PARAGUAY PY

PERU PE

PHILIPPINES PH

PITCAIRN PN

POLAND PL

PORTUGAL PT

PUERTO RICO PR

QATAR QA

REUNION RE

ROMANIA RO

RUSSIAN FEDERATION RU

RWANDA RW

SAINT HELENA SH

SAINT KITTS AND NEVIS KN

SAINT LUCIA LC

SAINT PIERRE AND MIQUELON PM

SAINT VINCENT AND THE GRENADINES VC

SAMOA WS

SAN MARINO SM

SAO TOME AND PRINCIPE ST

SAUDI ARABIA SA

SENEGAL SN

June 2008 259

 Country Codes

Country Code

SERBIA AND MONTENEGRO CS

SEYCHELLES SC

SIERRA LEONE SL

SINGAPORE SG

SLOVAKIA SK

SLOVENIA SI

SOLOMON ISLANDS SB

SOMALIA SO

SOUTH AFRICA ZA

SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS

SPAIN ES

SRI LANKA LK

SUDAN SD

SURINAME SR

SVALBARD AND JAN MAYEN SJ

SWAZILAND SZ

SWEDEN SE

SWITZERLAND CH

SYRIAN ARAB REPUBLIC SY

TAIWAN, PROVINCE OF CHINA TW

TAJIKISTAN TJ

TANZANIA, UNITED REPUBLIC OF TZ

THAILAND TH

TIMOR-LESTE TL

TOGO TG

TOKELAU TK

TONGA TO

TRINIDAD AND TOBAGO TT

260 June 2008

 Country Codes

Country Code

TUNISIA TN

TURKEY TR

TURKMENISTAN TM

TURKS AND CAICOS ISLANDS TC

TUVALU TV

UGANDA UG

UKRAINE UA

UNITED ARAB EMIRATES AE

UNITED KINGDOM GB

UNITED STATES US

UNITED STATES MINOR OUTLYING ISLANDS UM

URUGUAY UY

UZBEKISTAN UZ

VANUATU VU

VENEZUELA VE

VIET NAM VN

VIRGIN ISLANDS, BRITISH VG

VIRGIN ISLANDS, U.S. VI

WALLIS AND FUTUNA WF

WESTERN SAHARA EH

YEMEN YE

ZAMBIA ZM

ZIMBABWE ZW

June 2008 261

 Country Codes

262 June 2008

C State and Province Codes

TABLE C.1 State and Province Codes

Canadian Province or U.S. State Abbreviation

Alberta AB

British Columbia BC

Manitoba MB

New Brunswick NB

Newfoundland and Labrador NL

Northwest Territories NT

Nova Scotia NS

Nunavut NU

Ontario ON

Prince Edward Island PE

Quebec QC

Saskatchewan SK

Yukon YT

Alabama AL

Alaska AK

American Samoa AS

Arizona AZ

Arkansas AR

California CA

Colorado CO

Connecticut CT

Delaware DE

District of Columbia DC

Federated States of Micronesia FM

June 2008 263

 State and Province Codes

Canadian Province or U.S. State Abbreviation

Florida FL

Georgia GA

Guam GU

Hawaii HI

Idaho ID

Illinois IL

Indiana IN

Iowa IA

Kansas KS

Kentucky KY

Louisiana LA

Maine ME

Marshall Islands MH

Maryland MD

Massachusetts MA

Michigan MI

Minnesota MN

Mississippi MS

Missouri MO

Montana MT

Nebraska NE

Nevada NV

New Hampshire NH

New Jersey NJ

New Mexico NM

New York NY

North Carolina NC

North Dakota ND

264 June 2008

 State and Province Codes

Canadian Province or U.S. State Abbreviation

Northern Mariana Islands MP

Ohio OH

Oklahoma OK

Oregon OR

Palau PW

Pennsylvania PA

Puerto Rico PR

Rhode Island RI

South Carolina SC

South Dakota SD

Tennessee TN

Texas TX

Utah UT

Vermont VT

Virgin Islands VI

Virginia VA

Washington WA

West Virginia WV

Wisconsin WI

Wyoming WY

Armed Forces Americas AA

Armed Forces AE

Armed Forces Pacific AP

June 2008 265

 State and Province Codes

266 June 2008

D Currency Codes

TABLE D.1 Currency Codes

ISO-4217 Code Currency

AUD Australian Dollar

CAD Canadian Dollar

CHF Swiss Franc

CZK Czech Koruna

DKK Danish Krone

EUR Euro

GBP Pound Sterling

HKD Hong Kong Dollar

HUF Hungarian Forint

JPY Japanese Yen

NOK Norwegian Krone

NZD New Zealand Dollar

PLN Polish Zloty

SEK Swedish Krona

SGD Singapore Dollar

USD U.S. Dollar

June 2008 267

 Currency Codes

268 June 2008

E AVS and CVV2 Response Codes

z “AVS Response Codes” on page 269

z “CVV2 Response Codes” on page 271

AVS Response Codes

z AVS Response Codes for Visa, Mastercard, Discover, and American Express
z AVS Response Codes for Maestro and Solo

June 2008 269

 AVS and CVV2 Response Codes
AVS Response Codes

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

AVS Code Meaning Matched Details

A Address Address only (no ZIP)
B International “A” Address only (no ZIP)
C International “N” None
N O T E : N O T E : The transaction is declined.

D International “X” Address and Postal Code

E Not allowed for MOTO Not applicable
(Internet/Phone) transactions
N O T E : N O T E : The transaction is declined.

F UK-specific “X” Address and Postal Code

G Global Unavailable Not applicable
I International Unavailable Not applicable
N No None
N O T E : N O T E : The transaction is declined.

P Postal (International “Z”) Postal Code only (no Address)

R Retry Not applicable
S Service not Supported Not applicable
U Unavailable Not applicable
W Whole ZIP Nine-digit ZIP code (no Address)
X Exact match Address and nine-digit ZIP code
Y Yes Address and five-digit ZIP
Z ZIP Five-digit ZIP code (no Address)
All others Error Not applicable

TABLE E.2 AVS Response Codes for Maestro and Solo

AVS Code Meaning Matched Details

0 All the address information matched. All information matched
1 None of the address information None
matched.
N O T E : N O T E : The transaction is declined.

270 June 2008

 AVS and CVV2 Response Codes
CVV2 Response Codes

AVS Code Meaning Matched Details

2 Part of the address information Partial
matched.
3 The merchant did not provide AVS Not applicable
information. Not processed.
4 Address not checked, or acquirer had Not applicable
no response. Service not available.
Null No AVS response was obtained. Not applicable
Default value of field.

CVV2 Response Codes

z CVV2 Response Codes for Visa, MasterCard, Discover, and American Express
z CVV2 Response Codes for Maestro and Solo
TABLE E.3 CVV2 Response Codes for Visa, MasterCard, Discover, and American Express

CVV2 Code Meaning Matched Details

M Match CVV2CSC
N No match None
P Not processed Not applicable
S Service not supported Not applicable
U Service not available Not applicable
X No response Not applicable

TABLE E.4 CVV2 Response Codes for Maestro and Solo

CVV2 Code Meaning Matched Details

0 Matched CVV2
1 No match None
2 The merchant has not implemented Not applicable
CVV2 code handling

June 2008 271

 AVS and CVV2 Response Codes
CVV2 Response Codes

CVV2 Code Meaning Matched Details

3 Merchant has indicated that CVV2 is Not applicable
not present on card
4 Service not available Not applicable
All others Error Not applicable

272 June 2008