Web Services API

Reference

For Professional Use Only

Currently only available in English.

A usage Professional Uniquement

Disponible en Anglais uniquement pour l'instant.

Last Updated: July 2006

 PayPal Web Services API Reference

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

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Organization of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 1 Overview of the PayPal Web Services API . . . . . . . . . 17

Get Started Quickly: Integration Center . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Complementary Technical Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Open Standards Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Web Services Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Cryptography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 2 PayPal Web Services API Architecture . . . . . . . . . . . 21

Services Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
PayPal WSDL/XSD Schema Definitions. . . . . . . . . . . . . . . . . . . . . . . . . 22
API Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
SOAP RequesterCredentials: Username, Password, Signature, and Subject . . . . . 24
Public/Private Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
SSL Data Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
SOAP Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
SOAP Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
SOAP Message Style: doc-literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
SOAP Request Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Request Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Response Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
CorrelationID for Reporting Problems to PayPal . . . . . . . . . . . . . . . . . . . . 30
Test Tools: PayPal SDK Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Web Services API Reference July 2006 3

 Contents

PayPal Web Services API Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Character Encoding, Data Types and Formats, and Currencies . . . . . . . . . . . . 31
API Overview By Business Function and Service Endpoint . . . . . . . . . . . . . . . 32
APIs to Exchange Funds or Display Information . . . . . . . . . . . . . . . . . . . . 33
Instant Payment Notification and the APIs. . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 3 Core eBL Request/Response Structures . . . . . . . . . . 35

Diagram of core eBL Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
AbstractRequestType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
AbstractResponseType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 4 Authorization & Capture API . . . . . . . . . . . . . . . . 39

Funds Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Diagram of DoCapture Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
DoCaptureRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
DoCaptureResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Diagram of DoAuthorization Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
DoAuthorizationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
DoAuthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
DoVoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Diagram of DoVoid Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
DoVoidRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DoVoidResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DoReauthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Diagram of DoReauthorization Types . . . . . . . . . . . . . . . . . . . . . . . . . . 49
DoReauthorizationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
DoReauthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 5 Direct Payment API . . . . . . . . . . . . . . . . . . . . . 51

Diagram of DoDirectPayment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
DoDirectPaymentRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

4 July 2006 Web Services API Reference

 Contents

Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 6 Express Checkout API . . . . . . . . . . . . . . . . . . . . 65

SetExpressCheckout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Diagram of Set ExpressCheckout Types . . . . . . . . . . . . . . . . . . . . . . . . 66
SetExpressCheckoutRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
SetExpressCheckoutResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Diagram of GetExpressCheckoutDetails Types . . . . . . . . . . . . . . . . . . . . . 73
GetExpressCheckoutDetailsRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 74
GetExpressCheckoutDetailsResponse . . . . . . . . . . . . . . . . . . . . . . . . . 74
DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Diagram of DoExpressCheckoutPayment Types . . . . . . . . . . . . . . . . . . . . 77
DoExpressCheckoutPaymentRequest. . . . . . . . . . . . . . . . . . . . . . . . . . 79
DoExpressCheckoutPaymentResponse. . . . . . . . . . . . . . . . . . . . . . . . . 83

Chapter 7 GetTransactionDetails API . . . . . . . . . . . . . . . . . 87

Diagram of GetTransactionDetails Types . . . . . . . . . . . . . . . . . . . . . . . . . . 87
GetTransactionDetailsRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
GetTransactionDetailsResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Chapter 8 MassPay API . . . . . . . . . . . . . . . . . . . . . . . . 97

Instant Payment Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Diagram of MassPay Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
MassPayRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
MassPayResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Chapter 9 RefundTransaction API . . . . . . . . . . . . . . . . . . 101

Instant Payment Notification:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Diagram of RefundTransaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
RefundTransactionRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Web Services API Reference July 2006 5

 Contents

RefundTransactionResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Chapter 10 TransactionSearch API . . . . . . . . . . . . . . . . . . 103

Diagram of TransactionSearch Types . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
TransactionSearchRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
TransactionSearchResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Appendix A Error Codes and Messages for All PayPal APIs . . . . . . 109
General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Authorization & Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Direct Payments API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Express Checkout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Appendix B Country Codes . . . . . . . . . . . . . . . . . . . . . . 149

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

6 July 2006 Web Services API Reference

 List of Tables

Table 1.1 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Table 1.1 PayPal Technical Documentation . . . . . . . . . . . . . . . . . . . . . 17
Table 2.1 Location of PayPal WSDL and XSD Files . . . . . . . . . . . . . . . . . 22
Table 2.2 Basic PayPal API Set-up Concepts and Terminology . . . . . . . . . . . 22
Table 2.3 RequesterCredentials Authentication Elements in SOAP Header . . . . . 24
Table 2.4 SOAP Service Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 2.5 Annotation of Generic SOAP Request . . . . . . . . . . . . . . . . . . . 27
Table 2.6 Annotation of Generic SOAP Response . . . . . . . . . . . . . . . . . . 29
Table 2.7 PayPal-Supported Currencies, Currency Codes, and Maximum Transaction
Amounts 31
Table 2.8 API Overview by Business Function and Service Endpoint . . . . . . . . 32
Table 3.1 AbstractRequestType Fields . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 3.2 AbstractResponseType Fields . . . . . . . . . . . . . . . . . . . . . . . 36
Table 4.1 Authorization & Capture API Names, Purposes, and Types of Authorization .
39
Table 4.2 DoCaptureRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . 41
Table 4.3 DoCaptureResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . 42
Table 4.4 Response: PaymentInfoType Elements . . . . . . . . . . . . . . . . . . 42
Table 4.5 DoAuthorizationRequest Fields . . . . . . . . . . . . . . . . . . . . . . 46
Table 4.6 DoAuthorizationResponse Fields . . . . . . . . . . . . . . . . . . . . . 46
Table 4.7 DoVoidRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Table 4.8 DoVoidResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Table 4.9 DoReauthorizationRequest Fields . . . . . . . . . . . . . . . . . . . . . 50
Table 4.10 DoReauthorizationResponse Fields . . . . . . . . . . . . . . . . . . . . 50
Table 5.1 DoDirectPaymentRequest Fields . . . . . . . . . . . . . . . . . . . . . 52
Table 5.2 CreditCardDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . 53
Table 5.3 Request: PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . 54
Table 5.4 Request: ShipToAddress: AddressType Fields . . . . . . . . . . . . . . 56
Table 5.5 StateOrProvince: Abbreviations for Canada and U.S. . . . . . . . . . . . 57
Table 5.6 Request: PaymentDetailsItemType Fields . . . . . . . . . . . . . . . . . 60
Table 5.7 CardOwner: PayerInfoType Fields . . . . . . . . . . . . . . . . . . . . . 60
Table 5.8 CardOwner: AddressType Fields . . . . . . . . . . . . . . . . . . . . . . 61

Web Services API Reference July 2006 7

 List of Tables

Table 5.9 DoDirectPaymentResponse Fields . . . . . . . . . . . . . . . . . . . . . 62

Table 5.10 AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 5.11 CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 6.1 SetExpressCheckoutRequest Fields . . . . . . . . . . . . . . . . . . . . 67
Table 6.2 Address (Shipping Address): AddressType Elements . . . . . . . . . . . 71
Table 6.3 SetExpressCheckoutResponse Fields . . . . . . . . . . . . . . . . . . . 72
Table 6.4 GetExpressCheckoutDetailsRequest Fields . . . . . . . . . . . . . . . . 74
Table 6.5 GetExpressCheckoutDetailsResponse Fields . . . . . . . . . . . . . . . 74
Table 6.6 Response: PayerInfoType Elements . . . . . . . . . . . . . . . . . . . . 75
Table 6.7 Response: PayerName Elements . . . . . . . . . . . . . . . . . . . . . 76
Table 6.8 Response: AddressType Fields . . . . . . . . . . . . . . . . . . . . . . 76
Table 6.9 DoExpressCheckoutPaymentRequest Fields . . . . . . . . . . . . . . . 79
Table 6.10 Request: PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . 80
Table 6.11 Request: ShipToAddress: AddressType Fields . . . . . . . . . . . . . . 82
Table 6.12 Request: PaymentDetailsItemType Fields . . . . . . . . . . . . . . . . . 83
Table 6.13 DoExpressCheckoutPaymentResponse Fields . . . . . . . . . . . . . . 84
Table 6.14 Response: PaymentInfoType Elements . . . . . . . . . . . . . . . . . . 84
Table 7.1 GetTransactionDetailsRequest Fields . . . . . . . . . . . . . . . . . . . 88
Table 7.2 GetTransactionDetailsResponse Fields . . . . . . . . . . . . . . . . . . 88
Table 8.1 MassPayRequestType Fields . . . . . . . . . . . . . . . . . . . . . . . 98
Table 8.2 ReceiverInfoCodeType Enumeration . . . . . . . . . . . . . . . . . . . 98
Table 8.3 MassPayItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . 99
Table 9.1 RefundTransactionRequest Fields . . . . . . . . . . . . . . . . . . . . .102
Table 9.2 RefundTransactionResponse Fields . . . . . . . . . . . . . . . . . . . .102
Table 10.1 TransactionSearchRequest Fields . . . . . . . . . . . . . . . . . . . . .104
Table 10.2 PaymentTransactions Fields . . . . . . . . . . . . . . . . . . . . . . . .106
Table A.1 General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Table A.2 Authorization & Capture API Error Messages . . . . . . . . . . . . . . . 110
Table A.3 Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . 114
Table A.4 SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . .123
Table A.5 GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . .129
Table A.6 DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . .130
Table A.7 GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . .137
Table A.8 MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Table A.9 RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . .143
Table A.10 TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . .146

8 July 2006 Web Services API Reference

 List of Tables

Web Services API Reference July 2006 9

 List of Tables

10 July 2006 Web Services API Reference

 List of Figures

Figure 2.1 PayPal Web Services High-level Diagram . . . . . . . . . . . 21

Figure 2.2 Diagram of SOAP Request Envelope . . . . . . . . . . . . . 26
Figure 3.1 Core eBL Types . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 4.1 DoCapture Types . . . . . . . . . . . . . . . . . . . . . . 40
Figure 4.2 DoAuthorization Types . . . . . . . . . . . . . . . . . . . 45
Figure 4.3 DoVoid Types . . . . . . . . . . . . . . . . . . . . . . . . 47
Figure 4.4 DoReauthorization Types . . . . . . . . . . . . . . . . . . 49
Figure 5.1 DoDirectPayment Types . . . . . . . . . . . . . . . . . . . 51
Figure 6.1 SetExpressCheckout Types . . . . . . . . . . . . . . . . . 66
Figure 6.2 GetExpressCheckout Types . . . . . . . . . . . . . . . . . 73
Figure 6.3 DoExpressCheckoutPayment Types . . . . . . . . . . . . . 78
Figure 7.1 GetTransactionDetails Types . . . . . . . . . . . . . . . . . 87
Figure 8.1 MassPay Types . . . . . . . . . . . . . . . . . . . . . . . 97
Figure 9.1 RefundTransaction Types . . . . . . . . . . . . . . . . . . 101
Figure 10.1 TransactionSearch Types . . . . . . . . . . . . . . . . . . 103

Web Services API Reference July 2006 11

 List of Figures

12 July 2006 Web Services API Reference

 Preface

This Document
This document, PayPal Web Services API Reference, which describes the PayPal Web
Services Application Programming Interface (API) and service, replaces the edition issued
March, 2006.

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

Organization of This Document

Chapter 1, “Overview of the PayPal Web Services API,” presents high-level information about
the purposes of the API, supported development environments, and usage limits and fees.
Chapter 2, “PayPal Web Services API Architecture,” describes the architecture of the API
services, its security features, the PayPal SOAP and WSDL implementations, and data
characteristics, such as character encodings, currency and date/time formats, and other
information.
The central chapters describe individual PayPal Web Services APIs for a variety of business
functions.
Appendix A, “Error Codes and Messages for All PayPal APIs,” details specific errors and
warnings for each individual PayPal Web Services API.

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

Web Services API Reference July 2006 13

 Preface
Documentation Problems

Typeface How Used

serif italics A document title.

A term being discussed or defined.

For example: A file is a readable or writable stream of characters …

Boolean values (not keywords).

For example: The function returns true if it encounters an error.

monospaced Pathnames or file names that appear in body text frames.

Code-related names that appear in body text frames. Such names are used for functions,
callbacks, arguments, data structures, and fields.
For example: AbstractResponseType is the SOAP response type definition on which
all PayPal API response methods are based.

Components of Internet protocol requests and responses, such as HTTPS and FORM
variables.
For example: The PayPal system uses a method=POST request to return IPN status
variables related to subscriptions, such as txn_type.

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

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

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

Text attribute How Used

xxxxxx Hypertext link to a page in the current document or to another document in the set.

xxxxxx Hypertext link to a URL or that initiates a web action, such as sending mail.

Documentation Problems
If you discover any errors in or have any problems with this documentation, please email us by
following the instructions below. Describe the error or problem as completely as possible and
give us the document title, the date of the document (located at the foot of every page), and the
page number or page range.
To contact Developer Technical Support about documentation problems:

14 July 2006 Web Services API Reference

 Preface
Revision History

Log in to your account at https://developer.paypal.com/ by entering your email address and

password in the Member Log In box
Click Help Center at the bottom of the box on the right side of the page.
Click Email PayPal Technical Support.
Complete the form.

Revision History
Revision history for PayPal Web Services API Reference.

TABLE 1.1 Revision History

Date Description
July 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.

Web Services API Reference July 2006 15

 Preface
Revision History

16 July 2006 Web Services API Reference

 1 Overview of the PayPal Web
Services API

The PayPal Web Services 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.

Get Started Quickly: Integration Center

PayPal’s Integration Center at https://www.paypal.com/integration has step-by-step details for
getting started with the PayPal Software Development Kits (SDKs), Website Payments Pro,
Express Checkout, Website Payments Standard, Authorization & Capture, Instant Payment
Notification, and more.
Visit the Integration Center at:
https://www.paypal.com/integration

Complementary Technical Documentation

All PayPal technical documentation is listed here. The description of each guide indicates its
subject matter and documentation necessary for effective use of the guide.

TABLE 1.1 PayPal Technical Documentation

Guide Title Description Prerequisites

Website Payments Details basic PayPal payment process for shopping cart and single-item purchase. None
Standard Integration Account Profile settings for variations on basic payment process. Customization of
Guide PayPal's payment pages. HTML FORM variables for control of payment process.
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_Integratio
nGuide.pdf
Express Checkout Details use of Express Checkout API. PayPal placement on merchants' websites and Website Payments
Integration Guide related business rules. Standard Integration
https://www.paypal.com/en_US/pdf/PP_ExpressCheckout_IntegrationGuide.p Guide
df
Website Payments Details use of Express Checkout and Direct Payment APIs. PayPal placement on Website Payments
Pro Integration Guide merchants' websites and related business logic. Standard Integration
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsPro_IntegrationGui Guide
de.pdf

Web Services API Reference July 2006 17

 Overview of the PayPal Web Services API
Open Standards Background Information

TABLE 1.1 PayPal Technical Documentation

Guide Title Description Prerequisites

Order Management Details Instant Payment Notification (IPN) and Payment Data Transfer (PDT) for Website Payments
Integration Guide automated receipt of payment information after payment completion. Details IPN Standard Integration
HTML FORM variables and their meanings. Also includes information about Guide
Downloadable History Logs.
https://www.paypal.com/en_US/pdf/PP_OrderManagement_IntegrationGuide.
pdf
Java SDK Guide Details the use of the PayPal Software Development Kits for Java, Microsoft .NET, z Website
.NET SDK Guide Microsoft Classic ASP, and PHP to simplify use of the PayPal Web Services API. Payments
Classic ASP Guide https://www.paypal.com/en_US/pdf/PP_SDK_Java_Guide.pdf Standard
PHP SDK Guide https://www.paypal.com/en_US/pdf/PP_SDK_NET_Guide.pdf Integration
https://www.paypal.com/en_US/pdf/PP_SDK_ClassicASP_Guide.pdf Guide
https://www.paypal.com/en_US/pdf/PP_SDK_PHP_Guide.pdf z Website
Payments Pro
Integration
Guide
z Authorization &
Capture
Integration
Guide
z Sandbox User
Guide
z API Reference
Sandbox User Guide Describes the PayPal Sandbox testing environment for testing website payments and All other PayPal
Web Services APIs. Details how to get PayPal API digital certificates. guides for an
https://www.paypal.com/en_US/pdf/PP_Sandbox_UserGuide.pdf understanding of how
products work

Web Services API Field-by-field description of all PayPal Web Services APIs, their SOAP structures, and None
Reference error messages. Location of PayPal WSDL and XSD files.
https://www.paypal.com/en_US/pdf/PP_APIReference.pdf
Subscriptions and Describes HTML FORM variables for using PayPal for subscriptions to goods and Website Payments
Recurring Payments services. Standard Integration
Guide https://www.paypal.com/en_US/pdf/subscriptions.pdf Guide

Virtual Terminal User Details how to use the virtual terminal to accept credit card payments. None
Guide https://www.paypal.com/en_US/pdf/VT_user_guide.pdf

Open Standards Background Information

This section contains references to background information for understanding and using the
PayPal Web Services API.

18 July 2006 Web Services API Reference

 Overview of the PayPal Web Services API
Web Services Standards

Web Services Standards

Web Services are an ongoing open standards effort. For the latest information about
developments in Web Services, see the following site:
http://www.webservices.org/

Cryptography
The PayPal Web Services API uses public key infrastructure, specifically PKCS#12 and
Privacy Enhanced Mail (PEM). For more information about PKCS#12 and PEM files, see the
following sites:
z PKCS12 and other forms of securely available credentials:
http://www.faqs.org/rfcs/rfc3157.html
z PEM: http://www.ietf.org/rfc/rfc1421.txt

Web Services API Reference July 2006 19

 Overview of the PayPal Web Services API
Cryptography

20 July 2006 Web Services API Reference

 2 PayPal Web Services API
Architecture

The PayPal Web Services 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 Web Services is a combination of client-side and server-side
schemas, hardware and software servers, and core services.

FIGURE 2.1 PayPal Web Services 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

Web Services API Reference July 2006 21

 PayPal Web Services API Architecture
Services Architecture

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

TABLE 2.1 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 https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd
Components and https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd
Component Types

Production with Live PayPal Web Services API Service

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

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

API Concepts and Terminology

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

TABLE 2.2 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.

Business Partner A business partner can also be known as “hosting service,” “third-party e-commerce service,” “shopping
cart provider,” “online storefront,” or “gateway.”

22 July 2006 Web Services API Reference

 PayPal Web Services API Architecture
Services Architecture

TABLE 2.2 Basic PayPal API Set-up Concepts and Terminology

Term Definition
API Certificate 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 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.
Multiple API signatures can be associated with your API username and password. For security, every time
you view your API credential/signature on https://www.paypal.com, a new signature is generated. In your
API calls, you can use any of the signatures that PayPal generates for you. All the signatures are equally valid
until you remove your credentials by clicking Remove on the View API Signature page.

API Username A PayPal-generated identifying account name and password that you use specifically for making API calls.
and Password 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 merchant for whom the call is being made. This is the programmatic aspect
of third-party authentication. The value of the Subject field is the third-party’s API username.

First-Party A company makes API calls itself from its own server to PayPal's server. The company has its own API
Access 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 merchant's behalf. The merchant grants the third-party
Access his permission to make API calls for him.
Examples:
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 API username in the "Subject" field of an API call.
A merchant company's programmer has her own PayPal-issued API signature, username, and password. She
gives permission to a shopping cart service to access her API credentials. The shopping cart service makes
API calls on the programmer's company's behalf, using the programmer's credentials.

Security
The PayPal Web Services API service is protected to ensure that only authorized PayPal
members use it. There are three primary levels of security:
z API username/password and third-party account authentication
z Public/private key encryption via an API certificate or API signature
z Secure Sockets Layer (SSL) data transport
A failure of authenticated security at any one of these levels denies access to the PayPal Web
Services API.

Web Services API Reference July 2006 23

 PayPal Web Services API Architecture
Services Architecture

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 “SOAP Request Envelope” on
page 26.
<SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI” xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents” xsi:type=”ebl:UserIdPasswordType”>
<Username xsi:type=”xs:string”>api_username</Username>
<Password xsi:type=”xs:string”>api_password</Password>
<Signature xsi:type=”xs:string”>api_signature</Signature>
<Subject xsi:type=”xs:string”>authorizing_account_emailaddress</Subject>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
where:

TABLE 2.3 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 Web Services API. You
can see this value on https://www.paypal.com/ in your Profile under
API Access > API Certificate Information.
N O T E : The PayPal Sandbox User Guide contains details about how
you can obtain digital certificates for use with the PayPal Web
Services API.

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

<Signature> api_signature Your API signature, if you use one.

N O T E : The <Signature> element must be included in the SOAP
header, even if you do not rely on an API signature. In this
case, set <Signature> with no value:

<Signature/>

24 July 2006 Web Services API Reference

 PayPal Web Services API Architecture
SOAP Service Endpoints

TABLE 2.3 RequesterCredentials Authentication Elements in SOAP Header

Element Value Description

<Subject> authorizing_ The email address of a third-party for whom you are sending requests
account_ to the PayPal Web Services API. Your API username must have been
emailaddress granted permission by this third-party to make any particular PayPal
API request.
N O T E : The <Subject> element must be included in the SOAP
header, even if you are not making a request on someone
else’s behalf. In this case, set <Subject> with no value:

<Subject/>

Public/Private Key Encryption

Your security with the PayPal Web Services API relies on a set of public/private security keys
issued in the form of digital certificates by PayPal. These keys uniquely identify an API user to
prove his authorization to access PayPal Web Services. Each SOAP request is signed by your
private key, and PayPal Web Services processes a request only after authentication succeeds.

SSL Data Transport

All data must be transported over the Secure Hyper Text Transport Protocol (also known as
SHTTP or HTTPS), which relies on the Secure Sockets Layer (SSL) data communications
protocol.

SOAP Service Endpoints

Depending on your chosen authentication mechanism, your SOAP requests must be processed
by different service endpoints.

TABLE 2.4 SOAP Service Endpoints

Authentication
Mechanism Live Production Endpoint Test (Sandbox) Endpoint
API Signature https://api-3t.paypal.com/2.0/
https://api-aa-3t.paypal.com/2.0/ https://api.sandbox.paypal.com/2.0/
https://api-aa.sandbox.paypal.com/2.0/
API Certificate https://api.paypal.com/2.0/
https://api-aa.paypal.com/2.0/

N O T E : For thecorrespondence between API calls and their service endpoints, see Table 2.8,
“API Overview by Business Function and Service Endpoint” on page 32.

Web Services API Reference July 2006 25

 PayPal Web Services API Architecture
SOAP Implementation

SOAP Implementation
This section contains information about the PayPal Web Services 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: Abstract RequestType and
AbstractResponseType.

FIGURE 2.2 Diagram of SOAP Request Envelope

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

26 July 2006 Web Services API Reference

 PayPal Web Services API Architecture
SOAP Implementation

EXAMPLE 2.1 General Structure of PayPal API SOAP Request

1. <?xml version=”1.0” encoding=”UTF-8”?>
2. <SOAP-ENV:Envelope
3. xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
4. xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
5. xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
6. xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
7. SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”>
8. <SOAP-ENV:Header>
9. <RequesterCredentials
10. xmlns=”urn:ebay:api:PayPalAPI”>
11. <Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”>
12. <Username>api_username</Username>
13. <Password>api_password</Password>
14. <Signature/>
15. <Subject/>
16. </Credentials>
17. </RequesterCredentials>
18. </SOAP-ENV:Header>
19. <SOAP-ENV:Body>
20. <specific_api_name_Req xmlns=”urn:ebay:api:PayPalAPI”>
21. <specific_api_name_Request
22. xsi:type=”ns:specific_api_name_RequestType”>
23. <Version xsi:type=”xsd:string”>service_version</Version>
24. <required_or_optional_element xsi:type=”some_type_here”>
25. data
26. </required_or_optional_elements >
27. </specific_api_name_Request>
28. </specific_api_name_Req>
29. </SOAP-ENV:Body>
30. </SOAP-ENV:Envelope>

TABLE 2.5 Annotation of Generic SOAP Request

Lines Comment
12, 13 The <Username> and <Password> elements are part of the PayPal Web Services 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 24.
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 “<Signature>” on page 24.

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

19 through The SOAP request for every PayPal API follows this element naming pattern. The API’s specific
27 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.

Web Services API Reference July 2006 27

 PayPal Web Services API Architecture
SOAP Implementation

TABLE 2.5 Annotation of Generic SOAP Request

Lines Comment
22 The number of the PayPal Web Services API version is required on each SOAP request.

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
Web Services API.

EXAMPLE 2.1 General Structure of PayPal API SOAP Response: Success

1.<?xml version=”1.0”?>
2.<SOAP-ENV:Envelope
3. xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
4. xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
5. xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
6. xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
7. xmlns:xs=”http://www.w3.org/2001/XMLSchema”
8. xmlns:cc=”urn:ebay:apis:CoreComponentTypes”
9. xmlns:wsu=”http://schemas.xmlsoap.org/ws/2002/07/utility”
10. xmlns:saml=”urn:oasis:names:tc:SAML:1.0:assertion”
11. xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”
12. xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/12/secext”
13. xmlns:ebl=”urn:ebay:apis:eBLBaseComponents”
14. xmlns:ns=”urn:ebay:api:PayPalAPI”>
15. <SOAP-ENV:Header>
16. <Security xmlns=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xsi:type=”wsse:SecurityType”/>
17. <RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
18. <Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”/>
19. </RequesterCredentials>
20. </SOAP-ENV:Header>
21. <SOAP-ENV:Body id=”_0”>
22. <specific_api_name_Response xmlns=”urn:ebay:api:PayPalAPI”>
23. <Timestamp>dateTime_in_UTC/GMT</Timestamp>
24. <Ack xmlns=”urn:ebay:apis:eBLBaseComponents”>Success</Ack>
25. <Version xmlns=”urn:ebay:apis:eBLBaseComponents”>serviceVersion</Version>
26. <CorrelationId
xmlns=”urn:ebay:apis:eBLBaseComponents”>applicationCorrelation</CorrelationID>
27. <Build xmlns=”urn:ebay:apis:eBLBaseComponents”>api_build_number</Build>
28. <elements_for_specific_api_response>
29. data
30. </elements_for_specific_api_response>
31. </specific_api_name_Response>
32. </SOAP-ENV:Body>
33.</SOAP-ENV:Envelope>

28 July 2006 Web Services API Reference

 PayPal Web Services API Architecture
SOAP Implementation

TABLE 2.6 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. (For a complete list of possible returned strings, see
“AbstractResponseType” on page 36.)
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 29.
26 The <CorrelationID> element contains information about the PayPal application that
processed the request.

27 through The different PayPal APIs return different structures depending on their response definitions. For
30 detailed information, see the description of the individual APIs.
N O T E : 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
For a description of the contents of these elements, see Appendix A, “Error Codes and
Messages for All PayPal APIs.”
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 2.1 Example of SOAP Error Response: Bad Username or Password

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope details not shown>
<SOAP-ENV:Header>
.
. details not shown
.
</SOAP-ENV:Header>
<SOAP-ENV:Body id="_0">

Web Services API Reference July 2006 29

 PayPal Web Services API Architecture
PayPal Web Services API Definitions

<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</Version>
<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. We suggest that you capture the value of CorrelationID
so you can report it to PayPal.

Test Tools: PayPal SDK Console

The PayPal SDK includes the console, which is a good tool for testing and learning the PayPal
Web Services API. For more details about the console, see the PayPal SDK Guides.

PayPal Web Services API Definitions

The PayPal Web Services 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.

30 July 2006 Web Services API Reference

 PayPal Web Services API Architecture
PayPal Web Services API Definitions

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.
N O T E : eBL defines many structures that are specific to processing auctions. PayPal’s Web
Services schema includes these definitions to maintain compatibility with eBay’s Web
Services and for possible future joint use of Web Services across both eBay and
PayPal. The material in this book focuses only on those Web Services definitions
pertinent to use of the PayPal Web Services 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 Web Services 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.
Numeric and Date/Time Formats
The PayPal Web Services API schema defines the following data types for numeric and
date/time values.
z Numeric data types:
– int (32-bit), not integer.
– For percentage values: float, not decimal.
z Date/time values: Coordinated Universal Time (UTC/GMT), using ISO 8601 format, and
of type ns:dateTime.

PayPal-Supported Currencies. The following currencies are supported by PayPal.

TABLE 2.7 PayPal-Supported Currencies, Currency Codes, and Maximum

Transaction Amounts

Maximum Transaction
Code Currency Amount
AUD Australian Dollar 12,500 AUD

CAD Canadian Dollar 12,500 CAD

EUR Euro 8,000 EUR

GBP Pound Sterling 5,500 GBP

JPY Japanese Yen 1,000,000 JPY

USD U.S. Dollar 10,000 USD

Web Services API Reference July 2006 31

 PayPal Web Services API Architecture
PayPal Web Services API Definitions

The core currency amount data type is derived from string, and all currency amount elements
have the following structure. The currencyID attribute is required.
<Amount currencyID=”currencyCode”>ns:BasicAmountType</Amount>
(The element name Amount is an example; actual element names can vary depending on the
specific API.)
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 one of the values from the first column of Table 2.7, “PayPal-Supported
Currencies, Currency Codes, and Maximum Transaction Amounts” on page 31. Some APIs
support only a subset of these currencies.

API Overview By Business Function and Service Endpoint

The PayPal Web Services API consists of individual APIs for specific business uses, and the
individual APIs are grouped into two service endpoints.

TABLE 2.8 API Overview by Business Function and Service Endpoint

Business
Function SOAP Request/Response Production (Live) Endpoint Test (Sandbox) Endpoint:
Authorization & DoCaptureRequest api-aa.paypal.com/2.0/ api-aa.sandbox.paypal.com/2.0/
Capture API DoCaptureResponse api-aa-3t.paypal.com/2.0/
DoAuthorizationRequest
DoAuthorizationResponse
DoVoidRequest
DoVoidResponse
DoReauthorizationRequest
DoReauthorizationRespons
e
Direct Payments DoDirectPaymentRequest api-aa.paypal.com/2.0/
API DoDirectPaymentResponse api-aa-3t.paypal.com/2.0/

Express Checkout SetExpressCheckoutReques api-aa.paypal.com/2.0/ api-aa.sandbox.paypal.com/2.0/

API t api-aa-3t.paypal.com/2.0/
SetExpressCheckoutRespon
se
GetExpressCheckoutDetail
sRequest
GetExpressCheckoutDetail
sResponse
DoExpressCheckoutPayment
Request
DoExpressCheckoutPayment
Response

32 July 2006 Web Services API Reference

 PayPal Web Services API Architecture
PayPal Web Services API Definitions

TABLE 2.8 API Overview by Business Function and Service Endpoint

Business
Function SOAP Request/Response Production (Live) Endpoint Test (Sandbox) Endpoint:
GetTransaction GetTransactionDetailsReq api.paypal.com/2.0/ api.sandbox.paypal.com/2.0/
Details API uest api-3t.paypal.com/2.0/
GetTransactionDetailsRes
ponse
MassPay API MassPayRequest api.paypal.com/2.0/ api.sandbox.paypal.com/2.0/
MassPayResponse api-3t.paypal.com/2.0/
Refund RefundTransactionRequest api.paypal.com/2.0/ api.sandbox.paypal.com/2.0/
Transaction API RefundTransactionRespons api-3t.paypal.com/2.0/
e
Transaction TransactionSearchRequest api.paypal.com/2.0/ api.sandbox.paypal.com/2.0/
Search API TransactionSearchRespons api-3t.paypal.com/2.0/
e

APIs to Exchange Funds or Display Information

All PayPal Web Services APIs deal with business transactions. However, the APIs can be
further categorized as follows:
z APIs that result in an exchange of funds:
– Authorization & Capture
– Direct Payment
– Express Checkout
– MassPay
– RefundTransaction
z APIs that provide information about business transactions:
– GetTransactionDetails
– TransactionSearch

Instant Payment Notification and the APIs

Use of a PayPal Web Services API that results in an exchange of funds triggers the sending of
an Instant Payment Notification email to the recipient of the funds. The APIs that send Instant
Payment Notification email messages are as follows:
z MassPay
z RefundTransaction
For more information about Instant Payment Notification, see the PayPal Order Management
Integration Guide.

Web Services API Reference July 2006 33

 PayPal Web Services API Architecture
PayPal Web Services API Definitions

34 July 2006 Web Services API Reference

 3 Core eBL Request/Response
Structures

The PayPal Web Services API is built on core structures from the eBL schema that define
required elements in all SOAP requests and responses:
z AbstractRequestType
z AbstractResponseType

Diagram of core eBL Types

The following diagram represents the composition of the AbstractRequestType and
AbstractResponseType elements.

FIGURE 3.1 Core eBL Types

Web Services API Reference July 2006 35

 Core eBL Request/Response Structures
AbstractRequestType

A b s t r a c t R e q u e s t Ty p e
AbstractRequestType is the base type definition of all PayPal Web Services SOAP
requests.

IMPO RTANT: You must set the value of the Version element for all requests to any PayPal
Web Services API.

Fields

TABLE 3.1 AbstractRequestType Fields

Element Description Data Type Allowable Values Required?

Version A string representing the version of the request payload xs:string 2.0 Yes
schema

AbstractResponseType
AbstractResponseType is the base type definition of all PayPal Web Services SOAP
responses.

Fields
For error codes and messages and their meanings, see Appendix , “Error Codes and Messages
for All PayPal APIs.”

TABLE 3.2 AbstractResponseType Fields

Element Description Data Type Possible Values

Timestamp The date and time (UTC/GMT) the response was xs:dateTime Transaction-specific
generated by the PayPal Web Services service as a result
of processing a request

36 July 2006 Web Services API Reference

 Core eBL Request/Response Structures
AbstractResponseType

TABLE 3.2 AbstractResponseType Fields

Element Description Data Type Possible Values

Ack A token representing the application-level xs:token Success

acknowledgement code. Contains one of the following Failure
enumerated values: SuccessWithWarning
Success: Request processing succeeded FailureWithWarning
CustomCode
Failure: Request processing failed
SuccessWithWarning: Request processing completed
successfully but with some warning information that
could be useful for the requesting application to process or
record.
FailureWithWarning: Request processing failed with
some error and warning information that the requesting
application should process to determine causes of failure.
CustomCode: Reserved for internal or future use.

CorrelationID A string that identifies the exact API request that xs:string Transaction-specific
produced this response
Character length: 41 characters maximum.
Errors Error code for debugging a response. ns:ErrorType Transaction-specific
ErrorCode: token defining the error code number xs:token
ShortMessage: string containing the error message xs:string
LongMessage: string describing the error message

Version A string representing the version of the response payload xs:string 1.0
schema
Build A string representing the specific software build that xs:string
processes the request and generates the response

Web Services API Reference July 2006 37

 Core eBL Request/Response Structures
AbstractResponseType

38 July 2006 Web Services API Reference

 4 Authorization & Capture API

The Authorization & Capture API consists of individual requests and responses, as shown
below.

TABLE 4.1 Authorization & Capture API Names, Purposes, and Types of Authorization

Used With Type

API Purpose of Authorization

1. DoCapture Settle an order or previously authorized transaction Order and Basic

and obtain payment for either the complete amount
or any portion of it.

2. DoAuthorization Authorize an order that can be fulfilled over 29 Order only

days.

3. DoVoid Void an original authorization or order Order and Basic

4. DoReauthorization Reauthorize a previously authorized transaction Basic only

Funds Availability
Both DoAuthorization and DoReauthorization check the availability of a PayPal member’s
funds to obtain another honor period or to make a payment higher than you originally
authorized, up to 115% of the originally authorized amount (not to exceed an increase of $75
USD).

Web Services API Reference July 2006 39

 Authorization & Capture API
DoCapture

DoCapture
DoCaptureRequest is your request to completely or partially settle an order, an
authorization, or reauthorization.
N O T E : DoCaptureRequest is for use with both basic and order authorizations.

Diagram of DoCapture Types

The following diagram represents the composition of the DoCaptureRequestType and
DoCaptureResponseType elements. Elements required in the request are marked with an
asterisk.

FIGURE 4.1 DoCapture Types

40 July 2006 Web Services API Reference

 Authorization & Capture API
DoCapture

DoCaptureRequest
Request to capture funds from a PayPal member’s account.
Fields

TABLE 4.2 DoCaptureRequest Fields

Element Description Data Type Allowable Values Required?

Authorization The authorization identification number of the xs:string See description. Yes
ID payment you want to capture. This can be an order
number, an order authorization number, or a
rauthorization number.
Character length and limits: 19 single-byte
characters maximum
Amount Amount to capture. ebl:BasicAmount See description. Yes
Type
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
CompleteType Indicates if this capture is the last capture you intend ebl:Complete Default: Yes
to make. The default is Complete. CodeType Complete
N O T E : If CompleteType is Complete, any remaining NotComplete
amount of the original reauthorized
transaction is automatically voided.
Character length and limits: 12 single-byte
alphanumeric characters
InvoiceID Your invoice number or other identification xs:string See description. No
number.
N O T E : The InvoiceID value is recorded only if the
authorization you are capturing is an order
authorization, not a basic authorization.
Character length and limits: 127 single-byte
alphanumeric characters
Note An informational note about this settlement that is xs:string See description. No
displayed to the payer in email and in his transaction
history.
Character length and limits: 255 single-byte
characters

Web Services API Reference July 2006 41

 Authorization & Capture API
DoCapture

DoCaptureResponse
Response to DoCaptureRequest.
Fields

TABLE 4.3 DoCaptureResponse Fields

Element Description Data Type Possible Values

Authorization The authorization identification number you xs:string See description.

ID specified in the request.
Character length and limits: 19 single-byte
characters maximum
PaymentInfo Information about the payment. ebl:PaymentInfo See Table 4.4 on
Type page 42.

TABLE 4.4 Response: PaymentInfoType Elements

Element Description Data Type Possible Values

TransactionID Unique transaction ID of the payment. xs:string Transaction-

Character length and limitations: 17 single-byte specific
characters
Transaction The type of transaction ns:Payment cart
express-checkout
Type Character length and limitations: 15 single-byte TransactionCode
characters Type

PaymentType Indicates whether the payment is instant or delayed. ebl:PaymentCode none

Character length and limitations: Seven single-byte Type echeck
characters xs:string instant

PaymentDate Time/date stamp of payment xs:dateTime Transaction-

specific
GrossAmount The final amount charged, including any shipping ebl:BasicAmountTyp Transaction-
and taxes form your Merchant Profile. e specific

FeeAmount PayPal fee amount charged for the transaction ebl:BasicAmountTyp Transaction-
e specific

SettleAmount Amount deposited in your PayPal account after a ebl:BasicAmountTyp Transaction-

currency conversion. e specific

42 July 2006 Web Services API Reference

 Authorization & Capture API
DoCapture

TABLE 4.4 Response: PaymentInfoType Elements

Element Description Data Type Possible Values

TaxAmount Tax charged on the transaction ebl:BasicAmount Transaction-

Type specific
xs:string

ExchangeRate Exchange rate if a currency conversion occurred. xs:string Transaction-

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

Web Services API Reference July 2006 43

 Authorization & Capture API
DoCapture

TABLE 4.4 Response: PaymentInfoType Elements

Element Description Data Type Possible Values

PendingReason N O T E : PendingReason is returned in the ebl:PendingStatus none

response only if PaymentStatus is CodeType address
xs:token echeck
Pending. intl
The reason the payment is pending: multi-currency
verify
none: No pending reason
other
address: The payment is pending because your
customer did not include a confirmed shipping
address and your Payment Receiving Preferences is
set such that you want to manually accept or deny
each of these payments. To change your preference,
go to the Preferences section of your Profile.
echeck: The payment is pending because it was
made by an eCheck that has not yet cleared.
intl: The payment is pending because you hold a
non-U.S. account and do not have a withdrawal
mechanism. You must manually accept or deny this
payment from your Account Overview.
multi-currency: You do not have a balance in the
currency sent, and you do not have your Payment
Receiving Preferences set to automatically convert
and accept this payment. You must manually accept
or deny this payment.
verify: The payment is pending because you are not
yet verified. You must verify your account before
you can accept this payment.
other: The payment is pending for a reason other
than those listed above. For more information,
contact PayPal Customer Service.

44 July 2006 Web Services API Reference

 Authorization & Capture API
DoAuthorization

DoAuthorization
DoAuthorizationRequest is your request to authorize a customer order that can be
fulfilled within 29 days. You use DoAuthorizationRequest when you are ready to ship
goods to your customer. After you ship, you can capture funds with DoCapture.
N O T E : DoAuthorizationRequest is for use only with order authorizations, not basic
authorizations.
To use DoAuthorization you must have previously created a customer order. You can
create an order in several ways:
z With the DoExpressCheckoutPaymentRequest or DoDirectPaymentRequest
PaymentAction element set to Order.
z With a shopping cart or PayPal Website Payments transaction with the paymentaction
HTML variable set to order.

Diagram of DoAuthorization Types

The following diagram represents the composition of the DoAuthorizationRequestType
and DoAuthorizationResponseType elements. Elements required in the request are
marked with an asterisk.

FIGURE 4.2 DoAuthorization Types

Web Services API Reference July 2006 45

 Authorization & Capture API
DoAuthorization

DoAuthorizationRequest
Request to authorize all or part of a customer order amount.
Fields

TABLE 4.5 DoAuthorizationRequest Fields

Element Description Data Type Allowable Values Required?

TransactionID The value of the order’s transaction identification xs:string See description. Yes
number returned by a PayPal product.
Character length and limits: 19 single-byte
characters maximum
Amount Amount to authorize. ebl:BasicAmount See description. Yes
Type
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
TransactionEnt Type of transaction to authorize. The only allowable ebl:Transaction Order No
ity value is Order, which means that the transaction EntityType
represents a customer order that can be fulfilled over
29 days.

DoAuthorizationResponse
Response to DoAuthorizationRequest.
Fields

TABLE 4.6 DoAuthorizationResponse Fields

Element Description Data Type Possible Values

TransactionID An authorization identification number. xs:string See description.

Character length and limits: 17 single-byte
characters
Amount The amount you specified in the request. ebl:BasicAmount See description.
Type

46 July 2006 Web Services API Reference

 Authorization & Capture API
DoVoid

D o Vo i d
DoVoidRequest voids an order or an authorization.

IMPO RTANT: The AuthorizationID value on DoVoidRequest must be the original

authorization identification number, not the value of AuthorizationID
returned by DoReauthorizationResponse.
By definition, when the authorization period expires, the authorization or reauthorization of a
transaction is implicitly voided.
N O T E : DoVoidRequest is for use with both basic and order authorizations.

Diagram of DoVoid Types

The following diagram represents the composition of the DoVoidRequestType and
DoVoidResponseType elements. Elements required in the request are marked with an
asterisk.

FIGURE 4.3 DoVoid Types

Web Services API Reference July 2006 47

 Authorization & Capture API
DoVoid

DoVoidRequest
Request to void a prior authorization.
Fields

TABLE 4.7 DoVoidRequest Fields

Element Description Data Type Allowable Values Required?

AuthorizationI The value of the original authorization xs:string See description. Yes
D identification number returned by a PayPal product.
I M P O R T A N T : If you are voiding a transaction that
has been reauthorized, use the ID
from the original authorization, and
not the reauthorization.
Character length and limits: 19 single-byte
characters
Note An informational note about this settlement that is xs:string See description. No
displayed to the payer in email and in his transaction
history.
Character length and limits: 255 single-byte
characters

DoVoidResponse
Response to DoVoidRequest.
Fields

TABLE 4.8 DoVoidResponse Fields

Element Description Data Type Possible Values

Authorization The authorization identification number you xs:string See description.

ID specified in the request.
Character length and limits: 19 single-byte
characters

48 July 2006 Web Services API Reference

 Authorization & Capture API
DoReauthorization

DoReauthorization
To use DoReauthorization you must have previously authorized a transaction. You can
authorize a transaction in several ways:
– From the Merchant Services tab of your PayPal merchant account.
– With the DoExpressCheckoutPaymentRequest PaymentAction element set to
Authorization.
– With a shopping cart transaction (such as one that uses PayPal Website Payments) with
the paymentaction HTML variable set to authorization.
You can invoke DoReauthorizationRequest as many times as necessary to obtain one
successful reauthorization. When DoReauthorizationResponse returns success, the
settlement period restarts, you can capture funds, but you can no longer reauthorize.
N O T E : DoReauthorizationRequest is for use only with basic authorizations, not order
authorizations.

Diagram of DoReauthorization Types

The following diagram represents the composition of the
DoReauthorizationRequestType and DoReauthorizationResponseType elements.
Elements required in the request are marked with an asterisk.

FIGURE 4.4 DoReauthorization Types

Web Services API Reference July 2006 49

 Authorization & Capture API
DoReauthorization

DoReauthorizationRequest
Request to use Authorization & Capture to reauthorize a transaction.
Fields

TABLE 4.9 DoReauthorizationRequest Fields

Element Description Data Type Allowable Values Required?

Authorization The value of a previously authorized transaction xs:string Any previously Yes
ID identification number returned by a PayPal product. authorized PayPal
N O T E : You can obtain a buyer’s transaction transaction
number from the TransactionID identification
element of the PayerInfo structure number.
returned by
GetTransactionDetailsRespons
e.
Character length and limits: 19 single-byte
characters maximum
Amount Amount to reauthorize. cc:BasicAmount See description. Yes
Type
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).

DoReauthorizationResponse
Response to DoReauthorizationRequest.
Fields

TABLE 4.10 DoReauthorizationResponse Fields

Element Description Data Type Possible Values

Authorization A new authorization identification number. xs:string See description.
ID Character length and limits: 19 single-byte
characters

50 July 2006 Web Services API Reference

 5 Direct Payment API

With the Direct Payment API, you can obtain payment through PayPal directly from a buyer’s
credit card without the buyer logging into PayPal.

Diagram of DoDirectPayment Types

The following diagram represents the composition of the DoDirectPaymentRequestType
and DoDirectPaymentResponseType elements. Elements required in the request are
indicated with an asterisk.

FIGURE 5.1 DoDirectPayment Types

Web Services API Reference July 2006 51

 Direct Payment API
DoDirectPaymentRequest

DoDirectPaymentRequest
Request to use PayPal Direct Payment to obtain payment.
You must include the PaymentAction element in DoDirectPaymentRequest. Allowable
values for the PaymentAction element are Sale or Authorization:
z Set PaymentAction to Sale if the buyer’s order is final (for example, if the total cost of
the order is complete with shipping, handling and tax charges). This transaction is your
payment, and you expect no additional charge to the buyer.
z Set PaymentAction to Authorization if the total cost of the order at point of sale is
not complete for some reason (such as unknown shipping charges) and you expect to
capture funds after checkout is complete. You can then use PayPal Authorization &
Capture to obtain payment.
In either case, besides the PaymentAction element, DoDirectPaymentRequest requires
additional elements, such as the amount of the transaction, IP address of the buyer’s browser,
credit card number, type, and expiration date, and information about both the payer and the
payment.

Fields

TABLE 5.1 DoDirectPaymentRequest Fields

Allowable Required
Element Description Data Type Values ?
PaymentAction How you want to obtain payment: ebl:PaymentAction Default: The No
z Authorization indicates that this payment is a CodeType transaction
basic authorization subject to settlement with xs:token resulting from
PayPal Authorization & Capture. DoDirect
z Sale indicates that this is a final sale for which
Payment
you are requesting payment. Request will be a
final sale.
Character length and limit: Up to 13 single-byte
Authorization
alphabetic characters
Sale
N O T E : Order is
not allowed
for Direct
Payment.
CreditCard Information about the credit card to be charged. ebl:CreditCard See Table 5.2 on Yes
DetailsType page 53.
PaymentDetails Information about the payment ebl:PaymentDetails See Table 5.3 on Yes
Type page 54.

52 July 2006 Web Services API Reference

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.1 DoDirectPaymentRequest Fields

Allowable Required
Element Description Data Type Values ?
IPAddress IP address of the payer’s browser as recorded in its xs:string Any valid Internet Yes
HTTP request to your website. Protocol address.
N O T E : PayPal records this IP addresses as a means
to detect possible fraud.
Character length and limitations: 15 single-byte
characters, including periods, in dotted-quad
format: ???.???.???.???
Merchant Your customer session identification token. xs:string No
SessionId N O T E : PayPal records this optional session
identification token as an additional means
to detect possible fraud.
Character length and limitations: 64 single-byte
numeric characters

TABLE 5.2 CreditCardDetailsType Fields

Allowable Required
Element Description Data Type Values ?
CreditCardType Type of credit card. ebl:CreditCardType Visa Yes
Type MasterCard
Character length and limitations: Up to ten single-
byte alphabetic characters. Discover
Amex
I M P O R T A N T : If the credit card type is Switch or
Solo: Switch. See
important note in
1. The value of PaymentAction must be description.
Authorization.
Solo. See
2. The currencyId must be GBP. important note in
description.
CreditCard Credit card number xs:string See description. Yes
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 Credit card expiration month xs:int See description. Yes
Character length and limitations: Two single-byte
numeric characters, including leading zero.
ExpYear Credit card expiration year xs:int See description. Yes
Character length and limitations: Four single-byte
numeric characters.

Web Services API Reference July 2006 53

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.2 CreditCardDetailsType Fields

Allowable Required
Element Description Data Type Values ?
CVV2 Card Verification Value, version 2. xs:string See description. No.
N O T E : You must include a CVV2 value for those See note in
credit cards that use CVV2. description.
Required for Visa, MasterCard, American Express,
and Discover cards. Other card types might not
require a CVV2 value.
Character length for Visa, MasterCard, and
Discover: exactly three digits.
Character length for American Express: exactly
four digits.
I M P O R T A N T : To comply with credit card process-
ing regulations, once a transaction
has been completed, you must not
store the value of CVV2.
CardOwner Details about the owner of the credit card. ns:PayerInfoType See Table 5.7 on Yes
page 60.
StartMonth Month that Switch or Solo card was issued. xs:int See description. No.
Character length: two-digit, zero-filled if necessary.
StartYear Year that Switch or Solo card was issued. xs:int See description. No.
Character length: four digits.
IssueNumber Issue number of Switch or Solo card. xs:int See description. No.
Character length: two numeric digits maximum.

TABLE 5.3 Request: PaymentDetailsType Fields

Element Description Data Type Allowable Values Required?

OrderTotal Total of order, including shipping, handling, and ebl:BasicAmount See description. Yes
tax. Type
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ItemTotal Sum of cost of all items in this order. ebl:BasicAmount See description. No
Character length and limitations: 127 single-byte Type
characters

54 July 2006 Web Services API Reference

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.3 Request: PaymentDetailsType Fields

Element Description Data Type Allowable Values Required?

ShippingTotal Total shipping costs for this order. ebl:BasicAmount See description. No
N O T E : You must set the currencyID attribute to Type
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
HandlingTotal Total handling costs for this order. ebl:BasicAmount See description. No
N O T E : You must set the currencyID attribute to Type
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
TaxTotal Sum of tax for all items in this order. ebl:BasicAmount See description. No
N O T E : You must set the currencyID attribute to Type
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
Order Description of items the customer is purchasing. xs:string See description. No
Description Character length and limitations: 127 single-byte
alphanumeric characters
Custom A free-form field for your own use. xs:string See description. No
Character length and limitations: 256 single-byte
alphanumeric characters
InvoiceID Your own invoice or tracking number, as set by you xs:string See description. No
in the InvoiceID element of
SetExpressCheckoutRequest.
Character length and limitations: 127 single-byte
alphanumeric characters
ButtonSource An identification code for use by third-party xs:string See description. No
applications to identify transactions.
Character length and limitations: 32 single-byte
alphanumeric characters

Web Services API Reference July 2006 55

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.3 Request: PaymentDetailsType Fields

Element Description Data Type Allowable Values Required?

NotifyURL Your URL for receiving Instant Payment xs:string See description. No
Notification (IPN) about this transaction.
N O T E : If you do not specify NotifyURL 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 Address the order will be shipped to. ebl:AddressType See Table 5.4 on No
page 56.
PaymentDetails Details about each individual item included in the ebl:PaymentDetails See Table 5.6 on No
Item order ItemType page 60.

IMPO RTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.

TABLE 5.4 Request: ShipToAddress: AddressType Fields

Allowable Required
Element Descriptions Data Type Values ?
Name Person’s name associated with this address. xs:string See description. Yes
Character length and limitations: 32 single-byte
characters
Street1 First street address. xs:string See description. Yes
Character length and limitations: 100 single-byte
characters
Street2 Second street address. xs:string See description. No
Character length and limitations: 100 single-byte
characters
CityName Name of city. xs:string See description. Yes
Character length and limitations: 40 single-byte
characters
StateOr State or province. xs:string See Table 5.5 on No
Province page 57
Character length and limitations: 40 single-byte
characters
PostalCode U.S. ZIP code or other country-specific postal code. xs:string See description. No
Character length and limitations: 20 single-byte
characters

56 July 2006 Web Services API Reference

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.4 Request: ShipToAddress: AddressType Fields

Allowable Required
Element Descriptions Data Type Values ?
Country Country code. ebl:CountryCode See Appendix B. Yes
Character limit: Two single-byte characters Type
xs:string

TABLE 5.5 StateOrProvince: Abbreviations for Canada and U.S.

Canadian Province or U.S. State

Alberta AB

British Columbia BC

Manitoba MB

New Brunswick NB

Newfoundland and Labrador NF

Northwest_Territories NT

Nova_Scotia NS

Nunavut NU

Ontario ON

Prince_Edward_Island PE

Quebec QC

Saskatchewan SK

Yukon YK

Alabama AL

Alaska AK

American_Samoa AS

Arizona AZ

Arkansas AR

California CA

Colorado CO

Connecticut CT

Delaware DE

Web Services API Reference July 2006 57

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.5 StateOrProvince: Abbreviations for Canada and U.S.

Canadian Province or U.S. State

District Of Columbia DC

Federated States Of Micronesia FM

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

58 July 2006 Web Services API Reference

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.5 StateOrProvince: Abbreviations for Canada and U.S.

Canadian Province or U.S. State

North Carolina NC

North Dakota ND

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

Web Services API Reference July 2006 59

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.6 Request: PaymentDetailsItemType Fields

Allowable Required
Element Description Data Type Values ?
Name Item name. xs:string See description. No
Character length and limitations: 127 single-byte
characters
Amount Cost of item ebl:BasicAmount See description. No
N O T E : You must set the currencyID attribute to Type
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
Number Item number. xs:string See description. No
Character length and limitations: 127 single-byte
characters
Quantity Item quantity. xs:string See description. No
Character length and limitations: Any positive
integer
Tax Item sales tax. ebl:BasicAmount See description. No
Character length and limitations: any valid currency Type
amount; currency code is set the same as for
OrderTotal.

TABLE 5.7 CardOwner: PayerInfoType Fields

Allowable Required
Element Description DataType Values ?
Payer Email address of payer. ns:EmailAddress See description. No
Type
Character length and limitations: 127 single-byte
characters
FirstName Payer’s first name. ns:PersonName See description. Yes
Type
Character length and limitations: 25 single-byte
characters
LastName Payer’s last name. ns:PersonName See description. Yes
Type
Character length and limitations: 25 single-byte
characters

60 July 2006 Web Services API Reference

 Direct Payment API
DoDirectPaymentRequest

TABLE 5.7 CardOwner: PayerInfoType Fields

Allowable Required
Element Description DataType Values ?
Address Payer’s billing address information ns:AddressType See Table 5.8 on Yes
page 61.

TABLE 5.8 CardOwner: AddressType Fields

Allowable Required
Element Description DataType Values ?
Street1 First street address xs:string See description. Yes
Character length and limitations: 100 single-byte
characters
Street2 Second street address xs:string See description. No
Character length and limitations: 100 single-byte
characters
CityName Name of city xs:string See description. Yes
Character length and limitations: 40 single-byte
characters
StateOr State or province xs:string See description. Yes
Province
Character length and limitations: 40 single-byte
characters
Country Country code. ebl:CountryCode See Appendix 1. Yes
Type
Character length and limitations: Two single-byte
xs:string
characters.
PostalCode U.S. Zip code or other country-specific postal code xs:string See description. Yes
Character length and limitations: 20 single-byte
characters

Web Services API Reference July 2006 61

 Direct Payment API
DoDirectPaymentResponse

DoDirectPaymentResponse
Response to DoDirectPaymentRequest.
The Direct Payment API response contains the TransactionID element. In the case of a
final Sale, TransactionID is your record of the transaction processed with PayPal. In the
case of an Authorization, TransactionID is your key to capturing funds with PayPal
Authorization & Capture.
DoDirectPaymentResponse also returns the result of checking the buyer’s postal address
and credit card number (as submitted by you with DoDirectPaymentRequest) against the
U.S. banking industry standard Address Verification System (AVS) and Credit Card
Verification (CVV2) system.

Fields

TABLE 5.9 DoDirectPaymentResponse Fields

Element Description Data Type Possible Values

TransactionID Unique transaction ID of the payment. xs:string See description.
I M P O R T A N T : 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 The amount of the payment as specified by you on ebl:BasicAmount See description.
DoDirectPaymentRequest. Type

AVSCode Address Verification System response code. xs:string See Table 5.10,
Character limit: One single-byte alphanumeric “AVS Response
character Codes” on
page 63.
CVV2Code Result of the CVV2 check by PayPal. xs:string See Table 5.11,
“CVV2 Response
Codes” on
page 63.

62 July 2006 Web Services API Reference

 Direct Payment API
DoDirectPaymentResponse

TABLE 5.10 AVS Response Codes

AVS
Code Meaning Matched Details

A Address Address only (no ZIP)

B International “A” Address only (no ZIP)

C International “N” None

D International “X” Address and Postal Code

E Not allowed for MOTO (Internet/Phone) Not applicable

transactions

F UK-specific “X” Address and Postal Code

G Global Unavailable Not applicable

I International Unavailable Not applicable

N No None

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 Error Not applicable

others

TABLE 5.11 CVV2 Response Codes

CVV2
Code Meaning Matched Details

M Match CVV2

N No match None

Web Services API Reference July 2006 63

 Direct Payment API
DoDirectPaymentResponse

TABLE 5.11 CVV2 Response Codes

CVV2
Code Meaning Matched Details

P Not Processed Not applicable

S Service not Supported Not applicable

U Unavailable Not applicable

X No response Not applicable

All Error Not applicable

others

64 July 2006 Web Services API Reference

 6 Express Checkout API

The Express Checkout API is the Website Payments Pro alternative to standard PayPal
shopping cart processing.

IMPO RTANT: For a full understanding of the complete details about how to use PayPal
Express Checkout, consult the PayPal Express Checkout Integration Guide.
The Express Checkout API consists of three distinct SOAP requests that you make at the three
integration points during a customer checkout:
1. SetExpressCheckout
2. GetExpressCheckoutDetails
3. DoExpressCheckoutPayment

IMPO RTANT: All currency amount fields in the three Express Checkout APIs require that
the currencyID attribute be set to one of the supported currency codes. For
any one particular buyer’s checkout session, do not mix currencies either in
any single SOAP request or across SOAP requests. For example, do not set
currencyID to USD in one request and then to GBP in a later request for
the same buyer.

Web Services API Reference July 2006 65

 Express Checkout API
SetExpressCheckout

SetExpressCheckout
SetExpressCheckout indicates to PayPal that you are using Express Checkout to obtain
payment from your customer.

Diagram of Set ExpressCheckout Types

The following diagram represents the composition of the
SetExpressCheckoutRequestType and SetExpressCheckoutResponseType
elements. Elements required in the request are indicated with an asterisk.

FIGURE 6.1 SetExpressCheckout Types

66 July 2006 Web Services API Reference

 Express Checkout API
SetExpressCheckout

SetExpressCheckoutRequest
Request to use PayPal Express Checkout to obtain payment.

IMPO RTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.
Fields

TABLE 6.1 SetExpressCheckoutRequest Fields

Allowable Required
Element Description Data Type Values ?
Token On your first invocation of ebl:Express See the description No
SetExpressCheckoutRequest, the value of CheckoutTokenType of “Token” on
this token is returned by page 72.
SetExpressCheckoutResponse.
I M P O R T A N T : Include this element and its value
only if you want to modify an
existing checkout session with
another invocation of
SetExpressCheckoutReque
st; for example, if you want the
customer to edit his shipping
address on PayPal.
Character length and limitations: 20 single-byte
characters
OrderTotal The total cost of the order to the customer. If cc:BasicAmount See description. Yes
shipping cost and tax charges are known, include Type
them in OrderTotal; if not, OrderTotal should be the
current sub-total of the order.
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.

Web Services API Reference July 2006 67

 Express Checkout API
SetExpressCheckout

TABLE 6.1 SetExpressCheckoutRequest Fields

Allowable Required
Element Description Data Type Values ?
MaxAmount The expected maximum total amount of the cc:BasicAmount See description. No
complete order, including shipping cost and tax Type
charges.
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
Order Description of items the customer is purchasing. xs:string See description. No
Description
Character length and limitations: 127 single-byte
alphanumeric characters
Custom A free-form field for your own use, such as a xs:string See description. No
tracking number or other value you want PayPal to
return on
GetExpressCheckoutDetailsResponse
and
DoExpressCheckoutPaymentResponse.
Character length and limitations: 256 single-byte
alphanumeric characters
InvoiceID Your own unique invoice or tracking number. xs:string See description. No
PayPal returns this value to you on
DoExpressCheckoutPaymentResponse.
Character length and limitations: 127 single-byte
alphanumeric characters
ReturnURL URL to which the customer’s browser is returned xs:string See description. Yes
after choosing to pay with PayPal.
N O T E : PayPal recommends that the value of
ReturnURL be the final review page on
which the customer confirms the order and
payment.
Character length and limitations: no limit.
CancelURL URL to which the customer is returned if he does xs:string See description. Yes
not approve the use of PayPal to pay you.
N O T E : PayPal recommends that the value of
CancelURL be the original page on which the
customer chose to pay with PayPal.
Character length and limitations: no limit

68 July 2006 Web Services API Reference

 Express Checkout API
SetExpressCheckout

TABLE 6.1 SetExpressCheckoutRequest Fields

Allowable Required
Element Description Data Type Values ?
Address Customer’s shipping address. ebl:AddressType See Table 6.2 on No
N O T E : If you include a shipping address and set page 71.
the AddressOverride element on the
request, PayPal returns this same address in
GetExpressCheckoutDetailsRes
ponse.
ReqConfirm The value 1 indicates that you require that the xs:string 0 No
Shipping customer’s shipping address on file with PayPal be 1
a confirmed address.
N O T E : Setting this element overrides the setting
you have specified in your Merchant
Account Profile.
Character length and limitations: One single-byte
numeric character.
NoShipping The value 1 indicates that on the PayPal pages, no xs:string 0 No
shipping address fields should be displayed 1
whatsoever.
Character length and limitations: Four single-byte
numeric character.
Address The value 1 indicates that the PayPal pages should xs:string 0 No
Override display the shipping address set by you in the 1
Address element on this
SetExpressCheckoutRequest, not the
shipping address on file with PayPal for this
customer.
N O T E : Displaying the PayPal street address on file
does not allow the customer to edit that
address.
Character length and limitations: Four single-byte
numeric character.
LocaleCode Locale of pages displayed by PayPal during Express xs:string AU or en_AU No
Checkout. DE or de_DE
Character length and limitations: Five single-byte FR or fr_FR
alphabetic characters, upper- or lowercase. GB or en_GB
IT or it_IT
JP or ja_JP
US or en_US

Web Services API Reference July 2006 69

 Express Checkout API
SetExpressCheckout

TABLE 6.1 SetExpressCheckoutRequest Fields

Allowable Required
Element Description Data Type Values ?
PageStyle Sets the Custom Payment Page Style for payment xs:string See description. No
pages associated with this button/link. PageStyle
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- A URL for the image you want to appear at the top xs:string See description. No
image 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
cpp-header- Sets the border color around the header of the xs:string See description. No
border-color 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- Sets the background color for the header of the xs:string See description. No
back-color payment page.
Character length and limitation: Six character
HTML hexadecimal color code in ASCII
cpp-payflow- Sets the background color for the payment page. xs:string See description. No
color
Character length and limitation: Six character
HTML hexadecimal color code in ASCII

70 July 2006 Web Services API Reference

 Express Checkout API
SetExpressCheckout

TABLE 6.1 SetExpressCheckoutRequest Fields

Allowable Required
Element Description Data Type Values ?
PaymentAction How you want to obtain payment: ebl:PaymentAction Default: The No
CodeType transaction
z Authorization indicates that this payment is a
xs:token
basic authorization subject to settlement with resulting from
PayPal Authorization & Capture. DoExpress
z Order indicates that this payment is is an order
Checkout
authorization subject to settlement with PayPal Payment
Authorization & Capture. Request will be a
final sale.
z Sale indicates that this is a final sale for which
Authorization
you are requesting payment.
Order
I M P O R T A N T : You cannot set PaymentAction to
Sale
Sale on
SetExpressCheckoutReque
st and then change PaymentAction
to Authorization on the final API
DoExpressCheckoutPaymen
tRequest.
Character length and limit: Up to 13 single-byte
alphabetic characters
BuyerEmail Email address of the buyer as entered during ebl:EmailAddress See description. No
checkout. PayPal uses this value to pre-fill the Type
PayPal membership sign-up portion of the PayPal
login page.
Character length and limit: 127 single-byte
alphanumeric characters

N O T E : TheAddressType elements are required only if you include the Address element in
the SOAP request.

IMPO RTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.

TABLE 6.2 Address (Shipping Address): AddressType Elements

Allowable
Element Descriptions Data Type Values Required?
Name Person’s name associated with this shipping xs:string See description. No
address.
Character length and limitations: 32 single-byte
characters

Web Services API Reference July 2006 71

 Express Checkout API
SetExpressCheckout

TABLE 6.2 Address (Shipping Address): AddressType Elements

Allowable
Element Descriptions Data Type Values Required?
Street1 First street address. xs:string See description. Yes
Character length and limitations: 100 single-byte
characters
Street2 Second street address. xs:string See description. No
Character length and limitations: 100 single-byte
characters
CityName Name of city. xs:string See description. Yes
Character length and limitations: 40 single-byte
characters
StateOr State or province xs:string See description. Yes
Province
Character length and limitations: 40 single-byte
characters
PostalCode U.S. Zip code or other country-specific postal code xs:string See description. Yes
Character length and limitations: 20 single-byte
characters
Country Country code. ebl:CountryCode See Appendix B. Yes
Character limit: Two single-byte characters. Type
xs:string

SetExpressCheckoutResponse
Response to SetExpressCheckoutRequest.
Fields

TABLE 6.3 SetExpressCheckoutResponse Fields

Element Description Data Type Value

Token A timestamped token by which you identify to xs:string See description.
PayPal that you are processing this payment with
Express Checkout.
N O T E : The token expires after three hours.
If you set Token in the
SetExpressCheckoutRequest, the value of
Token in the response is identical to the value in
the request.
Character length and limitations: 20 single-byte
characters

72 July 2006 Web Services API Reference

 Express Checkout API
GetExpressCheckoutDetails

G e t E x p r e s s C h e c k o u t D e ta i l s
GetExpressCheckoutDetails returns information about the customer, including name
and address on file with PayPal.

Diagram of GetExpressCheckoutDetails Types

The following diagram represents the composition of the
GetExpressCheckoutDetailsRequestType and
GetExpressCheckoutDetailsResponseType elements.
Elements required in the request are indicated with an asterisk.

FIGURE 6.2 GetExpressCheckout Types

Web Services API Reference July 2006 73

 Express Checkout API
GetExpressCheckoutDetails

GetExpressCheckoutDetailsRequest
Obtain details about a payment to be processed by PayPal Express Checkout.
Fields

TABLE 6.4 GetExpressCheckoutDetailsRequest Fields

Allowable Required
Element Description Data Type Values ?
Token A timestamped token, the value of which was xs:string An unexpired token Yes
returned by
SetExpressCheckoutResponse.
Character length and limitations: 20 single-byte
characters

GetExpressCheckoutDetailsResponse
Response to GetExpressCheckoutDetailsRequest.
Fields

TABLE 6.5 GetExpressCheckoutDetailsResponse Fields

Element Description Data Type Possible Values

Token The timestamped token value that was returned by xs:string See the description
SetExpressCheckoutResponse and passed of “Token” on
on page 72.
GetExpressCheckoutDetailsRequest.
Character length and limitations: 20 single-byte
characters
PayerInfo Information about the payer. ebl:PayerInfoType See Table 6.6 on
page 75.
Custom A free-form field for your own use, as set by you in xs:string See description.
the Custom element of
SetExpressCheckoutRequest.
Character length and limitations: 256 single-byte
alphanumeric characters
InvoiceID Your own invoice or tracking number, as set by you xs:string See description.
in the InvoiceID element of
SetExpressCheckoutRequest.
Character length and limitations: 127 single-byte
alphanumeric characters

74 July 2006 Web Services API Reference

 Express Checkout API
GetExpressCheckoutDetails

TABLE 6.5 GetExpressCheckoutDetailsResponse Fields

Element Description Data Type Possible Values

ContactPhone Payer’s contact telephone number. xs:string See description.
N O T E : 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)

N O T E : Empty
elements are returned if there is no representative data for the customer. For
example, if the customer does not represent a business (and therefore has no business
name on file with PayPal), the returned element has no value, like this:
<PayerBusiness/>.
NOTE:

TABLE 6.6 Response: PayerInfoType Elements

Element Description DataType Possible Values

Payer Email address of payer. ebl:EmailAddress See description.
Character length and limitations: 127 single-byte Type
characters
PayerID Unique PayPal customer account number. ebl:UserIDType See description.
Character length and limitations:17 single-byte
characters maximum.
PayerStatus Status of payer. ebl:PayPalUser verified
Character length and limitations: 10 single-byte StatusCodeType unverified
alphabetic characters.
PayerName First and last name of payer ebl:PersonNameType See Table 6.7 on
page 76.
PayerCountry Payer’s country of residence in the form of ISO ebl:CountryCode See Appendix B.
standard 3166 two-character country codes. Type
Character length and limitations: Two single-byte
characters
PayerBusiness Payer’s business name. xs:string See description.
Character length and limitations: 127 single-byte
characters
Address Payer's shipping address address information. xs:string See Table 6.8 on
page 76.

Web Services API Reference July 2006 75

 Express Checkout API
GetExpressCheckoutDetails

TABLE 6.7 Response: PayerName Elements

Element Description DataType Possible Values

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

TABLE 6.8 Response: AddressType Fields

Element Descriptions Data Type Possible Values

AddressStatus Status of street address on file with PayPal ebl:AddressStatus none
TypeCode Confirmed
Unconfirmed
Name Person’s name associated with this address. xs:string See description.
Character length and limitations: 32 single-byte
characters
Street1 First street address. xs:string See description.
Character length and limitations: 100 single-byte
characters

76 July 2006 Web Services API Reference

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.8 Response: AddressType Fields

Element Descriptions Data Type Possible Values

Street2 Second street address. xs:string See description.
Character length and limitations: 100 single-byte
characters
CityName Name of city. xs:string See description.
Character length and limitations: 40 single-byte
characters
StateOr State or province xs:string See description.
Province
Character length and limitations: 40 single-byte
characters
PostalCode U.S. Zip code or other country-specific postal code xs:string See description.
Character length and limitations: 20 single-byte
characters
Country Country code. ebl:CountryCode See Appendix B.
Character limit: Two single-byte characters. Type
xs:string

DoExpressCheckoutPayment
With DoExpressCheckoutPayment, you either obtain payment through Express Checkout for a
final sale or request authorization for later capture of payment.

Diagram of DoExpressCheckoutPayment Types

The following diagram represents the composition of the
DoExpressCheckoutPaymentRequestType and
DoExpressCheckoutPaymentResponseType elements. Elements required in the request
are indicated with an asterisk.

Web Services API Reference July 2006 77

 Express Checkout API
DoExpressCheckoutPayment

FIGURE 6.3 DoExpressCheckoutPayment Types

78 July 2006 Web Services API Reference

 Express Checkout API
DoExpressCheckoutPayment

DoExpressCheckoutPaymentRequest
Request to obtain payment with PayPal Express Checkout.

IMPO RTANT: PayPal requires that a merchant using Express Checkout display to the
customer the same exact amount that the merchant sends to PayPal in the
OrderTotal element with the DoExpressCheckoutPaymentRequest
API.
Fields

TABLE 6.9 DoExpressCheckoutPaymentRequest Fields

Allowable Required
Element Description Data Type Values ?
Token The timestamped token value that was returned by xs:string See description. Yes
SetExpressCheckoutResponse and passed
on
GetExpressCheckoutDetailsRequest.
Character length and limitations: 20 single-byte
characters
PaymentAction How you want to obtain payment: ebl:PaymentAction Default: The No
z Authorization indicates that this payment is a CodeType transaction
basic authorization subject to settlement with xs:token resulting from
PayPal Authorization & Capture. DoExpress
z Order indicates that this payment is is an order
Checkout
authorization subject to settlement with PayPal Payment
Authorization & Capture. Request will be a
final sale.
z Sale indicates that this is a final sale for which
Authorization
you are requesting payment.
Order
I M P O R T A N T : You cannot set PaymentAction to
Sale
Sale on
SetExpressCheckoutReque
st and then change PaymentAction
to Authorization on the final PayPal
Express Checkout API
DoExpressCheckoutPaymen
tRequest.
Character length and limit: Up to 13 single-byte
alphabetic characters
PayerID Encrypted PayPal customer account identification ebl:UserIDType See description. Yes
number as returned by
GetExpressCheckoutDetailsResponse.
Character length and limitations: 127 single-byte
characters.

Web Services API Reference July 2006 79

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.9 DoExpressCheckoutPaymentRequest Fields

Allowable Required
Element Description Data Type Values ?
PaymentDetails Information about the payment ebl:PaymentDetails See Table 6.10 on Yes
Type page 80.

TABLE 6.10 Request: PaymentDetailsType Fields

Allowable Required
Element Description Data Type Values ?
OrderTotal Total of order, including shipping, handling, and ebl:BasicAmount See description. Yes
tax. Type
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ItemTotal Sum of cost of all items in this order. ebl:BasicAmount See description. No
Limitations: Must not exceed $10,000 USD in any Type
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
Shipping Total shipping costs for this order. ebl:BasicAmount See description. No
Total Type
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.

80 July 2006 Web Services API Reference

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.10 Request: PaymentDetailsType Fields

Allowable Required
Element Description Data Type Values ?
Handling Total handling costs for this order. ebl:BasicAmount See description. No
Total Type
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
TaxTotal Sum of tax for all items in this order. ebl:BasicAmount See description. No
N O T E : You must set the currencyID attribute to Type
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
Order Description of items the customer is purchasing. xs:string See description. No
Description
Character length and limitations: 127 single-byte
alphanumeric characters
Custom A free-form field for your own use. xs:string See description. No
Character length and limitations: 256 single-byte
alphanumeric characters
InvoiceID Your own invoice or tracking number. xs:string See description. No
Character length and limitations: 127 single-byte
alphanumeric characters
ButtonSource An identification code for use by third-party xs:string See description. No
applications to identify transactions.
Character length and limitations: 32 single-byte
alphanumeric characters
NotifyURL Your URL for receiving Instant Payment xs:string See description. No
Notification (IPN) about this transaction.
N O T E : If you do not specify NotifyURL 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

Web Services API Reference July 2006 81

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.10 Request: PaymentDetailsType Fields

Allowable Required
Element Description Data Type Values ?
ShipToAddress Address the order will be shipped to. ebl:AddressType See Table 6.11 on No
page 82.
PaymentDetails Details about each individual item included in the ebl:PaymentDetails See Table 6.12 on No
Item order ItemType page 83.

N O T E : TheAddressType elements are required only if you include the Address element in
the SOAP request.

IMPO RTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.

TABLE 6.11 Request: ShipToAddress: AddressType Fields

Allowable Required
Element Descriptions Data Type Values ?
Name Person’s name associated with this address. xs:string See description. Yes
Character length and limitations: 32 single-byte
characters
Street1 First street address. xs:string See description. Yes
Character length and limitations: 100 single-byte
characters
Street2 Second street address. xs:string See description. No
Character length and limitations: 100 single-byte
characters
CityName Name of city. xs:string See description. Yes
Character length and limitations: 40 single-byte
characters
StateOr State or province. xs:string See description. No
Province
Character length and limitations: 40 single-byte
characters
PostalCode U.S. ZIP code or other country-specific postal code. xs:string See description. No
Character length and limitations: 20 single-byte
characters
Country Country code. ebl:CountryCode See Appendix B. Yes
Character limit: Two single-byte characters Type
xs:string

82 July 2006 Web Services API Reference

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.12 Request: PaymentDetailsItemType Fields

Allowable Required
Element Description Data Type Values ?
Name Item name. xs:string See description. No
Character length and limitations: 127 single-byte
characters
Amount Cost of item ebl:BasicAmount See description. No
N O T E : You must set the currencyID attribute to Type
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
Number Item number. xs:string See description. No
Character length and limitations: 127 single-byte
characters
Quantity Item quantity. xs:string See description. No
Character length and limitations: Any positive
integer
Tax Item sales tax. ebl:BasicAmount See description. No
Currency code must be set the same as for Type
OrderTotal.
N O T E : You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
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 thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.

DoExpressCheckoutPaymentResponse
Response to DoExpressCheckoutPaymentRequest.

Web Services API Reference July 2006 83

 Express Checkout API
DoExpressCheckoutPayment

Fields

TABLE 6.13 DoExpressCheckoutPaymentResponse Fields

Element Description Data Type Possible Values

Token The timestamped token value that was returned by xs:string See the description
SetExpressCheckoutResponse and passed of “Token” on
on page 72.
GetExpressCheckoutDetailsRequest.
Character length and limitations:20 single-byte
characters
PaymentInfo Information about the payment. ebl:PaymentInfo See Table 6.14 on
Type page 84.

TABLE 6.14 Response: PaymentInfoType Elements

Element Description Data Type Possible Values

TransactionID Unique transaction ID of the payment. xs:string Transaction-
I M P O R T A N T : If the PaymentAction of the request specific
was Authorization or Order, the
value of TransactionID is your
AuthorizationID for use with the
Authorization & Capture APIs.
Character length and limitations:19 single-byte
characters
Transaction The type of transaction ns:Payment cart
express-checkout
Type Character length and limitations:15 single-byte TransactionCode
characters Type

PaymentType Indicates whether the payment is instant or delayed. ebl:PaymentCode none

Character length and limitations: Seven single-byte Type echeck
characters xs:string instant
PaymentDate Time/date stamp of payment xs:dateTime Transaction-
specific
GrossAmount The final amount charged, including any shipping ebl:BasicAmount Transaction-
and taxes from your Merchant Profile. Type specific
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 thousands separator is a comma
(,). Equivalent to nine characters maximum for
USD.

84 July 2006 Web Services API Reference

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.14 Response: PaymentInfoType Elements

Element Description Data Type Possible Values

FeeAmount PayPal fee amount charged for the transaction ebl:BasicAmount Transaction-
Character length and limitations: Does not Type specific
exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency,
decimal separator is a period (.), and the
thousands separator is a comma (,). Equivalent
to nine characters maximum for USD.
SettleAmount Amount deposited in your PayPal account after a ebl:BasicAmount Transaction-
currency conversion. Type specific

TaxAmount Tax charged on the transaction. ebl:BasicAmount Transaction-

Character length and limitations: Does not Type specific
exceed $10,000 USD in any currency. No xs:string
currency symbol. Regardless of currency,
decimal separator is a period (.), and the
thousands separator is a comma (,). Equivalent
to nine characters maximum for USD.
ExchangeRate Exchange rate if a currency conversion occurred. xs:string Transaction-
Relevant only if your are billing in their non- specific
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 Status of the payment: ebl:PaymentStatus Completed
Pending
Completed: The payment has been completed, and CodeType
the funds have been added successfully to your xs:token
account balance.
Pending: The payment is pending. See the
PendingReason element for more information.

Web Services API Reference July 2006 85

 Express Checkout API
DoExpressCheckoutPayment

TABLE 6.14 Response: PaymentInfoType Elements

Element Description Data Type Possible Values

PendingReason The reason the payment is pending: ebl:PendingStatus none
CodeType address
none: No pending reason
xs:token echeck
address: The payment is pending because your intl
customer did not include a confirmed shipping multi-currency
address and your Payment Receiving Preferences is verify
other
set such that you want to manually accept or deny
each of these payments. To change your preference,
go to the Preferences section of your Profile.
echeck: The payment is pending because it was
made by an eCheck that has not yet cleared.
intl: The payment is pending because you hold a
non-U.S. account and do not have a withdrawal
mechanism. You must manually accept or deny this
payment from your Account Overview.
multi-currency: You do not have a balance in the
currency sent, and you do not have your Payment
Receiving Preferences set to automatically convert
and accept this payment. You must manually accept
or deny this payment.
verify: The payment is pending because you are not
yet verified. You must verify your account before
you can accept this payment.
other: The payment is pending for a reason other
than those listed above. For more information,
contact PayPal customer service.

86 July 2006 Web Services API Reference

 7 GetTransactionDetails API

The GetTransactionDetails API retrieves information about a single transaction.

Diagram of GetTransactionDetails Types

The following diagram represents the composition of the
GetTransactionDetailsRequestType and GetTransactionDetailsResponseType
elements.

FIGURE 7.1 GetTransactionDetails Types

Web Services API Reference July 2006 87

 GetTransactionDetails API
GetTransactionDetailsRequest

G e t Tr a n s a c t i o n D e ta i l s R e q u e s t
Get details about a transaction.

Fields

TABLE 7.1 GetTransactionDetailsRequest Fields

Element Description Data Type Possible Values Required?

TransactionID Unique identifier of a transaction. xs:string Transaction-specific Yes

N O T E : The details for some kinds of transactions
cannot be retrieved with
GetTransactionDetailsRequest.
You cannot obtain details of bank transfer
withdrawals, for example.
Character length and limitations: 17 single-byte
alphanumeric characters

GetTransactionDetailsResponse
Response to GetTransactionDetailsRequest.
N O T E : Because
a field is defined in the formal structure of
GetTransactionDetailsResponse 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.

Fields
For error codes and messages and their meanings, see Appendix , “Error Codes and Messages
for All PayPal APIs.”

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

Payment ReceiverInfo Wrapper structure

Transaction PayerInfo
Details PaymentInfo
PaymentItem
Info

88 July 2006 Web Services API Reference

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

ReceiverInfo Includes elements described below ebl:ReceiverInfo

Type

Business Email address or account ID of the payment recipient (the xs:string

seller). Equivalent to Receiver if payment is sent to
primary account.
Character length and limitations: 127 single-byte
alphanumeric characters
Receiver Primary email address of the payment recipient (the xs:string
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 Unique account ID of the payment recipient (the seller). xs:string
This value is the same as the value of the recipient's
referral ID.
PayerInfo Includes elements described below ebl:PayerInfo
Type

Payer Email address of payer ns:EmailAddress

Character length and limitations: 127 single-byte Type
characters
PayerID Unique customer ID ebl:UserIDType
Character length and limitations: 17 single-byte
characters
PayerStatus Status of payer’s email address ebl:PayPalUser
StatusCodeType
Verified
Unverified

PayerName Salutation Payer’s salutation xs:string

(included in Character length and limitations: 20 single-byte
PayerInfo) characters

FirstName Payer’s first name ebl:NameType

Character length and limitations: 25 single-byte
characters
MiddleName Payer’s middle name ebl:NameType
Character length and limitations: 25 single-byte
characters
LastName Payer’s last name ebl:NameType
Character length and limitations: 25 single-byte
characters

Web Services API Reference July 2006 89

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

Suffix Payer’s suffix ebl:SuffixType

Character length and limitations: 12 single-byte
characters
PayerCountry Payment sender’s country of residence using standard ebl:CountryCode
two-character ISO 3166 country codes. See Appendix . Type
Character length and limitations: Two single-byte
characters
PayerBusiness Payer’s business name. xs:string
Character length and limitations: 127 single-byte
characters
Address Includes the following elements. ebl:AddressType
(included in
PayerInfo)

AddressOwner eBay company that maintains this address ebl:AddressOwner

TypeCode
xs:token
eBay
PayPal

AddressStatus Status of the address on file with PayPal ebl:AddressStatus

CodeType
xs:token
None
Confirmed
Unconfirmed

Name Person’s name associated with this address. xs:string

Character length and limitations: 32 single-byte
alphanumeric characters
Street1 First street address. xs:string
Character length and limitations: 300 single-byte
alphanumeric characters
Street2 Second street address. xs:string
Character length and limitations: 300 single-byte
alphanumeric characters
CityName Name of city. xs:string
Character length and limitations: 120 single-byte
alphanumeric characters
StateOrProvince State or province. xs:string
Character length and limitations: 120 single-byte
alphanumeric characters
Country Character limit: Two single-byte characters. ns:Country
See Appendix .

90 July 2006 Web Services API Reference

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

CountryName Expanded name of country. xs:string

Character length and limitations: 64 single-byte
alphanumeric characters
Phone Phone number associated with this address xs:string

PostalCode Postal code xs:string

PaymentInfo Includes the following elements. ebl:PaymentInfo

Type

ParentTransaction Original transaction to which this transaction is related. xs:string

ID This field is populated for the following transaction types:
z Reversal
z Capture of an authorized transaction.
z Reauthorization of a transaction.
z Capture of an order. The value of
ParentTransactionID is the original OrderID.
z Authorization of an order. The value of
ParentTransactionID is the original OrderID.
z Capture of an order authorization.
z Void of an order. The value of
ParentTransactionID is the original OrderID.
Character length and limitations: 19 single-byte
characters
TransactionID PayPal transaction identification number xs:string
Character length and limitations: 19 single-byte
characters
ReceiptID Receipt ID xs:string
Character length and limitations: 16 digits in xxxx-
xxxx-xxxx-xxxx format
TransactionType The type of transaction ebl:Payment
cart: Transaction created by customer via the PayPal TransactionCode
Shopping Cart feature. Type
send-money: Transaction created by customer from the xs:token
Send Money tab on the PayPal website. cart
web-accept: Transaction created by customer via Buy send_money
Now, Donation, or Auction Smart Logos. web-accept
subscr-*: Transaction created by customer via subscr-failed
Subscription. eot means “end of subscription term.” subscr-
cancelsubscr-
merch-pmt: preapproved payment. paymentsubscr-
mass-pay: Transaction created via MassPay. signupsubscr-
virtual-terminal: Transaction created via eotsubscr-
merchant virtual terminal. modifymercht-
pmtmass-
payvirtual-
terminal

Web Services API Reference July 2006 91

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

PaymentType The type of payment ebl:PaymentCode

Type
xs:string
none
echeck
instant

PaymentDate Date and time of payment xs:dateTime

GrossAmount Full amount of the customer’s payment, before xs:string

transaction fee is subtracted
FeeAmount Transaction fee associated with the payment xs:string

SettleAmount Amount deposited into the account’s primary balance ebl:BasicAmount

after a currency conversion from automatic conversion Type
through your Payment Receiving Preferences or manual
conversion through manually accepting a payment. This
amount is calculated after fees and taxes have been
assessed.
TaxAmount Amount of tax for transaction xs:string

ExchangeRate Exchange rate for transaction xs:string

92 July 2006 Web Services API Reference

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

PaymentStatus The status of the payment: ebl:PaymentStatus

None: No status CodeType
Canceled-Reversal: A reversal has been canceled. For xs:token
example, you won a dispute with the customer, and the None
funds for the transaction that was reversed have been Canceled-Reversal
returned to you. Completed
Completed: The payment has been completed, and the Denied
funds have been added successfully to your account Expired
balance. Failed
Denied: You denied the payment. This happens only if the In-Progress
payment was previously pending because of possible Partially-
reasons described for the PendingReason element. Refunded
Expired: This authorization has expired and cannot be Pending
captured. Processed
Failed: The payment has failed. This happens only if the Refunded
payment was made from your customer’s bank account. Reversed
In-Progress: The transaction is in process of authorization Voided
and capture.
Partially-Refunded: The transaction has been partially
refunded.
Pending: The payment is pending. See
“PendingReason” on page 94 for more
information.
Refunded: You refunded the payment.
Reversed: A payment was reversed due to a chargeback
or other type of reversal. The funds have been removed
from your account balance and returned to the buyer. The
reason for the reversal is specified in the ReasonCode
element.
Processed: A payment has been accepted.
Voided: This authorization has been voided.

Web Services API Reference July 2006 93

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

PendingReason The reason the payment is pending: ebl:PendingStatus

none: No pending reason CodeType
address: The payment is pending because your customer xs:token
did not include a confirmed shipping address and your none
Payment Receiving Preferences is set such that you want authorization
to manually accept or deny each of these payments. To address
change your preference, go to the Preferences section of echeck
your Profile. intl
authorization: You set <PaymentAction> multi-currency
Authorization</PaymentAction> on unilateral
SetExpressCheckoutRequest and have not yet captured upgrade
funds. verify
echeck: The payment is pending because it was made by other
an eCheck that has not yet cleared.
intl: The payment is pending because you hold a non-
U.S. account and do not have a withdrawal mechanism.
You must manually accept or deny this payment from
your Account Overview.
multi-currency: You do not have a balance in the
currency sent, and you do not have your Payment
Receiving Preferences set to automatically convert and
accept this payment. You must manually accept or deny
this payment.
unilateral: The payment is pending because it was
made to an email address that is not yet registered or
confirmed.
upgrade: The payment is pending because it was made
via credit card and you must upgrade your account to
Business or Premier status in order to receive the funds.
upgrade can also mean that you have reached the monthly
limit for transactions on your account.
verify: The payment is pending because you are not yet
verified. You must verify your account before you can
accept this payment.
other: The payment is pending for a reason other than
those listed above. For more information, contact PayPal
Customer Service.

94 July 2006 Web Services API Reference

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

ReasonCode The reason for a reversal if TransactionType is ebl:ReasonCodeType

reversal: xs:token
none: No reason code none
chargeback: A reversal has occurred on this transaction chargeback
due to a chargeback by your customer. guarantee
guarantee: A reversal has occurred on this transaction buyer-complaint
due to your customer triggering a money-back guarantee. refund
buyer-complaint: A reversal has occurred on this other
transaction due to a complaint about the transaction from
your customer.
refund: A reversal has occurred on this transaction
because you have given the customer a refund.
other: A reversal has occurred on this transaction due to
a reason not listed above.
PaymentItem Includes the following elements ebl:PaymentItem
Info InfoType

InvoiceID Invoice number you set in the original transaction. xs:string

Character length and limitations: 127 single-byte
alphanumeric characters
Custom Custom field you set in the original transaction. xs:string
Character length and limitations: 127 single-byte
alphanumeric characters
Memo Memo entered by your customer in PayPal Website xs:string
Payments note field.
Character length and limitations: 255 single-byte
alphanumeric characters
PaymentItem SaleTax Amount of tax charged on payment xs:string

Name Item name set by you or entered by the customer. If this xs:string
was a shopping cart transaction, PayPal appends the
number of the item to the HTML item_name variable. For
example, item_name1, item_name2, and so forth.
Character length and limitations: 127 single-byte
alphanumeric characters
Number Item number set by you. If this was a shopping cart xs:string
transaction, PayPal appends the number of the item to the
HTML item_name variable. For example, item_name1,
item_name2, and so forth.
Character length and limitations: 127 single-byte
alphanumeric characters
Quantity Quantity set by you or entered by the customer. xs:string
Character length and limitations: no limit
Amount Cost of item ebl:BasicAmount
Type

Web Services API Reference July 2006 95

 GetTransactionDetails API
GetTransactionDetailsResponse

TABLE 7.2 GetTransactionDetailsResponse Fields

Data Type and
Element Included Element Description Possible Values

Options PayPal item options for shopping cart ns:OptionType

name: xs:string
value: xs:string

Subscription Includes the following elements ebl:Subscription

InfoType

SubscriptionID ID generated by PayPal for the subscriber. xs:string

Character length and limitations: no limit
SubscriptionDate Subscription start date xs:dateTime

EffectiveDate Date when the subscription modification will be effective xs:dateTime

RetryTime Date PayPal will retry a failed subscription payment. xs:dateTime

Username Username generated by PayPal and given to subscriber to xs:string

access the subscription.
Character length and limitations: 64 alphanumeric single-
byte characters
Password Password generated by PayPal and given to subscriber to xs:string
access the subscription. For security, the value of the
password is hashed.
Character length and limitations: 128 alphanumeric
single-byte characters
Recurrences The number of payment installments that will occur at the xs:string
regular rate.
Character length and limitations: no limit
reattempt Indicates whether reattempts should occur upon payment xs:string
failures
recurring Indicates whether regular rate recurs. xs:string
1 = Yes

Subscription Amount The amount subscriber is to be charged in one payment. eb:BasicAmount

TermsType Character length and limitations: no limit Type

period The period of time that the subscriber will be charged. xs:string
Character length and limitations: no limit
Auction Includes the following elements ebl:AuctionInfo
Type

BuyerID Customer’s auction ID xs:string

ClosingDate Auction’s close date xs:string

multiItem Counter used for multi-item auction payments xs:string

96 July 2006 Web Services API Reference

 8 MassPay API

The MassPay API is the programmatic counterpart to the Mass Payment feature available
through the PayPal website. You can include up to 250 payments per MassPayRequest. You
must have a PayPal balance in each currency in which you want to make a payment and have
sufficient funds to cover the entire Mass Payment amount and fee. You cannot mix currencies
in the same MassPayRequest; a separate request is required for each currency.
The posting of payment transactions to individual recipient accounts is not handled by the
MassPay API but by a separate PayPal process.

Instant Payment Notification

The MassPay API triggers the sending of an Instant Payment Notification email to the
recipient of the funds.

Diagram of MassPay Types

The following diagram represents the composition of the MassPayRequestType,
MassPayRequestItemType, and MassPayResponseType elements.

FIGURE 8.1 MassPay Types

Web Services API Reference July 2006 97

 MassPay API
MassPayRequest

MassPayRequest
Process payments en masse to up to 250 different recipients.

Fields

TABLE 8.1 MassPayRequestType Fields

Element Description Data Type Possible Values Required?

EmailSubject Subject line of the email sent to all recipients. This subject xs:string See description. No
is not contained in the input file; you must create it with
your application.
Character length and limitations: 255 single-byte
alphanumeric characters
ReceiverType Indicates how you identify the recipients of payments in ebl:ReceiverInfo See Table 8.2. No
all MassPayItems: either by EmailAddress CodeType
(ReceiverEmail in MassPayItem) or by UserID xs:token
(ReceiverID in MassPayItem).
MassPayItem Details of each payment. ebl:MassPayItem See Table 8.3. Yes
Type
N O T E : A single MassPayRequest can include up to 250
MassPayItems

TABLE 8.2 ReceiverInfoCodeType Enumeration

Element Description Required?

EmailAddress Email address of recipient on file with PayPal. No

Character length and limitations: 12 single-byte
alphanumeric characters.
UserID Unique PayPal customer account number. No
Character length and limitations: 6 single-byte characters
maximum.

98 July 2006 Web Services API Reference

 MassPay API
MassPayRequest

TABLE 8.3 MassPayItemType Fields

Element Description Data Type Possible Values Required?

ReceiverEmail Email address of recipient. ebl:EmailAddress See descirption. No

I M P O R T A N T : You must specify either Receiver- Type
Email or ReceiverID, but you must not mix Re-
ceiverEmail and ReceiverID in the group of
MassPayItems. Use only one or the other, but not both, in
a single request.
Character length and limitations: 127 single-byte
characters maximum.
ReceiverID Unique PayPal customer account number. This value xs:string Transaction-specific No
corresponds to the value of PayerID returned by
GetTransactionDetails.
I M P O R T A N T : You must specify either Receiver-
Email or ReceiverID, but you must not mix Re-
ceiverEmail and ReceiverID in the group of
MassPayItems. Use only one or the other, but not both, in
a single request.
Character length and limitations: 17 single-byte
characters maximum.
Amount Payment amount. ebl:BasicAmount Transaction-specific Yes
Type
N O T E : You must set the currencyID attribute to one of
the three-character currency codes for any of the
supported PayPal currencies. See page 31.
I M P O R T A N T : You cannot mix currencies in a single
MassPayRequest. A single request must include items
that are of the same currency.
UniqueId Transaction-specific identification number for tracking in xs:string Transaction-specific No
an accounting system.
Character length and limitations: 30 single-byte
characters. No whitespace allowed.
Note Custom note for each recipient. xs:string Transaction-specific No
Character length and limitations: 4,000 single-byte
alphanumeric characters

Web Services API Reference July 2006 99

 MassPay API
MassPayResponse

MassPayResponse
Response to MassPayRequest.

Fields
The elements returned are the same as for AbstractResponseType. See page 36.
For error codes and messages and their meanings, see Appendix , “Error Codes and Messages
for All PayPal APIs.”

100 July 2006 Web Services API Reference

 9 RefundTransaction API

Use the RefundTransaction API to make either full or partial refunds.

Instant Payment Notification:

Use of the RefundTransaction API triggers the sending of an Instant Payment Notification
email to the recipient of the refund.

Diagram of RefundTransaction Types

The following diagram represents the composition of the
RefundTransactionRequestType and RefundTransactionResponseType elements.

FIGURE 9.1 RefundTransaction Types

RefundTransactionRequest
Request to refund a payment.
With RefundTransactionRequest, you must always pass the values of TransactionID
and RefundType. If RefundType is set to Full, you must not set Amount; however, if
RefundType is Partial, you must set Amount.

Web Services API Reference July 2006 101

 RefundTransaction API
RefundTransactionResponse

Fields

TABLE 9.1 RefundTransactionRequest Fields

Element Description Data Type Possible Values Required?

TransactionID Unique identifier of a transaction xs:string Transaction-specific Yes

Character length and limitations: 17 single-byte
alphanumeric characters
RefundType Type of refund you are making ebl:RefundPurpose Other Yes
TypeCodeType Full
xs:token Partial

Amount Refund amount. ebl:BasicAmount Transaction-specific See

Amount is required if RefundType is Partial. Type description
N O T E : If RefundType is Full, do not set Amount.
Memo Custom memo about the refund. xs:string Transaction-specific No
Character length and limitations: 255 single-byte
alphanumeric characters

RefundTransactionResponse
Response to RefundTransactionRequest.

Fields

TABLE 9.2 RefundTransactionResponse Fields

Element Description Data Type Value

Refund Unique transaction ID of the refund. xs:string See description.

TransactionID Character length and limitations:17 single-byte characters
FeeRefund Transaction fee refunded to original recipient of payment ebl:BasicAmount See description.
Amount Type

GrossRefund Amount of money refunded to original payer ebl:BasicAmount See description.

Amount Type

NetRefund Amount subtracted from PayPal balance of original ebl:BasicAmount See description.
Amount recipient of payment to make this refund Type

102 July 2006 Web Services API Reference

 10 TransactionSearch API

With TransactionSearchRequest you must always set the StartDate field. Some other
behavior:
z Setting TransactionID overrides all other fields (even the required StartDate field).
z The effect of setting other elements is additive or can alter the search criteria.
TransactionSearchResponse returns up to 100 matches. Partial matches are displayed.
For example, setting the TransactionSearchRequest FirstName to “Jess” returns
results such as “Jessica” and “Jesse”.
The most important returned element is TransactionID, which you can pass to
GetTransactionDetailsRequest in order to retrieve all available information about a
specific transaction.

Diagram of TransactionSearch Types

The following diagram represents the composition of the
TransactionSearchRequestType and PaymentTransactionSearchResultsType
elements.

FIGURE 10.1TransactionSearch Types

Web Services API Reference July 2006 103

 TransactionSearch API
TransactionSearchRequest

Tr a n s a c t i o n S e a r c h R e q u e s t
Request to search transaction history.

Fields

TABLE 10.1 TransactionSearchRequest Fields

Element Description Data Type Allowable Values Required?

StartDate The earliest transaction date at which to start the search. xs:dateTime Transaction-specific Yes
N O T E : No wildcards are allowed. The value must be in
UTC/GMT format.
EndDate The latest transaction date to be included in the search xs:dateTime Transaction-specific No
Payer Search by the buyer’s email address ebl:EmailAddress Transaction-specific No
Character length and limitations: 127 single-byte Type
alphanumeric characters xs:string

Receiver Search by the receiver’s email address. If the merchant ebl:EmailAddress Transaction-specific No
account has only one email, this is the primary email. Can Type
also be a non-primary email. xs:string

ReceiptID Search by the PayPal Account Optional receipt ID xs:string Transaction-specific No

TransactionID Search by the transaction ID. ebl:TransactionID Transaction-specific No
xs:string
N O T E : The returned results are from the merchant’s
transaction records.
Character length and limitations: 19 single-byte
characters maximum
InvoiceID Search by invoice identification key, as set by you for the xs:string Transaction-specific No
original transaction. InvoiceID searches the records
for items sold by the merchant, not the items purchased.
N O T E : No wildcards are allowed.
Character length and limitations: 127 single-byte
characters maximum
CardNumber Search by credit card number, as set by you for the xs:string Transaction-specific No
original transaction. CardNumber searches the
records for items sold by the merchant, not the items
purchased.
N O T E : No wildcards are allowed.
Character length and limitations: Must be at least 11 and
no more than 25 single-byte numeric characters
maximum. Special punctuation, such as dashes or spaces,
is ignored.

104 July 2006 Web Services API Reference

 TransactionSearch API
TransactionSearchRequest

TABLE 10.1 TransactionSearchRequest Fields

Element Description Data Type Allowable Values Required?

PayerName Search by the buyer's name ebl:PersonNameType Transaction-specific No

Salutation: 20 single-byte character limit xs:string
FirstName: 25 single-byte character limit
MiddleName: 25 single-byte character limit
LastName: 25 single-byte character limit
Suffix: 12 single-byte character limit

AuctionItem Search by auction item number of the purchased goods. xs:string Transaction-specific No
Number

Transaction Search by classification of transaction. ebl:Payment See description. No

Class TransactionClass
N O T E : Some kinds of possible classes of transactions
are not searchable with CodeType
xs:token
TransactionSearchRequest. You
cannot search for bank transfer withdrawals, for
example.
All: all transaction classifications
Sent: only payments sent
Received: only payments received
MassPay: only mass payments
MoneyRequest: only money requests
FundsAdded: only funds added to balance
FundsWithdrawn: only funds withdrawn from balance
Referral: only transactions involving referrals
Fee: only transactions involving fees
Subscription: only transactions involving subscriptions
Dividend: only transactions involving dividends
Billpay: only transactions involving BillPay Transactions
Refund: only transactions involving funds
CurrencyConversions: only transactions involving
currency conversions
BalanceTransfer: only transactions involving balance
transfers
Reversal: only transactions involving BillPay reversals
Shipping: only transactions involving UPS shipping fees
BalanceAffecting: only transactions that affect the
account balance
ECheck: only transactions involving eCheck
Amount Search by transaction amount ebl:BasicAmount Transaction-specific No
N O T E : You must set the currencyID attribute to Type
xs:string
one of the three-character currency codes for any
of the supported PayPal currencies.
CurrencyCode Search by currency code xs:token Transaction-specific No

Web Services API Reference July 2006 105

 TransactionSearch API
TransactionSearchResponse

TABLE 10.1 TransactionSearchRequest Fields

Element Description Data Type Allowable Values Required?

Status Search by transaction status: ebl:Payment Pending No

Pending: The payment is pending. The specific reason the Transaction Processing
payment is pending is returned by the StatusCodeType Success
GetTransactionDetails API PendingReason element. For xs:token Denied
Reversed
more information, see “PendingReason” on
page 94.
Processing: The payment is being processed.
Success: The payment has been completed and the funds
have been added successfully to your account balance.
Denied: You denied the payment. This happens only if the
payment was previously pending.
Reversed: A payment was reversed due to a chargeback or
other type of reversal. The funds have been removed from
your account balance and returned to the buyer.

TransactionSearchResponse
Response to TransactionSearchRequest.

Fields
For error codes and messages and their meanings, see Appendix , “Error Codes and Messages
for All PayPal APIs.”

TABLE 10.2 PaymentTransactions Fields

Element Description Data Type Possible Values

Timestamp The date and time (in UTC/GMT format) the transaction xs:dateTime Transaction-specific
occurred
Timezone The time zone of the transaction xs:string Transaction-specific
Type The type of the transaction xs:string Transaction-specific
Payer The email address of either the payer or the payment ebl:EmailAddress Transaction-specific
recipient (the “payee”). If GrossAmount is positive, Payer Type
is recipient of the funds. If GrossAmount is negative, xs:string
Payer is the paying customer.

Payer Display name of the payer xs:string Transaction-specific

DisplayName

TransactionID The transaction ID of the seller xs:string Transaction-specific

Status The status of the transaction. xs:string Transaction-specific
For details about statuses, see “PaymentStatus” on
page 93.

106 July 2006 Web Services API Reference

 TransactionSearch API
TransactionSearchResponse

TABLE 10.2 PaymentTransactions Fields

Element Description Data Type Possible Values

GrossAmount The total gross amount charged, including any profile ebl:BasicAmount Transaction-specific
shipping cost and taxes Type
xs:string

FeeAmount The fee that PayPal charged for the transaction BasicAmount Transaction-specific
Type
xs:string

NetAmount The net amount of the transaction BasicAmount Transaction-specific

Type
xs:string

Web Services API Reference July 2006 107

 TransactionSearch API
TransactionSearchResponse

108 July 2006 Web Services API Reference

A Error Codes and Messages for All PayPal
APIs

General API Errors

TABLE A.1 General API Errors

Short
Error Code Message Long Message Correcting This Error
10002 Authentication Username/Password is incorrect This error can be caused by
/Authorization an incorrect API username,
Failed 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 You do not have permissions to make this API
/Authorization call
Failed
10002 Authentication Account is locked or inactive
/Authorization
Failed
10002 Internal Error Internal Error
10002 Authentication Internal Error
/Authorization
Failed
10002 Authentication Account is not verified
/Authorization
Failed
10002 Authentication This call is not defined in the database!
/Authorization
Failed
10002 Authentication Token is not valid
/Authorization
Failed

July 2006 109

 Error Codes and Messages for All PayPal APIs
Authorization & Capture API Errors

TABLE A.1 General API Errors

Short
Error Code Message Long Message Correcting This Error
10002 Restricted Account is restricted
account
10002 Authentication Token is not valid
/Authorization
Failed
10002 Authentication API access is disabled for this account
/Authorization
Failed
10002 Authentication Client certificate is disabled
/Authorization
Failed
10002 Restricted Account is restricted
account

Authorization & Capture API Errors

TABLE A.2 Authorization & Capture API Error Messages

Error Short Returned By API

Code Message Long Message Call... Correcting This 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 permissions
denied to make this API call
10009 Transaction Account is locked or Retry the request at a later
refused inactive time or close order.
10010 Transaction Invalid argument
refused
because of an
invalid
argument. See
additional error
messages for
details.

110 July 2006

 Error Codes and Messages for All PayPal APIs
Authorization & Capture API Errors

TABLE A.2 Authorization & Capture API Error Messages

Error Short Returned By API

Code Message Long Message Call... Correcting This Error...
10600 Authorization Authorization is voided. DoAuthorization Close the order or
voided. DoCapture authorization.
DoReauthorization
DoVoid
10601 Authorization Authorization has expired. DoAuthorization Close the order or
expired. DoCapture authorization.
DoReauthorization
DoVoid
10602 Authorization Authorization has already DoAuthorization Close the order or
completed. been completed. DoCapture authorization.
DoReauthorization
DoVoid
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 ensure
must include cannot be unilateral. It must customer and seller are both
both buyer and include both buyer and seller PayPal members.
seller. to make an auth.
10605 Unsupported Currency is not supported. DoAuthorization Retry the request with a
currency. DoCapture PayPal-supported currency.

10606 Buyer cannot Transaction rejected, please DoAuthorization Contact the buyer.
pay. 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

July 2006 111

 Error Codes and Messages for All PayPal APIs
Authorization & Capture API Errors

TABLE A.2 Authorization & Capture API Error Messages

Error Short Returned By API

Code Message Long Message Call... Correcting This Error...
10610 Amount limit Amount specified exceeds DoAuthorization Reattempt the request with a
exceeded. allowable limit. DoCapture lower amount.
DoReauthorization
10611 Not enabled. Authorization & Capture DoAuthorization Contact PayPal Customer
feature is not enabled for the DoCapture Service.
merchant. Contact customer DoReauthorization
service.
10612 No more Maxmimum number of DoCapture Close the order.
settlement. allowable settlements has
been reached. No more
settlement for the
authorization.
10613 Currency Currency of capture must be DoCapture Ensure that the currencies
mismatch. the same as currency of are the same, and retry the
authorization. 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 the DoReauthorization Capture the reauthorization.
reauth. original authorization, not a
reauthorization.
10616 Maximum Maximum number of DoReauthorization Capture or close the
number of reauthorization allowed for authorization
reauthorization the auth is reached.
allowed for the
auth is reached.
10617 Reauthorizatio Reauthorization is not DoReauthorization Capture the authorization ro
n not allowed. allowed inside honor period. reauthorize outside of honor
period.
10618 Transaction Transaction has already been DoAuthorization Close the orde or
already voided voided or expired. DoCapture authorizationr.
or expired. DoReauthorization
DoVoid
10619 Invoice ID Invoice ID value exceeds DoCapture Check the length of the
value exceeds maximum allowable length. invoice ID and reattempt the
maximum request.
allowable
length.

112 July 2006

 Error Codes and Messages for All PayPal APIs
Authorization & Capture API Errors

TABLE A.2 Authorization & Capture API Error Messages

Error Short Returned By API

Code Message Long Message Call... Correcting This Error...
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 Order is voided. DoAuthorization Close this order.
voided. DoCapture
DoVoid
10623 Maximum Maximum number of DoAuthorization Capture this order.
number of authorization allowed for the DoCapture
authorization order is reached. DoReauthorization
allowed for the
DoVoid
order is
reached.
10624 Duplicate Payment has already been DoAuthorization Review the invoice ID and
invoice made for this InvoiceID. reattempt the request.
10625 Transaction The amount exceeds the DoAuthorization Reattempt the request with a
refused maximum amount for a DoCapture lower amount.
because of an single transaction. DoReauthorization
invalid
argument. See
additional error
messages for
details.
10626 Risk Transaction refused due to DoAuthorization Contact the buyer.
risk model DoCapture
DoReauthorization
10627 Transaction The invoice ID field is not DoAuthorization The Invoice ID field can only be
refused supported for basic DoReauthorization used with DoCapture.
because of an authorizations DoVoid
invalid
argument. See
additional error
messages for
details.

July 2006 113

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.2 Authorization & Capture API Error Messages

Error Short Returned By API

Code Message Long Message Call... Correcting This Error...
10628 This This transaction cannot be DoAuthorization Retry the request at a later time.
transaction processed at this time. Please DoCapture
cannot be try again later. DoReauthorization
processed at
DoVoid
this time.
Please try
again later.
10629 Reauthorizatio Reauthorization is not DoReauthorization Use DoAuthorization to
n 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.
11094 This This authorization can only
authorization be handled through the
cannot be marketplace which created
voided, it. It cannot directly be
reauthorized, voided, reauthorized, or
or captured captured against.
against.

Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

Error Short
Code Message Long Message Corrective Action
10500 Invalid This transaction cannot be Occurs when you have not agreed to the billing
Configuration processed due to an invalid agreement
merchant configuration.
10501 Invalid This transaction cannot be Occurs when the billing agreement is disabled or
Configuration processed due to an invalid inactive.
merchant configuration.
10502 Invalid Data This transaction cannot be The credit card used is expired
processed. Please use a valid
credit card.

114 July 2006

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

Error Short
Code Message Long Message Corrective Action
10504 Invalid Data This transaction cannot be The CVV provide is invalid. The CVV is between
processed. Please enter a valid 3-4 digits long
Credit Card Verification Number.
10505 Gateway This transaction cannot be The transaction was refused because the AVS
Decline processed. response returned the value of N, and the merchant
account is not able to accept such transactions.
10507 Invalid This transaction cannot be Your PayPal account is restricted - contact PayPal
Configuration processed. Please contact PayPal for more information
Customer Service.
10508 Invalid Data This transaction cannot be The expiration date must be a two-digit month and
processed. Please enter a valid four-digit year.
credit card expiration date.
10509 Invalid Data This transaction cannot be You must submit an IP address of the buyer with
processed. each API call
10510 Invalid Data The credit card type is not The credit card type entered is not currently
supported. Try another card type. supported by PayPal
10511 Invalid Data This transaction cannot be The merchant selected an 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 for this
processed. Please enter a first merchant
name.
10513 Invalid Data This transaction cannot be The last name of the buyer is required for this
processed. Please enter a last 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 not match
processed.
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.
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 supported
processed. The currency is not
supported at this time.

July 2006 115

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

Error Short
Code Message Long Message Corrective Action
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 This transaction cannot be The credit card entered is currently restricted by
Decline processed. Please enter a valid PayPal. Contact PayPal for more information
credit card number and type.
10535 Gateway This transaction cannot be The credit card entered is invalid
Decline processed. Please enter a valid
credit card number and type.
10536 Invalid Data This transaction cannot be The merchant entered an invoice ID that is already
processed. 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 country filter
processed. 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 maximum
processed. 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. Contact
processed. PayPal for more information
10540 Invalid Data The transaction cannot be The transaction was declined by PayPal because of
processed due to an invalid an invalid address.
address.
10541 Gateway This transaction cannot be The credit card entered is currently restricted by
Decline processed. Please enter a valid PayPal. Contact PayPal for more information
credit card number and type.
10542 Invalid Data This transaction cannot be The email address provided by the buyer is in an
processed. Please enter a valid invalid format
email address.
10544 Gateway This transaction cannot be The transaction was declined by PayPal. Contact
Decline processed. PayPal for more information
10545 Gateway This transaction cannot be The transaction was declined by PayPal because of
Decline processed. possible fraudulent activity. Contact PayPal for
more information

116 July 2006

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

Error Short
Code Message Long Message Corrective Action
10546 Gateway This transaction cannot be The transaction was declined by PayPal because of
Decline processed. 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 This transaction cannot be The merchant account attempting the transaction is
Configuration processed. The merchant's not a business account at PayPal. Check your
accouht is not able to process account settings
transactions.
10549 Invalid This transaction cannot be The merchant account attempting the transaction is
Configuration processed. The merchant's not able to process Direct Payment transactions.
account is not able to process Contact PayPal for more information.
transactions.
10550 Invalid This transaction cannot be Access to Direct Payment was disabled for your
Configuration processed. account. Contact PayPal for more information.
10552 Invalid This transaction cannot be The merchant account attempting the transaction
Configuration processed. does not have a confirmed email address with
PayPal. Check your account settings
10553 Gateway This transaction cannot be The merchant attempted a transaction where the
Decline processed. amount exceeded the upper limit for that merchant
10554 Filter Decline This transaction cannot be The transaction was declined because of a
processed. 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 a
processed. merchant risk filter for AVS. Specifically, the
merchant has set to decline transaction when the
AVS returned a partial match
10556 Filter Decline This transaction cannot be The transaction was declined because of a
processed. merchant risk filter for AVS. Specifically, the
merchant has set to decline transaction when the
AVS was unsupported
10701 Invalid Data There's an error with this The billing address entered is invalid.
transaction. Please enter a valid
billing address.
10702 Invalid Data There's an error with this There was a problem with a particular field in the
transaction. Please enter a valid address. The long error message will tell you what
address1 in the billing address. field is invalid

July 2006 117

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

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

118 July 2006

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

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

July 2006 119

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

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

120 July 2006

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

Error Short
Code Message Long Message Corrective Action
10732 Invalid Data There's an error with this There was a problem with a particular field in the
transaction. Please enter a valid address. The long error message will tell you what
shipping address. field is invalid
10733 Invalid Data There's an error with this There was a problem with a particular field in the
transaction. Please enter a valid address. The long error message will tell you what
state in the shipping address. field is invalid
10734 Invalid Data There's an error with this There was a problem with a particular field in the
transaction. Please enter your address. The long error message will tell you what
five digit postal code in the field is invalid
shipping address.
10735 Invalid Data There's an error with this There was a problem with a particular field in the
transaction. Please enter your address. The long error message will tell you what
five digit postal code in the field is invalid
shipping address.
10736 Invalid Data There's an error with this There was a problem with a particular field in the
transaction. Please enter a valid address. The long error message will tell you what
city and state in the shipping field is invalid
address.
10744 Invalid Data This transaction cannot be There was a problem with a particular field in the
processed. Please enter a valid address. The long error message will tell you what
country code in the billing field is invalid
address.
10745 Invalid Data This transaction cannot be There was a problem with a particular field in the
processed. Please enter a valid address. The long error message will tell you what
country code in the shipping field is invalid
address.
10746 Invalid Data This transaction cannot be There was a problem with a particular field in the
processed. Please use a valid address. The long error message will tell you what
country on the billing address. field is invalid
10747 Invalid Data This transaction cannot be The merchant entered an IP address that was in an
processed. 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 CVV to be
processed without a Credit Card entered, but no CVV was provided with this
Verification number. 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 field in the
transaction. Please enter a valid address. The long error message will tell you what
state in the shipping address. field is invalid

July 2006 121

 Error Codes and Messages for All PayPal APIs
Direct Payments API Errors

TABLE A.3 Direct Payment API Errors

Error Short
Code Message Long Message Corrective Action
10751 Invalid Data There's an error with this The merchant provided an address either in the
transaction. Please enter a valid United States or Canada, but the state provided is
state in the billing address. not a valid state in either country
10752 Gateway This transaction cannot be The transaction was declined by the issuing bank,
Decline processed. not PayPal. The merchant should attempt another
card
10754 Gateway This transaction cannot be The transaction was declined by PayPal. Contact
Decline processed. PayPal for more information
10755 Invalid Data This transaction cannot be The currency code entered by the merchant is not
processed due to an unsupported supported
currency.
10756 Gateway The transaction cannot be None - this is a PayPal internal error
Decline processed. The country and
billing address associated with
this credit card do not match.
10758 Invalid There's been an error due to The API username or password is incorrect for this
Configuration invalid API username and/or merchant
password.
10759 Gateway This transaction cannot be The transaction was declined by PayPal. Contact
Decline processed. Please enter a valid PayPal for more information
credit card number and type.
10760 Invalid This transaction cannot be The merchant's country of residence listed in their
Configuration processed. The country listed for PayPal account is not currently supported to allow
your business address is not Direct Payment transactions
currently supported.
10761 Gateway This transaction cannot be The transaction was declined because PayPal is
Decline processed. Please check the currently processing a transaction by the same
status of your first transaction buyer for the same amount. Can occur when a
before placing another order. buyer submits multiple, identical transactions in
quick succession
10762 Gateway This transaction cannot be The CVV provide is invalid. The CVV is between
Decline processed. 3-4 digits long
10763 Invalid Data This transaction cannot be None - this is a PayPal internal error
processed.
15001 Gateway This transaction cannot be The transaction was rejected by PayPal because of
Decline processed. excessive failures over a short period of time for
this credit card. Contact PayPal for more
information

122 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.3 Direct Payment API Errors

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

Express Checkout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error Short
Code Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal
error
10001 ButtonSource The transaction could not be
value loaded
truncated.
10001 Internal Error Internal Error

July 2006 123

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error Short
Code Message Long Message Correcting This Error...
10004 Transaction Transaction refused because of
refused an invalid argument. See
because of an additional error messages for
invalid details.
argument. See
additional error
messages for
details.
10004 Transaction The transaction id is not valid
refused
because of an
invalid
argument. See
additional error
messages for
details.
10007 Permission You do not have permissions to
denied make this API call
10102 PaymentActio PaymentAction of Order is
n of Order temporarily unavailable. Please
Temporarily try later or use other
Unavailable PaymentAction.
10402 Authorization This merchant account is not
only is not permitted to set PaymentAction
allowed for to Authorization. Please contact
merchant. Customer Service.
10404 Transaction ReturnURL is missing.
refused
because of an
invalid
argument. See
additional error
messages for
details.
10405 Transaction CancelURL is missing.
refused
because of an
invalid
argument. See
additional error
messages for
details.

124 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error Short
Code Message Long Message Correcting This Error...
10407 Transaction Invalid buyer email address
refused (BuyerEmail).
because of an
invalid
argument. See
additional error
messages for
details.
10409 You're not Express Checkout token was
authorized to issued for a merchant account
access this other than yours.
info.
10410 Invalid token Invalid token.
10411 This Express This Express Checkout session The token returned by
Checkout has expired. Token value is no SetExpressCheckoutResponse expires
session has longer valid. after three hours. If you attempt to send the
expired. DoExpressCheckoutPaymentRequest
after that time, you will receive error code 10411 in
DoExpressCheckoutPaymentResponse.
If you receive this error, you must return your
customer to PayPal to approve the use of PayPal
again. Display an error message to inform the
customer that the transaction expired, and provide a
button to return to PayPal. In this situation, you are
effectively restarting the entire checkout process.
(Do not reuse the expired token value on
SetExpressCheckoutRequest.) 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.
10412 Duplicate Payment has already been made PayPal checks that InvoiceID values are unique
invoice for this InvoiceID. 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.

July 2006 125

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error Short
Code Message Long Message Correcting This Error...
10415 Transaction A successful transaction has PayPal allows a token only once for a successful
refused already been completed for this transaction.
because of an token. Handling this error
invalid If you determine that your customers are clicking
argument. See your “Place Order” button twice, PayPal
additional error recommends that you disable the button after your
messages for customer has clicked it.
details.
10425 Express Express Checkout has been
Checkout has disabled for this merchant. Please
been disabled contact Customer Service.
for this
merchant.
10432 Transaction Invoice ID value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.
10433 Transaction Value of OrderDescription
refused element has been truncated.
because of an
invalid
argument. See
additional error
messages for
details.
10434 Transaction Value of Custom element has
refused been truncated.
because of an
invalid
argument. See
additional error
messages for
details.

126 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error Short
Code Message Long Message Correcting This Error...
10436 Transaction PageStyle value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.
10437 Transaction cpp-header-image value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.
10438 Transaction cpp-header-image value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.
10439 Transaction cpp-header-image value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.
10440 Transaction cpp-header-image value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.

July 2006 127

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.4 SetExpressCheckout API Errors

Error Short
Code Message Long Message Correcting This Error...
10537 Risk Control The transaction was refused
Country Filter because the country was
Failure prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control The transaction was refused
Max Amount because the maximum amount
Failure was excceeded as a result of your
Maximum Amount Risk Control
Settings.
10539 Payment Payment declined by your Risk
declined by Controls settings: PayPal Risk
your Risk Model.
Controls
settings:
PayPal Risk
Model.
10725 Shipping There was an error in the
Address Shipping Address Country field
Country Error
10727 Shipping The field Shipping Address1 is
Address1 required
Empty
10728 Shipping The field Shipping Address City
Address City is required
Empty
10729 Shipping The field Shipping Address State
Address State is required
Empty
10730 Shipping The field Shipping Address
Address Postal Postal Code is required
Code Empty
10731 Shipping The field Shipping Address
Address Country is required
Country Empty
10736 Shipping A match of the Shipping Address
Address City, State, and Postal Code
Invalid City failed.
State Postal
Code

128 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.5 GetExpressCheckoutDetails API Errors

Error Short
Code Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal
error
10001 ButtonSource The transaction could not be
value loaded
truncated.
10001 ButtonSource The transaction could not be
value loaded
truncated.
10004 Transaction Transaction refused because of
refused an invalid argument. See
because of an additional error messages for
invalid details.
argument. See
additional error
messages for
details.
10004 Transaction The transaction id is not valid
refused
because of an
invalid
argument. See
additional error
messages for
details.
10004 Invalid You can not get the details for
transaction this type of transaction
type
10004 Transaction The transaction could not be
refused loaded
because of an
invalid
argument. See
additional error
messages for
details.

July 2006 129

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.5 GetExpressCheckoutDetails API Errors

Error Short
Code Message Long Message Correcting This Error...
10004 Transaction The transaction id is not valid
refused
because of an
invalid
argument. See
additional error
messages for
details.
10007 Permission You do not have permissions to
denied make this API call
10007 Permission You do not have permission to
denied get the details of this transaction
10007 Permission You do not have permissions to
denied make this API call
10408 Express Express Checkout token is
Checkout missing.
token is
missing.
10409 You're not Express Checkout token was
authorized to issued for a merchant account
access this other than yours.
info.
10410 Invalid token Invalid token.
10411 This Express This Express Checkout session
Checkout has expired. Token value is no
session has longer valid.
expired.

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code 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

130 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10001 ButtonSource The transaction could not be
value loaded
truncated.
10001 Internal Error Internal Error
10004 Transaction Transaction refused because of
refused an invalid argument. See
because of an additional error messages for
invalid details.
argument. See
additional error
messages for
details.
10004 Transaction The transaction id is not valid
refused
because of an
invalid
argument. See
additional error
messages for
details.
10007 Permission You do not have permissions to
denied make this API call
10406 Transaction The PayerID value is invalid.
refused
because of an
invalid
argument. See
additional error
messages for
details.
10408 Express Express Checkout token is
Checkout missing.
token is
missing.
10409 You're not Express Checkout token was
authorized to issued for a merchant account
access this other than yours.
info.
10410 Invalid token Invalid token.

July 2006 131

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10411 This Express This Express Checkout session
Checkout has expired. Token value is no
session has longer valid.
expired.
10412 Duplicate Payment has already been made
invoice for this InvoiceID.
10413 Transaction The totals of the cart item If you include any of the following element values
refused amounts do not match order with DoExpressCheckoutPayment, the sum
because of an amounts. of their values must equal the value of
invalid OrderTotal.
argument. See z ItemTotal
additional error z ShippingTotal
messages for z HandlingTotal
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 The amount exceeds the
refused maximum amount for a single
because of an transaction.
invalid
argument. See
additional error
messages for
details.
10415 Transaction A successful transaction has
refused already been completed for this
because of an token.
invalid
argument. See
additional error
messages for
details.
10416 Transaction You have exceeded the You can send a maximum of 10
refused maximum number of payment DoExpressCheckoutPayment API calls for
because of an attempts for this token. any single token value, after which the token
invalid becomes invalid.
argument. See
additional error
messages for
details.

132 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10417 Transaction The transaction cannot complete It is possible that the payment method the customer
cannot successfully. Instruct the chooses on PayPal might not succeed when you
complete. customer to use an alternative send DoExpressCheckoutPayment. The
payment method. most likely cause is that the customer’s credit card
failed bank authorization. Another possible, though
rare, cause is that the final OrderTotal is
significantly higher than the original estimated
OrderTotal you sent with
SetExpressCheckout at Integration Point 1,
and the final OrderTotal does not pass PayPal’s
risk model analysis.
If the customer has no other PayPal funding source
that is likely to succeed,
DoExpressCheckoutPaymentResponse
returns error code 10417.
Instruct the customer that PayPal is unable to
process the payment and redisplay alternative
payment methods with which the customer can pay.
10418 Transaction The currencies of the shopping
refused cart amounts must be the same.
because of an
invalid
argument. See
additional error
messages for
details.
10419 Express Express Checkout PayerID is
Checkout missing.
PayerID is
missing.
10420 Transaction Express Checkout
refused PaymentAction is missing.
because of an
invalid
argument. See
additional error
messages for
details.

July 2006 133

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10421 This Express This Express Checkout session When your customer logs into PayPal, the PayPal
Checkout belongs to a different customer. PayerID is associated with the Express Checkout
session Token value mismatch. token. This error is caused by mixing tokens for
belongs to a two different PayerIDs. The Token and
different PayerID returned for any particular customer by
customer. GetExpressCheckoutDetailsResponse
must be the same ones you send with
DoExpressCheckoutPayment.
Verify that your programs are properly associating
the Tokens and PayerIDs.
10422 Customer must The customer must return to It is possible that the payment method the customer
choose new PayPal to select new funding chooses on PayPal might not succeed when you
funding sources. send
sources. DoExpressCheckoutPaymentRequest. If
the customer has a different PayPal funding source
that is likely to succeed,
DoExpressCheckoutPaymentResponse
returns error code 10422 so you can redirect the
customer back to PayPal.
10423 Transaction This transaction cannot be This error occurs if at Integration Point 1, you set
refused completed with PaymentAction PaymentAction to Sale with
because of an of Authorization. SetExpressCheckoutRequest but at
invalid Integration Point 3, you set PaymentAction to
argument. See Authorization with
additional error DoExpressCheckoutPayment.
messages for PayPal does not allow this switch from Sale to
details. Authorization in a single checkout session.
PayPal does allow the reverse, however. You can
set PaymentAction to Authorization with
SetExpressCheckout at Integration Point 1
and switch PaymentAction to Sale with
DoExpressCheckoutPayment at Integration
Point 3.
10424 Transaction Shipping address is invalid. If you receive this error message, PayPal
refused recommends that you return your customer to
because of an PayPal to review and approve new valid funding
invalid sources. Although this error is rare, you should
argument. See consider trapping the error to display a message to
additional error the customer describing what happened, along with
messages for a button or hyperlink to return to PayPal. the
details. chapter about best practices in
10431 Item amount is Item amount is invalid.
invalid.

134 July 2006

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10432 Transaction Invoice ID value exceeds
refused maximum allowable length.
because of an
invalid
argument. See
additional error
messages for
details.
10433 Transaction Value of OrderDescription
refused element has been truncated.
because of an
invalid
argument. See
additional error
messages for
details.
10434 Transaction Value of Custom element has
refused been truncated.
because of an
invalid
argument. See
additional error
messages for
details.
10435 Transaction The customer has not yet
refused confirmed payment for this
because of an Express Checkout session.
invalid
argument. See
additional error
messages for
details.
10441 Transaction The NotifyURL element value
refused exceeds maximum allowable
because of an length.
invalid
argument. See
additional error
messages for
details.
10442 ButtonSource The ButtonSource element value
value exceeds maximum allowable
truncated. length.

July 2006 135

 Error Codes and Messages for All PayPal APIs
Express Checkout API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10443 Transaction This transaction cannot be
refused completed with PaymentAction
because of an of Order.
invalid
argument. See
additional error
messages for
details.
10444 Transaction The transaction currency
refused specified must be the same as
because of an previously specified.
invalid
argument. See
additional error
messages for
details.
10445 This This transaction cannot be
transaction processed at this time. Please try
cannot be again later.
processed at
this time.
Please try
again later.
10446 Unconfirmed A confirmed email is required to
email make this API call.
10537 Risk Control The transaction was refused
Country Filter because the country was
Failure prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control The transaction was refused
Max Amount because the maximum amount
Failure was excceeded as a result of your
Maximum Amount Risk Control
Settings.
10539 Payment Payment declined by your Risk
declined by Controls settings: PayPal Risk
your Risk Model.
Controls
settings:
PayPal Risk
Model.

136 July 2006

 Error Codes and Messages for All PayPal APIs
GetTransactionDetails API Errors

TABLE A.6 DoExpressCheckoutPayment API Errors

Error Short
Code Message Long Message Correcting This Error...
10725 Shipping There was an error in the
Address Shipping Address Country field
Country Error
10727 Shipping The field Shipping Address1 is
Address1 required
Empty
10728 Shipping The field Shipping Address City
Address City is required
Empty
10729 Shipping The field Shipping Address State
Address State is required
Empty
10730 Shipping The field Shipping Address
Address Postal Postal Code is required
Code Empty
10731 Shipping The field Shipping Address
Address Country is required
Country Empty
10736 Shipping A match of the Shipping Address
Address City, State, and Postal Code
Invalid City failed.
State Postal
Code

GetTransactionDetails API Errors

TABLE A.7 GetTransactionDetails API Errors

Short
Error Code Message Long Message
10001 Internal Error Internal Error

July 2006 137

 Error Codes and Messages for All PayPal APIs
MassPay API Errors

MassPay API Errors

TABLE A.8 MassPay API Errors

Short
Error Code Message Long Message

10001 Invalid account The transaction failed as a result of an invalid credit card number.
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 The transaction could not be loaded

value
truncated.

10001 Transaction The masspay receiver_type is not a recognizable type

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

10002 Account The user account is locked

locked

10004 Transaction The number of input records is greater than maximum allowed
refused
because of an
invalid
argument. See
additional error
messages for
details.

138 July 2006

 Error Codes and Messages for All PayPal APIs
MassPay API Errors

TABLE A.8 MassPay API Errors

Short
Error Code Message Long Message

10004 Transaction The number of input records is less than or equal to zero
refused
because of an
invalid
argument. See
additional error
messages for
details.

10004 Transaction The note string length exceeds the maximum limit of 4000
refused characters
because of an
invalid
argument. See
additional error
messages for
details.

10004 Transaction The amount is missing

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

10004 Transaction The currency is missing

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

July 2006 139

 Error Codes and Messages for All PayPal APIs
MassPay API Errors

TABLE A.8 MassPay API Errors

Short
Error Code Message Long Message

10004 Transaction Currency is not supported

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

10004 Transaction The amount is not a valid number

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

10004 Transaction The amount exceeds the max limit of a single mass pay item
refused ~1
because of an
invalid
argument. See
additional error
messages for
details.

10004 Transaction The amount is less than or equal to zero

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

10004 Transaction The unique id string length exceeds the maximum limit of 30
refused characters
because of an
invalid
argument. See
additional error
messages for
details.

140 July 2006

 Error Codes and Messages for All PayPal APIs
MassPay API Errors

TABLE A.8 MassPay API Errors

Short
Error Code Message Long Message

10004 Transaction The unique id string contains a space as a character

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

10004 Transaction The transaction id is not valid

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

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

10301 User not The user is not allowed to send money through Mass Pay
allowed

10303 Restricted Account is restricted

account

10304 Unconfirmed The user account has unconfirmed email

email

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

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

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

10308 Masspay There is some configuration error

server
configuration
error

July 2006 141

 Error Codes and Messages for All PayPal APIs
MassPay API Errors

TABLE A.8 MassPay API Errors

Short
Error Code Message Long Message

10309 Masspay The mass pay server is unavailable

server
unavailable

10310 Unable to Unable to create payments for masspay

create payment

10311 Unable to Unable to submit payments for masspay

submit
payment

10312 Masspay The masspay server has reported errors

server error

10313 Masspay The masspay input file includes invalid data

Invalid Data

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

10317 Masspay The masspay input file includes invalid Email

Invalid Email

10320 Internal Error Internal Error

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

10327 Masspay The masspay input file includes invalid UserID

Invalid UserID

142 July 2006

 Error Codes and Messages for All PayPal APIs
RefundTransaction API Errors

RefundTransaction API Errors

TABLE A.9 RefundTransaction API Errors

Error Short
Code 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 The transaction could not be loaded
value
truncated.
10001 Internal Error Internal Error
10004 Transaction The partial refund amount must be a
refused positive amount
because of an
invalid
argument. See
additional error
messages for
details.
10004 Transaction You can not specify a partial amount with
refused a full refund
because of an
invalid
argument. See
additional error
messages for
details.
10004 Transaction A transaction id is required
refused
because of an
invalid
argument. See
additional error
messages for
details.

July 2006 143

 Error Codes and Messages for All PayPal APIs
RefundTransaction API Errors

TABLE A.9 RefundTransaction API Errors

Error Short
Code Message Long Message Correcting This Error...
10004 Transaction The partial refund amount must be a
refused positive amount
because of an
invalid
argument. See
additional error
messages for
details.
10004 Transaction You can not specify a partial amount with
refused a full refund
because of an
invalid
argument. See
additional error
messages for
details.
10004 Transaction A transaction id is required
refused
because of an
invalid
argument. See
additional error
messages for
details.
10004 Transaction Transaction class is not supported
refused
because of an
invalid
argument. See
additional error
messages for
details.
10004 Transaction The transaction id is not valid
refused
because of an
invalid
argument. See
additional error
messages for
details.
10007 Permission You do not have permission to refund this
denied transaction

144 July 2006

 Error Codes and Messages for All PayPal APIs
RefundTransaction API Errors

TABLE A.9 RefundTransaction API Errors

Error Short
Code Message Long Message Correcting This Error...
10007 Permission You do not have permissions to make this
denied API call
10009 Transaction You do not have a verified ACH This error can be caused by insufficient
refused 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 The partial refund amount must be less
refused than or equal to the original transaction
amount
10009 Transaction The partial refund amount must be less
refused than or equal to the remaining amount
10009 Transaction The partial refund amount is not valid
refused
10009 Transaction Because a complaint case exists on this
refused transaction, only a refund of the full or full
remaining amount of the transaction can
be issued
10009 Transaction You are over the time limit to perform a
refused refund on this transaction
10009 Transaction Can not do a full refund after a partial
refused refund
10009 Transaction Account is locked or inactive
refused
10009 Transaction The partial refund must be the same
refused currency as the original transaction
10009 Transaction This transaction has already been fully
refused refunded
10009 Transaction Account is restricted
refused
10009 Transaction You can not refund this type of transaction
refused

July 2006 145

 Error Codes and Messages for All PayPal APIs
TransactionSearch API Errors

TABLE A.9 RefundTransaction API Errors

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

TransactionSearch API Errors

TABLE A.10 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.

146 July 2006

 Error Codes and Messages for All PayPal APIs
TransactionSearch API Errors

TABLE A.10 TransactionSearch API Errors

Error
Code Short Message Long Message
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.
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.

July 2006 147

 Error Codes and Messages for All PayPal APIs
TransactionSearch API Errors

TABLE A.10 TransactionSearch API Errors

Error
Code Short Message Long Message
10007 Permission denied You do not have permissions to search for this transaction
10007 Permission denied You do not have permissions to make this API call
11002 Search warning The number of results were truncated. Please change your search
parameters if you wish to see all your results.

148 July 2006

B Country Codes

Country Code

Country Code BERMUDA BM

AFGHANISTAN AF BHUTAN BT

ÅLAND ISLANDS AX BOLIVIA BO

ALBANIA AL BOSNIA AND BA

HERZEGOVINA
ALGERIA DZ
BOTSWANA BW
AMERICAN SAMOA AS
BOUVET ISLAND BV
ANDORRA AD
BRAZIL BR
ANGOLA AO
BRITISH INDIAN OCEAN IO
ANGUILLA AI TERRITORY
ANTARCTICA AQ BRUNEI DARUSSALAM BN
ANTIGUA AND BARBUDA AG BULGARIA BG
ARGENTINA AR BURKINA FASO BF
ARMENIA AM BURUNDI BI
ARUBA AW CAMBODIA KH
AUSTRALIA AU CAMEROON CM
AUSTRIA AT CANADA CA
AZERBAIJAN AZ CAPE VERDE CV
BAHAMAS BS CAYMAN ISLANDS KY
BAHRAIN BH CENTRAL AFRICAN CF
REPUBLIC
BANGLADESH BD
CHAD TD
BARBADOS BB
CHILE CL
BELARUS BY
CHINA CN
BELGIUM BE
CHRISTMAS ISLAND CX
BELIZE BZ
COCOS (KEELING) ISLANDS CC
BENIN BJ
COLOMBIA CO

149
 Country Codes

Country Code Country Code

COMOROS KM FRENCH SOUTHERN TF

TERRITORIES
CONGO CG
GABON GA
CONGO, THE DEMOCRATIC CD
REPUBLIC OF THE GAMBIA GM

COOK ISLANDS CK GEORGIA GE

COSTA RICA CR GERMANY DE

COTE D'IVOIRE CI GHANA GH

CROATIA HR GIBRALTAR GI

CUBA CU GREECE GR

CYPRUS CY GREENLAND GL

CZECH REPUBLIC CZ GRENADA GD

DENMARK DK GUADELOUPE GP

DJIBOUTI DJ GUAM GU

DOMINICA DM GUATEMALA GT

DOMINICAN REPUBLIC DO GUERNSEY GG

ECUADOR EC GUINEA GN

EGYPT EG GUINEA-BISSAU GW

EL SALVADOR SV GUYANA GY

EQUATORIAL GUINEA GQ HAITI HT

ERITREA ER HEARD ISLAND AND HM

MCDONALD ISLANDS
ESTONIA EE
HOLY SEE (VATICAN CITY VA
ETHIOPIA ET STATE)
FALKLAND ISLANDS FK HONDURAS HN
(MALVINAS)
HONG KONG HK
FAROE ISLANDS FO
HUNGARY HU
FIJI FJ
ICELAND IS
FINLAND FI
INDIA IN
FRANCE FR
INDONESIA ID
FRENCH GUIANA GF
IRAN, ISLAMIC REPUBLIC IR
FRENCH POLYNESIA PF OF

150
 Country Codes

Country Code Country Code

IRAQ IQ MADAGASCAR MG

IRELAND IE MALAWI MW

ISLE OF MAN IM MALAYSIA MY

ISRAEL IL MALDIVES MV

ITALY IT MALI ML

JAMAICA JM MALTA MT

JAPAN JP MARSHALL ISLANDS MH

JERSEY JE MARTINIQUE MQ

JORDAN JO MAURITANIA MR

KAZAKHSTAN KZ MAURITIUS MU

KENYA KE MAYOTTE YT

KIRIBATI KI MEXICO MX

KOREA, DEMOCRATIC KP MICRONESIA, FEDERATED FM

PEOPLE'S REPUBLIC OF STATES OF

KOREA, REPUBLIC OF KR MOLDOVA, REPUBLIC OF MD

KUWAIT KW MONACO MC

KYRGYZSTAN KG MONGOLIA MN

LAO PEOPLE'S LA MONTSERRAT MS

DEMOCRATIC REPUBLIC
MOROCCO MA
LATVIA LV
MOZAMBIQUE MZ
LEBANON LB
MYANMAR MM
LESOTHO LS
NAMIBIA NA
LIBERIA LR
NAURU NR
LIBYAN ARAB JAMAHIRIYA LY
NEPAL NP
LIECHTENSTEIN LI
NETHERLANDS NL
LITHUANIA LT
NETHERLANDS ANTILLES AN
LUXEMBOURG LU
NEW CALEDONIA NC
MACAO MO
NEW ZEALAND NZ
MACEDONIA, THE FORMER MK
YUGOSLAV REPUBLIC OF NICARAGUA NI

NIGER NE

151
 Country Codes

Country Code Country Code

NIGERIA NG SAINT VINCENT AND THE VC

GRENADINES
NIUE NU
SAMOA WS
NORFOLK ISLAND NF
SAN MARINO SM
NORTHERN MARIANA MP
ISLANDS SAO TOME AND PRINCIPE ST

NORWAY NO SAUDI ARABIA SA

OMAN OM SENEGAL SN

PAKISTAN PK SERBIA AND MONTENEGRO CS

PALAU PW SEYCHELLES SC

PALESTINIAN TERRITORY, PS SIERRA LEONE SL

OCCUPIED
SINGAPORE SG
PANAMA PA
SLOVAKIA SK
PAPUA NEW GUINEA PG
SLOVENIA SI
PARAGUAY PY
SOLOMON ISLANDS SB
PERU PE
SOMALIA SO
PHILIPPINES PH
SOUTH AFRICA ZA
PITCAIRN PN
SOUTH GEORGIA AND THE GS
POLAND PL SOUTH SANDWICH ISLANDS

PORTUGAL PT SPAIN ES

PUERTO RICO PR SRI LANKA LK

QATAR QA SUDAN SD

REUNION RE SURINAME SR

ROMANIA RO SVALBARD AND JAN SJ

MAYEN
RUSSIAN FEDERATION RU
SWAZILAND SZ
RWANDA RW
SWEDEN SE
SAINT HELENA SH
SWITZERLAND CH
SAINT KITTS AND NEVIS KN
SYRIAN ARAB REPUBLIC SY
SAINT LUCIA LC
TAIWAN, PROVINCE OF TW
SAINT PIERRE AND PM CHINA
MIQUELON
TAJIKISTAN TJ

152
 Country Codes

Country Code Country Code

TANZANIA, UNITED TZ YEMEN YE

REPUBLIC OF
ZAMBIA ZM
THAILAND TH
ZIMBABWE ZW
TIMOR-LESTE TL

TOGO TG

TOKELAU TK

TONGA TO

TRINIDAD AND TOBAGO TT

TUNISIA TN

TURKEY TR

TURKMENISTAN TM

TURKS AND CAICOS TC

ISLANDS

TUVALU TV

UGANDA UG

UKRAINE UA

UNITED ARAB EMIRATES AE

UNITED KINGDOM GB

UNITED STATES US

UNITED STATES MINOR UM

OUTLYING ISLANDS

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

153
 Country Codes

154
 Index

Symbols BasicAmountType 54, 55, 60, 67, 68, 80, 81, 83, 84, 85,
105, 107
.NET SDK Guide 18 BasicAmountType data type 32
Billpay 105
Build 37
A
Business 89
AbstractRequestType 35, 36 ButtonSource 81
AbstractResponseType 35, 36, 100 BuyerEmail 71
Ack 28, 37 BuyerID 96
success response 29
Address 61, 69, 90
Address Verification System 62 C
AddressOverride 69 Canceled-Reversal 43, 93
AddressOwner 90 CancelURL 68
AddressOwnerTypeCode 90 Card Verification Value. See CVV2.
AddressStatus 90 CardNumber 104
AddressStatus CodeType 90 CardOwner 54
AddressType 56, 69, 82, 90 Certificate 23, 25
AddressVerifyResponseType 40, 45, 47, 49, 51, 66, 73, character encoding and character set
77
UTF-8 31
All 105
CityName 61, 90
Amount 60, 83, 95, 96, 99, 102, 105
Classic ASP Guide 18
API Certificate 23
ClosingDate 96
API password 24
Completed 43, 93
API Signature 23
console, SDK 30
API username 24
ContactPhone 75
api.paypal.com 32, 33
CoreComponentTypes.xsd 22
api-3t.paypal.com 33
CorrelationID 29, 30, 37
Auction 96
CorrelationId 28
AuctionInfoType 96
Country 61, 90
AuctionItemNumber 105
CountryCodeType 57, 72, 75, 77, 82
authentication for all SOAP requests 24
cpp-header-back-color 70
Authorization & Capture 32
cpp-header-border-color 70
AuthorizationID 62, 84
cpp-payflow-color 70
AVS 62
CreditCard 52
AVSCode 62
CreditCardNumber 53
CreditCardType 53
B currency amount data type 32
currency codes 31
BalanceAffecting 105 CurrencyCode 105
BalanceTransfer 105 CurrencyConversions 105
BasicAmount Type 92

Web Services API Reference July 2006 155

 Index

currencyID 54, 55, 60, 67, 68, 80, 81, 83, 99, 105 FailureWithWarning 37
currencyId Fee 105
must be GBP if CreditCardType is switch or Solo 53 FeeAmount 42, 85, 92, 107
currencyID required attribute 32 FeeRefundAmount 102
Custom 55, 68, 74, 81, 95 FirstName 60, 76, 89, 105
CustomCode 37 First-Party Access 23
CVV2 54 FundsAdded 105
CVV2Code 62 FundsWithdrawn 105

D G
date/time values 31 GetTransactionDetails 33
dateTime data type 31 GetTransactionDetailsRequest 88, 103
Denied 43, 93 GetTransactionDetailsRequestType 87
Denied (transaction status) 106 GetTransactionDetailsResponse 99
Direct Payment 32 GetTransactionDetailsResponseType 87
Dividend 105 GrossAmount 84, 92, 107
DoAuthorizationRequest 45 GrossRefundAmount 102
DoAuthorizationResponse 45
doc-literal SOAP messaging 26
H
HandlingTotal 55, 81
E HTTPS 25
eBL 22, 30
eBLBaseComponents.xsd 22
ECheck 105 I
echeck 42 In-Progress 93
EffectiveDate 96 instant 42
EmailAddress 98 Instant Payment Notification 33
EmailAddress Type 89 Mass Payment API 97
EmailAddressType 71, 75, 99, 104, 106 RefundTransaction API 33, 97, 101
EmailSubject 98 int, not integer 31
EndDate 104 Integration Center 17
ErrorCode 29 InvoiceID 55, 68, 74, 81, 95, 104
Errors 29, 37 IPAddress 53
ExchangeRate 85, 92 ItemTotal 54, 80
Expired 43, 93
ExpMonth 53
Express Checkout 32, 65 J
Express Checkout Integration Guide 17 Java SDK Guide 18
ExpressCheckoutTokenType 67
ExpYear 53
L
LastName 60, 76, 89, 105
F
LocaleCode 69
Failed 93 LongMessage 29
Failure 37

156 July 2006 Web Services API Reference

 Index

M PayerInfo Type 89
PayerInfoType 74
MassPay 33, 105 PayerName 75, 105
MassPayItem 98 PayerStatus 75, 89
MassPayItemType 98
PaymentAction 52, 71, 79, 84
MassPayRequest 97 must be Authorization if CreditCardType is Switch or
MassPayRequestItemType 97 Solo 53
MassPayRequestType 97 PaymentAction CodeType 52, 71, 79
MassPayResponseType 97 PaymentCodeType 42, 84
MaxAmount 68 PaymentDate 84, 92
Memo 102 PaymentDetails 52, 80
MerchantSessionId 53 PaymentDetailsItem 56, 82
MiddleName 76, 89, 105 PaymentDetailsItemType 56, 82
MoneyRequest 105 PaymentDetailsType 80
multiItem 96 PaymentInfo 84, 88, 91
PaymentInfo Type 91
PaymentInfoType 42, 84
N
PaymentItem 95
Name 83, 90, 95 PaymentItemInfo 88, 95
NameType 76, 89 PaymentStatus 85, 93
NetAmount 107 PaymentStatusCodeType 85, 93
NetRefund 102 PaymentTransactionClassCodeType 105
NoShipping 69 PaymentTransactionCodeType 42, 84
Note 99 PaymentTransactions 106
NotifyURL 81 PaymentTransactionSearchResultsType 103
Number 60, 83, 95 PaymentTransactionStatusCodeType 106
numeric data types 31 PaymentType 84, 92
PayPal-supported currencies 31
PayPalSvc.wsdl 22
O PayPalUser StatusCodeType 89
Options 96 PayPalUserStatusCodeType 75
OptionType 96 Pending 43, 93
Order Management Integration Guide 18 Pending (transaction status) 106
OrderDescription 55, 68, 81 PendingReason 43, 86, 94
OrderTotal 54, 67, 80 PendingStatusCodeType 94
percentage value format 31
period 96
P PersonNameType 105
ParentTransactionID 91 Phone 91
Partially-Refunded 93 PHP SDK Guide 18
Password 23, 24, 27, 96 PostalCode 61, 91
Payer 60, 75, 89, 104, 106 Processed 43, 93
PayerBusiness 75, 90 Processing (transaction status) 106
PayerCountry 75, 90
PayerDisplayName 106
PayerID 75, 79, 89, 99 Q
PayerInfo 74, 88, 89, 90 Quantity 60, 83, 95

Web Services API Reference July 2006 157

 Index

R ShippingTotal 55, 80
ShipToAddress 82
ReasonCode 43, 93, 95 ShortMessage 29
ReasonCodeType 95 Signature 23, 24, 27
reattempt 96
endpoint sfor 25
ReceiptID 91, 104 SOAP request authentication 24
Received 105 Software Development Kits 18
Receiver 89, 104
SSL 25
ReceiverEmail 99 StartDate 104
ReceiverID 89 StateOrProvince 61, 90
ReceiverInfo 88, 89
Status 106
ReceiverInfo Type 89 Street1 61, 90
Recurrences 96 Street2 61, 90
recurring 96
Subject 23, 24, 25, 27
Referral 105 Subscription 96, 105
Refund (transaction class) 105 SubscriptionDate 96
Refunded 43, 93
SubscriptionID 96
RefundPurposeTypeCodeType 102 Subscriptions and Recurring Payments Guide 18
RefundTransaction 33 SubscriptionTermsType 96
RefundTransactionID 102
Success 29, 37
RefundTransactionRequest 101, 102 Success (transaction status) 106
RefundTransactionRequestType 101 SuccessWithWarning 37
RefundTransactionResponseType 101
Suffix 76, 90, 105
RefundType 101, 102 SuffixType 76, 90
ReqConfirmShipping 69 Switch 53
RequesterCredentials 24, 27
RetryTime 96
ReturnURL 68 T
Reversal 105
Tax 60, 83
Reversed 43, 93
TaxAmount 85, 92
Reversed (transaction status) 106
TaxTotal 55, 81
rpc-encoding not supported 26
Third-Party Access 23
third-party authorization 24, 25
S Timestamp 28, 36, 106
format 31
SaleTax 95 Timezone 106
Salutation 76, 89, 105 Token 67, 74, 79, 84
Sandbox User Guide 18
transaction status search 106
SDK 30 TransactionClass 105
SDKs 17 TransactionID 62, 84, 88, 91, 101, 102, 103, 104, 106
security
TransactionSearch 33
API password 24 TransactionSearchRequest 103, 106
API username 24 TransactionSearchRequestType 103
third-party authorization 25
TransactionSearchResponse 103
Sent 105 TransactionType 84, 95
SettleAmount 85, 92 Type 106
Shipping 105

158 July 2006 Web Services API Reference

 Index

U
Unicode 31
UniqueID 99
UserID 98
UserIDType 75, 89
Username 23, 24, 27, 96
UTC/GMT 29, 31, 36, 106

V
Version 27, 36, 37
Virtual Terminal User Guide 18
Voided 43, 93

W
Web Services 19, 21
Web Services API Reference 18
Website Payments Pro Integration Guide 17
Website Payments Standard Integration Guide 17
WSDL 21, 22
location of PayPal WSDL configuration file 22

X
XSD 21
location for PayPal Web Services 22

Web Services API Reference July 2006 159