Paypal Soap Api Developer 2012 Reference Manual

2015-07-27

: Paypal Paypal-Soap-Api-Developer-2012-Reference-Manual-778001 paypal-soap-api-developer-2012-reference-manual-778001 paypal pdf

Open the PDF directly: View PDF PDF.
Page Count: 400 [warning: Documents this large are best viewed by clicking the View PDF Link!]

SOAP API Developer
Reference
Last updated: August 2012
SOAP API Developer Reference
Document Number: 100002.en_US-201208
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-
2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
SOAP API Developer Reference August 2012 3
Contents
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
What’s New in Version 93.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1 PayPal SOAP API Basics . . . . . . . . . . . . . . . . . .15
PayPal WSDL/XSD Schema Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
PayPal SOAP API Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
SOAP RequesterCredentials: Username, Password, Signature, and Subject. . . . . . . . 17
SOAP Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
SOAP Request Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Request Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
SOAP Message Style: doc-literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Response Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
CorrelationID for Reporting Problems to PayPal. . . . . . . . . . . . . . . . . . . . . . . 24
UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Date/Time Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Core Currency Amount Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Chapter 2 AddressVerify API Operation . . . . . . . . . . . . . . . .27
AddressVerify Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
AddressVerifyRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
AddressVerify Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
AddressVerify Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Contents
4August 2012 SOAP API Developer Reference
Chapter 3 Authorization and Capture API Operation Reference . . . .31
DoCapture API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
DoCapture Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
DoCapture Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
DoAuthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
DoAuthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
DoAuthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . 41
DoReauthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
DoReauthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . 44
DoReauthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . 45
DoVoid API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DoVoid Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DoVoid Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Chapter 4 DoDirectPayment API Operation . . . . . . . . . . . . . .51
DoDirectPayment Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
DoDirectPayment Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
CreditCardDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
PayerInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
PayerNameType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
PaymentDetailsItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
EbayItemPaymentDetailsItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . 65
AddressType (Shipping) Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ThreeDSecureRequest Fields (U.K. Merchants Only). . . . . . . . . . . . . . . . . . 66
DoDirectPayment Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
DoDirectPayment Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
FMFDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
RiskFilterListType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
ThreeDSecure Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Chapter 5 DoNonReferencedCredit API Operation . . . . . . . . . . .71
DoNonReferencedCredit Request Message. . . . . . . . . . . . . . . . . . . . . . . . . 71
DoNonReferencedCredit Request Fields . . . . . . . . . . . . . . . . . . . . . . . . 73
CreditCardDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
PayerNameType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
PayerInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
SOAP API Developer Reference August 2012 5
Contents
AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
DoNonReferencedCredit Response Message . . . . . . . . . . . . . . . . . . . . . . . . 78
DoNonReferencedCredit Response Fields . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 6 ExpressCheckout API Operations . . . . . . . . . . . . . .79
SetExpressCheckout API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SetExpressCheckout Request Message . . . . . . . . . . . . . . . . . . . . . . . . 79
SetExpressCheckout Response Message. . . . . . . . . . . . . . . . . . . . . . . .105
GetExpressCheckoutDetails API Operation . . . . . . . . . . . . . . . . . . . . . . . . .106
GetExpressCheckoutDetails Request Message. . . . . . . . . . . . . . . . . . . . .106
GetExpressCheckoutDetails Response Message . . . . . . . . . . . . . . . . . . . .107
DoExpressCheckoutPayment API Operation . . . . . . . . . . . . . . . . . . . . . . . .126
DoExpressCheckoutPayment Request Message . . . . . . . . . . . . . . . . . . . .126
DoExpressCheckoutPayment Response Message . . . . . . . . . . . . . . . . . . .139
Chapter 7 GetBalance API Operation. . . . . . . . . . . . . . . . . 155
GetBalance Request Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
GetBalance Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
GetBalance Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
GetBalance Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Chapter 8 GetPalDetails API Operation . . . . . . . . . . . . . . . 157
GetPalDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
GetPalDetails Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
GetPalDetails Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Chapter 9 GetTransactionDetails API Operation . . . . . . . . . . . 161
GetTransactionDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . .161
GetTransactionDetails Request Fields. . . . . . . . . . . . . . . . . . . . . . . . . .161
GetTransactionDetails Response Message . . . . . . . . . . . . . . . . . . . . . . . . .162
GetTransactionDetails Response Fields. . . . . . . . . . . . . . . . . . . . . . . . .168
PaymentTransactionDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . .170
ReceiverInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
PayerInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
PayerName Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
PaymentInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Contents
6August 2012 SOAP API Developer Reference
PaymentItemInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
PaymentItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
AuctionInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
SubscriptionInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
SubscriptionTermsType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
Chapter 10 ManagePendingTransactionStatus API Operation. . . . . 183
ManagePendingTransactionStatus Request Message. . . . . . . . . . . . . . . . . . . .183
ManagePendingTransactionStatus Request Fields . . . . . . . . . . . . . . . . . . .183
ManagePendingTransactionStatus Response Message. . . . . . . . . . . . . . . . . . .184
ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .184
Chapter 11 MassPay API Operation . . . . . . . . . . . . . . . . . . 185
MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
MassPay Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
MassPay Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
Chapter 12 Recurring Payments and Reference Transactions API
Operations187
CreateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .187
CreateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .187
CreateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .203
GetRecurringPaymentsProfileDetails API Operation . . . . . . . . . . . . . . . . . . . .204
GetRecurringPaymentsProfileDetails Request Message . . . . . . . . . . . . . . . .204
GetRecurringPaymentsProfileDetails Response Message . . . . . . . . . . . . . . .205
ManageRecurringPaymentsProfileStatus API Operation . . . . . . . . . . . . . . . . . .217
ManageRecurringPaymentsProfileStatus Request Message . . . . . . . . . . . . . .217
ManageRecurringPaymentsProfileStatus Response Message . . . . . . . . . . . . .218
BillOutstandingAmount API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
BillOutstandingAmount Request Message . . . . . . . . . . . . . . . . . . . . . . .219
BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .220
UpdateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .221
UpdateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .221
UpdateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .232
SetCustomerBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . .233
SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .233
SetCustomerBillingAgreement Response Message. . . . . . . . . . . . . . . . . . .237
SOAP API Developer Reference August 2012 7
Contents
CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .238
CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .238
CreateBillingAgreement API Response Message . . . . . . . . . . . . . . . . . . . .239
GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .240
GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .240
GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .241
BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
DoReferenceTransaction API Operation. . . . . . . . . . . . . . . . . . . . . . . . . . .251
DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .251
DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .265
Chapter 13 RefundTransaction API Operation. . . . . . . . . . . . . 275
RefundTransaction Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
RefundTransaction Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .276
MerchantStoreDetailsTypeFields . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
RefundTransaction Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .278
RefundTransaction Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .278
RefundInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280
Chapter 14 TransactionSearch API Operation . . . . . . . . . . . . . 281
TransactionSearch Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
TransactionSearch Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .282
PayerName Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
TransactionSearch Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .285
TransactionSearch Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .285
Appendix A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 287
General API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
DirectPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .317
DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .318
Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331
Contents
8August 2012 SOAP API Developer Reference
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .347
CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349
AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
ManagePendingTransactionStatus API Errors. . . . . . . . . . . . . . . . . . . . . . . .356
Appendix B Countries and Regions Supported by PayPal . . . . . . 357
Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 365
Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 369
Appendix E AVS and CVV2 Response Codes . . . . . . . . . . . . . 371
AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
AVS Response Codes for Visa, MasterCard, Discover, and American Express . . . .371
AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .372
CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
CVV2 Response Codes for Visa, MasterCard, Discover, and American Express. . . .373
CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .373
About Previous Versions of the API . . . . . . . . . . . . . . . . . . . 375
What’s New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
What’s New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
What’s New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
What’s New in Version 85.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
What’s New in Version 84.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .376
New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .376
New Field in DoReferenceTransactionResponseDetailsType . . . . . . . . . . . . .376
New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .377
What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
SOAP API Developer Reference August 2012 9
Contents
New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
New MerchantStoreDetailsType in DoCapture Request. . . . . . . . . . . . . . . . .377
New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .378
New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .378
What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .379
New Field in PaymentDetailsType in DoDirectPayment Request . . . . . . . . . . . .379
New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .379
What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380
New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .380
New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .380
What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380
Changes to BuyerDetailsType in SetExpressCheckout Request . . . . . . . . . . . .380
New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .381
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .381
What’s New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request 382
Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .383
What’s New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .384
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .384
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .385
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Contents
10 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 11
What’s New
What’s New in Version 93.0
Maintenance release. New 10486 error code added for redirects when the process declines the
transaction: The transaction couldn’t be completed. Please redirect your customer to PayPal.
What’s New in Version 93.0
12 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 13
Preface
About This Guide
The SOAP API Developer Reference describes the PayPal SOAP API.
Intended Audience
This guide is written for developers who are implementing solutions using the SOAP API. It is
written for developers who are implementing solutions using the SOAP API.
Where to Go for More Information
-Express Checkout Integration Guide
-Express Checkout Advanced Features Guide
-Merchant Setup and Administration Guide
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
Documentation Feedback
14 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 15
1PayPal SOAP API Basics
The PayPal SOAP 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). A wide range of development
tools on a variety of platforms support web services.
Like many web services, PayPal SOAP is a combination of client-side and server-side
schemas, hardware and software servers, and core services.
PayPal SOAP High-level Diagram
In an object-oriented processing model, the interface to SOAP requests/responses is an object
in your application’s native programming language. Your third-party SOAP client generates
business-object interfaces and network stubs from PayPal-provided WSDL and XSD files that
specify the PayPal SOAP message structure, its contents, and the PayPal API service bindings.
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 SOAP API Basics
PayPal WSDL/XSD Schema Definitions
1
16 August 2012 SOAP API Developer Reference
PayPal WSDL/XSD Schema Definitions
The PayPal Web Services schema and its underlying eBay Business Language (eBL) base and
core components are required for developing applications with the PayPal Web Services API.
The following are the locations of the WSDL and XSD files.
Location of PayPal WSDL and XSD Files
PayPal SOAP API Definitions
The PayPal SOAP API comprises individual API definitions for specific business functions.
As a foundation, the API relies on eBay Business Language (eBL) base and core components.
The core eBL structures AbstractRequestType and AbstractResponseType are the
basis of the SOAP request and response of each PayPal API. AbstractResponseType is
also the framework for error messages common across all PayPal APIs.
PayPal has made some schema design decisions that can affect how businesses design their
own applications.
-Enumerations: Enumerations are defined directly in the PayPal API schema.
-Troubleshooting information: The PayPal API returns information about elements that
trigger errors.
-Backward compatibility: The PayPal API is versioned so that business applications are
backward compatible when new elements are introduced to the server-side schema.
NOTE: eBL defines many structures that are specific to processing auctions. PayPal’s SOAP
schema includes these definitions to maintain compatibility with eBay’s SOAP and
for possible future joint use of SOAP across both eBay and PayPal. The material
focuses only on those SOAP definitions pertinent to use of the PayPal SOAP API.
Development and Test with the PayPal Sandbox API Service
PayPal Schema https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and
Component Types https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd
https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd
Production with Live PayPal Web Services API Service
PayPal Schema https://www.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and
Component Types http://www.paypal.com/wsdl/eBLBaseComponents.xsd
http://www.paypal.com/wsdl/CoreComponentTypes.xsd
SOAP API Developer Reference August 2012 17
PayPal SOAP API Basics
Security 1
Security
The PayPal SOAP API service is protected to ensure that only authorized PayPal members use
it. There are four levels of security:
1. A required API username (Username field) and API password (Password field).
2. A third required authentication mechanism, which is either one of the following:
– Client-side request signing using a PayPal-issued API Certificate
– Request authentication using an API Signature included in the request (Signature
field)
3. An optional third-party authorization to make the API call on some other account’s behalf
(the optional Subject field).
4. Secure Sockets Layer (SSL) data transport.
A failure of authenticated security at any one of these levels denies access to the PayPal SOAP
API service.
SOAP RequesterCredentials: Username, Password, Signature,
and Subject
For the security of your business, PayPal must verify that merchants or third-party developers
are permitted to initiate a transaction before they make one. PayPal authenticates each request.
If the request cannot be authenticated, a SOAP security fault is returned.
In the SOAP request header, your SOAP client must set the Username, Password elements
to pass an API username/password combination. In addition, you can set the Signature or
Subject elements to specify your API signature string and an optional third-party account
email address for authentication.
The following example shows part of the RequesterCredentials elements. These
elements are required for all SOAP requests.
<SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”>
<Username>api_username</Username>
<Password>api_password</Password>
<Signature>api_signature</Signature>
<Subject>authorizing_account_emailaddress</Subject>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
PayPal SOAP API Basics
SOAP Service Endpoints
1
18 August 2012 SOAP API Developer Reference
RequesterCredentials Authentication Elements in SOAP Header
Related information:
Request Structure
SOAP Service Endpoints
Depending on your chosen authentication mechanism, your SOAP requests must be processed
by different service endpoints.
SOAP Service Endpoints
SOAP Request Envelope
The following diagram illustrates the contents of a PayPal SOAP request envelope.
All PayPal APIs are based on two core structures: AbstractRequestType and
AbstractResponseType.
Element Value Description
<Username>api_username Your API username, which is auto-generated by PayPal when you
apply for a digital certificate to use the PayPal SOAP API. You can
see this value on https://www.paypal.com/ in your Profile under
API Access > API Certificate Information.
<Password> api_password Your API password, which you specify when you apply for a digital
certificate to use the PayPal SOAP API.
<Signature> api_signature Your API signature, if you use one instead of an API Certificate.
<Subject>authorizing_
account_
emailaddress
The email address of a third-party for whom you are sending
requests to the PayPal SOAP API. Your API username must have
been granted permission by this third-party to make any particular
PayPal API request.
Authentication
Mechanism Live Production Endpoint Test (Sandbox) Endpoint
API Signature https://api-3t.paypal.com/2.0/ https://api-3t.sandbox.paypal.com/2.0/
API Certificate https://api.paypal.com/2.0/ https://api.sandbox.paypal.com/2.0/
SOAP API Developer Reference August 2012 19
PayPal SOAP API Basics
Request Structure 1
Diagram of SOAP Request Envelope
Request Structure
The following annotated description of the SOAP request structure shows the elements
required by the PayPal SOAP API.
General Structure of PayPal API SOAP Request
<?xml version=”1.0” encoding=”UTF-8”?>
<SOAP-ENV:Envelope xmlns:xsi= ” http://www.w3.org/2001/XMLSchema-instance”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”
><SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”>
PayPal SOAP API Basics
Request Structure
1
20 August 2012 SOAP API Developer Reference
<Username>api_username</Username>
<Password>api_password</Password>
<Signature/>
<Subject/>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<specific_api_name_Req xmlns=”urn:ebay:api:PayPalAPI”>
<specific_api_name_Request>
<Version xmlns=urn:ebay:apis:eBLBaseComponents”>service_version
</Version>
<required_or_optional_fields xsi:type=”some_type_here”>data
</required_or_optional_fields>
</specific_api_name_Request>
</specific_api_name_Req>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Annotation of Generic SOAP Request
Related information:
SOAP RequesterCredentials: Username, Password, Signature, and Subject
Lines Comment
12, 13 The <Username> and <Password> fields are part of the PayPal SOAP API
<RequesterCredentials> security authentication mechanism you must construct for
every SOAP request header.
14 The <Signature> element should include your API signature string if that is the kind of API
credential you are using.
15 The <Subject> element can specify a third-party PayPal account by whom you are
authorized to make this request.
19 through 27 The SOAP request for every PayPal API follows this element-naming pattern. The API’s
specific name is appended with Req, and in this element the specific_api_name_Request is
nested. Each specific_api_name_Request has a corresponding
specific_api_name_RequestType.
22 The number of the PayPal SOAP API version is required on each SOAP request.
This version number is the value of ns:version in
https://www.paypal.com/wsdl/PayPalSvc.wsdl.
24 For details about required and optional elements and values for specific requests, see the
description of individual APIs.
SOAP API Developer Reference August 2012 21
PayPal SOAP API Basics
SOAP Message Style: doc-literal 1
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.
Response Structure
The following is an annotated description of the structure of a SOAP response from the PayPal
API where response is Success:
<?xml version=”1.0”?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV= ”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”
xmlns:cc=”urn:ebay:apis:CoreComponentTypes”
xmlns:wsu=”http://schemas.xmlsoap.org/ws/2002/07/utility”
xmlns:saml=”urn:oasis:names:tc:SAML:1.0:assertion”
xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”
xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xmlns:ebl=”urn:ebay:apis:eBLBaseComponents”
xmlns:ns=”urn:ebay:api:PayPalAPI”>
<SOAP-ENV:Header>
<Security
xmlns=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xsi:type=”wsse:SecurityType”
/>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials
xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”
/>
</RequesterCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body id=”_0”>
<specific_api_name_Response xmlns=”urn:ebay:api:PayPalAPI”>
<Timestamp xmlns=”urn:ebay:api:PayPalAPI”> dateTime_in_UTC/GMT
</TIMESTAMP>
<Ack xmlns=”urn:ebay:apis:eBLBaseComponents”>Success</Ack>
<Version xmlns=”urn:ebay:apis:eBLBaseComponents”>
serviceVersion
</Version>
<CorrelationId xmlns=”urn:ebay:apis:eBLBaseComponents”>
PayPal SOAP API Basics
Error Responses
1
22 August 2012 SOAP API Developer Reference
applicationCorrelation
</CorrelationID>
<Build xmlns=”urn:ebay:apis:eBLBaseComponents”>
api_build_number
</Build>
<elements_for_specific_api_response> data
</elements_for_specific_api_response>
</specific_api_name_Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Annotation of Generic SOAP Response
Related information:
Error Responses
Error Responses
If a request is malformed or contains 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 structure of error messages are as follows:
Lines Comment
22 and 31 The specific_api_name_Response start and end elements.
23 Each API response contains a timestamp with its date and time in UTC/GMT.
24 The <Ack> element contains the string Success after the corresponding request has been
successfully processed.
In the case of errors, Ack is set to a value other than Success, and the response body contains
an <Errors> element with information to help you troubleshoot the cause of the error. See
“Error Responses” on page 22.
26 The <CorrelationID> element contains information about the PayPal application that
processed the request.
Use the value of this element if you need to troubleshoot a problem with one of your requests.
27 through 30 The different PayPal APIs return different structures depending on their response definitions.
For detailed information, see the description of the individual APIs.
NOTE: Because a field is defined in the formal structure of an API response, this does not
mean that the field is necessarily returned. Data are returned in a response only if
PayPal has recorded data that corresponds to the field.
SOAP API Developer Reference August 2012 23
PayPal SOAP API Basics
Error Responses 1
The most important of these additional elements are as follows:
-ShortMessage
-LongMessage
-ErrorCode
Additional information can appear as part of ErrorParametersType. For example, if the
error in ParamID is ProcessorResponse, the Value would contain the processor-specific
error, such as 0091. Values set in the ErrorParametersType are not set by PayPal; rather,
they are passed through from the source.
NOTE: PayPal only passes selected values in ErrorParametersType.
The following example shows the error response if your API username and password do not
match a legitimate API username and password on file with PayPal.
Example of SOAP Error Response: Bad Username or Password
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV: Envelope details not shown >
<S OAP-ENV:Header>... details not shown.</SOAP-ENV:Header>
<SOAP-ENV:Body id="_0">
<GetTransactionDetailsResponse xmlns="urn:ebay:api:PayPalAPI">
<Timestamp xmlns="urn:ebay:apis:eBLBaseComponents">
2005-02-09T21:51:26Z
</Timestamp>
<Ack xmlns="urn:ebay:apis:eBLBaseComponents">Failure</Ack>
<Errors
xmlns="urn:ebay:apis:eBLBaseComponents"
xsi:type="ebl:ErrorType">
<ShortMessage xsi:type="xs:string">
Authentication/Authorization Failed
</ShortMessage>
<LongMessage xsi:type="xs:string">
Username/Password is incorrect
</LongMessage>
<ErrorCode xsi:type="xs:token">10002</ErrorCode>
<SeverityCode xmlns="urn:ebay:apis:eBLBaseComponents">
Error </SeverityCode>
PayPal SOAP API Basics
CorrelationID for Reporting Problems to PayPal
1
24 August 2012 SOAP API Developer Reference
</Errors>
<CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents">
debugging_info
</CorrelationID>
<Version xmlns="urn:ebay:apis:eBLBaseComponents">
1.000000
</Version>
<Build xmlns="urn:ebay:apis:eBLBaseComponents">1.0006</Build>..
other elements in response.
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Related information:
Response Structure
CorrelationID for Reporting Problems to PayPal
The value returned in CorrelationID is important for PayPal to determine the precise cause
of any error you might encounter. If you have to troubleshoot a problem with your requests,
we suggest that you capture the value of CorrelationID so you can report it to PayPal.
UTF-8 Character Encoding
The PayPal API assumes that all data in requests is in Unicode, specifically, the Unicode (or
UCS) Transformation Format, 8-bit encoding form (UTF-8).
In responses, the API always returns data in UTF-8.
Date/Time Formats
The PayPal SOAP API schema defines date/time values as Coordinated Universal Time
(UTC/GMT), using ISO 8601 format, and of type ns:dateTime. An example date/time
stamp is 2006-08-24T05:38:48Z
Core Currency Amount Data Type
The core currency amount data type is called BasicAmountType and is derived from
string. All currency amount fields have the following structure:
1. The currencyID attribute is required.
2. The amount must have two decimal places.
SOAP API Developer Reference August 2012 25
PayPal SOAP API Basics
Core Currency Amount Data Type 1
3. The decimal separator must be a period (“.”).
4. You must not use any thousands separator.
5. BasicAmountType has a data type of ebl:CurrencyCodeType, which defines a large
number of different currency codes. However, for your processing to succeed, you must set
currencyCode to a valid currency code. Some APIs support only a subset of currencies.
Here is an example. (The field name Amount is an example; actual field names can vary
depending on the specific API.)
<Amount currencyID=”currencyCode”>3.00</Amount>
PayPal SOAP API Basics
Core Currency Amount Data Type
1
26 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 27
2AddressVerify API Operation
The AddressVerify API operation confirms whether a postal address and postal code match
those of the specified PayPal account holder.
AddressVerify Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
AddressVerifyRequest Fields
Field Description
Email ebl:EmailAddressType
(Required) Email address of a PayPal member to verify.
Character length and limitations: 255 single-byte characters maximum with the input
mask: ?@?.??
AddressVerify API Operation
AddressVerify Response Message
2
28 August 2012 SOAP API Developer Reference
AddressVerify Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Street xs:string
(Required) First line of the billing or shipping postal address to verify. To pass
verification, the value of Street must match the first 3 single-byte characters of a
postal address on file for the PayPal member.
Character length and limitations: 35 single-byte characters maximum, including
alphanumeric plus - , . ‘ # \. Whitespace and case of input value are ignored.
Zip xs:string
(Required) Postal code to verify. To pass verification, the value of Zip must match
the first 5 single-byte characters of the postal code of the verified postal address for
the verified PayPal member.
Character length and limitations: 16 single-byte characters maximum. Whitespace
and case of input value are ignored.
Field Description
SOAP API Developer Reference August 2012 29
AddressVerify API Operation
AddressVerify Response Message 2
AddressVerify Response Fields
Field Description
ConfirmationCode ebl:AddressStatuscodeType
Indicates whether the address is a confirmed address on file at PayPal. It is one of the
following values:
-None – The request value of the Email element does not match any email address
on file at PayPal.
-Confirmed – If the response value of the StreetMatch element is Matched,
the entire postal address is confirmed.
-Unconfirmed – PayPal responds that the postal address is unconfirmed.
NOTE: The values Confirmed and Unconfirmed both indicate that the member
email address passed verification.
StreetMatch ebl:MatchStatusCodeType
Indicates whether the street address matches address information on file at PayPal. It
is one of the following values:
-None – The request value of the Email element does not match any email address
on file at PayPal. No comparison of other request values was made.
-Matched – The request value of the Street element matches the first 3 single-byte
characters of a postal address on file for the PayPal member.
-Unmatched – The request value of the Street element does not match any
postal address on file for the PayPal member.
ZipMatch ebl:MatchStatusCodeType
Indicates whether the zip address matches address information on file at PayPal. It is
one of the following values:
-None – The request value of the Street element was unmatched. No comparison
of the Zip element was made.
-Matched – The request value of the Zip element matches the zip code of the
postal address on file for the PayPal member.
-Unmatched – The request value of the Zip element does not match the zip code
of the postal address on file for the PayPal member.
CountryCode ebl:CountryCodeType
Country code (ISO 3166) on file for the PayPal email address.
Character length and limitations: 2 single-byte characters
PayPalToken xs:string
The token contains encrypted information about the member’s email address and
postal address. If you pass the value of the token in the HTML variable
address_api_token of Buy Now buttons, PayPal prevents the buyer from using
an email address or postal address other than those that PayPal verified with this API
call. The token is valid for 24 hours.
Character length and limitations: 94 single-byte characters
AddressVerify API Operation
AddressVerify Response Message
2
30 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 31
3Authorization and Capture API
Operation Reference
The Authorization and Capture API operations describe the PayPal API operations related to
delayed payment settlement:
DoCapture API Operation
Captures an authorized payment.
DoCapture Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Authorization and Capture API Operation Reference
DoCapture API Operation
3
32 August 2012 SOAP API Developer Reference
DoCapture Request Fields
Field Description
AuthorizationID xs:string
(Required) Authorization identification number of the payment you want to capture.
This is the transaction ID returned from DoExpressCheckoutPayment,
DoDirectPayment, or CheckOut. For point-of-sale transactions, this is the
transaction ID returned by the CheckOut call when the payment action is
Authorization.
Character length and limitations: 19 single-byte characters maximum
Amount ebl:BasicAmountType
(Required) Amount to capture.
NOTE: 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: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CompleteType ebl:CompleteCodeType
(Required) Indicates whether or not this is your last capture. It is one of the following
values:
-Complete – This is the last capture you intend to make.
-NotComplete – You intend to make additional captures.
NOTE: If Complete, any remaining amount of the original authorized transaction is
automatically voided and all remaining open authorizations are voided.
InvoiceID xs:string
(Optional) Your invoice number or other identification number that is displayed to
you and to the buyer in their transaction history. The value is recorded only if the
authorization you are capturing is an Express Checkout order authorization.
NOTE: This value on DoCapture overwrites a value previously set on
DoAuthorization.
Character length and limitations: 127 single-byte alphanumeric characters
Note xs:string
(Optional) An informational note about this settlement that is displayed to the buyer
in email and in their transaction history.
Character length and limitations: 255 single-byte characters
SOAP API Developer Reference August 2012 33
Authorization and Capture API Operation Reference
DoCapture API Operation 3
SoftDescriptor xs:string
(Optional) Per transaction description of the payment that is passed to the buyer’s
credit card statement.
If you provide a value in this field, the full descriptor displayed on the buyer’s
statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
Character length and limitations: The soft descriptor can contain only the following
characters:
-Alphanumeric characters
-- (dash)
-* (asterisk)
-. (period)
- {space}
If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
-The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
-The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
-The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow
MerchantStoreDetail
s
ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
Authorization and Capture API Operation Reference
DoCapture API Operation
3
34 August 2012 SOAP API Developer Reference
MerchantStoreDetailsTypeFields
DoCapture Response Message
NOTE: If you use version 56.0 or later of the DoCaptue API, only the authorization ID,
transaction ID, transaction type, payment date, gross amount, and payment status are
guaranteed to be returned. If you need the values of other fields and they are not
returned, you can obtain their values later by calling GetTransactionDetails or
by using the reporting mechanism. Not applicable to point of sale transactions.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Field Description
StoreID xs:string
Identifier of the merchant store at which the refund is given. This field is
required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
TerminalID xs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
SOAP API Developer Reference August 2012 35
Authorization and Capture API Operation Reference
DoCapture API Operation 3
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoCapture Response Fields
Field Description
AuthorizationID xs:string
Authorization identification number you specified in the request.
Character length and limits: 19 single-byte characters maximum
PaymentInfo ebl:PaymentInfoType
Information about the payment.
Authorization and Capture API Operation Reference
DoCapture API Operation
3
36 August 2012 SOAP API Developer Reference
PaymentInfoTypeFields
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
ParentTransactionID xs:string
Parent or related transaction identification number. This field is populated for the
following transaction types:
-Reversal. Capture of an authorized transaction.
-Reversal. Reauthorization of a transaction.
-Capture of an order. The value of ParentTransactionID is the original
OrderID.
-Authorization of an order. The value of ParentTransactionID is the original
OrderID.
-Capture of an order authorization.
-Void of an order. The value of ParentTransactionID is the original OrderID.
Character length and limitations: 16 digits
Only authorization of an order and capture of an order authorization apply to point-
of-sale transactions.
ReceiptID xs:string
Receipt identification number.
Character length and limitations: 16 digits
Empty for point-of-sale transactions.
TransactionType ns:PaymentTransactionCodeType
The type of transaction. It is one of the following values:
-cart
-express-checkout
Character length and limitations:15 single-byte characters
Field Description
SOAP API Developer Reference August 2012 37
Authorization and Capture API Operation Reference
DoCapture API Operation 3
PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
-none
-echeck
-instant
Character length and limitations: 7 single-byte characters
PaymentDate xs:dateTime
Time/date stamp of payment. For example: 2006-08-15T17:23:15Z
GrossAmount ebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile. Shipping and taxes do not apply to point-of-sale transactions.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
FeeAmount ebl:BasicAmountType
PayPal fee amount charged for the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
ExchangeRate xs:string
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the customer chooses to pay with a currency other than
the non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: A decimal that does not exceed 17 characters,
including decimal point
Field Description
Authorization and Capture API Operation Reference
DoCapture API Operation
3
38 August 2012 SOAP API Developer Reference
PaymentStatus ebl:PendingStatusCodeType
Status of the payment. It is one of the following values:
NOTE: In a successful DoCapture response for a point-of-sale authorization, the only
value value is Completed.
-None – No status
-Canceled-Reversal – This means a reversal has been canceled. For example,
you won a dispute with the customer, and the funds for the transaction that was
reversed have been returned to you.
-Completed – The payment has been completed, and the funds have been added
successfully to your account balance. This is the only value status for point-of-
sale transactions.
-Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the PendingReason
element.
-Expired – The authorization period for this payment has been reached.
-Failed – The payment has failed. This happens only if the payment was made
from your customer’s bank account.
-Pending – The payment is pending. See the PendingReason field for more
information.
-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.
Field Description
SOAP API Developer Reference August 2012 39
Authorization and Capture API Operation Reference
DoCapture API Operation 3
PendingReason ebl:PendingStatusCodeType
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending. This field does not apply to capturing point-of-sale authorizations,
which do not create pending payments.
Reason the payment is pending. It is one of the following values:
-none: – No pending reason.
-address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
-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.
Field Description
Authorization and Capture API Operation Reference
DoAuthorization API Operation
3
40 August 2012 SOAP API Developer Reference
DoAuthorization API Operation
Authorize a payment.
DoAuthorization Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoAuthorization Request Fields
Field Description
TransactionID xs:string
(Required) Value of the order’s transaction identification number returned by PayPal.
Character length and limitations: 19 single-byte characters
Amount ebl:BasicAmountType
(Required) Amount to authorize.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TransactionEntity ebl:TransactionEntityType
(Optional) Type of transaction to authorize. The only allowable value is Order,
which means that the transaction represents a buyer order that can be fulfilled over 29
days.
SOAP API Developer Reference August 2012 41
Authorization and Capture API Operation Reference
DoAuthorization API Operation 3
DoAuthorization Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoAuthorization Response Fields
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
TransactionID xs:string
Authorization identification number.
Amount ebl:BasicAmountType
Amount you specified in the request.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Authorization and Capture API Operation Reference
DoAuthorization API Operation
3
42 August 2012 SOAP API Developer Reference
AuthorizationInfo Fields
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
PaymentStatus ebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
-None – No status.
-Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
-Completed – 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 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 the buyer’s bank account.
-In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field for more
information.
-Refunded – You refunded the payment.
-Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element specifies the reason for the
reversal.
-Processed – A payment has been accepted.
-Voided – An authorization for this transaction has been voided.
Field Description
SOAP API Developer Reference August 2012 43
Authorization and Capture API Operation Reference
DoAuthorization API Operation 3
PendingReason ebl:PendingStatusCodeType
Reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set
such that you want to manually accept or deny each of these payments. To
change your preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-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.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by
PayPal for risk.
-unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
-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.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
ProtectionEligibility xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payment and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
Field Description
Authorization and Capture API Operation Reference
DoReauthorization API Operation
3
44 August 2012 SOAP API Developer Reference
DoReauthorization API Operation
DoReauthorization Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ProtectionEligibility
Type
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
both Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's
Seller Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is available since version 64.4.
Field Description
SOAP API Developer Reference August 2012 45
Authorization and Capture API Operation Reference
DoReauthorization API Operation 3
DoReauthorization Request Fields
DoReauthorization Response Message
NOTE: Not all fields shown are available for use. Only use fields described in the
documentation.
DoReauthorization Response Fields
Field Description
AuthorizationID xs:string
(Required) Value of a previously authorized transaction identification number
returned by PayPal.
Character length and limitations: 19 single-byte characters
Amount ebl:BasicAmountType
(Required) Amount to reauthorize.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
AuthorizationID xs:string
New authorization identification number.
Character length and limits:19 single-byte characters
Authorization and Capture API Operation Reference
DoReauthorization API Operation
3
46 August 2012 SOAP API Developer Reference
AuthorizationInfo Fields
Field Description
PaymentStatus ebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
-None – No status.
-Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
-Completed – 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 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 the buyer’s bank account.
-In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field for more
information.
-Refunded – You refunded the payment.
-Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element specifies the reason for the
reversal.
-Processed – A payment has been accepted.
-Voided – An authorization for this transaction has been voided.
SOAP API Developer Reference August 2012 47
Authorization and Capture API Operation Reference
DoReauthorization API Operation 3
PendingReason ebl:PendingStatusCodeType
Reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set
such that you want to manually accept or deny each of these payments. To
change your preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-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.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by
PayPal for risk.
-unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
-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.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
ProtectionEligibility xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payment and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
Field Description
Authorization and Capture API Operation Reference
DoVoid API Operation
3
48 August 2012 SOAP API Developer Reference
DoVoid API Operation
Void an order or an authorization.
DoVoid Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ProtectionEligibility
Type
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
both Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's
Seller Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is available since version 64.4.
Field Description
SOAP API Developer Reference August 2012 49
Authorization and Capture API Operation Reference
DoVoid API Operation 3
DoVoid Request Fields
DoVoid Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Field Description
AuthorizationID xs:string
(Required) Original authorization ID specifying the authorization to void or, to void
an order, the order ID.
IMPORTANT: If you are voiding a transaction that has been reauthorized, use the ID
from the original authorization, and not the reauthorization.
Character length and limitations: 19 single-byte characters
Note xs:string
(Optional) Informational note about this void that is displayed to the buyer in email
and in their transaction history.
Character length and limitations: 255 single-byte characters
Authorization and Capture API Operation Reference
DoVoid API Operation
3
50 August 2012 SOAP API Developer Reference
DoVoidResponse Fields
Field Description
AuthorizationID xs:string
Authorization identification number you specified in the request.
Character length and limitations: 19 single-byte characters
SOAP API Developer Reference August 2012 51
4DoDirectPayment API Operation
The DoDirectPayment API Operation enables you to process a credit card payment.
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoDirectPayment API Operation
DoDirectPayment Request Message
4
52 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 53
DoDirectPayment API Operation
DoDirectPayment Request Message 4
DoDirectPayment API Operation
DoDirectPayment Request Message
4
54 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 55
DoDirectPayment API Operation
DoDirectPayment Request Message 4
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoDirectPayment API Operation
DoDirectPayment Request Message
4
56 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoDirectPayment Request Fields
Field Description
PaymentAction ebl:PaymentActionCodeType
(Optional) How you want to obtain payment. It is one of the following values:
-Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
-Sale – This is a final sale for which you are requesting payment (default).
NOTE: Order is not allowed for Direct Payment.
Character length and limit: Up to 13 single-byte alphabetic characters
SOAP API Developer Reference August 2012 57
DoDirectPayment API Operation
DoDirectPayment Request Message 4
CreditCard ebl:CreditCardDetailsType
(Required) Information about the credit card to be charged.
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the credit card to be charged.
IPAddress xs:string
(Required) IP address of the buyer’s browser.
NOTE: PayPal records this IP addresses as a means to detect possible fraud.
Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
MerchantSessionId xs:string
(Optional) Your customer session identification token.
NOTE: PayPal records this optional session identification token as an additional
means to detect possible fraud.
Character length and limitations: 64 single-byte numeric characters
ReturnFMFDetails xs:boolean
(Optional) Flag to indicate whether you want the results returned by Fraud
Management Filters. By default, you do not receive this information. It is one of the
following values:
-0 – Do not receive FMF details (default).
-1 – Receive FMF details.
ThreeDSecureRequest ns:ThreeDSecureRequestType
(Optional) Information about 3-D Secure settings (UK only).
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
58 August 2012 SOAP API Developer Reference
CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover,
and Visa are allowable. For Canada, only MasterCard and Visa are allowable and
Interac debit cards are not supported. It is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro: See note.
NOTE: If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber xs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2 xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
SOAP API Developer Reference August 2012 59
DoDirectPayment API Operation
DoDirectPayment Request Message 4
PayerInfoType Fields
StartYear xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumber xs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
Payer ebl:EmailAddressType
(Required) Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
(Optional) Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PayerStatus ebl:PayPalUserStatusCodeType
(Optional) Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerName ebl:PersonNameType
(Optional) First and last name of buyer.
PayerCountry ebl:CountryCodeType
(Optional) Buyer’s country of residence in the form of ISO standard 3166 two-
character country codes.
Character length and limitations: 2 single-byte characters
PayerBusiness xs:string
(Optional) Buyer’s business name.
Character length and limitations: 127 single-byte characters
Address xs:string
(Optional) Buyer’s shipping address information.
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
60 August 2012 SOAP API Developer Reference
PayerNameType Fields
AddressType Fields
Field Description
Salutation xs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
(Required) State or province.
Character length and limitations: 40 single-byte characters
Country ebl:CountryCodeType
(Required) Country code.
Character length and limitationst: 2 single-byte characters
SOAP API Developer Reference August 2012 61
DoDirectPayment API Operation
DoDirectPayment Request Message 4
PaymentDetailsType Fields
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
OrderTotal ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. This field must be set to a value
greater than 0.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ItemTotal ebl:BasicAmountType
(Optional) Sum of cost of all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
62 August 2012 SOAP API Developer Reference
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a non-
negative currency amount or null if you offer insurance options.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
InsuranceTotal is available since version 53.0.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingDiscount is available since version 53.0.
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
OrderDescription xs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
SOAP API Developer Reference August 2012 63
DoDirectPayment API Operation
DoDirectPayment Request Message 4
Custom xs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL from
your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ns:AddressType
(Optional) Address to which the order is shipped.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.
Recurring ns:RecurringFlagType
(Optional) Flag to indicate a recurring transaction. It is one of the following values:
-Any value other than Y – This is not a recurring transaction (default).
-Y – This is a recurring transaction.
NOTE: To pass Y in this field, you must have established a billing agreement with the
buyer specifying the amount, frequency, and duration of the recurring
payment.
This field is introduced in version 80.0 of the API.
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
64 August 2012 SOAP API Developer Reference
PaymentDetailsItemType Fields
Field Description
Name xs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
Description is available since version 53.0.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
(Optional) Cost of item.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:integer
(Optional) Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
EbayItemPayment
DetailsItem
eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.
SOAP API Developer Reference August 2012 65
DoDirectPayment API Operation
DoDirectPayment Request Message 4
EbayItemPaymentDetailsItemType Fields
AddressType (Shipping) Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters
AuctionTransaction
Id
xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters
Field Description
Name xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address; may be required for other countries.
Character length and limitations: 20 single-byte characters
DoDirectPayment API Operation
DoDirectPayment Request Message
4
66 August 2012 SOAP API Developer Reference
ThreeDSecureRequest Fields (U.K. Merchants Only)
Country ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
AuthStatus3ds xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the PAResStatus value
returned by cmpi_authenticate. Otherwise, set this field to blank.
MpiVendor3ds xs:string
(Optional) A value returned by the Cardinal Centinel. Set this field to the
Enrolled value returned by cmpi_lookup.
Cavv xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Cavv value returned by
cmpi_authenticate. Otherwise, set this field to blank.
Eci3ds xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the EciFlag value returned
by cmpi_authenticate. Otherwise, set this field to the EciFlag value
returned by cmpi_lookup.
XID xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Xid value returned by
cmpi_authenticate. Otherwise, set this field to blank.
Field Description
SOAP API Developer Reference August 2012 67
DoDirectPayment API Operation
DoDirectPayment Response Message 4
DoDirectPayment Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoDirectPayment API Operation
DoDirectPayment Response Message
4
68 August 2012 SOAP API Developer Reference
DoDirectPayment Response Fields
Related information:
AVS Response Codes
AVS Response Codes for Visa, MasterCard, Discover, and American Express
AVS Response Codes for Maestro
FMFDetailsType Fields
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
NOTE: If the PaymentAction of the request was Authorization, the value of
TransactionID is your AuthorizationID for use with the Authorization and
Capture APIs.
Character length and limitations: 19 single-byte characters
Amount ebl:BasicAmountType
This value is the amount of the payment as specified by you on
DoDirectPaymentRequest for reference transactions with direct payments.
AVSCode xs:string
Address Verification System response code.
Character length and limitations: 1 single-byte alphanumeric character
CVV2Code xs:string
Result of the CVV2 check by PayPal.
FMFDetails ebl:FMFDetailsType
Fraud filter details.
PaymentAdviceCode xs:string
Response code from the processor when a recurrng transaction is declined. For details
on the codes, see https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-
content&content_ID=merchant/cc_compliance_error_codes
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment.
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment.
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
SOAP API Developer Reference August 2012 69
DoDirectPayment API Operation
DoDirectPayment Response Message 4
RiskFilterListType Fields
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.
Field Description
ID xs:int
Filter ID. It is one of the following values:
-1 - AVS No Match
-2 - AVS Partial Match
-3 - AVS Unavailable/Unsupported
-4 - Card Security Code (CSC) Mismatch
-5 - Maximum Transaction Amount
-6 - Unconfirmed Address
-7 - Country Monitor
-8 - Large Order Number
-9 - Billing/Shipping Address Mismatch
-10 - Risky ZIP Code
-11 - Suspected Freight Forwarder Check
-12 - Total Purchase Price Minimum
-13 - IP Address Velocity
-14 - Risky Email Address Domain Check
-15 - Risky Bank Identification Number (BIN) Check
-16 - Risky IP Address Range
-17 - PayPal Fraud Model
Name xs:string
Filter name.
Description xs:string
Filter description.
Field Description
DoDirectPayment API Operation
DoDirectPayment Response Message
4
70 August 2012 SOAP API Developer Reference
ThreeDSecure Response Fields
Field Description
VPAS Visa Payer Authentication Service status. The value indicates whether
Verified by Visa confirms that the information received is acceptable. It is
eturned only for Verified by Visa transactions.
Authentication:
-Good result – 2 or D
-Bad result – 1
Attempted authentication:
-Good result – 3, 6, 8, A, or C
-Bad result – 4, 7, or 9
No liability shift: Blank, 0, or B
EciSubmitted3ds Electronic Commerce Indicator (ECI) that PayPal submitted with the
payment authorisation request. This might not be the same value received
from the merchant. In rare cases, PayPal is required to use a different ECI
for authorisation based on the full set of 3-D Secure values provided from
the cmpi_authenticate request.
MasterCard:
-01 – Merchant Liability
-02 – Issuer Liability
Visa:
-05 – Issuer Liability
-06 – Issuer Liability
-07 – Merchant Liability
SOAP API Developer Reference August 2012 71
5DoNonReferencedCredit API
Operation
The DoNonReferencedCredit API issues a credit to a card not referenced by the original
transaction.
DoNonReferencedCredit Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
72 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 73
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message 5
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoNonReferencedCredit Request Fields
Field Description
Amount ns:BasicAmountType
(Required) Total of order, including shipping, handling, and tax. Amount =
NetAmount + ShippingAmount + TaxAmount
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
74 August 2012 SOAP API Developer Reference
NetAmount ns:BasicAmountType
(Optional) Total amount of all items in this transaction.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
TaxAmount ns:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Character length and limitations: The value must be zero or greater and cannot exceed
$10,000 USD in any currency. No currency symbol. Must have 2 decimal places,
decimal separator must be a period (.), and the optional thousands separator must be a
comma (,).
ShippingAmount ns:BasicAmountType
(Optional) Total shipping costs in this transaction.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Character length and limitations: Value must be zero or greater and cannot exceed
$10,000 USD in any currency. No currency symbol. Must have 2 decimal places,
decimal separator must be a period (.), and the optional thousands separator must be a
comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
CreditCard ebl:CreditCardDetailsType
(Required) Information about the credit card to be charged.
ReceiverEmail xs:string
Comment xs:string
(Optional) Field used by merchant to record why this credit was issued to a buyer. It
is similar to a “memo” field (freeform text or string field).
Field Description
SOAP API Developer Reference August 2012 75
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message 5
CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover,
and Visa are allowable. For Canada, only MasterCard and Visa are allowable and
Interac debit cards are not supported. It is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro: See note.
NOTE: If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber xs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2 xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
76 August 2012 SOAP API Developer Reference
PayerNameType Fields
PayerInfoType Fields
StartYear xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumber xs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
Salutation xs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
(Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
(Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
Payer ns:EmailAddressType
(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FirstName ns:PersonNameType
(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
Field Description
SOAP API Developer Reference August 2012 77
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message 5
AddressType Fields
LastName ns:PersonNameType
(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Address ns:AddressType
(Required) Buyer’s billing address information.
Field Description
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
(Required) State or province.
Character length and limitations: 40 single-byte characters
Country ebl:CountryCodeType
(Required) Country code.
Character length and limitationst: 2 single-byte characters
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
DoNonReferencedCredit API Operation
DoNonReferencedCredit Response Message
5
78 August 2012 SOAP API Developer Reference
DoNonReferencedCredit Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoNonReferencedCredit Response Fields
Field Description
TransactionID ns:TransactionId
Unique identifier of a transaction.
Character length and limitations: 17 single-byte alphanumeric characters.
Amount ns:BasicAmountType
Total of order, including shipping, handling, and tax.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
SOAP API Developer Reference August 2012 79
6ExpressCheckout API Operations
Express Checkout API operations include SetExpressCheckout,
GetExpressCheckoutDetails, and DoExpressCheckoutPayment.
SetExpressCheckout API Operation
The SetExpressCheckout API operation initiates an Express Checkout transaction.
SetExpressCheckout Request Message
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
80 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 81
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
82 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 83
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
84 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 85
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
86 August 2012 SOAP API Developer Reference
SetExpressCheckout Request Fields
Field Description
OrderTotal
(deprecated)
ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. If the transaction does not include a
one-time purchase such as when you set up a billing agreement for a recurring
payment, set this field to 0.
NOTE: 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: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is deprecated since version 53.0. Use OrderTotal in
PaymentDetailsType instead.
MaxAmount ebl:BasicAmountType
(Optional) The expected maximum total amount of the complete order, including
shipping cost and tax charges. If the transaction includes one or more one-time
purchases, this field is ignored.
For recurring payments, you should pass the expected average transaction amount
(default 25.00). PayPal uses this value to validate the buyer’s funding source.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
NOTE: This field is required when implementing the Instant Update API callback.
PayPal recommends that the maximum total amount be slightly greater than
the sum of the line-item order details, tax, and the shipping options of greatest
value.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
OrderDescription
(deprecated)
xs:string
(Optional) Description of items the buyer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
This field is deprecated since version 53.0. Use OrderDescription in
PaymentDetailsType instead.
SOAP API Developer Reference August 2012 87
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
Custom (deprecated)xs:string
(Optional) A free-form field for your own use, such as a tracking number or other
value you want PayPal to return on GetExpressCheckoutDetails response and
response.
Character length and limitations: 256 single-byte alphanumeric characters
This field is deprecated since version 53.0. Use Custom in PaymentDetailsType
instead.
InvoiceID (deprecated)xs:string
(Optional) Your own unique invoice or tracking number. PayPal returns this value to
you on DoExpressCheckoutPayment response. If the transaction does not include
a one-time purchase, this field is ignored.
Character length and limitations: 127 single-byte alphanumeric characters
This field is deprecated since version 53.0. Use InvoiceID in
PaymentDetailsType instead.
ReturnURL xs:string
(Required) URL to which the buyer’s browser is returned after choosing to pay with
PayPal. For digital goods, you must add JavaScript to this page to close the in-context
experience.
NOTE: PayPal recommends that the value be the final review page on which the
buyer confirms the order and payment or billing agreement.
Character length and limitations: 2048 single-byte characters
CancelURL xs:string
(Required) URL to which the buyer is returned if the buyer does not approve the use
of PayPal to pay you. For digital goods, you must add JavaScript to this page to close
the in-context experience.
NOTE: PayPal recommends that the value be the original page on which the buyer
chose to pay with PayPal or establish a billing agreement.
Character length and limitations: 2048 single-byte characters
CallbackURL xs:string
(Optional) URL to which the callback request from PayPal is sent. It must start with
HTTPS for production integration. It can start with HTTPS or HTTP for sandbox
testing.
Character length and limitations: 1024 single-byte characters
This field is available since version 53.0.
CallbackTimeout int
(Optional) An override for you to request more or less time to be able to process the
callback request and respond. The acceptable range for the override is 1 to 6 seconds.
If you specify a value greater than 6, PayPal uses the default value of 3 seconds.
Character length and limitations: An integer between 1 and 6
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
88 August 2012 SOAP API Developer Reference
Address (deprecated)ebl:AddressType
(Optional) Buyer’s shipping address.If you include a shipping address and set the
AddressOverride element on the request, PayPal returns this same address in
GetExpressCheckoutDetailsResponse.
This field is deprecated since version 53.0. Use ShipToAddress in
PaymentDetailsType instead.
ReqConfirmShipping xs:string
Indicates whetheror not you require the buyer’s shipping address on file with PayPal
be a confirmed address. For digital goods, this field is required, and you must set it to
0. It is one of the following values:
-0 – You do not require the buyer’s shipping address be a confirmed address.
-1 – You require the buyer’s shipping address be a confirmed address.
NOTE: Setting this field overrides the setting you specified in your Merchant
Account Profile.
Character length and limitations: 1 single-byte numeric character
NoShipping xs:string
Determines where or not PayPal displays shipping address fields on the PayPal pages.
For digital goods, this field is required, and you must set it to 1. It is one of the
following values:
-0 – PayPal displays the shipping address on the PayPal pages.
-1 – PayPal does not display shipping address fields whatsoever.
-2 – If you do not pass the shipping address, PayPal obtains it from the buyer’s
account profile.
Character length and limitations: 4 single-byte numeric characters
FlatRateShippingOpt
ions
ebl:ShippingOptionsType
Flat rate shipping options. This field is required if you are specifying the Callback
URL.
AllowNote xs:string
(Optional) Enables the buyer to enter a note to the merchant on the PayPal page
during checkout. The note is returned in the GetExpressCheckoutDetails
response and the DoExpressCheckoutPayment response. It is one of the following
values:
-0 – The buyer is unable to enter a note to the merchant.
-1 – The buyer is able to enter a note to the merchant.
Character length and limitations: 1 single-byte numeric character
This field is available since version 53.0.
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the payment.
Field Description
SOAP API Developer Reference August 2012 89
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
AddressOverride xs:string
(Optional) Determines whether or not the PayPal pages should display the shipping
address set by you in this SetExpressCheckout request, not the shipping address on
file with PayPal for this buyer. Displaying the PayPal street address on file does not
allow the buyer to edit that address. It is one of the following values:
-0 – The PayPal pages should not display the shipping address.
-1 – The PayPal pages should display the shipping address.
Character length and limitations: 1 single-byte numeric character
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
90 August 2012 SOAP API Developer Reference
LocaleCode xs:string
(Optional) Locale of pages displayed by PayPal during Express Checkout. It is one of
the following country code values supported by PayPal (default is US):
-AU – Australia
-AT – Austria
-BE – Belgium
-BR – Brazil
-CA – Canada
-CH – Switzerland
-CN – China
-DE – Germany
-ES – Spain
-GB – United Kingdom
-FR – France
-IT – Italy
-NL – Netherlands
-PL – Poland
-PT – Portugal
-RU – Russia
-US – United States
-The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)
Character length and limitations: 2-character country code
PageStyle xs:string
(Optional) Name of the Custom Payment Page Style for payment pages associated
with this button or link. It corresponds to the HTML variable page_style for
customizing payment pages. It is the same name as the Page Style Name you chose to
add or edit the page style in your PayPal Account profile.
Character length and limitations: 30 single-byte alphabetic characters
Field Description
SOAP API Developer Reference August 2012 91
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
cpp-header-image xs:string
(Optional) URL for the image you want to appear at the top left of the payment page.
The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored on a secure (https) server. If you
do not specify an image, the business name displays.
Character length and limitations: 127 single-byte alphanumeric characters
cpp-header-border-
color
xs:string
(Optional) Sets the border color around the header of the payment page. The border is
a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels
high. By default, the color is black.
Character length and limitations: 6-character HTML hexadecimal ASCII color code
cpp-header-back-
color
xs:string
(Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitations: 6-character HTML hexadecimal ASCII color code
cpp-payflow-color xs:string
(Optional) Sets the background color for the payment page. By default, the color is
white.
Character length and limitations: 6-character HTML hexadecimal ASCII color code
PaymentAction
(deprecated)
ebl:PaymentActionCodeType
(Optional) How you want to obtain payment. If the transaction does not include a
one-time purchase, this field is ignored. It is one of the following values:
-Sale – This is a final sale for which you are requesting payment (default).
-Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
-Order – This payment is an order authorization subject to settlement with PayPal
Authorization and Capture.
NOTE: You cannot set this field to Sale in SetExpressCheckout request and then
change this value to Authorization or Order in the
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to Sale.
Character length and limitations: Up to 13 single-byte alphabetic characters
This field is deprecated. Use PaymentAction in PaymentDetailsType instead.
BuyerEmail ebl:EmailAddressType
(Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion on the PayPal pages.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
92 August 2012 SOAP API Developer Reference
SolutionType ebl:SolutionTypeType
(Optional) Type of checkout flow. It is one of the following values:
-Sole – Buyer does not need to create a PayPal account to check out. This is
referred to as PayPal Account Optional.
-Mark – Buyer must have a PayPal account to check out.
NOTE: You can pass Mark to selectively override the PayPal Account Optional
setting if PayPal Account Optional is turned on in your merchant account.
Passing Sole has no effect if PayPal Account Optional is turned off in your
account
LandingPage ebl:LandingPageType
(Optional) Type of PayPal page to display. It is one of the following values:
-Billing – Non-PayPal account
-Login – PayPal account login
ChannelType ebl:ChannelType
(Optional) Type of channel. It is one of the following values:
-Merchant – Non-auction seller
-eBayItem – eBay auction
giropaySuccessURL xs:string
(Optional) The URL on the merchant site to redirect to after a successful giropay
payment.
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.
giropayCancelURL xs:string
(Optional) The URL on the merchant site to redirect to after a successful giropay
payment.
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.
BanktxnPendingURL xs:string
(Optional) The URL on the merchant site to transfer to after a bank transfer payment.
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.
BillingAgreement
Details
ns:BillingAgreementDetailsType
(Optional) Billing agreement details.
Enhanced
CheckoutData
ed:EnhancedCheckoutDataType
(Optional) Enhanced data for different industry segments. This field is for eBay use
only.
OtherPaymentMethods ns:OtherPaymentMethodDetailsType
(Optional) List of other payment methods with which the buyer can pay.
Field Description
SOAP API Developer Reference August 2012 93
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
BuyerDetails ns:BuyerDetailsType
(Optional) Details about the buyer's account.
BrandName xs:string
(Optional) A label that overrides the business name in the PayPal account on the
PayPal hosted checkout pages.
Character length and limitations: 127 single-byte alphanumeric characters
FundingSourceDetail
s
ns:FundingSourceDetailsType
(Optional) Funding source preferences.
CustomerServiceNumb
er
xs:string
(Optional) Merchant Customer Service number displayed on the PayPal pages.
Character length and limitations: 16 single-byte characters
GiftMessageEnable xs:string
(Optional) Enables the gift message widget on the PayPal pages. It is one of the
following values:
-0 – Do not enable gift message widget.
-1 – Enable gift message widget.
GiftReceiptEnable xs:string
(Optional) Enable gift receipt widget on the PayPal pages. It is one of the following
values:
-0 – Do not enable gift receipt widget.
-1 – Enable gift receipt widget.
GiftWrapEnable xs:string
(Optional) Enable gift wrap widget on the PayPal pages. It is one of the following
values:
-0 – Do not enable gift wrap widget.
-1 – Enable gift wrap widget.
NOTE: If you pass the value 1 in this field, values for the gift wrap amount and gift
wrap name are not passed, the gift wrap name is not displayed, and the gift
wrap amount displays as 0.00.
GiftWrapName xs:string
(Optional) Label for the gift wrap option such as “Box with ribbon”.
Character length and limitations: 25 single-byte characters
GiftWrapAmount ebl:BasicAmounttype
(Optional) Amount to be charged to the buyer for gift wrapping..
NOTE: 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: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
94 August 2012 SOAP API Developer Reference
BuyerEmailOptinEnab
le
xs:string
(Optional) Enables the buyer to provide their email address on the PayPal pages to be
notified of promotions or special events. Is one of the following values:
-0 – Do not enable buyer to provide email address.
-1 – Enable the buyer to provide email address.
SurveyQuestion xs:string
(Optional) Text for the survey question on the PayPal pages. If the survey question is
present, at least 2 survey answer options must be present.
Character length and limitations: 50 single-byte characters
SurveyEnable xs:string
(Optional) Enables survey functionality. It is one of the following values:
-0 – Disables survey functionality.
-1 – Enables survey functionality.
SurveyChoice xs:string
(Optional) Possible options for the survey answers on the PayPal pages. Answers are
displayed only if a valid survey question is present.
Character length and limitations: 15 single-byte characters
TotalType ns:TotalType
(Optional) Enables display of “Estimated Total” instead of “Total” in the cart review
area. It is one of the following values:
-Total
-EstimatedTotal
Character length and limitations: 14 single-byte characters
This field is available with API Version 64.0 or later.
NoteToBuyer xs:string
(Optional) Displays a note to buyers in the cart review area below the total amount.
Use the note to tell buyers about items in the cart, such as your return policy or that
the total excludes shipping and handling.
Character length and limitations: 127 single-byte characters
This field is available with API Version 64.0 or later.
PaymentReason ns:PaymentReasonType
Indicates the type of transaction. It is one of the following values:
-None – Transaction is not identified as a particular type.
-Refund – Identifies the transaction as a refund.
Field Description
SOAP API Developer Reference August 2012 95
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
AddressType Fields
PaymentDetailsType Fields
When implementing parallel payments, you can create up to 10 sets of payment details type
parameter fields, each representing one payment you are hosting on your marketplace.
Field Description
Name xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address and may be required for other countries.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
96 August 2012 SOAP API Developer Reference
Field Description
OrderTotal ebl:BasicAmountType
(Required) Total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the
current sub-total of the order. If the transaction includes one or more one-time
purchases, this field must be equal to the sum of the purchases. Set this field to 0 if
the transaction does not include a one-time purchase such as when you set up a
billing agreement for a recurring payment that is not immediately charged. When
the field is set to 0, purchase-specific fields are ignored.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ItemTotal ebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a non-
negative currency amount or null if you offer insurance options.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
InsuranceTotal is available since version 53.0.
SOAP API Developer Reference August 2012 97
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ShippingDiscount is available since version 53.0.
InsuranceOptionOffer
ed
xs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. Is one of the following values:
-true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a positive
number.
-false – The Insurance option displays ‘No.’
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
OrderDescription xs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
98 August 2012 SOAP API Developer Reference
Custom xs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ns:AddressType
(Optional) Address to which the order is shipped.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.
EnhancedPaymentData ed:EnhancedPaymentDataType
(Optional) Enhanced Data section to accept channel-specific data (eBay).
NoteText xs:string
(Optional) Note to the merchant.
Character length and limitations: 255 single-byte characters
SellerDetails ns:SellerDetailsType
(Optional) Details about the merchant. This information is used for emails sent out
for eBay transactions.
TransactionId xs:string
(Optional) Transaction identification number of the transaction that was created.
NOTE: This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
AllowedPaymentMethod
Type
xs:string
(Optional) The payment method type. Specify the value InstantPaymentOnly.
Field Description
SOAP API Developer Reference August 2012 99
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
PaymentDetailsItemType Fields
PaymentAction ebl:PaymentActionCodeType
How you want to obtain payment. When implementing parallel payments, this field
is required and must be set to Order. When implementing digital goods, this field
is required and must be set to Sale. If the transaction does not include a one-time
purchase, this field is ignored. It is one of the following values:
-Sale – This is a final sale for which you are requesting payment (default).
-Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
-Order – This payment is an order authorization subject to settlement with
PayPal Authorization and Capture.
NOTE: You cannot set this field to Sale in SetExpressCheckout request and
then change the value to Authorization or Order in the
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to Sale.
Character length and limitations: Up to 13 single-byte alphabetic characters
PaymentRequestID xs:string
A unique identifier of the specific payment request, which is required for parallel
payments.
Character length and limitations: Up to 127 single-byte characters
Field Description
Name xs:string
Item name. This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Amount ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 53.0.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
100 August 2012 SOAP API Developer Reference
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Quantity xs:integer
Item quantity. This field is required when you pass a value for ItemCategory.
For digital goods (ItemCategory=Digital), this field is required.
Character length and limitations: Any positive integer
This field is introduced in version 53.0.
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ItemWeight xs:integer
(Optional) Item weight corresponds to the weight of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer
ItemLength xs:integer
(Optional) Item length corresponds to the length of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer
ItemWidth xs:integer
(Optional) Item width corresponds to the width of the item. You can pass this data
to the shipping carrier as is without having to make an additional database query.
Character length and limitations: Any positive integer
ItemHeight xs:integer
(Optional) Item height corresponds to the height of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer
EbayItemPayment
DetailsItem
eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.
ItemURL xs:string
(Optional) URL for the item.
Field Description
SOAP API Developer Reference August 2012 101
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
SellerDetailsType Fields
EbayItemPaymentDetailsItemType Fields
EnhancedItemData ed:EnhancedItemDataType
(Optional) Enhanced data for each item in the cart. For eBay use only.
ItemCategory ns:ItemCategoryType
Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
PayPalAccountID xs:string
Unique identifier for the merchant. For parallel payments, this field is required and
must contain the Payer Id or the email address of the merchant.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters
AuctionTransactionId xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters
CartID xs:string
(Optional) The unique identifier provided by eBay for this order from the buyer.
Character length: 255 single-byte characters
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
102 August 2012 SOAP API Developer Reference
BuyerDetailsType Fields
FundingSourceDetailsType Fields
Field Description
BuyerId xs:string
(Optional) The unique identifier provided by eBay for this buyer. The value may or
may not be the same as the username. In the case of eBay, it is different.
Character length and limitations: 255 single-byte characters
BuyerUserName xs:string
(Optional) The user name of the user at the marketplaces site.
BuyerRegistrationDa
te
xs:dateTime
(Optional) Date when the user registered with the marketplace.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
TaxIdDetails ebl:TaxIdDetailsType
Details about the buyer’s tax information. This field is required for Brazil and is for
Brazil use only.
This field is introduced in API version 72.0.
Field Description
AllowPushFunding xs:string
(Optional) Indicates whether the merchant can accept push funding. It is one of the
following values:
-0 – Merchant can accept push funding.
-1 – Merchant cannot accept push funding.
NOTE: This field overrides the setting in the merchant's PayPal account.
AllowedPaymentMetho
d
ns:AllowedPaymentMethodType
(Optional) The type of funding sources allowed. It is one of the following values:
-Default – Merchant supports all funding sources.
-InstantOnly – Merchant only supports instant payments.
-AnyFundingSource – All funding methods allowed, to be chosen by the buyer
irrespective of the merchant profile setting.
-InstantFundingSource – Only instant funding methods are allowed. Block
echeck, meft, elevecheck. This value overrides any merchant profile settings.
SOAP API Developer Reference August 2012 103
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
ShippingOptionsType Fields
BillingAgreementDetailsType Fields
Field Description
ShippingOptionIsDefau
lt
xs:boolean
Default shipping optio displayed on the PayPal pages. This field is required if you
specify the Callback URL. It is one of the following values:
-true – This is the default flat-rate shipping option. PayPal displays this option
and its amount by default.
-false – This flat-rate shipping option and its amount are not displayed as the
default.
NOTE: There must be ONE and ONLY ONE default. It is not OK to have no
default.
ShippingOptionName xs:string
Internal name of the shipping option such as Air, Ground, Expedited, and so forth.
This field is required if you specify the Callback URL.
Character length and limitations: 50 character-string.
ShippingOptionAmount ebl:BasicAmountType
Amount of the flat rate shipping option. This field is required if you specify the
Callback URL.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
Field Description
BillingType ns:BillingCodeType
(Required) Type of billing agreement. For recurring payments, this field must be set
to RecurringPayments. In this case, you can specify up to ten billing agreements.
Other defined values are not valid.
Type of billing agreement for reference transactions. You must have permission from
PayPal to use this field. This field must be set to one of the following values:
-MerchantInitiatedBilling - PayPal creates a billing agreement for each
transaction associated with buyer. You must specify version 54.0 or higher to use
this option.
-MerchantInitiatedBillingSingleAgreement - PayPal creates a single
billing agreement for all transactions associated with buyer. Use this value unless
you need per-transaction billing agreements. You must specify version 58.0 or
higher to use this option.
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
104 August 2012 SOAP API Developer Reference
TaxIdDetailsType Type Fields
BillingAgreement
Description
xs:string
Description of goods or services associated with the billing agreement. This field is
required for each recurring payment billing agreement. PayPal recommends that the
description contain a brief summary of the billing agreement terms and conditions.
For example, buyer is billed at “9.99 per month for 2 years”.
Character length and limitations: 127 single-byte alphanumeric characters
PaymentType ns:MerchantPullPaymentCodeType
(Optional) Type of PayPal payment you require for the billing agreement. It is one of
the following values:
-Any
-InstantOnly
NOTE: For recurring payments, this field is ignored.
BillingAgreement
Custom
xs:string
(Optional) Custom annotation field for your own use.
NOTE: For recurring payments, this field is ignored.
Character length and limitations: 256 single-byte alphanumeric bytes
Field Description
TaxIdType xs:string
Buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
This field is introduced in API version 72.0.
TaxId xs:string
Buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14
single-byte characters for businesses.
This field is introduced in API version 72.0.
Field Description
SOAP API Developer Reference August 2012 105
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
SetExpressCheckout Response Message
NOTE: Not all fields shown are available for use. Only use fields described in the
documentation.
SetExpressCheckout Response Fields
Field Description
Token xs:string
A timestamped token by which you identify to PayPal that you are processing this
payment with Express Checkout. The token expires after three hours. If you set the
token in the SetExpressCheckout request, the value of the token in the response is
identical to the value in the request.
Character length and limitations: 20 single-byte characters
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
106 August 2012 SOAP API Developer Reference
GetExpressCheckoutDetails API Operation
The GetExpressCheckoutDetails API operation obtains information about an Express
Checkout transaction.
GetExpressCheckoutDetails Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetExpressCheckoutDetails Request Fields
Field Description
Token xs:string
(Required) A timestamped token, the value of which was returned by
SetExpressCheckout response.
Character length and limitations: 20 single-byte characters
SOAP API Developer Reference August 2012 107
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
GetExpressCheckoutDetails Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
108 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 109
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
110 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 111
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
112 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 113
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
114 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetExpressCheckoutDetails Response Fields
Field Description
Token xs:string
The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
PayerInfo ebl:PayerInfoType
Information about the payer.
Custom xs:string
A free-form field for your own use, as set by you in the Custom element of the
SetExpressCheckout request.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
Your own invoice or tracking number, as set by you in the element of the same name
in the SetExpressCheckout request.
Character length and limitations: 127 single-byte alphanumeric characters
SOAP API Developer Reference August 2012 115
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
ContactPhone xs:string
Buyer’s contact phone number.
NOTE: PayPal returns a contact phone number only if your Merchant Account
Profile settings require that the buyer enter one.
Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers)
or +XXX XXXXXXXX (for international numbers)
PaymentDetails ebl:PaymentDetailsType
Information about the payment.
PayPalAdjustment cc:BasicAmountType
A discount or gift certificate offered by PayPal to the buyer. This amount is
represented by a negative amount. If the buyer has a negative PayPal account
balance, PayPal adds the negative balance to the transaction amount, which is
represented as a positive value.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
Note xs:string
Text entered by the buyer on the PayPal website if you set the AllowNote field to 1
in SetExpressCheckout.
Character length and limitations: 255 single-byte characters
This field is deprecated.
RedirectRequired xs:boolean
Flag to indicate whether you need to redirect the buyer back to PayPal after
successfully completing the transaction.
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.
UserSelectedOptions ebl:UserSelectedOptionsType
Shipping options and insurance.
CheckoutStatus ebl:CheckoutStatusType
Status of the checkout session. If payment is completed, the transaction identification
number of the resulting transaction is returned. It is one of the following values:
-PaymentActionNotInitiated
-PaymentActionFailed
-PaymentActionInProgress
-PaymentCompleted
GiftMessage xs:string
Gift message entered by the buyer on the PayPal checkout pages.
Character length and limitations: 150 single-byte characters
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
116 August 2012 SOAP API Developer Reference
PayerInfoType Fields
GiftReceiptEnable xs:string
Whether the buyer requested a gift receipt. It is one of the following values:
-true – The buyer requested a gift receipt.
-false – The buyer did not request a gift receipt.
GiftWrapName xs:string
Returns the gift wrap name only if the buyer selects gift option on the PayPal pages.
Character length and limitations: 25 single-byte characters
GiftWrapAmount ebl:BasicAmountType
Returns the gift wrap amount only if the buyer selects the gift option on the PayPal
pages.
NOTE: You must set the currencyID attribute to one of the 3-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. Must have two decimal places, decimal separator must be a period
(.), and the optional thousands separator must be a comma (,).
BuyerMarketingEmail ebl:EmailAddressType
Buyer’s email address if the buyer provided it on the PayPal pages.
Character length and limitations: 127 single-byte characters
SurveyQuestion xs:string
Survey question on the PayPal checkout pages.
Character length and limitations: 50 single-byte characters
SurveyChoiceSelecte
d
xs:string
Survey response the buyer selects on the PayPal pages.
Character length and limitations: 15 single-byte characters
PaymentRequestInfo ns:PaymentRequestInfoType
Payment request information for each bucket in the cart.
Field Description
Payer ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations: 13 single-byte alphanumeric characters
Field Description
SOAP API Developer Reference August 2012 117
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
PayerNameType Fields
PayerStatus ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerName ebl:PersonNameType
First and last name of buyer.
PayerCountry ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: 2 single-byte characters
PayerBusiness xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters
Address xs:string
Buyer’s shipping address information.
TaxIdDetails ns:TaxIdDetailsType
Details about the buyer’s tax information.
This field is introduced in API version 72.0.
Field Description
Salutation xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
118 August 2012 SOAP API Developer Reference
AddressType Fields
PaymentDetailsType Fields
When implementing parallel payments, you can create up to 10 sets of payment details type
parameter fields, each representing one payment you are hosting on your marketplace.
Field Description
Name xs:string
Person’s name associated with this shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCodeType
Country code.
Character length and limitations: 2 single-byte characters
Phone xs:string
Phone number.
Character length and limitations: 20 single-byte characters
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
SOAP API Developer Reference August 2012 119
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
Field Description
OrderTotal ebl:BasicAmountType
The total cost of the transaction to the buyer. If shipping cost (not applicable to
digital goods) and tax charges are known, include them in this value. If not, this
value should be the current sub-total of the order. If the transaction includes one
or more one-time purchases, this field must be equal to the sum of the purchases.
Set this field to 0 if the transaction does not include a one-time purchase such as
when you set up a billing agreement for a recurring payment that is not
immediately charged. Purchase-specific fields are ignored. For digital goods, the
following must be true:
-total cost > 0
-total cost <= total cost passed in the call to SetExpressCheckout
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ItemTotal ebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.
PayPal recommends that you pass the same value in the call to
DoExpressCheckoutPayment that you passed in the call to
SetExpressCheckout.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
120 August 2012 SOAP API Developer Reference
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if you offer insurance options.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
InsuranceTotal is available since version 53.0.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ShippingDiscount is available since version 53.0.
InsuranceOptionOffered xs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal pages. Is one of the following values:
-true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a
positive number.
-false – The Insurance option displays ‘No.’
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
Field Description
SOAP API Developer Reference August 2012 121
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
OrderDescription xs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
NotifyURL xs:string
Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to
DoExpressCheckoutPayment. This value is ignored when
set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ns:AddressType
Address the order is shipped to.
PaymentDetailsItem ebl:PaymentDetailsItemType
Details about each individual item included in the order.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
122 August 2012 SOAP API Developer Reference
PaymentDetailsItemType Fields
EnhancedPaymentData ed:EnhancedPaymentDataType
Enhanced Data section to accept channel-specific data.
NoteText xs:string
Note to the merchant.
Character length and limitations: 255 single-byte characters
TransactionId xs:string
Transaction identification number of the transaction that was created.
NOTE: This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
AllowedPaymentMethodTy
pe
xs:string
The payment method type. Specify the value InstantPaymentOnly.
PaymentRequestID xs:string
A unique identifier of the specific payment request. Required when
implementing parallel payments.
Character length and limitations: Up to 127 single-byte characters
Field Description
Name xs:string
Item name.
Character length and limitations: 127 single-byte characters
Description xs:string
Item description.
Character length and limitations: 127 single-byte characters
This field is available since version 53.0.
Amount ebl:BasicAmountType
Cost of item.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
Number xs:string
Item number.
Character length and limitations: 127 single-byte characters
Field Description
SOAP API Developer Reference August 2012 123
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
Quantity xs:integer
Item quantity.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ItemWeight xs:integer
Weight of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer
ItemLength xs:integer
Length of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer
ItemWidth xs:integer
Width of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer
ItemHeight xs:integer
Height of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer
EbayItemPayment
DetailsItem
eBl:ebayItemPaymentDetailsItemType
Information relating to an auction sale on eBay.
ItemCategory ns:ItemCategoryType
Indicates whether the item is digital or physical. For digital goods
(ItemCategory=Digital), this field is required. It is one of the following
values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
124 August 2012 SOAP API Developer Reference
EbayItemPaymentDetailsItemType Fields
UserSelectedOptionsType Fields
Field Description
ItemNumber xs:string
Auction item number.
Character length: 765 single-byte characters
AuctionTransactionId xs:string
Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
Auction order identification number.
Character length: 64 single-byte characters
CartID xs:string
The unique identifier provided by eBay for this order from the buyer.
Character length: 255 single-byte characters
Field Description
ShippingCalculationM
ode
xs:string
Describes how the options that were presented to the buyer were determined. It is
one of the following values:
-API - Callback
-API - Flatrate
InsuranceOptionSelec
ted
xs:boolean
The option that the buyer chose for insurance. It is one of the following values:
-Yes – The buyer opted for insurance.
-No – The buyer did not opt for insurance.
ShippingOptionIsDefa
ult
xs:boolean
Indicates whether the buyer chose the default shipping option. It is one of the
following values:
-true – The buyer chose the default shipping option.
-false – The buyer did not choose the default shipping option.
Character length and limitations: true or false
ShippingOptionAmount ebl:BasicAmountType
The shipping amount that the buyer chose.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
SOAP API Developer Reference August 2012 125
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
SellerDetailsType Fields
PaymentRequestInfoType Fields
PaymentErrorType Fields
ShippingOptionName xs:string
The name of the shipping option, such as air or ground.
Field Description
PayPalAccountID xs:string
Unique identifier for the merchant. For parallel payments, this field contains
either the Payer Id or the email address of the merchant.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
TransactionId xs:string
Transaction ID for up to 10 parallel payment requests.
This field is available since version 64.0.
PaymentRequestID xs:string
Payment request ID for up to 10 payment requests.
This field is available since version 64.0.
PaymentError ns:ErrorType
Errors associated with the bucket of parallel payment requests.
This field is available since version 64.0.
Field Description
ShortMessage xs:string
Payment error short message.
LongMessage xs:string
Payment error long message.
ErrorCode xs:string
Payment error code.
SeverityCode xs:string
Payment error severity code.
ErrorParameters xs:string
Application-specific error values indicating more about the error condition.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
126 August 2012 SOAP API Developer Reference
TaxIdDetailsType Fields
DoExpressCheckoutPayment API Operation
The DoExpressCheckoutPayment API operation completes an Express Checkout
transaction.
If you set up a billing agreement in your SetExpressCheckout API call, the billing
agreement is created when you call the DoExpressCheckoutPayment API operation.
DoExpressCheckoutPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Field Description
TaxIdType xs:string
Buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
This field is introduced in API version 72.0.
TaxId xs:string
Buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14
single-byte characters for businesses.
This field is introduced in API version 72.0.
SOAP API Developer Reference August 2012 127
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
128 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoExpressCheckoutPayment Request Fields
Field Description
Token xs:string
(Required) The timestamped token value that was returned in the
SetExpressCheckout response and passed in the
GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
PaymentAction
(deprecated)
ebl:PaymentActionCodeType
(Required) How you want to obtain payment. It is one of the following values:
-Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
-Order – This payment is an order authorization subject to settlement with PayPal
Authorization and Capture.
-Sale – This is a final sale for which you are requesting payment.
NOTE: You cannot set this value to Sale in the SetExpressCheckout request and
then change this value to Authorization in the
DoExpressCheckoutPayment request.
Character length and limitations: Up to 13 single-byte alphabetic characters
This field is deprecated. Use PaymentAction in PaymentDetailsType instead.
SOAP API Developer Reference August 2012 129
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PayerID ebl:UserIDType
(Required) Unique PayPal buyer account identification number as returned in the
GetExpressCheckoutDetails response
Character length and limitations: 13 single-byte alphanumeric characters
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the payment.
UserSelectedOptions ebl:UserSelectedOptionsType
(Optional) Shipping options and insurance selected by the buyer.
ReturnFMFDetails xs:boolean
(Optional) Flag to indicate whether you want the results returned by Fraud
Management Filters. By default, you do not receive this information. It is one of the
following values:
-0 – Do not receive FMF details (default).
-1 – Receive FMF details.
GiftMessage xs:string
(Optional) The gift message the buyer entered on the PayPal pages.
Character length and limitations: 150 single-byte characters
GiftReceiptEnable xs:string
(Optional) Whether the buyer selected a gift receipt on the PayPal pages. It is one of
the following vaues:
-true – The buyer selected a gift message.
-false – The buyer did not select a gift message.
GiftWrapName xs:string
(Optional) Return the gift wrap name only if the buyer selected the gift option on the
PayPal pages.
Character length and limitations: 25 single-byte characters
GiftWrapAmount ebl:BasicAmounttType
(Optional) Amount only if the buyer selected the gift option on the PayPal pages.
NOTE: 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: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
BuyerMarketingEmail ebl:EmailAddressType
(Optional) The buyer email address opted in by the buyer on the PayPal pages.
Character length and limitations: 127 single-byte characters
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
130 August 2012 SOAP API Developer Reference
AddressType Fields
SurveyQuestion xs:string
(Optional) Survey question on the PayPal pages.
Limitations: 50 single-byte characters
SurveyChoiceSelecte
d
xs:string
(Optional) Survey response that the buyer selected on the PayPal pages.
Character length and limitations: 15 single-byte characters
ButtonSource xs:string
(Optional) Identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
Field Description
Name xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address and may be required for other countries.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Field Description
SOAP API Developer Reference August 2012 131
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PaymentDetailsType Fields
When implementing parallel payments, you can create up to 10 sets of payment details type
parameter fields, each representing one payment you are hosting on your marketplace.
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
OrderTotal ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost (not
applicable to digital goods) and tax charges are known, include them in this
value. If not, this value should be the current sub-total of the order. If the
transaction includes one or more one-time purchases, this field must be equal
to the sum of the purchases. Set this field to 0 if the transaction does not
include a one-time purchase such as when you set up a billing agreement for a
recurring payment that is not immediately charged. When the field is set to 0,
purchase-specific fields are ignored. For digital goods, the following must be
true:
-total cost > 0
-total cost <= total cost passed in the call to SetExpressCheckout
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ItemTotal ebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.
PayPal recommends that you pass the same value in the call to
DoExpressCheckoutPayment that you passed in the call to
SetExpressCheckout.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
132 August 2012 SOAP API Developer Reference
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if you offer insurance options.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
InsuranceTotal is available since version 53.0.
ShippingDiscount ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a negative number. It includes no
currency symbol. It must have 2 decimal places, the decimal separator must be
a period (.), and the optional thousands separator must be a comma (,).
ShippingDiscount is available since version 53.0.
InsuranceOptionOffered xs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. Is one of the following values:
-true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a
positive number.
-false – The Insurance option displays ‘No.’
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
Field Description
SOAP API Developer Reference August 2012 133
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
OrderDescription xs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
ButtonSource (deprecated)xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
(Optional) An identification code for use by third-party applications to identify
transactions. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive.
Character length and limitations: 32 single-byte alphanumeric characters
ButtonSource is deprecated since version 63.0. Use ButtonSource in the
DoExpressCheckoutPayment request fields instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
134 August 2012 SOAP API Developer Reference
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about
this transaction. If you do not specify this value in the request, the notification
URL from your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to
DoExpressCheckoutPayment. This value is ignored when
set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress ns:AddressType
(Optional) Address to which the order is shipped.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.
EnhancedPaymentData ed:EnhancedPaymentDataType
(Optional) Enhanced Data section to accept channel-specific data (eBay).
NoteText xs:string
(Optional) Note to the merchant.
Character length and limitations: 255 single-byte characters
SoftDescriptor xs:string
A per transaction description of the payment that is passed to the buyer’s credit
card statement.
NOTE: Ignore when PaymentAction=Order.
SellerDetails ns:SellerDetailsType
(Optional) Details about the merchant. This information is used for emails sent
out for eBay transactions.
TransactionId xs:string
(Optional) Transaction identification number of the transaction that was
created.
NOTE: This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
AllowedPaymentMethodType xs:string
(Optional) The payment method type. Specify the value
InstantPaymentOnly.
Field Description
SOAP API Developer Reference August 2012 135
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PaymentDetailsItemType Fields
PaymentAction ebl:PaymentActionCodeType
How you want to obtain payment. When implementing parallel payments, this
field is required and must be set to Order. When implementing digital goods,
this field is required and must be set to Sale. If the transaction does not
include a one-time purchase, this field is ignored. It is one of the following
values:
-Sale – This is a final sale for which you are requesting payment (default).
-Authorization – This payment is a basic authorization subject to
settlement with PayPal Authorization and Capture.
-Order – This payment is an order authorization subject to settlement with
PayPal Authorization and Capture.
NOTE: You cannot set this field to Sale in SetExpressCheckout request
and then change the value to Authorization or Order in the
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set
the field to Sale.
Character length and limitations: Up to 13 single-byte alphabetic characters
PaymentRequestID xs:string
A unique identifier of the specific payment request. Required when
implementing parallel payments.
Character length and limitations: Up to 127 single-byte characters
Field Description
Name xs:string
Item name. This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
136 August 2012 SOAP API Developer Reference
Amount ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 53.0.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Quantity xs:integer
Item quantity. This field is required when you pass a value for ItemCategory.
For digital goods (ItemCategory=Digital), this field is required.
Character length and limitations: Any positive integer
This field is introduced in version 53.0.
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ItemWeight xs:integer
(Optional) Item weight corresponds to the weight of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer
ItemLength xs:integer
(Optional) Item length corresponds to the length of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer
ItemWidth xs:integer
(Optional) Item width corresponds to the width of the item. You can pass this data
to the shipping carrier as is without having to make an additional database query.
Character length and limitations: Any positive integer
Field Description
SOAP API Developer Reference August 2012 137
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
EbayItemPaymentDetailsItemType Fields
ItemHeight xs:integer
(Optional) Item height corresponds to the height of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer
EbayItemPayment
DetailsItem
eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.
ItemURL xs:string
(Optional) URL for the item.
EnhancedItemData ed:EnhancedItemDataType
(Optional) Enhanced data for each item in the cart. For eBay use only.
ItemCategory ns:ItemCategoryType
Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters
AuctionTransactionId xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters
CartID xs:string
(Optional) The unique identifier provided by eBay for this order from the buyer.
Character length: 255 single-byte characters
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
138 August 2012 SOAP API Developer Reference
UserSelectedOptions Fields
SellerDetailsType Fields
Field Description
InsuranceOptionSelec
ted
xs:boolean
(Optional) The option that the buyer chose for insurance. It is one of the following
values:
-Yes – The buyer opted for insurance.
-No – The buyer did not opt for insurance.
ShippingOptionIsDefa
ult
xs:boolean
(Optional) Whether the buyer chose the default shipping option. It is one of the
following values:
-true – The buyer chose the default shipping option.
-false – The buyer did not choose the default shipping option.
ShippingOptionAmount ebl:BasicAmountType
(Optional) The shipping amount that the buyer chose.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ShippingOptionName xs:string
(Optional) The name of the shipping option, such as air or ground.
Field Description
SellerID xs:string
(Optional) Unique non-changing identifier for the merchant at the marketplace
site. This ID is not displayed.
Character length and limitations: 13 single-byte alphanumeric characters
SellerUserName xs:string
(Optional) Current name of the merchant or business at the marketplace site. This
name may be shown to the buyer.
SellerRegistrationDat
e
xs:dateTime
(Optional) Date when the merchant registered with the marketplace.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
SOAP API Developer Reference August 2012 139
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
DoExpressCheckoutPayment Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
140 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 141
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
142 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoExpressCheckoutPayment Response Fields
Field Description
Token xs:string
The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
PaymentInfo ebl:PaymentInfoType
Information about the payment.
Note xs:string
The text entered by the buyer on the PayPal website if you set the AllowNote field
to 1 in SetExpressCheckout.
This field is available since version 53.0.
Character length and limitations: 255 single-byte characters
RedirectRequired xs:boolean
Flag to indicate whether you need to redirect the buyer back to PayPal after
successfully completing the transaction.
If set to true, you can redirect users to the following URL with the token value
appended:
https://www.paypal.com/cgi-bin/webscr?cmd=_complete-express-
checkout&token=(token)
NOTE: Use this field only if you are using giropay or bank transfer payment methods
in Germany.
SOAP API Developer Reference August 2012 143
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
SuccessPageRedirect
Requested
xs:boolean
Flag to indicate whether you would like to redirect the buyer to sign up for
PayPal after completing the transaction.
If set to true, you can redirect users to the following URL with the token value
appended::
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout-
success&token=(token)
BillingAgreementID xs:string
The ID of the billing agreement associated with the Express Checkout transaction.
FMFDetails
(deprecated)
ebl:FMFDetailsType
Fraud filter details.
This field is deprecated since version 63.0. Use FMFDetails in PaymentInfoType
instead.
ShipAmount xs:string
Amount of shipping charged on this transaction.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator must be a period (.), and
the optional thousands separator must be a comma (,). Equivalent to nine characters
maximum for USD.
SellerId xs:string
Unique, non-changing identifier for the merchant at the marketplace site. (Optional)
Character length and limitations: 13 single-byte alphanumeric characters.
SellerUserName xs:string
Current name of the merchant or business at the marketplace site. This name may be
shown to the buyer.
SellerRegistrationD
ate
xs:dateTime
Date when the merchant registered with the marketplace.
Character length and limitations: Date and time are in UTC/GMT format. For
example: 2011-06-24T05:38:?48Z.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
144 August 2012 SOAP API Developer Reference
PaymentInfoType Fields
When implementing parallel payments, up to 10 payment information type sets of payment
information type parameter fields can be returned, each representing one payment you are
hosting on your marketplace.
ParentTransactionID ns:TransactionId
Parent or related transaction identification number. This field is populated for the
following transaction types:
-Reversal
-Capture of an authorized transaction
-Reauthorization of a transaction
-Capture of an order. The value of ParentTransactionID is the original
OrderID.
-Authorization of an order. The value of ParentTransactionID is the original
OrderID.
-Capture of an order authorization
-Void of an order. The value of ParentTransactionID is the original OrderID.
Character length and limits: 19 single-byte characters maximum.
ReceiptID ns:ReceiptID
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format.
ExpectedeCheckClear
Date
xs:dateTime
eCheck latest expected clear date.
ShippingMethod xs:string
Shipping method selected by the user during check-out.
InstrumentCategory xs:string
This field holds the category of the instrument only when it is promotional. Return
value 1 represents BML.
OfferCode xs:string
Code used to identify the promotion offer.
OfferTrackingID xs:string
Unique identification for merchant/buyer/offer combo.
Field Description
SOAP API Developer Reference August 2012 145
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
Unique transaction ID of the payment. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive.
Store this number for tracking the order. It represents an order placeholder in the
PayPal system for a subsequent authorization by UATP.
NOTE: If the PaymentAction of the request was Authorization or Order, this
value is your AuthorizationID for use with the Authorization & Capture
APIs.
Character length and limitations: 19 single-byte characters
TransactionType ns:PaymentTransactionCodeType
Type of transaction. It is one of the following values:
Type of transaction. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive. It is one of the following values:
-cart
-express-checkout
Character length and limitations: 15 single-byte characters
PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is
one of the following values:
-none
-echeck
-instant
Character length and limitations: 7 single-byte characters
PaymentDate xs:dateTime
Time/date stamp of payment.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
GrossAmount ebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile.
The final amount charged, including any shipping and taxes from your Merchant
Profile. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
146 August 2012 SOAP API Developer Reference
FeeAmount ebl:BasicAmountType
PayPal fee amount charged for the transaction.
PayPal fee amount charged for the transaction. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
Amount deposited in your PayPal account after a currency conversion. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ExchangeRate xs:string
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account. You can specify
up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point
Field Description
SOAP API Developer Reference August 2012 147
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PaymentStatus ebl:PaymentStatusCodeType
The status of the payment. It is one of the following values:
The status of the payment. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive. It is one of the following values:
-None – No status.
-Canceled-Reversal – A reversal has been canceled; for example, when you
win a dispute and the funds for the reversal have been returned to you.
-Completed – 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 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 buyer’s bank account.
-In-Progress – The transaction has not terminated, e.g. an authorization may be
awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field 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.
-Completed-Funds-Held – The payment has been completed, and the funds
have been added successfully to your pending balance.
See the HoldDecision field for more information.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
148 August 2012 SOAP API Developer Reference
PendingReason ebl:PendingStatusCodeType
Reason the payment is pending. It is one of the following values:
Reason the payment is pending. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your buyer 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.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-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.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
-unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
-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.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
Field Description
SOAP API Developer Reference August 2012 149
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
ReasonCode ebl:ReasonCodeType
Reason for a reversal if TransactionType is reversal. It is one of the following values:
Reason for a reversal if TransactionType is reversal. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive. It is one of the following
values:
-none – No reason code.
-chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
-guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
-buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
-refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
-other – A reversal has occurred on this transaction due to a reason not listed
above.
HoldDecision xs:string
Reason that this payment is being held. It is one of the following values:
Reason that this payment is being held. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive. It is one of the following values:
-newsellerpaymenthold – This is a new merchant.
-paymenthold – A hold is placed on the merchant’s transaction for a reason not
listed.
This field is available since version 71.0 and is returned only if PaymentStatus is
Completed-Funds-Held.
This field is available since version 71.0 and is returned only if
PAYMENTINFO_n_PAYMENTSTATUS is Completed-Funds-Held.
ProtectionEligibili
ty
xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
Prior to version 64.4, the kind of seller protection in force for the transaction. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is one of
the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payments and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
150 August 2012 SOAP API Developer Reference
ProtectionEligibili
tyType
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
Since version 64.4, the kind of seller protection in force for the transaction. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is one of
the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment
-Ineligible – Merchant is not protected under the Seller Protection Policy
This field is available since version 64.4.
StoreId xs:string
StoreId as entered in the transaction
TerminalId xs:string
TerminalId as entered in the transaction
EbayTransactionId xs:string
eBay transaction identification number.
eBay transaction identification number. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive.
Character length and limitations: 255 single-byte characters
PaymentRequestID xs:string
Unique identifier of the specific payment request. The value should match the one
you passed in the DoExpressCheckout request.
Unique identifier of the specific payment request. The value should match the one
you passed in the DoExpressCheckout request. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
Character length and limitations: Up to 127 single-byte characters
EnhancedPaymentInfo xs:EnhancedPaymentInfoType
Enhanced payment information.
SellerDetails xs:SellerDetailsType
Details about this merchant.
FMFDetails xs:FMFDetailsType
List of fraud management filters.
PaymentError ns:ErrorType
Indicates the payment status for an individual payment request in the case of parallel
payments.
Field Description
SOAP API Developer Reference August 2012 151
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
UserSelectedOptions Fields
PaymentErrorType Fields
InstrumentDetails ns:InstrumentDetailsType
Promotional instrument information.
This field is introduced in API version 71.0.
OfferDetails ns:OfferDetailsType
Specific information for an offer.
This field is introduced in API version 71.0.
Field Description
ShippingCalculationM
ode
xs:string
Describes how the options that were presented to the buyer were determined. It is
one of the following values:
-API - Callback
-API - Flatrate
InsuranceOptionSelec
ted
xs:boolean
The option that the buyer chose for insurance. It is one of the following values:
-Yes – The buyer opted for insurance.
-No – The buyer did not opt for insurance.
ShippingOptionIsDefa
ult
xs:boolean
Indicates whether the buyer chose the default shipping option. It is one of the
following values:
-true – The buyer chose the default shipping option.
-false – The buyer did not choose the default shipping option.
Character length and limitations: true or false
ShippingOptionAmount ebl:BasicAmountType
The shipping amount that the buyer chose.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ShippingOptionName xs:string
The name of the shipping option, such as air or ground.
Field Description
ShortMessage xs:string
Payment error short message.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
152 August 2012 SOAP API Developer Reference
SellerDetailsType Fields
FMFDetailsType Fields
LongMessage xs:string
Payment error long message.
ErrorCode xs:string
Payment error code.
SeverityCode xs:string
Payment error severity code.
ErrorParameters xs:string
Application-specific error values indicating more about the error condition.
Field Description
PayPalAccountID xs:string
Unique identifier for the merchant. For parallel payments, this field contains
either the Payer Id or the email address of the merchant.
Character length and limitations: 127 single-byte alphanumeric characters
SecureMerchantAccountID xs:useridtype
Unique PayPal customer account number (of the merchant). This field is
returned in the response. It is ignored if passed in the request.
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment.
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment.
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.
Field Description
SOAP API Developer Reference August 2012 153
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
RiskFilterListType Fields
Field Description
ID xs:int
Filter ID. It is one of the following values:
-1 - AVS No Match
-2 - AVS Partial Match
-3 - AVS Unavailable/Unsupported
-4 - Card Security Code (CSC) Mismatch
-5 - Maximum Transaction Amount
-6 - Unconfirmed Address
-7 - Country Monitor
-8 - Large Order Number
-9 - Billing/Shipping Address Mismatch
-10 - Risky ZIP Code
-11 - Suspected Freight Forwarder Check
-12 - Total Purchase Price Minimum
-13 - IP Address Velocity
-14 - Risky Email Address Domain Check
-15 - Risky Bank Identification Number (BIN) Check
-16 - Risky IP Address Range
-17 - PayPal Fraud Model
Name xs:string
Filter name.
Description xs:string
Filter description.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
154 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 155
7GetBalance API Operation
The GetBalance API Operation obtains the available balance for a PayPal account.
GetBalance Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetBalance Request Fields
Field Description
ReturnAllCurrencies xs:string
(Optional) Indicates whether to return all currencies. It is one of the following values:
-0 – Return only the balance for the primary currency holding.
-1 – Return the balance for each currency holding.
NOTE: This field is availalble since version 51. Prior versions return only the
balance for the primary currency holding.
GetBalance API Operation
GetBalance Response Message
7
156 August 2012 SOAP API Developer Reference
GetBalance Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetBalance Response Fields
Field Description
Balance ebl:BasicAmountType
Available balance and associated currency code for the primary currency holding.
BalanceTimeStamp xs:dateTime
Time that the balance was reported.
BalanceHoldings ebl:BasicAmountType
Available balance and associated currency code for each currency held, including the
primary currency. The first currency is the primary currency.
SOAP API Developer Reference August 2012 157
8GetPalDetails API Operation
The GetPalDetails API operation obtains your Pal ID, which is the PayPal-assigned
merchant account number, and other information about your account. You need the account
number when working with dynamic versions of PayPal buttons and logos.
GetPalDetails Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetPalDetails API Operation
GetPalDetails Response Message
8
158 August 2012 SOAP API Developer Reference
GetPalDetails Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetPalDetails Response Fields
Field Description
Pal xs:string
PayPal-assigned merchant account number.
SOAP API Developer Reference August 2012 159
GetPalDetails API Operation
GetPalDetails Response Message 8
Locale xs:string
Country code representing the merchant’s default locale. It is one of the following
locales:
-AU – Australia
-AT – Austria
-BE – Belgium
-BR – Brazil
-CA – Canada
-CH – Switzerland
-CN – China
-DE – Germany
-ES – Spain
-GB – United Kingdom
-FR – France
-IT – Italy
-NL – Netherlands
-PL – Poland
-PT – Portugal
-RU – Russia
-US – United States
-The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)
Character length and limitations: 2 single-byte characters
Field Description
GetPalDetails API Operation
GetPalDetails Response Message
8
160 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 161
9GetTransactionDetails API
Operation
The GetTransactionDetails API operation obtains information about a specific
transaction.
GetTransactionDetails Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetTransactionDetails Request Fields
Field Description
TransactionID xs:string
(Required) Unique identifier of a transaction.
NOTE: The details for some kinds of transactions cannot be retrieved with
GetTransactionDetails. You cannot obtain details of bank transfer
withdrawals, for example.
Character length and limitations: 17 single-byte alphanumeric characters
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
162 August 2012 SOAP API Developer Reference
GetTransactionDetails Response Message
NOTE: All fields defined in the formal structure of GetTransactionDetailsResponse
are not necessarily returned. Data are returned in a response only if PayPal has
recorded data that corresponds to the field.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 163
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
164 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 165
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
166 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 167
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
168 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetTransactionDetails Response Fields
Field Description
PaymentTransaction
Details
Wrapper structure.
ShippingCalculation
Mode
xs:string
Describes how the options that were presented to the buyer were determined.
It is one of the following values:
-Callback – Shipping option rates are based on the buyer’s location.
-FlatRate – Shipping options are flat rates.
SOAP API Developer Reference August 2012 169
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
InsuranceOptionSele
cted
xs:boolean
Whether the buyer selected the insurance option. It is one of the following values:
-true – The buyer selected Yes for the insurance option.
-false – The buyer did not select the insurance option. The option is No.
The value true is returned if the buyer selected the option. Otherwise false is
returned.
ShippingOptionIsDef
ault
xs:boolean
Default shipping option displayed on the PayPal pages. This field is required if you
specify the Callback URL. It is one of the following values:
-true – This is the default flat-rate shipping option. PayPal displays this option by
default.
-false – This flat-rate shipping option is not displayed as the default.
NOTE: There must be ONE and ONLY ONE default. It is not OK to have no default.
ShippingOptionName xs:string
Internal name of the shipping option such as Air, Ground, Expedited, and so forth.
This field is required if you specify the Callback URL.
Character length and limitations: 50 character-string.
ShippingOptionAmoun
t
ebl:BasicAmountType
Amount of the flat rate shipping option. This field is required if you specify the
Callback URL.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
GiftMessage xs:string
The gift message the buyer entered on the PayPal pages.
Limitations: 100 single-byte characters
GiftReceiptEnable xs:string
Indicates whether a gift receipt widget is enabled on the PayPal pages. It is one of the
following values:
-0 – Do not enable gift receipt widget.
-1 – Enable gift receipt widget.
GiftWrapName xs:string
Label for the gift wrap option such as “Blue box with ribbon”.
Limitations: 25 single-byte characters
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
170 August 2012 SOAP API Developer Reference
PaymentTransactionDetailsType Fields
GiftWrapAmount ebl:BasicAmounttype
Amount to be charged to the buyer for the gift wrap.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
BuyerMarketingEmail ebl:EmailAddressType
The email address the buyer entered on the PayPal pages to be notified of promotions
or special events.
Limitations: 127 single-byte characters
SurveyQuestion xs:string
Text for the survey question on the PayPal pages. If the survey question is present, at
least 2 survey answer options need to be present.
Limitations: 50 single-byte characters
SurveyChoiceSelecte
d
xs:string
Survey response the buyer selected on the PayPal pages.
Limitations: 15 single-byte characters
Field Description
ReceiverInfo ebl:ReceiverInfoType
Information about the merchant, such as details of a single transaction, primary email
address, and unique account ID.
PayerInfo ebl:PayerInfoType
Information about the buyer, such as the buyer’s email address, customer account
identification number, shipping address, and country of residence.
PaymentInfo ebl:PaymentInfoType
Information about the transaction, such as the transaction ID, the type of transaction,
and whether the payment is instant or delayed.
PaymentItemInfo ebl:PaymentItemInfoType
Information about the payment item, such as the sales tax, the invoice number, and
whether the buyer left a note to the merchant.
Field Description
SOAP API Developer Reference August 2012 171
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
ReceiverInfoType Fields
PayerInfoType Fields
Field Description
Business xs:string
Details about a single transaction. This field is not application for point-of-sale
transactions.
Receiver xs:string
Primary email address of the payment recipient (the merchant).
If you are the recipient of the payment and the payment is sent to your non-primary
email address, the value of Receiver is still your primary email address.
Character length and limitations: 127 single-byte alphanumeric characters
ReceiverID xs:string
Unique account ID of the payment recipient (the merchant). This value is the same as
the value of the recipient's referral ID.
Field Description
Payer ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PayerStatus ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerName ebl:PersonNameType
First and last name of buyer.
PayerCountry ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 2-character country
codes.
Character length and limitations: 2 single-byte characters
PayerBusiness xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
172 August 2012 SOAP API Developer Reference
PayerName Fields
AddressType Fields
Address ns:AddressType
Buyer’s shipping address information.
Field Description
Salutation xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
AddressOwner ebl:AddressOwnerTypeCode
eBay company that maintains this address. It is one of the following values:
-eBay
-PayPal
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
Field Description
SOAP API Developer Reference August 2012 173
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
PaymentInfoType Fields
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ns:CountryCode
Country code.
Character length and limitations: 2 single-byte characters
CountryName xs:string
Expanded name of country.
Character length and limitations: 64 single-byte alphanumeric characters
Phone xs:string
Phone number.
Character length and limitations: 20 single-byte characters
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
174 August 2012 SOAP API Developer Reference
ParentTransactionID xs:string
Parent or related transaction identification number. This value in this field is for the
following transaction types:
-Reversal – Capture of an authorized transaction.
-Reversal – Reauthorization of a transaction.
-Capture of an order – The value of ParentTransactionID is the original
OrderID.
-Authorization of an order – The value of ParentTransactionID is the original
OrderID.
-Capture of an order authorization.
-Void of an order – The value of ParentTransactionID is the original
OrderID.
Character length and limitations: 16 digits
ReceiptID xs:string
Receipt identification number
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format
TransactionType ns:PaymentTransactionCodeType
The type of transaction. It is one of the following values:
-cart
-express-checkout
Character length and limitations:15 single-byte characters
PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
-none
-echeck
-instant
Character length and limitations: 7 single-byte characters
PaymentDate xs:dateTime
Time/date stamp of payment,
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
GrossAmount ebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
SOAP API Developer Reference August 2012 175
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
FeeAmount ebl:BasicAmountType
PayPal fee amount charged for the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ExchangeRate xs:string
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
176 August 2012 SOAP API Developer Reference
PaymentStatus ebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
-None – No status
-Canceled-Reversal– A reversal has been canceled, for example, when you
win a dispute and the funds for the reversal have been returned to you.
-Completed – 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 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 buyer’s bank account.
-In-Progress – The transaction has not terminated, for example, an
authorization may be awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field 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.
Field Description
SOAP API Developer Reference August 2012 177
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
PendingReason ebl:PendingStatusCodeType
The reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your buyer 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.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-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.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
-unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
-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.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
ReasonCode ebl:ReasonCodeType
The reason for a reversal if the transaction type is reversal. It is one of the following
values:
-none – No reason code.
-chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
-guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
-buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
-refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
-other – A reversal has occurred on this transaction due to a reason not listed
above.
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
178 August 2012 SOAP API Developer Reference
PaymentItemInfoType Fields
ProtectionEligibili
ty
xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payments and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
ProtectionEligibili
tyType
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is introduced in API version 64.4.
StoreId xs:string
StoreId as entered in the transaction.
TerminalId xs:string
TerminalId as entered in the transaction.
Field Description
InvoiceID xs:string
Invoice number you set in the original transaction.
Character length and limitations: 256 single-byte alphanumeric characters
Custom xs:string
Custom field you set in the original transaction.
Character length and limitations: 127 single-byte alphanumeric characters
Memo xs:string
Memo entered by your customer in PayPal Website Payments note field.
Character length and limitations: 255 single-byte alphanumeric characters
SalesTax xs:string
Amount of tax charged on payment.
Field Description
SOAP API Developer Reference August 2012 179
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
PaymentItemType Fields
PaymentItem ebl:PaymentItemType
Amount of tax charged on payment.
Subscription ebl:SubscriptionInfoType
Subscription information.
Auction ebl:AuctionInfoType
Subscription information.
Field Description
EbayItemTxnId xs:string
(Optional) The eBay auction transaction ID of the item that you use to identify items
that the buyer purchased.
Character length and limitations: 255 single-byte characters
Name xs:string
Item name set by you or entered by the customer.
NOTE: Character length and limitations: 127 single-byte alphanumeric characters.
Number xs:string
Item number set by you. If this was a shopping cart transaction, PayPal appends the
number of the item to the HTML item_number variable, for example,
item_number1, item_number2, and so forth.
Character length and limitations: 127 single-byte alphanumeric characters
Quantity xs:string
Quantity set by you or entered by the buyer.
Character length and limitations: no limit
CouponID xs:string
(Optional) Coupon identification number.
CouponAmount xs:string
(Optional) Amount (value) of the coupon.
CouponAmountCurrenc
y
xs:string
(Optional) Currency of the coupon amount, e.g., a 3-character currency code.
LoyaltyCardDiscount
Amount
xs:string
(Optional) Amount of discount associated with this Loyalty Card incentive.
NOTE: Use character string as shown.
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
180 August 2012 SOAP API Developer Reference
AuctionInfoType Fields
SubscriptionInfoType Fields
LoyaltyCardDiscount
Currency
xs:string
(Optional) Currency of the loyalty card discount, for example, a 3-character currency
code.
NOTE: Use character string as shown.
Amount ebl:BasicAmountType
Cost of item.
Options ns:OptionType
name: xs:string
value: xs:string
PayPal item options for shopping cart.
Field Description
BuyerID xs:string
Buyer’s auction ID.
ClosingDate xs:string
Auction’s close date.
MultiItem xs:string
Counter used for multi-item auction payments.
Field Description
SubscriptionID xs:string
ID generated by PayPal for the subscriber.
Character length and limitations: No limit
SubscriptionDate xs:dateTime
Subscription start date.
EffectiveDate xs:dateTime
Date when the subscription modification is effective.
RetryTime xs:dateTime
Date PayPal retrys a failed subscription payment.
Field Description
SOAP API Developer Reference August 2012 181
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
SubscriptionTermsType Fields
UserName xs:string
Username that PayPal generates and gives to the subscriber to access the subscription.
Character length and limitations: 64 alphanumeric single-byte characters
Password xs:string
Password that PayPal generates and gives to the subscriber to access the subscription.
For security, the value of the password is hashed.
Character length and limitations: 128 alphanumeric single-byte characters
Recurrences xs:string
The number of payment installments that occur at the regular rate.
Character length and limitations: No limit
reattempt xs:string
Indicates whether reattempts should occur upon payment failures.
recurring xs:string
Indicates whether regular rate recurs. It is one of the following values:
-1 – Yes
SubscriptionTermsTy
pe
ns:SubscriptionTermsType
Subscription terms.
Field Description
Amount eb:BasicAmountType
Amount subscriber is to be charged in 1 payment.
Character length and limitations: No limit
Period xs:string
Period of time that the subscriber is charged.
Character length and limitations: No limit
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
182 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 183
10 ManagePendingTransactionStatus
API Operation
The ManagePendingTransactionStatus API operation accepts or denys a pending transaction
held by Fraud Management Filters.
ManagePendingTransactionStatus Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ManagePendingTransactionStatus Request Fields
Field Description
TransactionID (Required) The transaction ID of the payment transaction.
Action (Required) The operation you want to perform on the transaction. It is one of the
following values:
-Accept – Accepts the payment
-Deny – Rejects the payment
ManagePendingTransactionStatus API Operation
ManagePendingTransactionStatus Response Message
10
184 August 2012 SOAP API Developer Reference
ManagePendingTransactionStatus Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ManagePendingTransactionStatus Response Fields
Field Description
TransactionID The transaction ID of the transaction whose payment has been denied or accepted.
Status Displays in the following message:
“The Status of the transaction after running your action (accept/deny) is
TransactionStatus.”
TransactionStatus is one of the following values:
-Pending
-Processing
-Completed
-Denied
-Reversed
-Display Only
-Partially Refunded
-Created Refunded
SOAP API Developer Reference August 2012 185
11 MassPay API Operation
The MassPay API operation makes a payment to one or more PayPal account holders.
MassPay Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
MassPay Request Fields
Field Description
EmailSubject xs:string
(Optional) The subject line of the email that PayPal sends when the transaction
completes. The subject line is the same for all recipients.
Character length and limitations: 255 single-byte alphanumeric characters
MassPay API Operation
MassPay Response Message
11
186 August 2012 SOAP API Developer Reference
MassPay Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
MassPay Response Fields
The elements returned are the same as for AbstractResponseType.
MassPayItem ebl:MassPayItemType
(Required) Details of each payment.
NOTE: A single MassPayRequest can include up to 250 MassPayItems.
ReceiverType ebl:ReceiverInfoCodeType
(Optional) How you identify the recipients of payments in this call to MassPay. It is
one of the following values:
-EmailAddress
-UserID
-PhoneNumber
Field Description
SOAP API Developer Reference August 2012 187
12 Recurring Payments and
Reference Transactions API
Operations
The PayPal API includes the following API operations supporting recurring payments and
reference transactions:
CreateRecurringPaymentsProfile API Operation
The CreateRecurringPaymentsProfile API operation creates a recurring payments
profile.
You must invoke the CreateRecurringPaymentsProfile API operation for each profile
you want to create. The API operation creates a profile and an associated billing agreement.
NOTE: There is a one-to-one correspondence between billing agreements and recurring
payments profiles. To associate a recurring payments profile with its billing
agreement, you must ensure that the description in the recurring payments profile
matches the description of a billing agreement. For version 54.0 and later, use
SetExpressCheckout to initiate creation of a billing agreement.
CreateRecurringPaymentsProfile Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
188 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 189
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
190 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 191
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
192 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
CreateRecurringPaymentsProfile Request Fields
Field Description
Token xs:string
A timestamped token, the value of which was returned in the response to the first call
to SetExpressCheckout. You can also use the token returned in the
SetCustomerBillingAgreement response. Either this token or a credit card
number is required. If you include both token and credit card number, the token is
used and credit card number is ignored Call CreateRecurringPaymentsProfile
once for each billing agreement included in SetExpressCheckout request and use
the same token for each call. Each CreateRecurringPaymentsProfile request
creates a single recurring payments profile.
NOTE: Tokens expire after approximately 3 hours.
SOAP API Developer Reference August 2012 193
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
RecurringPaymentsProfileDetailsType Fields
CreditCard ns:CreditCardDetailsType
Credit card information for recurring payments using direct payments. Either a token
or a credit card number is required. If you include both token and credit card number,
the token is used and credit card number is ignored.
RecurringPayments
ProfileDetails
ns:RecurringPaymentsProfileDetails
(Required) You can include up to 10 recurring payments profiles per request. The
order of the profile details must match the order of the billing agreement details
specified in the SetExpressCheckout request.
ScheduleDetails ns:ScheduleDetailsType
(Required) Describes the recurring payments schedule, including the regular payment
period, whether there is a trial period, and the number of payments that can fail before
a profile is suspended.
Field Description
SubscriberName xs:string
(Optional) Full name of the person receiving the product or service paid for by the
recurring payment. If not present, the name in the buyer’s PayPal account is used.
Character length and limitations: 32 single-byte characters
SubscriberShipping
Address
ns:AddressType
(Optional) The subscriber’s shipping address associated with this profile, if
applicable. If not specified, the ship-to address from buyer’s PayPal account is used.
NOTE: Shipping Address is optional, but if you include it, certain fields are required.
BillingStartdate xs:dateTime
(Required) The date when billing for this profile begins.
NOTE: The profile may take up to 24 hours for activation.
Character length and limitations: Must be a valid date, in UTC/GMT format
ProfileReference xs:string
(Optional) The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
194 August 2012 SOAP API Developer Reference
ScheduleDetailsType Fields
Field Description
Description xs:string
(Required) Description of the recurring payment.
NOTE: You must ensure that this field matches the corresponding billing agreement
description included in the SetExpressCheckout request.
Character length and limitations: 127 single-byte alphanumeric characters
ActivationDetails ns:ActivationDetailsType
(Optional) Information about activating a profile, such as whether there is an initial
non-recurring payment amount immediately due upon profile creation and how to
override a pending profile PayPal suspends when the initial payment amount fails.
TrialPeriod ns:BillingPeriodDetailsType
(Optional) Trial period for this schedule.
PaymentPeriod ns:BillingPeriodDetailsType
(Required) Regular payment period for this schedule.
MaxFailedPayments xs:int
(Optional) Number of scheduled payments that can fail before the profile is
automatically suspended. An IPN message is sent to the merchant when the specified
number of failed payments is reached.
Character length and limitations: Number string representing an integer
AutoBillOutstanding
Amount
ns:AutoBillType
(Optional) Indicates whether you would like PayPal to automatically bill the
outstanding balance amount in the next billing cycle. The outstanding balance is the
total amount of any previously failed scheduled payments that have yet to be
successfully paid. It is one of the following values:
-NoAutoBill – PayPal does not automatically bill the outstanding balance.
-AddToNextBilling – PayPal automatically bills the outstanding balance.
SOAP API Developer Reference August 2012 195
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
BillingPeriodDetailsType Fields
Field Description
PaymentPeriod.Billi
ngPeriod
ns:BillingPeriodType
(Required) Unit for billing during this subscription period. It is one of the following
values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE: The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
PaymentPeriod.Billi
ngFrequency
xs:int
(Required) Number of billing periods that make up one billing cycle.
The combination of billing frequency and billing period must be less than or equal to
one year. For example, if the billing cycle is Month, the maximum value for billing
frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing
frequency is 52.
NOTE: If the billing period is SemiMonth., the billing frequency must be 1.
PaymentPeriod.Total
BillingCycles
xs:int
(Optional) Number of billing cycles for payment period.
-For the regular payment period, if no value is specified or the value is 0, the
regular payment period continues until the profile is canceled or deactivated.
-For the regular payment period, if the value is greater than 0, the regular payment
period will expire after the trial period is finished and continue at the billing
frequency for TotalBillingCycles cycles.
PaymentPeriod.Amoun
t
cc:BasicAmountType
(Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
196 August 2012 SOAP API Developer Reference
TrialPeriod.Billing
Period
ns:BillingPeriodType
Unit for billing during this subscription period; required if you specify an optional
trial period. It is one of the following values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE: The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
TrialPeriod.Billing
Frequency
xs:int
Number of billing periods that make up one billing cycle; required if you specify an
optional trial period.
The combination of billing frequency and billing period must be less than or equal to
one year. For example, if the billing cycle is Month, the maximum value for billing
frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing
frequency is 52.
NOTE: If the billing period is SemiMonth., the billing frequency must be 1.
TrialPeriod.TotalBi
llingCycles
xs:int
(Optional) Number of billing cycles for trial payment period.
TrialPeriod.Amount cc:BasicAmountType
Billing amount for each billing cycle during this payment period; required if you
specify an optional trial period. This amount does not include shipping and tax
amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingAmount cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
SOAP API Developer Reference August 2012 197
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
ActivationDetailsType Fields
TaxAmount cc:BasicAmountType
(Optional) Taxamount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
InitialAmount cc:BasicAmountType
(Optional) Initial non-recurring payment amount due immediately upon profile
creation. Use an initial amount for enrolment or set-up fees.
NOTE: All amounts included in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
FailedInitialAmount
Action
ns:FailedPaymentAction
(Optional) Action you can specify when a payment fails. It is one of the following
values:
-ContinueOnFailure – By default, PayPal suspends the pending profile in the
event that the initial payment amount fails. You can override this default behavior
by setting this field to ContinueOnFailure. Then, if the initial payment amount
fails, PayPal adds the failed payment amount to the outstanding balance for this
recurring payment profile.
When you specify ContinueOnFailure, a success code is returned to you in the
CreateRecurringPaymentsProfile response and the recurring payments
profile is activated for scheduled billing immediately. You should check your IPN
messages or PayPal account for updates of the payment status.
-CancelOnFailure – If this field is not set or you set it to CancelOnFailure,
PayPal creates the recurring payment profile, but places it into a pending status
until the initial payment completes. If the initial payment clears, PayPal notifies
you by IPN that the pending profile has been activated. If the payment fails,
PayPal notifies you by IPN that the pending profile has been canceled.
Field Description
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
198 August 2012 SOAP API Developer Reference
AddressType (Shipping) Fields
Field Description
Name xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address; may be required for other countries.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
SOAP API Developer Reference August 2012 199
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
CreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover,
and Visa are allowable. For Canada, only MasterCard and Visa are allowable and
Interac debit cards are not supported. It is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro: See note.
NOTE: If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber xs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2 xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
StartYear xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
200 August 2012 SOAP API Developer Reference
PayerInfoType Fields
PayerNameType Fields
IssueNumber xs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
Payer ebl:EmailAddressType
(Required) Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
(Optional) Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PayerStatus ebl:PayPalUserStatusCodeType
(Optional) Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerName ebl:PersonNameType
(Optional) First and last name of buyer.
PayerCountry ebl:CountryCodeType
(Optional) Buyer’s country of residence in the form of ISO standard 3166 two-
character country codes.
Character length and limitations: 2 single-byte characters
PayerBusiness xs:string
(Optional) Buyer’s business name.
Character length and limitations: 127 single-byte characters
Address xs:string
(Optional) Buyer’s shipping address information.
Field Description
Salutation xs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
Field Description
SOAP API Developer Reference August 2012 201
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
AddressType Fields
FirstName ebl:PersonNameType
(Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
(Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
(Required) State or province.
Character length and limitations: 40 single-byte characters
Country ebl:CountryCodeType
(Required) Country code.
Character length and limitationst: 2 single-byte characters
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
202 August 2012 SOAP API Developer Reference
PaymentDetailsItemType Fields
Field Description
ItemCategory ns:ItemCategoryType
Indicates whether the item is digital or physical. For digital goods, this field is
required and must be set to Digital to get the best rates. Is one of the following
values:
-Digital
-Physical
This field is introduced in version 69.0.
Name xs:string
Item name. This field is required when ItemCategory is passed.
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.
Description xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.
Amount ebl:BasicAmountType
Cost of item. This field is required when ItemCategory is passed.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.
Quantity xs:integer
Item quantity. This field is required when ItemCategory is passed.
Character length and limitations: Any positive integer
This field is introduced in version 69.0.
SOAP API Developer Reference August 2012 203
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
CreateRecurringPaymentsProfile Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
CreateRecurringPaymentsProfile Response Fields
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.
Field Description
ProfileID xs:string
A unique identifier for future reference to the details of this recurring payment.
Character length and limitations: Up to 14 single-byte alphanumeric characters.
ProfileStatus ns:RecurringPaymentsProfileStatusType
Status of the recurring payment profile.
-ActiveProfile – The recurring payment profile has been successfully created
and activated for scheduled payments according the billing instructions from the
recurring payments profile.
-PendingProfile – The system is in the process of creating the recurring
payment profile. Please check your IPN messages for an update.
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
204 August 2012 SOAP API Developer Reference
GetRecurringPaymentsProfileDetails API Operation
The GetRecurringPaymentsProfileDetails API operation obtains information about a
recurring payments profile.
GetRecurringPaymentsProfileDetails Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetRecurringPaymentsProfileDetails Request Fields
Field Description
ProfileID xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. 19-character profile IDs are
supported for compatibility with previous versions of the PayPal API.
Character length and limitations: 14 single-byte alphanumeric characters
SOAP API Developer Reference August 2012 205
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
GetRecurringPaymentsProfileDetails Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
206 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 207
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
208 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 209
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetRecurringPaymentsProfileDetails Response Fields
Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
ProfileStatus ns:RecurringPaymentsProfileStatusType
Status of the recurring payment profile. It is one of the following values:
-Active
-Pending
-Cancelled
-Suspended
-Expired
Description xs:string
Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
210 August 2012 SOAP API Developer Reference
AutoBillOutstanding
Amount
ns:AutoBillType
Indicates whether you would like PayPal to automatically bill the outstanding balance
amount in the next billing cycle. The outstanding balance is the total amount of any
previously failed scheduled payments that have yet to be successfully paid. It is one
of the following values:
-NoAutoBill – PayPal does not automatically bill the outstanding balance
amount.
-AddToNextBilling – PayPal automatically bills the outstanding balance amount.
MaxFailedPayments xs:int
Number of scheduled payments that can fail before the profile is automatically
suspended.
Character length and limitations: Number string representing an integer
RecurringPayments
ProfileDetails
ns:RecurringPaymentsProfileDetailsType
Buyer information for this recurring payments profile.
CurrentRecurring
PaymentsPeriod
ns:BillingPeriodDetailsType
Details of the current subscription period. This field is not returned if the profile is
canceled or expired.
RecurringPayments
Summary
ns:RecurringPaymentsSummaryDetailsType
Payment summary for this recurring payments profile.
AggregateAmount ns:AmountType
Total amount collected thus far for scheduled payments.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
AggregateOptionalAm
ount
ns:AmountType
Total amount collected thus far for optional payments.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
FinalPaymentDueDate ns:DateTime
Final scheduled payment due date before the profile expires.
CreditCard ns:CreditCardDetailsType
If this is a recurring payments profile using direct payments, this field contains the
credit card information for this profile.
NOTE: Only the last 4 digits of the credit card account number are returned. The
CVV2 value is not returned.
Field Description
SOAP API Developer Reference August 2012 211
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
RecurringPaymentsProfileDetailsType Fields
AddressType (Shipping) Fields
Field Description
SubscriberName xs:string
Full name of the person receiving the product or service paid for by the recurring
payment. If not present, the name in the buyer’s PayPal account is used.
Character length and limitations: 32 single-byte characters.
SubscriberShipping
Address
ns:AddressType
The subscriber’s shipping address associated with this profile, if applicable. If you do
not specify it, the ship-to address from buyer’s PayPal account is used.
NOTE: Shipping Address is optional, but if you include it, you are required to pass
certain fields.
BillingStartdate xs:dateTime
The date when billing for this profile begins.
Must be a valid date, in UTC/GMT format.
NOTE: The profile may take up to 24 hours for activation.
ProfileReference xs:string
The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters.
Field Description
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
212 August 2012 SOAP API Developer Reference
BillingPeriodDetailsType Fields
StateOrProvince xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCode
Country code.
Character length and limitations: 2 single-byte characters
Field Description
BillingPeriod ns:BillingPeriodType
Unit for billing during this subscription period. It is one of the following values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE: The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
BillingFrequency xs:int
Number of billing periods that make up one billing cycle. The combination of billing
frequency and billing period must be less than or equal to one year. For example, if
the billing cycle is Month, the maximum value for billing frequency is 12. Similarly,
if the billing cycle is Week, the maximum value for billing frequency is 52.
NOTE: If the billing period is SemiMonth., the billing frequency must be 1.
TotalBillingCycles xs:int
Number of billing cycles for payment period (either the regular payment period or the
trial period).
-For the trial period, the value must be greater than 0.
-For the regular payment period, if no value is specified or the value is 0, the
regular payment period continues until the profile is canceled or deactivated.
-For the regular payment period, if the value is greater than 0, the regular payment
period will expire after the trial period is finished and continue at the billing
frequency for TotalBillingCycles cycles.
Field Description
SOAP API Developer Reference August 2012 213
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
RecurringPaymentsSummaryDetailsType Fields
Amount cc:BasicAmountType
Billing amount for each billing cycle during this payment period. This amount does
not include shipping and tax amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingAmount cc:BasicAmountType
Shipping amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxAmount cc:BasicAmountType
Tax amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
NextBillingDate xs:dateTime
The next scheduled billing date, in YYYY-MM-DD format.
NumberCycles
Completed
xs:int
The number of billing cycles completed in the current active subscription period. A
billing cycle is considered completed when payment is collected or after retry
attempts to collect payment for the current billing cycle have failed.
NumberCycles
Remaining
xs:int
The number of billing cycles remaining in the current active subscription period.
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
214 August 2012 SOAP API Developer Reference
CreditCardDetailsType Fields
OutstandingBalance cc:BasicAmountType
The current past due or outstanding balance for this profile.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.
FailedPaymentCount xs:int
The total number of failed billing cycles for this profile.
LastPaymentDate xs:dateTime
The date of the last successful payment received for this profile, in YYYY-MM-DD
format.
LastPaymentAmount cc:BasicAmountType
The amount of the last successful payment received for this profile.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.
Field Description
CreditCardType ebl:CreditCardType
Type of credit card. Is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro – See note.
NOTE: If the credit card type is Maestro, you must set the currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber xs:string
Credit card number. Only the last 4 digits of the credit card number are returned.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
ExpMonth xs:int
Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
Field Description
SOAP API Developer Reference August 2012 215
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
PayerInfoType Fields
AddressType Fields
ExpYear xs:int
Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CardOwner ns:PayerInfoType
Details about the owner of the credit card.
StartMonth xs:int
Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
StartYear xs:int
Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumber xs:string
Issue number of Maestro card.
Character length and limitations: 2 numeric digits
Field Description
Payer ns:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters
FirstName ns:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters
LastName ns:PersonNameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters
Address ns:AddressType
Buyer’s billing address information.
Field Description
AddressOwner ebl:AddressOwnerTypeCode
eBay company that maintains this address. It is one of the following values:
-eBay
-PayPal
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
216 August 2012 SOAP API Developer Reference
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ns:CountryCode
Country code.
Character length and limitations: 2 single-byte characters
CountryName xs:string
Expanded name of country.
Character length and limitations: 64 single-byte alphanumeric characters
Phone xs:string
Phone number.
Character length and limitations: 20 single-byte characters
Field Description
SOAP API Developer Reference August 2012 217
Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API Operation 12
ManageRecurringPaymentsProfileStatus API Operation
The ManageRecurringPaymentsProfileStatus API operation cancels, suspends, or
reactivates a recurring payments profile.
ManageRecurringPaymentsProfileStatus Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ManageRecurringPaymentsProfileStatus Request Fields
Field Description
ProfileID xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
Character length and limitations: 14 single-byte alphanumeric characters. 19
character profile IDs are supported for compatibility with previous versions of the
PayPal API.
Action ns:StatusChangeActionType
(Required) The action to be performed to the recurring payments profile. Must be one
of the following:
-Cancel – Only profiles in Active or Suspended state can be canceled.
-Suspend – Only profiles in Active state can be suspended.
-Reactivate – Only profiles in a suspended state can be reactivated.
Note xs:string
(Optional) The reason for the change in status. For profiles created using Express
Checkout, this message is included in the email notification to the buyer when the
status of the profile is successfully changed, and can also be seen by both you and the
buyer on the Status History page of the PayPal account.
Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API Operation
12
218 August 2012 SOAP API Developer Reference
ManageRecurringPaymentsProfileStatus Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
ManageRecurringPaymentsProfileStatus Response Fields
Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. For each action, an error is
returned if the recurring payments profile has a status that is not compatible with the
action. Errors are returned in the following cases:
-Cancel – Profile status is not Active or Suspended.
-Suspend – Profile status is not Active.
-Reactivate – Profile status is not Suspended.
SOAP API Developer Reference August 2012 219
Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API Operation 12
BillOutstandingAmount API Operation
The BillOutstandingAmount API operation bills the buyer for the outstanding balance
associated with a recurring payments profile.
BillOutstandingAmount Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
BillOutstandingAmount Request Fields
Field Description
ProfileID xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
NOTE: The profile must have a status of either Active or Suspended.
Character length and limitations: 14 single-byte alphanumeric characters. 19
character profile IDs are supported for compatibility with previous versions of the
PayPal API.
Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API Operation
12
220 August 2012 SOAP API Developer Reference
BillOutstandingAmount Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
BillOutstandingAmount Response Fields
Amount cc:BasicAmountType
(Optional) The amount to bill. The amount must be less than or equal to the current
outstanding balance of the profile. If no value is specified, PayPal attempts to bill the
entire outstanding balance amount.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Note xs:string
(Optional) The reason for the non-scheduled payment. For profiles created using
Express Checkout, this message is included in the email notification to the buyer for
the non-scheduled payment transaction, and can also be seen by both you and the
buyer on the Status History page of the PayPal account.
Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. An error is returned if the profile
specified in the BillOutstandingAmount request has a status of canceled or
expired.
Field Description
SOAP API Developer Reference August 2012 221
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
UpdateRecurringPaymentsProfile API Operation
The UpdateRecurringPaymentsProfile API operation updates a recurring payments profile.
UpdateRecurringPaymentsProfile Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
222 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 223
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
224 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 225
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
UpdateRecurringPaymentsProfile Request Fields
Field Description
ProfileID xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
Character length and limitations: 14 single-byte alphanumeric characters. 19
character profile IDs are supported for compatibility with previous versions of the
PayPal API.
Note xs:string
(Optional) The reason for the update to the recurring payments profile. This message
is included in the email notification to the buyer for the recurring payments profile
update. This note can also be seen by both you and the buyer on the Status History
page of the PayPal account.
Description xs:string
(Optional) Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters
SubscriberName xs:string
(Optional) Full name of the person receiving the product or service paid for by the
recurring payment. If not present, the name in the buyer’s PayPal account is used.
Character length and limitations: 32 single-byte characters
SubscriberShipping
Address
ns:AddressType
(Optional) The subscriber’s shipping address associated with this profile, if
applicable. If you do not specify it, the ship-to address from buyer’s PayPal account is
used.
NOTE: Shipping Address is optional, but if you update any of the address fields, you
must enter all of them. For example, if you want to update the subsriber’s
street address, you must specify all of the fields listed in
ShipTo: AddressType, not just the field for the street address.
ProfileReference xs:string
(Optional) The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters
AdditionalBilling
Cycles
xs:int
(Optional) The number of additional billing cycles to add to this profile.
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
226 August 2012 SOAP API Developer Reference
Amount cc:BasicAmountType
(Optional) Billing amount for each cycle in the subscription period, not including
shipping and tax amounts.
NOTE: For recurring payments with Express Checkout, the payment amount can be
increased by no more than 20% every 180 days (starting when the profile is
created).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingAmount cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during the regular payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxAmount cc:BasicAmountType
(Optional) Tax amount for each billing cycle during the regular payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
OutstandingBalance cc:BasicAmountType
(Optional) The current past due or outstanding amount for this profile. You can only
decrease the outstanding amount. It cannot be increased.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
AutoBillOutstanding
Amount
ns:AutoBillType
(Optional) This field indicates whether you would like PayPal to automatically bill
the outstanding balance amount in the next billing cycle. It is one of the following
values:
-NoAutoBill – PayPal does not automatically bill the outstanding balance.
-AddToNextBilling – PayPal automatically bills the outstanding balance
Field Description
SOAP API Developer Reference August 2012 227
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
AddressType (Shipping) Fields
MaxFailedPayments xs:int
(Optional) The number of failed payments allowed before the profile is automatically
suspended. The specified value cannot be less than the current number of failed
payments for this profile.
Character length and limitations: Number string representing an integer
BillingStartdate xs:dateTime
(Optional) The date when billing for this profile begins.
NOTE: The profile may take up to 24 hours for activation.
Character length and limitations: Must be a valid date, in UTC/GMT format
TrialPeriod ns:BillingPeriodDetailsType
(Optional) The trial period for this schedule.
PaymentPeriod ns:BillingPeriodDetailsType
(Optional) The regular payment period for this schedule.
CreditCard ns:CreditCardDetailsType
(Optional) Credit card information for this profile, if applicable. Credit card billing
address is optional, but if you update any of the address fields, you must enter all of
them. For example, if you want to update the street address, you must specify all of
the address fields listed in CreditCardDetailsType, not just the field for the
street address.
NOTE: Only enter credit card details for recurring payments with direct payments.
Field Description
Name xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
228 August 2012 SOAP API Developer Reference
BillingPeriodDetailsType Fields
StateOrProvince xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address; may be required for other countries.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
PaymentPeriod.Total
BillingCycles
xs:int
(Optional) Number of billing cycles for payment period.
-For the regular payment period, if no value is specified or the value is 0, the
regular payment period continues until the profile is canceled or deactivated.
-For the regular payment period, if the value is greater than 0, the regular payment
period will expire after the trial period is finished and continue at the billing
frequency for TotalBillingCycles cycles.
PaymentPeriod.Amoun
t
cc:BasicAmountType
(Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TrialPeriod.TotalBi
llingCycles
xs:int
(Optional) Number of billing cycles for trial payment period.
Field Description
SOAP API Developer Reference August 2012 229
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
CreditCardDetailsType Fields
TrialPeriod.Amount cc:BasicAmountType
Billing amount for each billing cycle during this payment period; required if you
specify an optional trial period. This amount does not include shipping and tax
amounts.
NOTE: All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingAmount cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxAmount cc:BasicAmountType
(Optional) Tax amount for each billing cycle during this payment period.
NOTE: All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
CreditCardType ebl:CreditCardType
(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover,
and Visa are allowable. For Canada, only MasterCard and Visa are allowable and
Interac debit cards are not supported. It is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro: See note.
NOTE: If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
Field Description
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
230 August 2012 SOAP API Developer Reference
PayerInfoType Fields
CreditCardNumber xs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
ExpMonth xs:int
(Required) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYear xs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2 xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwner ns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
StartYear xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumber xs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
Payer ns:EmailAddressType
(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FirstName ns:PersonNameType
(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
Field Description
SOAP API Developer Reference August 2012 231
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
AddressType Fields
LastName ns:PersonNameType
(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Address ns:AddressType
(Required) Buyer’s billing address information.
Field Description
Street1 xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
(Required) State or province.
Character length and limitations: 40 single-byte characters
Country ebl:CountryCodeType
(Required) Country code.
Character length and limitationst: 2 single-byte characters
PostalCode xs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
232 August 2012 SOAP API Developer Reference
UpdateRecurringPaymentsProfile Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
UpdateRecurringPaymentsProfile Response Fields
Field Description
ProfileID xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. An error is returned if the profile
specified in the BillOutstandingAmount request has a status of canceled or
expired.
SOAP API Developer Reference August 2012 233
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation 12
SetCustomerBillingAgreement API Operation
The SetCustomerBillingAgreement API operation initiates the creation of a billing
agreement.
NOTE: If you are using Express Checkout with version 54.0 or later of the API, do not use the
SetCustomerBillingAgreement API operation to set up a billing agreement. Use
the SetExpressCheckout API operation instead.
SetCustomerBillingAgreement Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SetCustomerBillingAgreement Request Fields
Field Description
BillingAgreement
Details
ns:BillingAgreementDetailsType
(Required) Details of the billing agreement such as the billing type, billing agreement
description, and payment type.
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation
12
234 August 2012 SOAP API Developer Reference
ReturnURL xs:string
(Required) URL to which the buyer’s browser is returned after choosing to pay with
PayPal.
NOTE: PayPal recommends that the value be the final review page on which the
buyer confirms the billing agreement.
Character length and limitations: no limit
CancelURL xs:string
(Required) URL to which the customer is returned if he does not approve the use of
PayPal to pay you.
NOTE: PayPal recommends that the value be the original page on which the
customer chose to pay with PayPal or establish a billing agreement.
Character length and limitations: no limit
Field Description
SOAP API Developer Reference August 2012 235
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation 12
LocaleCode xs:string
(Optional) Locale of pages displayed by PayPal during checkout. PayPal supports the
following 2-character country codes:
-AU – Australia
-AT – Austria
-BE – Belgium
-BR – Brazil
-CA – Canada
-CH – Switzerland
-CN – China
-DE – Germany
-ES – Spain
-GB – United Kingdom
-FR – France
-IT – Italy
-NL – Netherlands
-PL – Poland
-PT – Portugal
-RU – Russia
-US – United States
-The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)
Any other value defaults to US.
Character length and limitations: 2 single-byte characters
PageStyle xs:string
(Optional) Sets the Custom Payment Page Style for payment pages associated with
this button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name you chose
when adding or editing the page style in your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters
Field Description
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation
12
236 August 2012 SOAP API Developer Reference
BillingAgreementDetails Fields
cpp-header-image xs:string
(Optional) A URL for the image you want to appear at the top left of the payment
page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored on a secure (https) server.
Character length and limitations: 127 single-byte alphanumeric characters
cpp-header-border xs:string
(Optional) Sets the border color around the header of the payment page. The border is
a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels
high.
Character length and limitations: 6-character HTML hexadecimal color code in
ASCII
cpp-header-back-
color
xs:string
(Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII
cpp-payflow-color xs:string
(Optional) Sets the background color for the payment page.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII
BuyerEmail ns:EmailAddressType
(Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion of the PayPal login page.
Character length and limit: 127 single-byte alphanumeric characters
Field Description
BillingType ns:BillingCodeType
(Required) Type of billing agreement. For recurring payments, this field must be set
to RecurringPayments. In this case, you can specify up to ten billing agreements.
Other defined values are not valid.
Type of billing agreement for reference transactions. You must have permission from
PayPal to use this field. This field must be set to one of the following values:
-MerchantInitiatedBilling - PayPal creates a billing agreement for each
transaction associated with buyer. You must specify version 54.0 or higher to use
this option.
-MerchantInitiatedBillingSingleAgreement - PayPal creates a single
billing agreement for all transactions associated with buyer. Use this value unless
you need per-transaction billing agreements. You must specify version 58.0 or
higher to use this option.
Field Description
SOAP API Developer Reference August 2012 237
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation 12
SetCustomerBillingAgreement Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
BillingAgreement
Description
xs:string
Description of goods or services associated with the billing agreement. This field is
required for each recurring payment billing agreement. PayPal recommends that the
description contain a brief summary of the billing agreement terms and conditions.
For example, buyer is billed at “9.99 per month for 2 years”.
Character length and limitations: 127 single-byte alphanumeric characters
PaymentType ns:MerchantPullPaymentCodeType
(Optional) Type of PayPal payment you require for the billing agreement. It is one of
the following values:
-Any
-InstantOnly
NOTE: For recurring payments, this field is ignored.
BillingAgreement
Custom
xs:string
(Optional) Custom annotation field for your own use.
NOTE: For recurring payments, this field is ignored.
Character length and limitations: 256 single-byte alphanumeric bytes
Field Description
Recurring Payments and Reference Transactions API Operations
CreateBillingAgreement API Operation
12
238 August 2012 SOAP API Developer Reference
SetCustomerBillingAgreement Response Fields
CreateBillingAgreement API Operation
The CreateBillingAgreement API operation creates a billing agreement with a PayPal
account holder. CreateBillingAgreement is only valid for reference transactions.
CreateBillingAgreement Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
CreateBillingAgreement Request Fields
Field Description
Token xs:string
A unique time-stamped token, which uniquely identifies this transaction in
subsequent API calls.
NOTE: The token expires after 3 hours.
Character length and limitations: 20 single-byte characters
Field Description
Token xs:string
(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE: The token expires after 3 hours.
Character length and limitations: 20 single-byte characters
SOAP API Developer Reference August 2012 239
Recurring Payments and Reference Transactions API Operations
CreateBillingAgreement API Operation 12
CreateBillingAgreement API Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
CreateBillingAgreement Response Fields
Field Description
BillingAgreementID xs:string
Identification number of the billing agreement.
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation
12
240 August 2012 SOAP API Developer Reference
GetBillingAgreementCustomerDetails API Operation
The GetBillingAgreementCustomerDetails API operation obtains information about a billing
agreement’s PayPal account holder.
GetBillingAgreementCustomerDetails Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
GetBillingAgreementCustomerDetails Request Fields
Field Description
Token xs:string
(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE: The token expires after 3 hours.
Character length and limitations: 20 single-byte characters
SOAP API Developer Reference August 2012 241
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation 12
GetBillingAgreementCustomerDetails Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Only use fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation
12
242 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Only use fields described in the
documentation.
GetBillingAgreementCustomerDetails Response Fields
Field Description
PayerInfo ns:PayerInfoType
Information about the buyer such as the buyer’s name, email address, and country of
residence.
SOAP API Developer Reference August 2012 243
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation 12
PayerInfoType Fields
PayerNameType Fields
Field Description
Payer ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PayerStatus ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerName ebl:PersonNameType
First and last name of buyer.
PayerCountry ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 2-character country
codes.
Character length and limitations: 2 single-byte characters
PayerBusiness xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters
Address ns:AddressType
Buyer’s shipping address information.
Field Description
Salutation xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation
12
244 August 2012 SOAP API Developer Reference
AddressType Fields
LastName ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
AddressStatus ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
Name xs:string
Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCode
Country code.
Character length and limitations: 2 single-byte characters
Field Description
SOAP API Developer Reference August 2012 245
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation 12
BAUpdate API Operation
The BAUpdate API operation updates or deletes a billing agreement.
BAUpdate Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
BAUpdate Request Fields
Field Description
ReferenceID xs:string
(Required) An ID, such as a billing agreement ID or a reference transaction ID that is
associated with a billing agreement.
BillingAgreementSta
tus
ebl:MerchantPullStatusCodeType
(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
NOTE: If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation
12
246 August 2012 SOAP API Developer Reference
BAUpdate Response Message
NOTE: Not all fields show are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
BillingAgreement
Description
xs:string
(Optional) Description of goods or services associated with the billing agreement.
This field is required for each recurring payment billing agreement. PayPal
recommends that the description contain a brief summary of the billing agreement
terms and conditions. For example, buyer will be billed at “9.99 per month for 2
years”.
Character length and limitations: 127 single-byte alphanumeric characters
BillingAgreement
Custom
xs:string
(Optional) Custom annotation field for your own use.
NOTE: For recurring payments, this field is ignored.
Character length and limitations: 256 single-byte alphanumeric characters
Field Description
SOAP API Developer Reference August 2012 247
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation
12
248 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
BAUpdate Response Fields
Field Description
BillingType ns:BillingCodeType
Type of billing agreement.
BillingAgreement
Description
xs:string
Description of goods or services associated with the billing agreement. This field is
required for each recurring payment billing agreement.
Character length and limitations: 127 single-byte alphanumeric characters
SOAP API Developer Reference August 2012 249
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation 12
PayerInfoType Fields
BillingAgreement
Custom
xs:string
Custom annotation field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
BillingAgreementSta
tus
ebl:MerchantPullStatusCodeType
(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
NOTE: If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.
BillingAgreementMax cc:BasicAmountType
Maximum amount for this billing agreement.
NOTE: This field only has a value if the buyer signed up for PayPal using
Preapproved Payments; it is included for backwards compatibility with
legacy systems.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
PayerInfo ns:PayerInfoType
Information about the buyer such as the buyer’s name, email address, and country of
residence.
Field Description
Payer ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerID ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PayerStatus ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerName ebl:PersonNameType
First and last name of buyer.
Field Description
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation
12
250 August 2012 SOAP API Developer Reference
PayerNameType Fields
AddressType Fields
PayerCountry ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 2-character country
codes.
Character length and limitations: 2 single-byte characters
PayerBusiness xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters
Address ns:AddressType
Buyer’s shipping address information.
Field Description
Salutation xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
Name xs:string
Billing name associated with this billing address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First billing street address.
Character length and limitations: 100 single-byte characters
Field Description
SOAP API Developer Reference August 2012 251
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
DoReferenceTransaction API Operation
The DoReferenceTransaction API operation processes a payment from a buyer’s account,
which is identified by a previous transaction.
DoReferenceTransaction Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Street2 xs:string
Second billing street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of billing city.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
Billing state or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. billing ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCode
Billing country code.
Character length and limitations: 2 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
252 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 253
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
254 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 255
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoReferenceTransaction Request Fields
Field Description
ReferenceID xs:string
(Required) A transaction ID from a previous purchase, such as a credit card charge
using the DoDirectPayment API, or a billing agreement ID.
PaymentAction xs:string
(Optional) How you want to obtain payment. It is one of the following values:
-Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
-Sale – This is a final sale for which you are requesting payment.
PaymentDetails ebl:PaymentDetailsType
(Required) Information about the payment.
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
256 August 2012 SOAP API Developer Reference
IPAddress xs:string
(Optional) IP address of the buyer’s browser.
NOTE: PayPal records this IP addresses as a means to detect possible fraud.
Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
ReqConfirmShipping Whether you require that the buyer’s shipping address on file with PayPal be a
confirmed address. You must have permission from PayPal to not require a confirmed
address. It is one of the following values:
-0 – You do not require that the buyer’s shipping address be a confirmed address.
-1 – You require that the buyer’s shipping address be a confirmed address.
NOTE: Setting this field overrides the setting you have specified in your Merchant
Account Profile.
Character length and limitations: 1 single-byte numeric character
MerchantSessionId xs:string
(Optional) Your buyer session identification token.
NOTE: PayPal records this optional session identification token as an additional
means to detect possible fraud.
Character length and limitations: 64 single-byte numeric characters
ReturnFMFDetails xs:boolean
(Optional) Flag to indicate whether you want the results returned by Fraud
Management Filters. By default, you do not receive this information. It is one of the
following values:
-0 – Do not receive FMF details (default)
-1 – Receive FMF details
Field Description
SOAP API Developer Reference August 2012 257
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
SoftDescriptor xs:string
(Optional) Per transaction description of the payment that is passed to the consumer’s
credit card statement.
If the API request provides a value for the soft descriptor field, the full descriptor
displayed on the buyer’s statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
The soft descriptor can contain only the following characters:
-Alphanumeric characters
-- (dash)
-* (asterisk)
-. (period)
- {space}
If you use any other characters (such as “,”), PayPal returns an error code. The soft
descriptor does not include the phone number, which can be toggled between the
merchant’s customer service number and PayPal’s customer service number. The
maximum length of the total soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters shown in the data format. Thus, the maximum length of
the soft descriptor passed in the API request is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
-The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
-The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
-The soft descriptor is passed in as JanesFlowerGifts LLC
The resulting descriptor string on the credit card would be:
PAYPAL *EBAY JanesFlow
PaymentReason ns:PaymentReasonType
Indicates the type of transaction. It is one of the following values:
-None – Transaction is not identified as a particular type.
-Refund – Identifies the transaction as a refund.
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
258 August 2012 SOAP API Developer Reference
AddressType (Shipping) Fields
Field Description
Name xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1 xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2 xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityName xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
StateOrProvince xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCode xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address; may be required for other countries.
Character length and limitations: 20 single-byte characters
Country ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phone xs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
SOAP API Developer Reference August 2012 259
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
PaymentDetailsType Fields
Field Description
OrderTotal ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. Set this field to 0 if the transaction
does not include a one-time purchase such as when you set up a billing agreement for
a recurring payment that is not immediately charged. When the field is set to 0,
purchase-specific fields are ignored.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ItemTotal ebl:BasicAmountType
(Optional) Sum of cost of all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingTotal ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
HandlingTotal ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
260 August 2012 SOAP API Developer Reference
TaxTotal ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
OrderDescription xs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
Custom xs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
ButtonSource xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL from
your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
Field Description
SOAP API Developer Reference August 2012 261
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
PaymentDetailsItemType Fields
ShipToAddress ns:AddressType
(Optional) Address the order is shipped to.
PaymentDetailsItem ebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.
Recurring ns:RecurringFlagType
(Optional) Flag to indicate a recurring transaction. It is one of the following values:
-Any value other than Y – This is not a recurring transaction (default).
-Y – This is a recurring transaction.
NOTE: To pass Y in this field, you must have established a billing agreement with the
buyer specifying the amount, frequency, and duration of the recurring
payment.
This field is introduced in version 80.0 of the API.
Field Description
ItemCategory ns:ItemCategoryType
Indicates whether the item is digital or physical. For digital goods, this field is
required and you must set it to Digital to get the best rates. It is one of the
following values:
-Digital
-Physical
This field is introduced in version 69.0.
Name xs:string
Item name. This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters
Description xs:string
(Optional) Item description.
This field is available since version 53.0.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
262 August 2012 SOAP API Developer Reference
EbayItemPaymentDetailsItemType Fields
Number xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantity xs:integer
Item quantity. This field is required when you pass a value forItemCategory.
Character length and limitations: Any positive integer
Tax ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters
AuctionTransaction
Id
xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderID xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters
Field Description
SOAP API Developer Reference August 2012 263
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
ReferenceCreditCardDetailsType Fields
Field Description
CreditCardType ebl:CreditCardType
(Optional) Type of credit card. Is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro: See note.
For UK, only Maestro, MasterCard, Discover, and Visa are allowable. For
Canada, only MasterCard and Visa are allowable. Interac debit cards are not
supported.
NOTE: If the credit card type is Maestro, you must set the currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber xs:string
(Optional) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
ExpMonth xs:int
(Optional) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYear xs:int
(Optional) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2 xs:string
(Optional) Card Verification Value, version 2. To comply with credit card processing
regulations, you must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwner ns:PayerInfoType
(Optional) Details about the owner of the credit card.
StartMonth xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
264 August 2012 SOAP API Developer Reference
PayerNameType Fields
StartYear xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumber xs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum.
Field Description
Salutation xs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
(Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
(Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
SOAP API Developer Reference August 2012 265
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
DoReferenceTransaction Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
266 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 267
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoReferenceTransaction Response Fields for Express Checkout
Field Description
PaymentInfo ns:PaymentInfoType
Information about the payment such as the transaction ID, whether the payment is
instant or delayed, and the settlement amount.
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
268 August 2012 SOAP API Developer Reference
PaymentInfoType Fields
AVSCode xs:string
Address Verification System response code.
Character limit: 1 single-byte alphanumeric character
CVV2Code xs:string
Result of the CVV2 check by PayPal.
BillingAgreementID xs:string
Billing agreement identifier returned if the value of ReferenceID in the request is a
billing agreement identification number.
FMFDetails ebl:FMFDetailsType
Fraud filter details.
PaymentAdviceCode xs:string
Response code from the processor when a recurring transaction is declined. For
details on the meanings of the codes, see https://merchant.paypal.com/us/cgi-
bin/?&cmd=_render-content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Field Description
SOAP API Developer Reference August 2012 269
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
ParentTransactionID xs:string
Parent or related transaction identification number. This value in this field is for the
following transaction types:
-Reversal – Capture of an authorized transaction.
-Reversal – Reauthorization of a transaction.
-Capture of an order – The value of ParentTransactionID is the original
OrderID.
-Authorization of an order – The value of ParentTransactionID is the original
OrderID.
-Capture of an order authorization.
-Void of an order – The value of ParentTransactionID is the original
OrderID.
Character length and limitations: 16 digits
ReceiptID xs:string
Receipt identification number
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format
TransactionType ns:PaymentTransactionCodeType
The type of transaction. It is one of the following values:
-cart
-express-checkout
Character length and limitations:15 single-byte characters
PaymentType ebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
-none
-echeck
-instant
Character length and limitations: 7 single-byte characters
PaymentDate xs:dateTime
Time/date stamp of payment,
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
GrossAmount ebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
270 August 2012 SOAP API Developer Reference
FeeAmount ebl:BasicAmountType
PayPal fee amount charged for the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
SettleAmount ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxAmount ebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ExchangeRate xs:string
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point
Field Description
SOAP API Developer Reference August 2012 271
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
PaymentStatus ebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
-None – No status
-Canceled-Reversal– A reversal has been canceled, for example, when you
win a dispute and the funds for the reversal have been returned to you.
-Completed – 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 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 buyer’s bank account.
-In-Progress – The transaction has not terminated, for example, an
authorization may be awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field 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.
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
272 August 2012 SOAP API Developer Reference
PendingReason ebl:PendingStatusCodeType
The reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your buyer 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.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-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.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
-unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
-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.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
ReasonCode ebl:ReasonCodeType
The reason for a reversal if the transaction type is reversal. It is one of the following
values:
-none – No reason code.
-chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
-guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
-buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
-refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
-other – A reversal has occurred on this transaction due to a reason not listed
above.
Field Description
SOAP API Developer Reference August 2012 273
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
FMFDetailsType Fields
ProtectionEligibili
ty
xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payments and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
ProtectionEligibili
tyType
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is introduced in API version 64.4.
StoreId xs:string
StoreId as entered in the transaction.
TerminalId xs:string
TerminalId as entered in the transaction.
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment.
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment.
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
274 August 2012 SOAP API Developer Reference
RiskFilterListType Fields
Field Description
ID xs:int
Filter ID. It is one of the following values:
-1 - AVS No Match
-2 - AVS Partial Match
-3 - AVS Unavailable/Unsupported
-4 - Card Security Code (CSC) Mismatch
-5 - Maximum Transaction Amount
-6 - Unconfirmed Address
-7 - Country Monitor
-8 - Large Order Number
-9 - Billing/Shipping Address Mismatch
-10 - Risky ZIP Code
-11 - Suspected Freight Forwarder Check
-12 - Total Purchase Price Minimum
-13 - IP Address Velocity
-14 - Risky Email Address Domain Check
-15 - Risky Bank Identification Number (BIN) Check
-16 - Risky IP Address Range
-17 - PayPal Fraud Model
Name xs:string
Filter name.
Description xs:string
Filter description.
SOAP API Developer Reference August 2012 275
13 RefundTransaction API Operation
The RefundTransaction API operation issues a refund to the PayPal account holder associated
with a transaction.
RefundTransaction Request Message
RefundTransaction API Operation
RefundTransaction Request Message
13
276 August 2012 SOAP API Developer Reference
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
RefundTransaction Request Fields
Field Description
TransactionID xs:string
(Required) Unique identifier of the transaction to be refunded.
Character length and limitations: 17 single-byte alphanumeric characters
InvoiceID xs:string
(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
RefundType ebl:RefundPurposeTypeCodeType
Type of refund you are making. It is one of the following values:
-Full – Full refund (default).
-Partial – Partial refund.
-ExternalDispute – External dispute. (Value available since version 82.0)
-Other – Other type of refund. (Value available since version 82.0)
Amount ebl:BasicAmountType
(Optional) Refund amount. The amount is required if RefundType is Partial.
NOTE: If RefundType is Full, do not set the amount.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Memo xs:string
(Optional) Custom memo about the refund.
Character length and limitations: 255 single-byte alphanumeric characters
RetryUntil xs:dateTime
(Optional) Maximum time until you must retry the refund.
NOTE: This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
SOAP API Developer Reference August 2012 277
RefundTransaction API Operation
RefundTransaction Request Message 13
MerchantStoreDetailsTypeFields
RefundSource ebl:RefundSourceCodeType
(Optional)Type of PayPal funding source (balance or eCheck) that can be used for
auto refund. It is one of the following values:
-any – The merchant does not have a preference. Use any available funding
source.
-default – Use the merchant’s preferred funding source, as configured in the
merchant’s profile.
-instant – Use the merchant’s balance as the funding source.
-eCheck – The merchant prefers using the eCheck funding source. If the
merchant’s PayPal balance can cover the refund amount, use the PayPal balance.
NOTE: This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
MerchantStoreDetail
s
ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.
RefundAdvice xs:boolean
(Optional) Flag to indicate that the buyer was already given store credit for a given
transaction. It is one of the following values:
-true – The buyer was already given store credit for a given transaction.
-false – The buyer was not given store credit for a given transaction.
This field is available since version 85.0.
RefundItemDetails ebl:InvoiceItemType
(Optional) Details about the individual items to be returned.
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
StoreID xs:string
Identifier of the merchant store at which the refund is given. This field is
required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
RefundTransaction API Operation
RefundTransaction Response Message
13
278 August 2012 SOAP API Developer Reference
RefundTransaction Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
RefundTransaction Response Fields
TerminalID xs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
RefundTransactionID xs:string
Unique transaction ID of the refund.
Character length and limitations:17 single-byte characters
Field Description
SOAP API Developer Reference August 2012 279
RefundTransaction API Operation
RefundTransaction Response Message 13
FeeRefundAmount ebl:BasicAmountType
Transaction fee refunded to original recipient of payment.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
GrossRefundAmount ebl:BasicAmountType
Amount refunded to the original payer. Say, for example, a buyer makes $100
purchase, the buyer was refunded $20 a week ago and is refunded $30 in this
transaction. The gross refund amount is $30 (in this transaction).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
NetRefundAmount ebl:BasicAmountType
Amount subtracted from PayPal balance of the original recipient of payment, to make
this refund.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TotalRefundedAmount ebl:BasicAmountType
Total amount refunded so far from the original purchase. Say, for example, a buyer
makes $100 purchase, the buyer was refunded $20 a week ago and is refunded $30 in
this transaction. The gross refund amount is $30 (in this transaction). The total
refunded amount is $50.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is available since version 67.0.
RefundInfo ebl:RefundInfoType
Contains refund payment status information.
This field is available since version 84.0.
MsgSubId xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
RefundTransaction API Operation
RefundTransaction Response Message
13
280 August 2012 SOAP API Developer Reference
RefundInfoType Fields
Field Description
RefundStatus ns:PaymentStatusCodeType
Status of the refund. It is one of the following values:
-instant
-delayed
This field is available since version 84.0.
PendingReason xs:PendingStatusCodeType
Reason that the refund payment status is delayed. It is one of the following values:
-none – The refund status is instant.
-echeck – The refund status is delayed.
This field is available since version 84.0.
SOAP API Developer Reference August 2012 281
14 TransactionSearch API Operation
The TransactionSearch API searches transaction history for transactions that meet the
specified criteria.
NOTE: The maximum number of transactions that can be returned from a TransactionSearch
API call is 100.
TransactionSearch Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
TransactionSearch API Operation
TransactionSearch Request Message
14
282 August 2012 SOAP API Developer Reference
TransactionSearch Request Fields
Field Description
StartDate xs:dateTime
(Required) The earliest transaction date at which to start the search.
Character length and limitations: No wildcards are allowed. The value must be in
UTC/GMT.
EndDate xs:dateTime
(Optional) The latest transaction date to be included in the search.
Character length and limitations: No wildcards are allowed. The value must be in
UTC/GMT.
Payer xs:string
ebl:EmailAddressType
(Optional) Search by the buyer’s email address.
Character length and limitations: 127 single-byte alphanumeric characters
Receiver ebl:EmailAddressType
(Optional) Search by the receiver’s email address. If the merchant account has only
one email address, this is the primary email. It can also be a non-primary email
address.
ReceiptID xs:string
(Optional) Search by the PayPal Account Optional receipt ID. This field is not
applicable to point-of-sale transactions.
TransactionID ebl:TransactionID
(Optional) Search by the transaction ID. The returned results are from the merchant’s
transaction records.
Character length and limitations: 19 single-byte characters maximum
InvoiceID xs:string
(Optional) Search by invoice identification key, as set by you for the original
transaction. This field searches the records for items the merchant sells.
Character length and limitations: 127 single-byte characters maximum with no
wildcards allowed
CardNumber xs:string
(Optional) Search by credit card number, as set by you for the original transaction.
This field searches the records for items the merchant sells. The field is not applicable
to point-of-sale.
NOTE: No wildcards are allowed.
Character length and limitations: Must be at least 11 and no more than 25 single-byte
numeric characters maximum. Special punctuation, such as dashes or spaces, is
ignored.
PayerName ebl:PersonNameType
(Optional) Search by the buyer’s name.
SOAP API Developer Reference August 2012 283
TransactionSearch API Operation
TransactionSearch Request Message 14
AuctionItemNumber xs:string
(Optional) Search by auction item number of the purchased goods. This field is not
applicable to point-of-sale.
TransactionClass ePaymentTransactionClassCodeType
(Optional) Search by classification of transaction. Some kinds of possible classes of
transactions are not searchable with this field. You cannot search for bank transfer
withdrawals, for example. It is one of the following values:
-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 ebl:BasicAmountType
(Optional) Search by transaction amount.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CurrencyCode xs:token
(Optional) Search by 3-character, ISO 4217 currency code.
Field Description
TransactionSearch API Operation
TransactionSearch Request Message
14
284 August 2012 SOAP API Developer Reference
PayerName Fields
Status ebl:PaymentTransactionStatusCodeType
(Optional) Search by transaction status. It is one of the following values:
-Pending – The payment is pending. The specific reason the payment is pending
is returned by the GetTransactionDetails API PendingReason field.
-Processing – The payment is being processed.
-Success – The payment has been completed and the funds have been added
successfully to your account balance.
-Denied – You denied the payment. This happens only if the payment was
previously pending.
-Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer.
ProfileID xs:string
(Optional) An alphanumeric string (generated by PayPal) that uniquely identifies a
recurring profile. You can specify the Profile ID in the TransactionSearch API
operation to obtain all payments associated with the identified profile.
Field Description
Salutation xs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstName ebl:PersonNameType
(Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleName ebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastName ebl:NameType
(Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffix ebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
SOAP API Developer Reference August 2012 285
TransactionSearch API Operation
TransactionSearch Response Message 14
TransactionSearch Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
TransactionSearch Response Fields
Field Description
Timestamp xs:dateTime
Date and time in UTC/GMT that the transaction occurred.
TransactionSearch API Operation
TransactionSearch Response Message
14
286 August 2012 SOAP API Developer Reference
Timezone xs:string
Time zone of the transaction. The value is always GMT.
Type xs:string
Type of the transaction. It is one of the following values:
-Currency Conversion (credit)
-Currency Conversion (debit)
-Payment
-Recurring Payment
-Temporary Hold
-Transfer
-Donation
Payer ebl:EmailAddressType
Email address of either the buyer or the payment recipient (the “payee”). If the
payment amount is positive, this field is the recipient of the funds. If the payment is
negative, this field is the paying buyer.
PayerDisplayName xs:string
Display name of the buyer.
TransactionID xs:string
Merchant’s transaction ID.
Status xs:string
The status of the transaction.
GrossAmount ebl:BasicAmountType
The total gross amount charged, including any profile shipping cost and taxes.
FeeAmount ebl:BasicAmountType
The fee that PayPal charged for the transaction.
NetAmount ebl:BasicAmountType
The net amount of the transaction.
Field Description
SOAP API Developer Reference August 2012 287
AAPI Error Codes
The PayPal API can return multiple errors for any operation.
General API Errors
General API Errors
Error
Code Short Message Long Message Correcting This Error
10002 Authentication/Authoriza
tion Failed Username/Password is incorrect This error can be caused by an incorrect
API username, an incorrect API
password, or an invalid API signature.
Make sure that all three of these values
are correct. For your security, PayPal
does not report exactly which of these
three values might be in error.
10002 Authentication/Authoriza
tion Failed You do not have permission to
make this API call
10002 Authentication/Authoriza
tion Failed Account is locked or inactive
10002 Internal Error Internal Error
10002 Authentication/Authoriza
tion Failed Internal Error
10002 Authentication/Authoriza
tion Failed Account is not verified
10002 Authentication/Authoriza
tion Failed This call is not defined in the
database!
10002 Authentication/Authoriza
tion Failed Token is not valid
10002 Restricted account Account is restricted Your PayPal merchant account has been
restricted. Contact your PayPal account
manager for resolution.
10002 Authentication/Authoriza
tion Failed API access is disabled for this
account
API Error Codes
Validation Errors
A
288 August 2012 SOAP API Developer Reference
Validation Errors
Validation Errors
10002 Authentication/Authoriza
tion Failed Client certificate is disabled
10006 Version error Version is not supported
10008 Security error Security header is not valid
10101 This API Temporarily
Unavailable This API is temporarily
unavailable. Please try later.
Error Code Short Message Long Message
81000 Missing Parameter Required Parameter Missing : Unable to identify
parameter
81001 Invalid Parameter A Parameter is Invalid : Unable to identify parameter
81002 Unspecified Method Method Specified is not Supported
81003 Unspecified Method No Method Specified
81004 Unspecified Method No Request Received
81100 Missing Parameter OrderTotal (Amt) : Required parameter missing
81101 Missing Parameter MaxAmt : Required parameter missing
81102 Missing Parameter ReturnURL: Required parameter missing
81103 Missing Parameter NotifyURL : Required parameter missing
81104 Missing Parameter CancelURL : Required parameter missing
81105 Missing Parameter ShipToStreet : Required parameter missing
81106 Missing Parameter ShipToStreet2 : Required parameter missing
81107 Missing Parameter ShipToCity : Required parameter missing
81108 Missing Parameter ShipToState : Required parameter missing
81109 Missing Parameter ShipToZip : Required parameter missing
81110 Missing Parameter Country : Required parameter missing
81111 Missing Parameter ReqConfirmShipping : Required parameter missing
81112 Missing Parameter NoShipping : Required parameter missing
81113 Missing Parameter AddrOverride : Required parameter missing
Error
Code Short Message Long Message Correcting This Error
SOAP API Developer Reference August 2012 289
API Error Codes
Validation Errors A
81114 Missing Parameter LocaleCode : Required parameter missing
81115 Missing Parameter PaymentAction : Required parameter missing
81116 Missing Parameter Email : Required parameter missing
81117 Missing Parameter Token : Required parameter missing
81118 Missing Parameter PayerID : Required parameter missing
81119 Missing Parameter ItemAmt : Required parameter missing
81120 Missing Parameter ShippingAmt : Required parameter missing
81121 Missing Parameter HandlingAmt : Required parameter missing
81122 Missing Parameter TaxAmt : Required parameter missing
81123 Missing Parameter IPAddress : Required parameter missing
81124 Missing Parameter ShipToName : Required parameter missing
81125 Missing Parameter L_Amt : Required parameter missing
81126 Missing Parameter Amt : Required parameter missing
81127 Missing Parameter L_TaxAmt : Required parameter missing
81128 Missing Parameter AuthorizationID : Required parameter missing
81129 Missing Parameter CompleteType : Required parameter missing
81130 Missing Parameter CurrencyCode : Required parameter missing
81131 Missing Parameter TransactionID : Required parameter missing
81132 Missing Parameter TransactionEntity : Required parameter missing
81133 Missing Parameter Acct : Required parameter missing
81134 Missing Parameter ExpDate : Required parameter missing
81135 Missing Parameter FirstName : Required parameter missing
81136 Missing Parameter LastName : Required parameter missing
81137 Missing Parameter Street : Required parameter missing
81138 Missing Parameter Street2 : Required parameter missing
81139 Missing Parameter City : Required parameter missing
81140 Missing Parameter State : Required parameter missing
81141 Missing Parameter Zip : Required parameter missing
81142 Missing Parameter CountryCode : Required parameter missing
81143 Missing Parameter RefundType : Required parameter missing
81144 Missing Parameter StartDate : Required parameter missing
Error Code Short Message Long Message
API Error Codes
Validation Errors
A
290 August 2012 SOAP API Developer Reference
81145 Missing Parameter EndDate : Required parameter missing
81146 Missing Parameter MPID : Required parameter missing
81147 Missing Parameter CreditCardType : Required parameter missing
81148 Missing Parameter User : Required parameter missing
81149 Missing Parameter Pwd : Required parameter missing
81150 Missing Parameter Version : Required parameter missing
81200 Missing Parameter Amt : Invalid parameter
81201 Invalid Parameter MaxAmt : Invalid parameter
81203 Invalid Parameter NotifyURL : Invalid parameter
81205 Invalid Parameter ShipToStreet : Invalid parameter
81206 Invalid Parameter ShipToStreet2 : Invalid parameter
81207 Invalid Parameter ShipToCity : Invalid parameter
81208 Invalid Parameter ShipToState : Invalid parameter
81209 Invalid Parameter ShipToZip : Invalid parameter
81210 Invalid Parameter Country : Invalid parameter
81211 Invalid Parameter ReqConfirmShipping : Invalid parameter
81212 Invalid Parameter Noshipping : Invalid parameter
81213 Invalid Parameter AddrOverride : Invalid parameter
81214 Invalid Parameter LocaleCode : Invalid parameter
81215 Invalid Parameter PaymentAction : Invalid parameter
81219 Invalid Parameter ItemAmt : Invalid parameter
81220 Invalid Parameter ShippingAmt : Invalid parameter
81221 Invalid Parameter HandlingTotal Amt : Invalid parameter
81222 Invalid Parameter TaxAmt : Invalid parameter
81223 Invalid Parameter IPAddress : Invalid parameter
81224 Invalid Parameter ShipToName : Invalid parameter
81225 Invalid Parameter L_Amt : Invalid parameter
81226 Invalid Parameter Amt : Invalid parameter
81227 Invalid Parameter L_TaxAmt : Invalid parameter
81229 Invalid Parameter CompleteType : Invalid parameter
81230 Invalid Parameter CurrencyCode : Invalid parameter
Error Code Short Message Long Message
SOAP API Developer Reference August 2012 291
API Error Codes
DirectPayment API Errors A
DirectPayment API Errors
DirectPayment API Errors
81232 Invalid Parameter TransactionEntity : Invalid parameter
81234 Invalid Parameter ExpDate : Invalid parameter
81235 Invalid Parameter FirstName : Invalid parameter
81236 Invalid Parameter LastName : Invalid parameter
81237 Invalid Parameter Street : Invalid parameter
81238 Invalid Parameter Street2 : Invalid parameter
81239 Invalid Parameter City : Invalid parameter
81243 Invalid Parameter RefundType : Invalid parameter
81244 Invalid Parameter StartDate : Invalid parameter
81245 Invalid Parameter EndDate : Invalid parameter
81247 Invalid Parameter CreditCardType : Invalid parameter
81248 Invalid Parameter Username : Invalid parameter
81249 Invalid Parameter Password : Invalid parameter
81250 Invalid Parameter Version : Invalid parameter
81251 Internal Error Internal Service Error
99998 Transaction refused because of an
invalid argument. See additional
error messages for details.
Currency is not supported
Error
Code Short Message Long Message Corrective Action
10102 PaymentAction of Order
Temporarily Unavailable PaymentAction of Order is
temporarily unavailable. Please
try later or use other
PaymentAction.
10401 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Order total is missing.
Error Code Short Message Long Message
API Error Codes
DirectPayment API Errors
A
292 August 2012 SOAP API Developer Reference
10418 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The currencies of the shopping
cart amounts must be the same.
10426 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item total is invalid.
10427 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping total is invalid.
10428 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Handling total is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Tax total is invalid.
10432 Invalid argument Invoice ID value exceeds
maximum allowable length.
10485 Payment not authorized Payment has not been authorized
by the user.
10500 Invalid Configuration This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when you have not agreed to the
billing agreement.
10501 Invalid Configuration This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when the billing agreement is
disabled or inactive.
10502 Invalid Data This transaction cannot be
processed. Please use a valid
credit card.
The credit card used is expired.
10504 Invalid Data This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The CVV provided is invalid. The CVV
is between 3-4 digits long.
10505 Gateway Decline This transaction cannot be
processed. The transaction was refused because the
AVS response returned the value of N,
and the merchant account is not able to
accept such transactions.
Error
Code Short Message Long Message Corrective Action
SOAP API Developer Reference August 2012 293
API Error Codes
DirectPayment API Errors A
10507 Invalid Configuration This transaction cannot be
processed. Please contact PayPal
Customer Service.
Your PayPal account is restricted.
Contact PayPal for more information.
10508 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration date.
The expiration date must be a two-digit
month and four-digit year.
10509 Invalid Data This transaction cannot be
processed. You must submit an IP address of the
buyer with each API call.
10510 Invalid Data The credit card type is not
supported. Try another card type. The credit card type entered is not
currently supported by PayPal.
10511 Invalid Data This transaction cannot be
processed. The merchant selected a value for the
PaymentAction field that is not
supported.
10512 Invalid Data This transaction cannot be
processed. Please enter a first
name.
The first name of the buyer is required
for this merchant.
10513 Invalid Data This transaction cannot be
processed. Please enter a last
name.
The last name of the buyer is required
for this merchant.
10519 Invalid Data Please enter a credit card. The credit card field was blank.
10520 Invalid Data This transaction cannot be
processed. The total amount and item amounts do
not match.
10521 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card.
The credit card entered is invalid.
10523 Internal Error This transaction cannot be
processed. None. This is a PayPal internal error.
10525 Invalid Data This transaction cannot be
processed. The amount to be
charged is zero.
The merchant entered an amount of zero.
10526 Invalid Data This transaction cannot be
processed. The currency is not
supported at this time.
The currency code entered is not
supported.
10527 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is invalid.
10534 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is currently
restricted by PayPal. Contact PayPal for
more information.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
294 August 2012 SOAP API Developer Reference
10535 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is invalid.
10536 Invalid Data This transaction cannot be
processed. The merchant entered an invoice ID that
is already associated with a transaction
by the same merchant. By default, the
invoice ID must be unique for all
transactions. To change this setting, log
into PayPal or contact customer service.
10537 Filter Decline This transaction cannot be
processed. The transaction was declined by the
country filter managed by the merchant.
To accept this transaction, change your
risk settings on PayPal.
10538 Filter Decline This transaction cannot be
processed. The transaction was declined by the
maximum amount filter managed by the
merchant. To accept this transaction,
change your risk settings on PayPal.
10539 Filter Decline This transaction cannot be
processed. The transaction was declined by PayPal.
Contact PayPal for more information.
10540 Invalid Data The transaction cannot be
processed due to an invalid
address.
The transaction was declined by PayPal
because of an invalid address.
10541 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is currently
restricted by PayPal. Contact PayPal for
more information.
10542 Invalid Data This transaction cannot be
processed. Please enter a valid
email address.
The email address provided by the buyer
is in an invalid format.
10544 Gateway Decline This transaction cannot be
processed. The transaction was declined by PayPal.
Contact PayPal for more information.
10545 Gateway Decline This transaction cannot be
processed. The transaction was declined by PayPal
because of possible fraudulent activity.
Contact PayPal for more information.
10546 Gateway Decline This transaction cannot be
processed. The transaction was declined by PayPal
because of possible fraudulent activity
on the IP address. Contact PayPal for
more information.
10547 Internal Error This transaction cannot be
processed. None. This is a PayPal internal error.
Error
Code Short Message Long Message Corrective Action
SOAP API Developer Reference August 2012 295
API Error Codes
DirectPayment API Errors A
10548 Invalid Configuration This transaction cannot be
processed. The merchant’s
account is not able to process
transactions.
The merchant account attempting the
transaction is not a business account at
PayPal. Check your account settings.
10549 Invalid Configuration This transaction cannot be
processed. The merchan’s
account is not able to process
transactions.
The merchant account attempting the
transaction is not able to process Direct
Payment transactions. Contact PayPal
for more information.
10550 Invalid Configuration This transaction cannot be
processed. Access to Direct Payment was disabled
for your account. Contact PayPal for
more information.
10552 Invalid Configuration This transaction cannot be
processed. The merchant account attempting the
transaction does not have a confirmed
email address with PayPal. Check your
account settings.
10553 Gateway Decline This transaction cannot be
processed. The merchant attempted a transaction
where the amount exceeded the upper
limit for that merchant.
10554 Filter Decline This transaction cannot be
processed. The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set to
decline transaction when the AVS
returned a no match (AVS = N).
10555 Filter Decline This transaction cannot be
processed. The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set the
filter to decline transactions when the
AVS returns a partial match.
10556 Filter Decline This transaction cannot be
processed. The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set the
filter to decline transactions when the
AVS is unsupported.
10561 Invalid Data There’s an error with this
transaction. Please enter
complete billing address.
10562 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration year.
10563 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration month.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
296 August 2012 SOAP API Developer Reference
10564 Gateway Decline This transaction cannot be
processed. There was a problem processing this
transaction.
10565 Merchant country
unsupported The merchant country is not
supported.
10566 Credit card type
unsupported The credit card type is not
supported.
10567 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
10571 Transaction approved, but
with invalid Card
Security Code (CSC)
format.
This transaction was approved,
although the Card Security Code
(CSC) had too few, too many, or
invalid characters. Based on your
account profile settings, the
invalid CSC was not given to the
card issuer for its approval
process.
If you want to require valid CVV values,
change the risk control settings in your
account profile.
10701 Invalid Data There’s an error with this
transaction. Please enter a valid
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10702 Invalid Data There’s an error with this
transaction. Please enter a valid
address1 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10703 Invalid Data There’s an error with this
transaction. Please enter a valid
address2 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10704 Invalid Data There’s an error with this
transaction. Please enter a valid
city in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10705 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10706 Invalid Data There’s an error with this
transaction. Please enter a valid
postal code in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10707 Invalid Data There’s an error with this
transaction. Please enter a valid
country in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
SOAP API Developer Reference August 2012 297
API Error Codes
DirectPayment API Errors A
10708 Invalid Data There’s an error with this
transaction. Please enter a
complete billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10709 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10709 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10710 Invalid Data There’s an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10710 Invalid Data There’s an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10711 Invalid Data There’s an error with this
transaction. Please enter your
state in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10712 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10713 Invalid Data There’s an error with this
transaction. Please enter a
country in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10713 Invalid Data There’s an error with this
transaction. Please enter a
country in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10714 Invalid Data There’s an error with this
transaction. Please enter a valid
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10715 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10716 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
298 August 2012 SOAP API Developer Reference
10717 Invalid Data There’s an error with this
transaction. Please enter a valid
postal code in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10718 Invalid Data There’s an error with this
transaction. Please enter a valid
city and state in the billing
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10719 Invalid Data There’s an error with this
transaction. Please enter a valid
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10720 Invalid Data There’s an error with this
transaction. Please enter a valid
address1 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10721 Invalid Data There’s an error with this
transaction. Please enter a valid
address2 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10722 Invalid Data There’s an error with this
transaction. Please enter a valid
city in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10723 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10724 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10725 Invalid Data There’s an error with this
transaction. Please enter a valid
country in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10726 Invalid Data There’s an error with this
transaction. Please enter a
complete shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10726 Invalid Data There’s an error with this
transaction. Please enter a
complete shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10727 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
SOAP API Developer Reference August 2012 299
API Error Codes
DirectPayment API Errors A
10727 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10728 Invalid Data There’s an error with this
transaction. Please enter a city in
the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10728 Invalid Data There’s an error with this
transaction. Please enter a city in
the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10729 Invalid Data There’s an error with this
transaction. Please enter your
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10730 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10731 Invalid Data There’s an error with this
transaction. Please enter a
country in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10731 Invalid Data There’s an error with this
transaction. Please enter a
country in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10732 Invalid Data There’s an error with this
transaction. Please enter a valid
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10733 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10734 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10735 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10736 Invalid Data There’s an error with this
transaction. Please enter a valid
city and state in the shipping
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
300 August 2012 SOAP API Developer Reference
10744 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the billing
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10745 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the shipping
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10746 Invalid Data This transaction cannot be
processed. Please use a valid
country on the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10747 Invalid Data This transaction cannot be
processed. The merchant entered an IP address that
was in an invalid format. The IP address
must be in a format such as
123.456.123.456.
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification Number.
The merchant’s configuration requires a
CVV to be entered, but no CVV was
provided with this transaction. Contact
PayPal if you wish to change this setting.
10750 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10751 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
The merchant provided an address either
in the United States or Canada, but the
state provided is not a valid state in
either country.
10752 Gateway Decline This transaction cannot be
processed. The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.
10754 Gateway Decline This transaction cannot be
processed. The transaction was declined by PayPal.
Contact PayPal for more information.
10755 Invalid Data This transaction cannot be
processed due to an unsupported
currency.
The currency code entered by the
merchant is not supported.
10756 Gateway Decline The transaction cannot be
processed. The country and
billing address associated with
this credit card do not match.
None. This is a PayPal internal error.
10758 Invalid Configuration There’s been an error due to
invalid API username and/or
password.
The API username or password is
incorrect for this merchant.
Error
Code Short Message Long Message Corrective Action
SOAP API Developer Reference August 2012 301
API Error Codes
DirectPayment API Errors A
10759 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The transaction was declined by PayPal.
Contact PayPal for more information.
10760 Invalid Configuration This transaction cannot be
processed. The country listed for
your business address is not
currently supported.
The merchant’s country of residence
listed in their PayPal account is not
currently supported to allow Direct
Payment transactions.
10761 Gateway Decline This transaction cannot be
processed. Please check the
status of your first transaction
before placing another order.
The transaction was declined because
PayPal is currently processing a
transaction by the same buyer for the
same amount. Can occur when a buyer
submits multiple, identical transactions
in quick succession.
10762 Gateway Decline This transaction cannot be
processed. The CVV provide is invalid. The CVV is
between 3-4 digits long.
10763 Invalid Data This transaction cannot be
processed. None - this is a PayPal internal error.
10764 This transaction cannot be
processed at this time.
Please try again later.
This transaction cannot be
processed at this time. Please try
again later.
The transaction was declined by PayPal.
Please try again later. If the problem
persists, please contact PayPal.
11068 Seller restriction. All sellers restricted.
11610 Payment Pending your
review in Fraud
Management Filters
Payment Pending your review in
Fraud Management Filters
11611 Transaction blocked by
your settings in FMF Transaction blocked by your
settings in FMF
11612 Could not process your
request to accept/deny the
transaction
Could not process your request to
accept/deny the transaction
11821 This transaction cannot be
processed This transaction cannot be
processed because it has already
been denied by a Fraud
Management Filter
You cannot capture a payment after it
has been denied by a Fraud Management
Filter. You can control whether a Fraud
Management Filter denies a transaction
by changing the filter's settings in the
profile.
12000 Transaction is not
compliant due to missing
or invalid 3-D Secure
authentication values.
Transaction is not compliant due
to missing or invalid 3-D Secure
authentication values.
Check ECI, ECI3DS, CAVV, XID fields.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
302 August 2012 SOAP API Developer Reference
12001 Transaction is not
compliant due to missing
or invalid 3-D Secure
authentication values.
Transaction is not compliant due
to missing or invalid 3-D Secure
authentication values.
Check ECI, ECI3DS, CAVV, XID fields.
15001 Gateway Decline This transaction cannot be
processed. The transaction was rejected by PayPal
because of excessive failures over a
short period of time for this credit card.
Contact PayPal for more information.
15002 Gateway Decline This transaction cannot be
processed. The transaction was declined by PayPal.
Contact PayPal for more information.
15003 Invalid Configuration This transaction cannot be
processed. The transaction was declined because
the merchant does not have a valid
commercial entity agreement on file
with PayPal. Contact PayPal for more
information.
15004 Gateway Decline This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The transaction was declined because
the CVV entered does not match the
credit card.
15005 Processor Decline This transaction cannot be
processed. The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.
15006 Processor Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.
15007 Processor Decline This transaction cannot be
processed. Please use a valid
credit card.
The transaction was declined by the
issuing bank because of an expired
credit card. The merchant should attempt
another card.
15008 Invalid Data This transaction has been
completed, but the total of items
in the cart did not match the total
of all items.
15011 Gateway Decline This credit card was issued from
an unsupported country.
Error
Code Short Message Long Message Corrective Action
SOAP API Developer Reference August 2012 303
API Error Codes
SetExpressCheckout API Errors A
SetExpressCheckout API Errors
SetExpressCheckout API Errors
Error
Code Short Message Long Message Correcting This Error...
10001 ButtonSource value
truncated. The transaction could not be loaded
10001 Internal Error Internal Error
10003 Missing argument. OtherPaymentMethodID is missing.
10003 Missing argument. OtherPaymentMethodLabel is
missing.
10003 Missing argument. OtherPaymentMethodType is
missing.
10003 Missing argument. One or more of these giropay URLs
is missing: giropaySuccessURL,
giropayCancelURL,
BanktxnPendingURL.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Transaction refused because of an
invalid argument. See additional
error messages for details.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid value for request billing
address parameter.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid item URL.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
OtherPaymentMethodType is
invalid.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
RegistrationDate of buyer is invalid.
API Error Codes
SetExpressCheckout API Errors
A
304 August 2012 SOAP API Developer Reference
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback overall
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback overall
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback total
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback total
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback recent
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback recent
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
SellerRegistrationDate is invalid.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback overall
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback overall
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback total
positive count.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 305
API Error Codes
SetExpressCheckout API Errors A
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback total
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback recent
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback recent
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay item transaction date.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay item buyer protection
type.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay item payment hold risk.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Multiple eBay order IDs not allowed.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
AllowPushFunding value specified is
invalid. It must be 0 or 1 or an empty
string.
10005 Option not supported. Merchant not enabled to use
enhanced checkout data.
10005 Option not supported. Merchant not enabled to use
OtherPaymentMethodDetails.
10005 Option not supported. Transaction ID is not supported.
10007 Permission denied You do not have permission to make
this API call
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
306 August 2012 SOAP API Developer Reference
10010 Invalid Invoice Non-ASCII invoice id is not
supported.
10101 Option not supported. Express Checkout temporarily
unavailable. Please try later.
10102 PaymentAction of Order
Temporarily Unavailable PaymentAction of Order is
temporarily unavailable. Please try
later or use other PaymentAction.
10103 Please use another Solution
Type. Your Solution Type is temporarily
unavailable. If possible, please use
another Solution Type.
10400 Transaction refused because
of an invalid argument. See
additional error messages for
details.
OrderTotal is missing.
10401 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Order total is invalid.
10402 Authorization only is not
allowed for merchant. This merchant account is not
permitted to set PaymentAction to
Authorization. Please contact
Customer Service.
10404 Transaction refused because
of an invalid argument. See
additional error messages for
details.
ReturnURL is missing.
10405 Transaction refused because
of an invalid argument. See
additional error messages for
details.
CancelURL is missing.
10407 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid buyer email address
(BuyerEmail).
10409 You’re not authorized to
access this info. Express Checkout token was issued
for a merchant account other than
yours.
10410 Invalid token Invalid token.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 307
API Error Codes
SetExpressCheckout API Errors A
10411 This Express Checkout
session has expired. This Express Checkout session has
expired. Token value is no longer
valid.
If you receive this error, you
must return your buyer to
PayPal to approve the use of
PayPal again. Display an error
message to inform the buyer
that the transaction expired,
and provide a button to return
to PayPal. In this situation, you
are effectively restarting the
entire checkout process. (Do
not reuse the expired token
value on
SetExpressCheckout
request.) However, because
you already know the final
OrderTotal, be sure to
update the value for that
element if appropriate. You
might also want to update the
values for ReturnURL and
CancelURL, if necessary.
10412 Duplicate invoice Payment has already been made for
this InvoiceID. PayPal checks that
InvoiceID values are unique
for any particular merchant. If
you send an InvoiceID value
already associated with another
transaction in the PayPal
system, PayPal returns error
code 10412.
You might not be able to
correct this error during an
actual checkout. If you receive
this error, research why it
might occur and modify your
implementation of Express
Checkout to ensure that you
generate unique invoice
identification numbers.
10413 Transaction refused because
of an invalid argument. See
additional error messages for
details
The totals of the cart item amounts
do not match order amounts. If you receive this error, be
sure the total of the payment
detail item parameters, such as
ItemTotal, HandlingTotal,
TaxTotal, and so forth add up
to the order total.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
308 August 2012 SOAP API Developer Reference
10415 Transaction refused because
of an invalid argument. See
additional error messages for
details.
A successful transaction has already
been completed for this token. PayPal allows a token only
once for a successful
transaction.
If you determine that your
buyers are clicking your “Place
Order” button twice, PayPal
recommends that you disable
the button after your buyer has
clicked it.
10418 Transaction refused because
of an invalid argument. See
additional error messages for
details
The currencies of the shopping cart
amounts must be the same.
10425 Express Checkout has been
disabled for this merchant. Express Checkout has been disabled
for this merchant. Please contact
Customer Service.
10426 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item total is invalid.
10427 Transaction refused because
of an invalid argument. See
additional error messages for
details
Shipping total is invalid.
10428 Transaction refused because
of an invalid argument. See
additional error messages for
details
Handling total is invalid.
10429 Transaction refused because
of an invalid argument. See
additional error messages for
details
Tax total is invalid.
10430 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item amount is missing.
10431 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item amount is invalid.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 309
API Error Codes
SetExpressCheckout API Errors A
10432 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invoice ID value exceeds maximum
allowable length.
10433 Transaction refused because
of an invalid argument. See
additional error messages for
details
Value of Order Description has been
truncated.
10434 Transaction refused because
of an invalid argument. See
additional error messages for
details
Value of Custom element has been
truncated.
10436 Transaction refused because
of an invalid argument. See
additional error messages for
details.
PageStyle value exceeds maximum
allowable length.
10437 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10438 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10439 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10440 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10441 Transaction refused because
of an invalid argument. See
additional error messages for
details
The NotifyURL element value
exceeds maximum allowable length.
10442 ButtonSource value
truncated. The ButtonSource element value
exceeds maximum allowable length.
10446 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Sale is only allowed PaymentAction.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
310 August 2012 SOAP API Developer Reference
10457 Error occurred in
communicating to eBay eBay API creation error
10458 Error occurred in
communicating to eBay eBay API unknown failure
10459 Error occurred in
communicating to eBay eBay API failure
10460 Error occurred in
communicating to eBay Parsing error
10461 Error occurred in
communicating to eBay Item number invalid, removed, or
unavailable
10462 Error occurred in
communicating to eBay Order not found
10463 Error occurred in
communicating to eBay eBay user password incorrect
10464 Error occurred in
communicating to eBay Item ID and Transaction ID
mismatch
10465 Error occurred in
communicating to eBay eBay user invalid
10467 Error occurred in
communicating to eBay Duplicate Item ID
10468 Transaction refused because
of an invalid argument. See
additional error messages for
details
Duplicate Order ID
10469 PaymentAction of Order
Temporarily Unavailable Express Auctions is unavailable
10470 Wowo flag is off for
ExpressO feature Solution Type passed as Sole while
ExpressO feature is turned off
10471 Transaction refused because
of an invalid argument. See
additional error messages for
details
ReturnURL is missing
10472 Transaction refused because
of an invalid argument. See
additional error messages for
details
CancelURL is missing
10473 Error occurred in
communicating to eBay Multiple Order IDs are not supported
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 311
API Error Codes
SetExpressCheckout API Errors A
10474 Invalid Data This transaction cannot be processed.
The country code in the shipping
address must match the buyer's
country of residence
10475 Transaction refused because
of an invalid argument. See
additional error messages for
details
This transaction cannot be completed
with PaymentAction of Sale
10476 Invalid Data Maximum number of billing
agreements exceeded
10477 Invalid Data More than one billing agreement
specified for reference transaction
10478 Invalid Data Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments
10479 Invalid Data Billing agreement types cannot be
mixed in the same request
10480 Invalid Data Invalid billing agreement type
10485 Payment not authorized Payment has not been authorized by
the user.
10537 Risk Control Country Filter
Failure The transaction was refused because
the country was prohibited as a result
of your Country Monitor Risk
Control Settings.
10538 Risk Control Max Amount
Failure The transaction was refused because
the maximum amount was excceeded
as a result of your Maximum
Amount Risk Control Settings.
10539 Payment declined by your
Risk Controls settings:
PayPal Risk Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
10725 Shipping Address Country
Error There was an error in the Shipping
Address Country field
10727 Shipping Address1 Empty The field Shipping Address1 is
required
10728 Shipping Address City
Empty The field Shipping Address City is
required
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
312 August 2012 SOAP API Developer Reference
10729 Shipping Address State
Empty The field Shipping Address State is
required
10730 Shipping Address Postal
Code Empty The field Shipping Address Postal
Code is required
10731 Shipping Address Country
Empty The field Shipping Address Country
is required
10736 Shipping Address Invalid
City State Postal Code A match of the Shipping Address
City, State, and Postal Code failed.
10800 Invalid Data Your request is too long. Check
URLs and other long strings.
11001 Exceeds maximum length. Value of NoteText element is
truncated.
11001 Exceeds maximum length. OtherPaymentMethodID exceeds
maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLabel exceeds
maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLabelDescripti
on exceeds maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLongDescripti
on exceeds maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLongDescripti
onTitle exceeds maximum length.
11001 Exceeds maximum length. OtherPaymentMethodIcon exceeds
maximum length.
11068 Seller restriction. All sellers restricted.
11547 Recurring payments
temporarily unavailable; try
again later
Recurring payments temporarily
unavailable.
11547 Permission denied. Permission Denied. You are not
authorized to do this kind of
transaction
11601 Request for billing address
failed Billing address request is not enabled
for merchant
11602 Request for billing address
failed Feature not yet available
11801 Invalid Data You cannot pass both new and
deprecated parameter address fields.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 313
API Error Codes
SetExpressCheckout API Errors A
11802 Invalid Data You cannot pass both the new and
deprecated Custom parameter.
11803 Invalid Data You cannot pass both the new and
deprecated Invoice ID parameter.
11804 Invalid Data You cannot pass both the new and
deprecated order description.
11805 Invalid Data You cannot pass both the new and
deprecated order total or amount
parameters.
11806 Invalid Data You cannot pass both the new and
deprecated
ProfileAddressChangeDate
parameter.
11807 Invalid Data You cannot pass both the new and
deprecated ShippingMethod
parameter.
11810 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invalid Insurance Amount.
11811 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invalid Shipping Discount.
11812 Invalid Data The value of Description parameter
has been truncated.
11813 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invalid callback URL.
Callback URL is wrong type Callback URL is wrong type; you
must use the HTTPS Ensure that your callback URL
starts with https://.
11814 Invalid data Invalid value for AllowNote.
11815 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item sales tax is invalid.
Callback options missing You must specify callback options
when you specify a callback URL
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
314 August 2012 SOAP API Developer Reference
Invalid callback timeout The callback timeout is is zero; you
must specify a longer timeout
Line items missing Line items are required when specify
a callback URL for flate rate
shipping options
Callback URL is too long The callback URL must not exceed
1,024 characters
Multiple default shipping
options specified You can only specify one default
shipping option at a time
No default shipping option
specified You must specify a default shipping
option
Invalid shipping total Invalid shipping total; it should equal
the shipping amount of the default
shipping option
Invalid shipping options Invalid shipping options; you must
specify a name and amount for each
shipping option
11821 Invalid shipping options Invalid shipping options; you must
specify a name and amount for each
shipping option type
11822 Multiple default shipping
options specified More than one shipping option type
is marked as the default; you can
only specify one default shipping
option at a time
11823 No default shipping option
specified You must specify one shipping
option type as the default
11824 Invalid callback timeout The callback timeout is zero; you
must specify a longer timeout value
11825 Flat-rate shipping options
are missing Flat-rate shipping options are
missing; you must specify flat-rate
shipping options when you specify a
callback URL
11826 Invalid shipping total Invalid shipping total; it should equal
the shipping amount of the selected
shipping option
11827 Line items missing Line items missing; line items are
required when you specify a callback
URL for flat-rate shipping options
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 315
API Error Codes
SetExpressCheckout API Errors A
11828 Maximum amount of order
not specified Maximum amount of order not
specified; you must specify the
estimated value of the order when
using a flat-rate shipping option
11829 Shipping total is missing Shipping total is missing; you must
specify a shipping total when using a
flat-rate shipping option
11830 Insurance amount is missing Insurance amount is missing; you
have offered insurance but have not
specified an amount.
11831 Callback URL is too long Callback URL is too long; it must not
exceed 1,024 characters
11832 Maximum amount of order
is less than itemized amounts Maximum amount of order is less
than itemized amounts; the value of
all items, including handling,
shipping, tax, and insurance cannot
be greater than the maximum amount
of the order
12109 Option not supported. Seller blocks payments via eBay
checkout for all eBay items.
12124 Option not supported. Express Checkout not supported for
you.
12200 Buyer ID is not present. Buyer ID must be specified to
process an Immediate Payment item.
12201 Immediate Payment item
was not found. The item specified is either not valid
or is not currently available for
purchase as an Immediate Payment
item.
Please check that the item is a
valid Immediate Payment item.
12202 More than one eBay item is
present. Only one Immediate Payment item
can be paid for in a single PayPal
payment transaction.
12205 eBay Transaction ID and
eBay Order ID must be null. Requests for eBay Immediate
Payment items should not contain
either eBay transaction ID or eBay
order ID. If the fields are present,
they should contain null values.
12207 Cart ID is required for
Immediate Payment item. Cart ID is required for Immediate
Payment item.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
316 August 2012 SOAP API Developer Reference
12208 eBay item amount does not
match Express Checkout
API item amount.
eBay item amount must match
Express Checkout API item amount.
13100 Parallel payments
functionality is not available Parallel payments functionality is not
available
13101 Invalid Data Payment action of Order is only
supported for parallel payments
13102 Payment Request ID is
missing Payment Request ID is mandatory
for parallel payments
13103 Duplicate Payment Request
ID passed Payment Request ID must be unique
for parallel payments
13104 Transaction refused because
of an invalid argument. See
Additional error messages
for details.
Number of payment requests exceeds
maximum number of supported
requests.
13105 Invalid Data Billing Agreement is not supported
for parallel payments.
13106 Invalid Data You cannot pass both the new and
deprecated PaymentAction
parameter.
13108 Merchant is not eligible. Merchant is not eligible for parallel
payments.
13110 Multi Payments Sale is Not
allowed Due to some technical diffculties the
Multi Payments for Sale is not
avaliable now please try again later.
13111 Mixed Payment action not
supported The Payment Action passed should
be unique, mixed Payment Action
not supported
13114 Buyer Didn't Complete The Buyer returned without
completing the payment
13115 Seller ID Missing Seller ID is mandatory for parallel
payments
13116 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction is in progress for this
token.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 317
API Error Codes
GetExpressCheckoutDetails API Errors A
GetExpressCheckoutDetails API Errors
GetExpressCheckoutDetails API Errors
Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal error
10001 ButtonSource value
truncated. The transaction could not be loaded
10001 ButtonSource value
truncated. The transaction could not be loaded
10003 Missing argument. OtherPaymentMethodID is missing.
10003 Missing argument. OtherPaymentMethodLabel is missing.
10003 Missing argument. OtherPaymentMethodType is missing.
10003 Missing argument. One or more of these giropay URLs is
missing: giropaySuccessURL,
giropayCancelURL,
BanktxnPendingURL.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Transaction refused because of an
invalid argument. See additional error
messages for details.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10004 Invalid transaction type You can not get the details for this type
of transaction
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction could not be loaded
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10007 Permission denied You do not have permission to make
this API call
10007 Permission denied You do not have permission to get the
details of this transaction
API Error Codes
DoExpressCheckoutPayment API Errors
A
318 August 2012 SOAP API Developer Reference
DoExpressCheckoutPayment API Errors
DoExpressCheckoutPayment API Errors
10007 Permission denied You do not have permission to make
this API call
10408 Express Checkout token is
missing. Express Checkout token is missing.
10409 You’re not authorized to
access this info. Express Checkout token was issued for
a merchant account other than yours.
10410 Invalid token Invalid token.
10411 This Express Checkout
session has expired. This Express Checkout session has
expired. Token value is no longer valid.
13112 Cannot Pay Seller. The Buyer will not be able to Pay the
seller for this transaction
13116 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction is in progress for this
token.
Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Transaction failed due to
internal error
10001 Internal Error Warning an internal error has
occurred. The transaction id
may not be correct
10001 ButtonSource value
truncated. The transaction could not be
loaded
10001 Internal Error Internal Error
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Transaction refused because of
an invalid argument. See
additional error messages for
details.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction id is not valid
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 319
API Error Codes
DoExpressCheckoutPayment API Errors A
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid item URL.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
SellerRegistrationDate is
invalid.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
overall positive count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
overall negative count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
total positive count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
total negative count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
recent positive count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
recent negative count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay item transaction
date.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay item buyer
protection type.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
320 August 2012 SOAP API Developer Reference
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay item payment
hold risk.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Multiple eBay order IDs not
allowed.
10007 Permission denied You do not have permissions to
make this API call
10406 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The PayerID value is invalid.
10408 Express Checkout token is
missing. Express Checkout token is
missing.
10409 You’re not authorized to
access this info. Express Checkout token was
issued for a merchant account
other than yours.
10410 Invalid token Invalid token.
10411 This Express Checkout
session has expired. This Express Checkout session
has expired. Token value is no
longer valid.
10412 Duplicate invoice Payment has already been
made for this InvoiceID.
10413 Transaction refused
because of an invalid
argument. See additional
error messages for details
The totals of the cart item
amounts do not match order
amounts.
If you receive this error, be sure the
total of the payment detail item
parameters, such as ItemTotal,
HandlingTotal, TaxTotal, and so forth
add up to the order total.
10414 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The amount exceeds the
maximum amount for a single
transaction.
10415 Transaction refused
because of an invalid
argument. See additional
error messages for details.
A successful transaction has
already been completed for this
token.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 321
API Error Codes
DoExpressCheckoutPayment API Errors A
10416 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You have exceeded the
maximum number of payment
attempts for this token.
10417 Transaction cannot
complete. The transaction cannot
complete successfully. Instruct
the customer to use an
alternative payment method.
Instruct the buyer that PayPal is unable
to process the payment and redisplay
alternative payment methods with
which the buyer can pay.
10418 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The currencies of the shopping
cart amounts must be the same.
10419 Express Checkout
PayerID is missing. Express Checkout PayerID is
missing.
10420 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Express Checkout
PaymentAction is missing.
10421 This Express Checkout
session belongs to a
different customer.
This Express Checkout session
belongs to a different customer.
Token value mismatch.
Verify that your programs are properly
associating the Tokens and PayerIDs.
10422 Customer must choose
new funding sources. The customer must return to
PayPal to select new funding
sources.
10424 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping address is invalid. If you receive this error message,
PayPal recommends that you return
your buyer to PayPal to review and
approve new valid funding sources.
Although this error is rare, you should
consider trapping the error to display a
message to the buyer describing what
happened, along with a button or
hyperlink to return to PayPal.
10426 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item total is invalid.
10427 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping total is invalid.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
322 August 2012 SOAP API Developer Reference
10428 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Handling total is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Tax total is invalid.
10431 Item amount is invalid. Item amount is invalid.
10432 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invoice ID value exceeds
maximum allowable length.
10433 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of OrderDescription
element has been truncated.
10434 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of Custom element has
been truncated.
10435 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The customer has not yet
confirmed payment for this
Express Checkout session.
10441 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The NotifyURL element value
exceeds maximum allowable
length.
10442 ButtonSource value
truncated. The ButtonSource element
value exceeds maximum
allowable length.
10443 Transaction refused
because of an invalid
argument. See additional
error messages for details.
This transaction cannot be
completed with
PaymentAction of Order.
10444 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction currency
specified must be the same as
previously specified.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 323
API Error Codes
DoExpressCheckoutPayment API Errors A
10445 This transaction cannot be
processed at this time.
Please try again later.
This transaction cannot be
processed at this time. Please
try again later.
10446 Unconfirmed email A confirmed email is required
to make this API call.
10474 Invalid Data This transaction cannot be
processed. The country code in
the shipping address must
match the buyer’s country of
residence.
The buyer selects the country of
residence when they sign up for their
PayPal account. The country of
residence displays after the dash in the
title on the Account Overview page.
10481 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PaymentAction of
Authorization is not allowed
with Unilateral and Non-
Credentialed authentication.
10486 This transaction couldn't
be completed. This transaction couldn't be
completed. Please redirect your
customer to PayPal.
Redirect the buyer back to PayPal using
the original token so that the customer
can use or add a new funding
instrument.
10482 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PaymentAction of Order is not
allowed with Unilateral and
Non-Credentialed
authentication.
10537 Risk Control Country
Filter Failure The transaction was refused
because the country was
prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control Max Amount
Failure The transaction was refused
because the maximum amount
was excceeded as a result of
your Maximum Amount Risk
Control Settings.
10539 Payment declined by your
Risk Controls settings:
PayPal Risk Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
10725 Shipping Address Country
Error There was an error in the
Shipping Address Country
field
10727 Shipping Address1 Empty The field Shipping Address1 is
required
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
324 August 2012 SOAP API Developer Reference
10728 Shipping Address City
Empty The field Shipping Address
City is required
10729 Shipping Address State
Empty The field Shipping Address
State is required
10730 Shipping Address Postal
Code Empty The field Shipping Address
Postal Code is required
10731 Shipping Address Country
Empty The field Shipping Address
Country is required
10736 Shipping Address Invalid
City State Postal Code A match of the Shipping
Address City, State, and Postal
Code failed.
11001 Exceeds maximum length. Value of NoteText element is
truncated.
11610 Payment Pending your
review in Fraud
Management Filters
Payment Pending your review
in Fraud Management Filters
11611 Transaction blocked by
your settings in FMF Transaction blocked by your
settings in FMF
11612 Could not process your
request to accept/deny the
transaction
Could not process your request
to accept/deny the transaction
11820 Transaction refused
because of an invalid
argument. See additional
error messages for details
Invalid Order URL.
Invalid shipping amount Invalid shipping amount; it
should equal the shipping
amount of the selected
shipping option
Invalid shipping options Invalid shipping options; you
must specify a name and
amount for each shipping
option
11821 Invalid shipping options Invalid shipping options; you
must specify a name and
amount for each shipping
option type
11826 Invalid shipping total Invalid shipping total; it should
equal the shipping amount of
the selected shipping option
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 325
API Error Codes
DoExpressCheckoutPayment API Errors A
12125 PP incentive no longer
available. There's a problem with the
redemption code(s) you
entered and can't be used at this
time. Your payment has not
been processed. Please go back
to PayPal so that the code(s)
can be removed, your order
total can be updated and then
you'll be able to complete
checkout.
12126 Payment could not be
processed at this time.
Incentive temporarily
unavailable.
We're having problems
processing redemption codes at
this time. Your payment has
not been processed. You can
try to check out again at a later
time or complete your payment
without the discount applied.
12201 Immediate Payment item
was not found. The item specified is either not
valid or is not currently
available for purchase as an
Immediate Payment item.
Please check that the item is a valid
Immediate Payment item.
12203 Payment rolled back
because of pending item. Payment was not created
because it would have been in a
pending state, which is
unacceptable for Immediate
Payment items.
12204 Transaction reversed. Error occurred causing
transaction reversal.
12206 The value of
PaymentAction must be
Sale for Immediate
Payment item.
Order and Authorization are
not acceptable values for
PaymentAction when the item
is an Immediate Payment
12207 Cart ID is required for
Immediate Payment item. Cart ID is required for
Immediate Payment item.
12208 eBay item amount does
not match Express
Checkout API item
amount.
eBay item amount does not
match Express Checkout API
item amount.
13100 Parallel payments
functionality is not
available
Parallel payments functionality
is not available
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
326 August 2012 SOAP API Developer Reference
13101 Invalid Data Payment action of Order is
only supported for parallel
payments
13102 Payment Request ID is
missing Payment Request ID is
mandatory for parallel
payments
13103 Duplicate Payment
Request ID passed Payment Request ID must be
unique for parallel payments
13104 Transaction refused
because of an invalid
argument. See Additional
error messages for details.
Number of payment requests
exceeds maximum number of
supported requests.
13106 Invalid Data You cannot pass both the new
and deprecated PaymentAction
parameter.
13107 Parallel payments partially
successful. One or more payment requests
failed. Check individual
payment responses for more
information.
13110 Multi Payments Sale is
Not allowed Due to some technical
diffculties the Multi Payments
for Sale is not avaliable now
please try again later.
13111 Mixed Payment action not
supported The Payment Action passed
should be unique, mixed
Payment Action not supported
13113 Buyer Cannot Pay. The Buyer cannot pay with
PayPal for this transaction.
13115 Seller ID Missing Seller ID is mandatory for
parallel payments
13116 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction is in progress
for this token.
13751 Could not retrieve the
original successful
response.
Transaction completed
successfully, but could not
retrieve the original successful
response.
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 327
API Error Codes
Authorization and Capture API Errors A
Authorization and Capture API Errors
Authorization and Capture API Error Messages
Error
Code Short
Message Long Message Returned By API
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
denied You do not have
permissions to make this
API call
10009 Transaction
refused Account is locked or
inactive Retry the request at a
later time or close order.
10010 Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.
Invalid argument
10202 Exceed max Transaction would
exceed user’s monthly
maximum
DoAuthorization
DoCapture
10600 Authorization
voided. Authorization is voided. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10601 Authorization
expired. Authorization has
expired. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10602 Authorization
completed. Authorization has already
been completed. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10603 The buyer is
restricted. The buyer account is
restricted. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Contact the buyer.
API Error Codes
Authorization and Capture API Errors
A
328 August 2012 SOAP API Developer Reference
10604 Authorization
must include
both buyer and
seller.
Authorization transaction
cannot be unilateral. It
must include both buyer
and seller to make an
auth.
DoAuthorization Review the order to
ensure customer and
seller are both PayPal
members.
10605 Unsupported
currency. Currency is not
supported. DoAuthorization
DoCapture
Retry the request with a
PayPal-supported
currency.
10606 Buyer cannot
pay. Transaction rejected,
please contact the buyer. DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10607 Auth&Capture
unavailable. Authorization & Capture
feature unavailable. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Contact PayPal Customer
Service.
10608 Funding source
missing. The funding source is
missing. DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10609 Invalid
transactionID. Transaction id is invalid. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Check the validity of the
authorization ID and
reattempt the request.
10610 Amount limit
exceeded. Amount specified
exceeds allowable limit. DoAuthorization
DoCapture
DoReauthorization
Reattempt the request
with a lower amount.
10611 Not enabled. Authorization & Capture
feature is not enabled for
the merchant. Contact
customer service.
DoAuthorization
DoCapture
DoReauthorization
Contact PayPal Customer
Service.
10612 No more
settlement. Maxmimum number of
allowable settlements has
been reached. No more
settlement for the
authorization.
DoCapture Close the order.
10613 Currency
mismatch. Currency of capture must
be the same as currency
of authorization.
DoCapture Ensure that the currencies
are the same, and retry
the request.
10614 Cannot void
reauth. You can void only the
original authorization,
not a reauthorization.
DoVoid Void the authorization.
Error
Code Short
Message Long Message Returned By API
Call... Correcting This
Error...
SOAP API Developer Reference August 2012 329
API Error Codes
Authorization and Capture API Errors A
10615 Cannot reauth
reauth. You can reauthorize only
the original authorization,
not a reauthorization.
DoReauthorization Capture the
reauthorization.
10616 Maximum
number of
reauthorization
allowed for the
auth is reached.
Maximum number of
reauthorization allowed
for the auth is reached.
DoReauthorization Capture or close the
authorization.
10617 Reauthorization
not allowed. Reauthorization is not
allowed inside honor
period.
DoReauthorization Capture the authorization
or reauthorize outside of
honor period.
10618 Transaction
already voided
or expired.
Transaction has already
been voided or expired. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10619 Invoice ID value
exceeds
maximum
allowable
length.
Invoice ID value exceeds
maximum allowable
length.
DoCapture Check the length of the
invoice ID and reattempt
the request.
10620 Order has
already been
voided, expired,
or completed.
Order has already been
voided, expired, or
completed.
DoAuthorization
DoCapture
DoVoid
Close this order.
10621 Order has
expired. Order has expired. DoAuthorization
DoCapture
DoVoid
Close this order.
10622 Order is voided. Order is voided. DoAuthorization
DoCapture
DoVoid
Close this order.
10623 Maximum
number of
authorization
allowed for the
order is reached.
Maximum number of
authorization allowed for
the order is reached.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Capture this order.
10624 Duplicate
invoice Payment has already
been made for this
Invoice ID.
DoAuthorization Review the invoice ID
and reattempt the request.
Error
Code Short
Message Long Message Returned By API
Call... Correcting This
Error...
API Error Codes
Authorization and Capture API Errors
A
330 August 2012 SOAP API Developer Reference
10625 Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.
The amount exceeds the
maximum amount for a
single transaction.
DoAuthorization
DoCapture
DoReauthorization
Reattempt the request
with a lower amount.
10626 Risk Transaction refused due
to risk model. DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10627 Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.
The invoice ID field is
not supported for basic
authorizations.
DoAuthorization
DoReauthorization
DoVoid
The Invoice ID field can
be used only with
DoCapture.
10628 This transaction
cannot be
processed at this
time. Please try
again later.
This transaction cannot
be processed at this time.
Please try again later.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Retry the request at a
later time.
10629 Reauthorization
not allowed. Reauthorization is not
allowed for this type of
authorization.
DoReauthorization Use DoAuthorization to
authorize the order.
10630 Item amount is
invalid. Item amount is invalid. DoAuthorization
DoCapture
Check the item amount to
ensure that it is not zero
or negative.
10631 Processor
Warning. The authorization is
being processed. DoAuthorization
11094 This
authorization
cannot be
voided,
reauthorized, or
captured against.
This authorization can
only be handled through
the marketplace which
created it. It cannot
directly be voided,
reauthorized, or captured
against.
13122 Transaction
refused. Transaction violates
PayPal use DoCapture
Error
Code Short
Message Long Message Returned By API
Call... Correcting This
Error...
SOAP API Developer Reference August 2012 331
API Error Codes
GetTransactionDetails API Errors A
GetTransactionDetails API Errors
GetTransactionDetails API Errors
TransactionSearch API Errors
TransactionSearch API Errors
Error Code Short Message Long Message
10001 Internal Error Internal Error
10004 Transaction refused because of an
invalid argument. See additional
error messages for details.
Store ID is required if Terminal ID is specified.
Error
Code Short Message Long Message
10001 Internal Error Internal Error
10001 ButtonSource value
truncated. The transaction could not be loaded
10003 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Start date is a required parameter
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Start date is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
End date is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Currency is not supported
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Transaction class is not supported
API Error Codes
TransactionSearch API Errors
A
332 August 2012 SOAP API Developer Reference
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Receipt id is not valid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Payer email is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Auction item id is not valid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Receiver email is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
You can not search for a transaction id and a receipt id
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Receiver can only be specified for payments you’ve received
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10007 Permission denied You do not have permission to search for this transaction
10007 Permission denied You do not have permission to make this API call
11002 Search warning The number of results were truncated. Please change your search
parameters if you wish to see all your results.
Error
Code Short Message Long Message
SOAP API Developer Reference August 2012 333
API Error Codes
RefundTransaction API Errors A
RefundTransaction API Errors
RefundTransaction API Errors
Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Warning an internal error has occurred.
The transaction id may not be correct
10001 Internal Error The transaction could not be loaded.
10002 Restricted account Account is restricted.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The partial refund amount must be a
positive amount
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You can not specify a partial amount
with a full refund
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
A transaction id is required
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction id is not valid
10007 Permission denied You do not have permission to refund
this transaction
10007 Permission denied You do not have permissions to make
this API call
API Error Codes
RefundTransaction API Errors
A
334 August 2012 SOAP API Developer Reference
10009 Transaction refused You do not have a verified ACH This error can be caused by
insufficient funds in your
PayPal balance to cover the
amount of the refund and either
of the following:
-Not having yet verified the
bank account associated
with your PayPal account
-Not having any bank
account associated with
your PayPal account
Be sure that you have sufficient
funds in your PayPal balance
and that you have verified the
associated bank account.
10009 Transaction refused The partial refund amount must be less
than or equal to the original transaction
amount
10009 Transaction refused The partial refund amount must be less
than or equal to the remaining amount
10009 Transaction refused The partial refund amount is not valid
10009 Transaction refused Because a complaint case exists on this
transaction, only a refund of the full or
full remaining amount of the
transaction can be issued
10009 Transaction refused You are over the time limit to perform a
refund on this transaction
10009 Transaction refused Can not do a full refund after a partial
refund
10009 Transaction refused Account is locked or inactive
10009 Transaction refused The partial refund must be the same
currency as the original transaction
10009 Transaction refused This transaction has already been fully
refunded
10009 Transaction refused Account is restricted
10009 Transaction refused You can not refund this type of
transaction
10009 Transaction refused You can not do a partial refund on this
transaction
Error
Code Short Message Long Message Correcting This Error...
SOAP API Developer Reference August 2012 335
API Error Codes
RefundTransaction API Errors A
10009 Transaction refused The account for the counterparty is
locked or inactive
10009 Transaction refused This transaction already has a
chargeback filed
10009 Transaction refused You have not filled out the Direct Debit
Instruction
10011 Invalid transaction id value Transaction refused because of an
invalid transaction id value
10755 Unsupported currency Currency is not supported
11603 Conflict with prior request
with same Message
Submission ID.
One or more critical fields in the
request conflict with prior message
with the same Message Submission ID
(specified in MSGSUBID parameter).
11604 Request for Message
Submission ID already in
progress.
Request for the specified Message
Submission ID (specified in
MSGSUBID parameter) cannot be
started until the previous request
finishes.
Retry the request at a later
time.
11607 Duplicate request for
specified Message
Submission ID.
The specified Message Submission ID
(specified in MSGSUBID parameter) is
a duplicate; result parameters of the
original request are attached.
Retry the request at a later
time.
11996 Use Adaptive Payment
Refund API To do a refund on an Adaptive Payment
transaction, please use the Adaptive
Payment Refund API
12302 Dispute Refund Not
Allowed This transaction already has a PayPal
dispute filed
13513 Duplicate request for
specified Invoice ID. The specified Invoice ID is a duplicate.
13531 Funding source provided
for this operation is not
supported
The funding source provided for this
operation is not supported. Please
provide a valid value.
13601 Refund cannot exceed the
transaction amount. Refunds to users without PayPal
accounts cannot exceed the transaction
amount.
13602 Insufficient funds Refund failed due to insufficient funds
in your PayPal account
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
MassPay API Errors
A
336 August 2012 SOAP API Developer Reference
MassPay API Errors
MassPay API Errors
Error
Code Short Message Long Message
10001 Invalid account number. The transaction failed as a result of an invalid credit card number.
Check the number or attempt with another card.
10001 Internal Error Internal Error
10001 Internal Error The transaction could not be loaded
10001 ButtonSource value truncated. The transaction could not be loaded
10001 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The masspay receiver_type is not a recognizable type
10002 Account locked The user account is locked
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The number of input records is greater than maximum allowed
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The number of input records is less than or equal to zero
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The note string length exceeds the maximum limit of 4000
characters
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount is missing
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The currency is missing
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
Currency is not supported
SOAP API Developer Reference August 2012 337
API Error Codes
MassPay API Errors A
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount is not a valid number
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount exceeds the max limit of a single mass pay item
~1
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount is less than or equal to zero
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The unique id string length exceeds the maximum limit of 30
characters
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The unique id string contains a space as a character
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10007 Permission denied You do not have permissions to make this API call
10301 User not allowed The user is not allowed to send money through Mass Pay
10303 Restricted account Account is restricted
10304 Unconfirmed email The user account has unconfirmed email
10305 Limit Exceeded The user account needs to have its sending limit removed in order to
make a mass payment.
10306 Limit Exceeded The user’s international account needs to have its sending limit
removed in order to make a mass payment
10307 Receive only account The user account is receive only and therefore cannot send payments
out
10308 Masspay server configuration
error There is some configuration error
10309 Masspay server unavailable The mass pay server is unavailable
10310 Unable to create payment Unable to create payments for masspay
Error
Code Short Message Long Message
API Error Codes
Recurring Payments Errors
A
338 August 2012 SOAP API Developer Reference
Recurring Payments Errors
The following table lists errors for the following APIs that handle recurring payments profiles:
-CreateRecurringPaymentsProfile
-GetRecurringPaymentsProfileDetails
-ManageRecurringPaymentsProfileStatus
-UpdateRecurringPaymentsProfile
-BillOutstandingAmount
Recurring Payments Errors
10311 Unable to submit payment Unable to submit payments for masspay
10312 Masspay server error The masspay server has reported errors
10313 Masspay Invalid Data The masspay input file includes invalid data
10314 Masspay input parse error The input to the masspay server is incorrect. Please make sure that
you are using a correctly formatted input.
10317 Masspay Invalid Email The masspay input file includes invalid Email
10320 Internal Error Internal Error
10321 Insufficient funds The account does not have sufficient funds to do this masspay
10327 Masspay Invalid UserID The masspay input file includes invalid UserID
Error
Code Short Message Long Message Additional Information
10001 Invalid account number The transaction failed as a result of
invalid credit card number. Check
the number or attempt with another
credit card.
10003 Missing argument Item name, amount and quantity
are required if item category is
provided.
Scenario: Merchant passes item
category as either Digital or
Physical but does not also pass
one of the following parameters:
name, amount, or quantity.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You are not signed up to accept
payment for digitally delivered
goods.
Scenario: Merchant is not signed
up for digital goods but passes
item category as Digital.
Error
Code Short Message Long Message
SOAP API Developer Reference August 2012 339
API Error Codes
Recurring Payments Errors A
10004 Cart item calculation
mismatch. Cart item calculation mismatch.
The regular non-trial billing period
amount is different than the sum of
the amounts for each item in the
cart.
Scenario: When the regular non-
trial billing period amount is
different than the sum of the
amounts for each item in the
cart.
10004 Tax calculation mismatch. Tax calculation mismatch. The tax
amount for the regular non-trial
billing period is different than the
sum of the tax for each item in the
cart.
Scenario: When the tax for the
regular non-trial billing period is
different than the sum of the tax
for each item in the cart.
10478 Invalid Data Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments.
10501 Invalid Configuration This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when the billing
agreement is disabled or
inactive.
10502 Invalid Data This transaction cannot be
processed. Please use a valid credit
card.
The credit card used is expired.
10504 Invalid Data This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The CVV provided is invalid.
The CVV is between 3-4 digits
long.
10505 Gateway Decline This transaction cannot be
processed. The transaction was refused
because the AVS response
returned the value of N, and the
merchant account is not able to
accept such transactions.
10507 Invalid Configuration This transaction cannot be
processed. Please contact PayPal
Customer Service.
Your PayPal account is
restricted. Contact PayPal for
more information.
10508 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration date.
The expiration date must be a
two-digit month and four-digit
year.
10509 Invalid Data This transaction cannot be
processed. You must submit an IP address
of the buyer with each API call.
10510 Invalid Data The credit card type is not
supported. Try another card type. The credit card type entered is
not currently supported by
PayPal.
Error
Code Short Message Long Message Additional Information
API Error Codes
Recurring Payments Errors
A
340 August 2012 SOAP API Developer Reference
10511 Invalid Data This transaction cannot be
processed. The merchant selected an value
for the PaymentAction field that
is not supported.
10512 Invalid Data This transaction cannot be
processed. Please enter a first
name.
The first name of the buyer is
required for this merchant.
10513 Invalid Data This transaction cannot be
processed. Please enter a last
name.
The last name of the buyer is
required for this merchant.
10535 Gateway decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
10548 Invalid Configuration This transaction cannot be
processed. The merchant’s account
is not able to process transactions.
The merchant account
attempting the transaction is not
a business account at PayPal.
Check your account settings.
10550 Invalid Configuration This transaction cannot be
processed. Access to Direct Payment was
disabled for your account.
Contact PayPal for more
information.
10561 Invalid Data There’s an error with this
transaction. Please enter complete
billing address.
10565 Merchant country
unsupported The merchant country is not
supported.
10709 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10710 Invalid Data There’s an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10711 Invalid Data There’s an error with this
transaction. Please enter your state
in the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10712 Invalid Data There’s an error with this
transaction. Please enter your five
digit postal code in the billing
address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 341
API Error Codes
Recurring Payments Errors A
10713 Invalid Data There’s an error with this
transaction. Please enter a country
in the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10744 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the billing address.
There was a problem with a
particular field in the address.
The long error message will tells
you which field is invalid.
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification Number.
The merchant’s configuration
requires a CVV to be entered,
but no CVV was provided with
this transaction. Contact PayPal
if you wish to change this
setting.
10751 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
The merchant provided an
address either in the United
States or Canada, but the state
provided is not a valid state in
either country.
10752 Gateway Decline This transaction cannot be
processed. The transaction was declined by
the issuing bank, not PayPal. The
merchant should attempt another
card.
10760 Invalid Configuration This transaction cannot be
processed. The country listed for
your business address is not
currently supported.
The merchant’s country of
residence listed in their PayPal
account is not currently
supported to allow Direct
Payment transactions.
11089 Transaction Refused. Account is locked or inactive.
11501 Invalid merchant country The merchant’s country is
currently not supported Missing token
11502 The token is missing or is
invalid The token is missing or is invalid One or more subscription detail
fields are missing from the
request.
11503 Missing subscription details Missing subscription details One or more schedule detail
fields are missing from the
request.
11504 Missing schedule details Missing schedule details
11505 Start date should be greater
than current date Subscription start date should be
greater than current date
Error
Code Short Message Long Message Additional Information
API Error Codes
Recurring Payments Errors
A
342 August 2012 SOAP API Developer Reference
11506 Invalid max failed
payments Max failed payments, if supplied,
must be >= 0
11507 Invalid trial amount Trial amount must be >= 0
11508 Invalid trial total billing
cycles Trial total billing cycles must be >
0
11509 Invalid trial billing period Trial billing period must be one of
Day, Week, Month, SemiMonth, or
Year
11510 Invalid trial amount Trial amount must be >= 0
11511 Invalid currency for trial
amount This currency is currently not
supported for trial amount. Currency must be USD.
11512 Invalid trial shipping
amount Trial shipping amount must be >=
0If a trial shipping amount is
supplied, it must be >= 0.
11513 Invalid currency for trial
shipping amount This currency is currently not
supported for trial shipping amount Currency must be USD.
11514 Invalid profile status The profile status is invalid.
11515 Invalid currency for trial tax
amount This currency is currently not
supported for trial tax amount Currency must be USD.
11516 Invalid billing frequency Billing Frequency must be > 0 and
be less than or equal to one year The combination of billing
frequency and billing period
cannot exceed one year.
11517 Invalid total billing cycles Total billing cycles must be >= 0 (0
means continuous)
11518 Invalid billing period Billing period must be one of Day,
Week, Month, SemiMonth, or Year
11519 Invalid amount Bill amount must be greater than 0
11520 Invalid currency for amount This currency is currently not
supported for amount Currency must be USD.
11521 Invalid shipping amount Shipping amount must be >= 0
11522 Invalid currency for
shipping amount This currency is currently not
supported for shipping amount Currency must be USD.
11523 Invalid tax amount Tax amount must be >= 0
11524 Invalid currency for tax
amount This currency is currently not
supported for tax amount Currency must be USD.
11531 Invalid profile status The profile status must be one of
(A)ctive, (C)ancelled, or e(X)pired
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 343
API Error Codes
Recurring Payments Errors A
11543 Invalid payer country The payer’s country is currently
not supported
11544 Invalid period status The trial period status must be one
of (A)ctive or (C)ancelled
11545 Denied Payer’s account is denied
11546 Denied Merchant account is denied
11547 This feature is not available
at this time Recurring payments feature is not
currently available; try again later
11548 Invalid currency code Invalid currency code, all currency
codes much match
11549 Start Date is required Subscription start date is required
11550 Start Date should be valid Subscription start date should be
valid
11551 Profile ID is missing from
the request Profile ID is missing from the
request
11552 Invalid profile ID The profile ID is invalid
11553 Invalid action value
provided Invalid action value provided
11554 Note is missing from the
request Note is missing from the request
11555
11556 Invalid profile status for
cancel action; profile
should be active or
suspended
Invalid profile status for suspend
action; profile should be active
11557 Invalid profile status for
suspend action; profile
should be active
Invalid profile status for reactivate
action; profile should be suspended
11558 Invalid profile status for
reactivate action; profile
should be suspended
The activation type is invalid
11560 Invalid activation type The activation type is invalid
11561 Invalid initial amount The initial amount is invalid
11562 Invalid auto bill type The auto bill type is invalid
Error
Code Short Message Long Message Additional Information
API Error Codes
Recurring Payments Errors
A
344 August 2012 SOAP API Developer Reference
11564 The number of failed
payments should be greater
than the current number of
failed payments
The number of failed payments
should be greater than the current
number of failed payments
11567 The time of the update is
too close to the billing date The time of the update is too close
to the billing date
11568 Invalid currency for
delinquent amount Invalid currency for delinquent
amount
11569 Cannot increase delinquent
amount Cannot increase delinquent amount
11570 The maximum number of
failed payments should be
greater than the current
number of failed payments
The maximum number of failed
payments should be greater than
the current number of failed
payments
11571 The total amount cannot
exceed 120% increment per
180 days
The total amount cannot exceed
120% increment per 180 days
11576 Bill amount is greater than
outstanding balance Bill amount is greater than
outstanding balance
11577 Another outstanding
payment is scheduled Another outstanding payment is
scheduled
11578 Bill outstanding amount not
processed because of
scheduled payment
Recurring payment scheduled
within 24 hours, so we are not
processing the bill outstanding
amount
11579 Payment is failing Payment is failing
11581 Invalid Data Profile description is invalid.
11582 No payment in queue No scheduled payment has been
found.
11583 DPRP feature is unavailable DPRP feature is unavailable
11584 Inactive profile Profile is not active
11585 Missing Token or buyer
credit card Missing token or payment source
11586 DPRP is disabled DPRP is disabled for this
merchant.
11587 Billing Address is Partial Billing Address is Partial
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 345
API Error Codes
SetCustomerBillingAgreement Errors A
SetCustomerBillingAgreement Errors
SetCustomerBillingAgreement Errors
11590 Profile update is not
required Based on your input request,
profile already up to date.
11592 Subscription profiles are
not supported for recurring
payments
Subscription profiles are not
supported for recurring payments
13122 Transaction refused Transaction violates PayPal use
13701 Invalid Data Item Category value is invalid.
Only Digital or Physical are
allowed.
Scenario: When merchant passes
an item category value other than
Digital or Physical.
15004 Gateway Decline This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
Error
Code Short Message Long Message Additional Information
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid argument; BillingType
input field is set to None
10404 Transaction refused
because of an invalid
argument. See additional
error messages for details.
ReturnURL is missing. ReturnURL tag has no content.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid value for request billing
address parameter.
10405 Transaction refused
because of an invalid
argument. See additional
error messages for details.
CancelURL is missing. CancelURL tag has no content.
10407 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid buyer email address
(BuyerEmail). Invalid BuyerEmail (badly
formatted or violates SMTP
protocol defined email address
format) or BuyerEmail is passed
as an empty tag.
Error
Code Short Message Long Message Additional Information
API Error Codes
SetCustomerBillingAgreement Errors
A
346 August 2012 SOAP API Developer Reference
10436 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PageStyle value exceeds maximum
allowable length. PageStyle tag is too long.
10437 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-header-image value exceeds
maximum allowable length. cpp_header_image tag is too
long; maximum length is 127.
10438 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-header-border-color value
exceeds maximum allowable
length.
cpp_header_border_color tag is
too long; maximum length is 6.
10439 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-header-back-color value
exceeds maximum allowable
length.
cpp_header_back_color tag is
too long; maximum length is 6.
10440 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-payflow-color value exceeds
maximum allowable length. cpp_payflow_color tag is too
long; maximum length is 6.
10471 Transaction refused
because of an invalid
argument. See additional
error messages for details.
ReturnURL is invalid. ReturnURL tag contains invalid
URL.
10472 Transaction refused
because of an invalid
argument. See additional
error messages for details.
CancelURL is invalid. CancelURL tag contains invalid
URL.
10476 Transaction refused
because of an invalid
argument. See additional
error messages for details.
10477 Transaction refused
because of an invalid
argument. See additional
error messages for details.
10485 Payment not authorized Payment has not been authorized
by the user.
11452 Merchant not enabled for
reference transactions Merchant not enabled for reference
transactions This merchant is not enabled for
Mark reference transaction.
Warning only.
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 347
API Error Codes
GetBillingAgreementCustomerDetails Errors A
GetBillingAgreementCustomerDetails Errors
GetBillingAgreementCustomerDetails Errors
CreateBillingAgreement Errors
CreateBillingAgreement Errors
11453 Reference transactions
temporarily unavailable. Reference transaction feature not
currently available; try again later Feature not enabled because
system is running in standin
mode. Warning only.
11601 Request for billing address
failed Billing address request is not
enabled for merchant
11602 Request for billing address
failed Feature not yet available
Error
Code Short Message Long Message Additional Information
10408 Missing token Token is missing Token is missing.
10409 You’re not authorized to
access this info. Express Checkout token was
issued for a merchant account
other than yours.
Token belongs to a different
merchant.
10410 Invalid token Invalid token Token is invalid.
10411 This Express Checkout
session has expired. This Express Checkout session has
expired. Token value is no longer
valid.
Token expired.
Error
Code Short Message Long Message Additional Information
10408 Missing token Token is missing Token is missing.
10409 You’re not authorized to
access this info. Express Checkout token was
issued for a merchant account
other than yours.
Token belongs to a different
merchant.
10410 Invalid token Invalid token Token is invalid.
10411 This Express Checkout
session has expired. This Express Checkout session has
expired. Token value is no longer
valid.
Token expired.
Error
Code Short Message Long Message Additional Information
API Error Codes
UpdateBillingAgreement Errors
A
348 August 2012 SOAP API Developer Reference
UpdateBillingAgreement Errors
UpdateBillingAgreement Errors
11455 Buyer did not accept billing
agreement Buyer did not accept billing
agreement Buyer has not agreed to the
billing agreement.
11456 A successful Billing
Agreement has already
been created for this token.
Transaction refused because of an
invalid argument. See additional
error messages for details.
Token has already been used to
create a billing agreement.
10408 Missing token Token is missing Token is missing.
10409 You’re not authorized to
access this info. Express Checkout token was
issued for a merchant account
other than yours.
Token belongs to a different
merchant.
10410 Invalid token Invalid token Token is invalid.
10411 This Express Checkout
session has expired. This Express Checkout session has
expired. Token value is no longer
valid.
Token expired.
Error
Code Short Message Long Message Additional Information
10001 Internal Error Internal Error
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid argument; description field
or custom field is empty and the
status is active
Check the description and
custom fields of the billing
agreement. Either the description
or custom field is empty and the
status is active or the contents of
one of these fields exceeds the
maximum field length.
10201 Billing Agreement was
cancelled Billing Agreement was cancelled Billing agreement has been
cancelled.
10204 User’s account is closed or
restricted User’s account is closed or
restricted
10209 Disabled Preapproved Payments not
enabled. Merchant pull is not enabled for
the country or merchant is not
enabled for merchant pull.
10209 Disabled Preapproved Payments not
enabled. Account number mismatch
exists for the API caller and the
account the billing agreement
belongs to.
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 349
API Error Codes
DoReferenceTransaction Errors A
DoReferenceTransaction Errors
All Reference Transactions-Related API Errors
10211 Invalid billing agreement
ID Invalid transaction or billing
agreement ID; could not find
Billing Agreement in database
11451 Billing Agreement Id or
transaction Id is not valid Billing Agreement Id or
transaction Id is not valid ReferenceID field is empty.
11451 Billing Agreement Id or
transaction Id is not valid Billing Agreement Id or
transaction Id is not valid Reference id refers to an invalid
transaction.
11452 Merchant not enabled for
reference transactions Merchant not enabled for reference
transactions This merchant is not enabled for
Mark reference transaction.
Error
Code Short Message Long Message Additional Information
10001 Internal Error Internal Error
10002 Authentication/Authorizati
on Failed
10003 Missing argument Item name, amount and quantity
are required if item category is
provided.
Scenario: Merchant passes item
category as either Digital or
Physical but does not also pass
one of the following parameters:
name, amount, or quantity.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You are not signed up to accept
payment for digitally delivered
goods.
Scenario: Merchant is not signed
up for digital goods but passes
item category as Digital.
10004 Cart item calculation
mismatch. Cart item calculation mismatch.
The regular non-trial billing period
amount is different than the sum of
the amounts for each item in the
cart.
Scenario: When the regular non-
trial billing period amount is
different than the sum of the
amounts for each item in the
cart.
10004 Tax calculation mismatch. Tax calculation mismatch. The tax
amount for the regular non-trial
billing period is different than the
sum of the tax for each item in the
cart.
Scenario: When the regular non-
trial billing period is different
than the sum of the tax for each
item in the cart.
Error
Code Short Message Long Message Additional Information
API Error Codes
DoReferenceTransaction Errors
A
350 August 2012 SOAP API Developer Reference
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid payment type argument
10009 Transaction refused The account for the counterparty is
locked or inactive Merchant is
locked/close/restricted.
10010 Invalid Invoice Non-ASCII invoice id is not
supported Non-ASCII characters are used
in InvoiceID field.
10201 Agreement canceled Billing Agreement was cancelled Billing agreement is not active.
10202 Exceed max Transaction would exceed user’s
monthly maximum Transaction would exceed the
monthly limit.
10203 Action required Transaction failed, action required
by user
10204 User’s account is closed or
restricted User’s account is closed or
restricted
10205 Risk Transaction refused due to risk
model
10206 Duplicate Transaction was already processed
10207 Retry Transaction failed but user has
alternate funding source Retry the transaction with an
alternate funding source.
10209 Disabled Preapproved Payments not
enabled. Merchants is not enabled for
preapproved payments (PAP);
applies only to legacy PAP
billing agreements.
10210 No Funding Transaction failed because has no
funding sources Payee has no funding sources.
10211 Invalid MP ID Invalid MP ID.
10212 Profile preference setting A profile preference is set to
automatically deny certain
transactions
A profile preference is set that
automatically denies this kind of
transaction.
10213 Invalid Soft Descriptor The soft descriptor passed in
contains invalid characters
10214 Soft descriptor format error.
10215 Soft Descriptor truncated The soft descriptor was truncated
10216 Confirmed address required Transaction refused because a
confirmed address is not available Transaction refused because a
confirmed address is not
available.
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 351
API Error Codes
DoReferenceTransaction Errors A
10400 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Order total is missing. TotalOrder amount is missing.
10401 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Order total is invalid. TotalOrder amount is invalid.
10402 Authorization only is not
allowed for merchant. This merchant account is not
permitted to set PaymentAction? to
Authorization. Please contact
Customer Service.
Merchant is not eligible for auth
settlement.
10406 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The PayerID? value is invalid. Merchant account number is
invalid.
10412 Duplicate invoice Payment has already been made
for this InvoiceID?. Payment already made for the
invoice.
10413 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The totals of the cart item amounts
do not match order amounts. Total of cart items does not
match order total.
10414 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The amount exceeds the maximum
amount for a single transaction. Amount exceeds the max
amount for a single txn.
10417 Transaction cannot
complete. The transaction cannot complete
successfully. Instruct the customer
to use an alternative payment
method.
Account not associated with a
usable funding source.
10417 Transaction cannot
complete. The transaction cannot complete
successfully. Instruct the customer
to use an alternative payment
method.
Credit card or Billing Agreement
is required to complete payment.
10418 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The currencies of the shopping cart
amounts must be the same. Currencies in the shopping cart
must be the same.
10420 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PaymentAction? tag is missing. PaymentAction? tag is missing.
Error
Code Short Message Long Message Additional Information
API Error Codes
DoReferenceTransaction Errors
A
352 August 2012 SOAP API Developer Reference
10426 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item total is invalid. ItemTotal amount is invalid.
10427 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping total is invalid. ShippingTotal amount is invalid.
10428 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Handling total is invalid. HandlingTotal amount is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Tax total is invalid. TaxTotal amount is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item sales tax is invalid PaymentDetailsItem.Tax field is
invalid. Warning only; API
executes.
10430 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item amount is missing. PaymentDetailsItem.Amount
field is missing. Warning only;
API executes.
10431 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item amount is invalid. PaymentDetailsItem.Amount
field is invalid. Warning only;
API executes.
10432 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invoice ID value exceeds
maximum allowable length. InvoiceID field is too long;
maximum length is 256.
10433 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of OrderDescription element
has been truncated. OrderDescription field is too
long; maximum length is 127.
Warning only; API executes.
10434 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of Custom element has been
truncated. Custom field is too long;
maximum length is 256.
Warning only; API executes.
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 353
API Error Codes
DoReferenceTransaction Errors A
10441 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The NotifyURL element value
exceeds maximum allowable
length.
NotifyURL field is too long;
maximum length for notify URL
is 2048.
10442 ButtonSource value
truncated. The ButtonSource element value
exceeds maximum allowable
length.
ButtonSource field is too long;
maximum length is 32. Warning
only; API executes.
10504 The cvv2 is invalid. This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
CVV2 field is invalid.
10527 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
CreditCardNumber and/or
CreditCardType is invalid.
10537 Risk Control Country Filter
Failure The transaction was refused
because the country was prohibited
as a result of your Country Monitor
Risk Control Settings.
Transaction refused due to
country monitor risk control.
10538 Risk Control Max Amount
Failure The transaction was refused
because the maximum amount was
excused as a result of your
Maximum Amount Risk Control
Settings.
Transaction refused due to max
amount risk control.
10539 Payment declined by your
Risk Controls settings:
PayPal Risk Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
Transaction declined by Risk
Control settings: PayPal Risk
model.
10546 Gateway Decline This transaction cannot be
processed. IP fraud models failed.
10560 Invalid Data The issue number of the credit card
is invalid. IssueNumber is invalid.
10567 Invalid Data A Start Date or Issue Number is
required. None of Start date or issue
number is specified (only applies
to Switch credit cards).
10600 Authorization voided Authorization voided.
10601 Authorization expired. Authorization has expired
10621 Order has expired. Order has expired.
10622 Order is voided. Order is voided.
10623 Maximum number of
authorization allowed for
the order is reached.
Maximum number of authorization
allowed for the order is reached.
Error
Code Short Message Long Message Additional Information
API Error Codes
DoReferenceTransaction Errors
A
354 August 2012 SOAP API Developer Reference
10725 Shipping Address Country
Error There was an error in the Shipping
Address Country field Shipping address error in
country field.
10727 Shipping Address1 Empty The field Shipping Address1 is
required Shipping address error in
address1 field.
10728 Shipping Address City
Empty The field Shipping Address City is
required Shipping address error in city
field.
10729 Shipping Address State
Empty The field Shipping Address State is
required Shipping address error in state
field.
10730 Shipping Address Postal
Code Empty The field Shipping Address Postal
Code is required Shipping address error in postal
code.
10731 Shipping Address Country
Empty The field Shipping Address
Country is required Country code is empty in
shipping address.
10736 Shipping Address Invalid
City State Postal Code A match of the Shipping Address
City, State, and Postal Code failed. Match of shipping address, city,
state, and postal code failed.
10747 Invalid Data This transaction cannot be
processed without a valid IP
address.
IPAddress field is invalid.
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification number.
CVV2 field is missing.
10755 Unsupported Currency. This transaction cannot be
processed due to an unsupported
currency.
11084 User does not have a good
funding source with which
to pay.
User does not have a good funding
source with which to pay. Scenario: The credit card
associated with the account
could not be used and there is no
other funding source with which
to complete the transaction.
11091 The transaction was
blocked as it would exceed
the sending limit for this
buyer.
The transaction was blocked as it
would exceed the sending limit for
this buyer.
The transaction was declined by
PayPal. Please have the buyer
contact PayPal Customer
Service.
11302 Cannot pay self The transaction was refused
because you cannot send money to
yourself.
Cannot pay self. Merchant is
referencing own transaction.
11451 Billing Agreement Id or
transaction Id is not valid Billing Agreement Id or
transaction Id is not valid Invalid reference id.
Error
Code Short Message Long Message Additional Information
SOAP API Developer Reference August 2012 355
API Error Codes
DoReferenceTransaction Errors A
11451 Billing Agreement Id or
transaction Id is not valid Billing Agreement Id or
transaction Id is not valid Reference transaction is not
associated with a billing
agreement.
11451 Billing Agreement Id or
transaction Id is not valid Billing Agreement Id or
transaction Id is not valid Reference id either not found or
could not be decrypted.
11451 Billing Agreement Id or
transaction Id is not valid Billing Agreement Id or
transaction Id is not valid Reference id either not found or
could not be decrypted.
11452 Merchant not enabled for
reference transactions Merchant not enabled for reference
transactions This merchant is not enabled for
Mark reference transaction.
11453 Reference transactions
temporarily unavailable. Reference transaction feature not
currently available; try again later Feature wired off.
11453 Reference transactions
temporarily unavailable. Reference transaction feature not
currently available; try again later Feature not supported in standin.
11454 Warning: Could not send
email to the buyer Warning: Could not send email to
the buyer Failed to send email to buyer.
This error is not fatal and
generates a warning.
11459 Invalid Data The shipping address must match
the user’s address in the PayPal
account.
The shipping address on file
does not match the requested
shipping address.
11610 Payment Pending your
review in Fraud
Management Filters
Payment Pending your review in
Fraud Management Filters
11611 Transaction blocked by
your settings in FMF Transaction blocked by your
settings in FMF
11612 Could not process your
request to accept/deny the
transaction
Could not process your request to
accept/deny the transaction
13122 Transaction refused Transaction violates PayPal Use
13701 Invalid Data Item Category value is invalid.
Only Digital or Physical are
allowed.
Scenario: When merchant passes
an item category value other than
Digital or Physical.
18014 Gateway Decline This transaction cannot be
processed. This transaction cannot be
processed without a Credit Card
Verification number.
Error
Code Short Message Long Message Additional Information
API Error Codes
AddressVerify API Errors
A
356 August 2012 SOAP API Developer Reference
AddressVerify API Errors
AddressVerify API Errors
ManagePendingTransactionStatus API Errors
ManagePendingTransactionStatus API Errors
Error Code Short Message Long Message
10004 Transaction refused because
of an invalid argument. See
additional error messages
for details.
Invalid email format.
10004 Transaction refused because
of an invalid argument. See
additional error messages
for details.
Invalid street format
10004 Transaction refused because
of an invalid argument. See
additional error messages
for details.
Invalid zip format
10009 The API is disabled. The Address API is currently disabled
Error Code Short Message Long Message
11614 Could not process your request
to accept/deny the transaction Could not process your request to accept/deny the transaction
11614 The transaction has already
been Accepted/Denied and the
status cannot be changed
The transaction has already been Accepted/Denied and the
status cannot be changed
SOAP API Developer Reference August 2012 357
BCountries and Regions
Supported by PayPal
PayPal uses 2-character IS0-3166-1 codes for specifying countries and regions that are
supported in fields and variables. Countries marked with an asterisk ( * ) are not supported for
PayPal Payments Pro and Virtual Terminal.
Country or Region Country or Region Code
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA * DZ *
AMERICAN SAMOA AS
ANDORRA AD
ANGUILLA AI
ANTARCTICA * AQ *
ANTIGUA AND BARBUDA AG
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
BARBADOS BB
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOSNIA-HERZEGOVINA BA
Countries and Regions Supported by PayPal
B
358 August 2012 SOAP API Developer Reference
BOTSWANA BW
BOUVET ISLAND * BV *
BRAZIL BR
BRITISH INDIAN OCEAN TERRITORY * IO *
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN REPUBLIC * CF *
CHILE CL
CHINA CN
CHRISTMAS ISLAND * CX *
COCOS (KEELING) ISLANDS CC
COLOMBIA CO
COOK ISLANDS CK
COSTA RICA CR
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
ESTONIA EE
FALKLAND ISLANDS (MALVINAS) FK
FAROE ISLANDS FO
FIJI FJ
Country or Region Country or Region Code
SOAP API Developer Reference August 2012 359
Countries and Regions Supported by PayPal B
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN TERRITORIES TF
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUERNSEY GG
GUYANA GY
HEARD ISLAND AND MCDONALD ISLANDS * HM *
HOLY SEE (VATICAN CITY STATE) VA
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
Country or Region Country or Region Code
Countries and Regions Supported by PayPal
B
360 August 2012 SOAP API Developer Reference
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KIRIBATI KI
KOREA, REPUBLIC OF KR
KUWAIT KW
KYRGYZSTAN KG
LATVIA LV
LESOTHO LS
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA MK
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
MICRONESIA, FEDERATED STATES OF FM
MOLDOVA, REPUBLIC OF MD
MONACO MC
MONGOLIA MN
MONTENEGRO ME
MONTSERRAT MS
Country or Region Country or Region Code
SOAP API Developer Reference August 2012 361
Countries and Regions Supported by PayPal B
MOROCCO MA
MOZAMBIQUE MZ
NAMIBIA NA
NAURU NR
NEPAL * NP *
NETHERLANDS NL
NETHERLANDS ANTILLES AN
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA ISLANDS MP
NORWAY NO
OMAN OM
PALAU PW
PALESTINE PS
PANAMA PA
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
Country or Region Country or Region Code
Countries and Regions Supported by PayPal
B
362 August 2012 SOAP API Developer Reference
SAINT HELENA SH
SAINT KITTS AND NEVIS KN
SAINT LUCIA LC
SAINT PIERRE AND MIQUELON PM
SAINT VINCENT AND THE GRENADINES VC
SAMOA WS
SAN MARINO SM
SAO TOME AND PRINCIPE * ST *
SAUDI ARABIA SA
SENEGAL SN
SERBIA RS
SEYCHELLES SC
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOUTH AFRICA ZA
SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS
SPAIN ES
SURINAME SR
SVALBARD AND JAN MAYEN SJ
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
TAIWAN, PROVINCE OF CHINA TW
TANZANIA, UNITED REPUBLIC OF TZ
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
Country or Region Country or Region Code
SOAP API Developer Reference August 2012 363
Countries and Regions Supported by PayPal B
TRINIDAD AND TOBAGO TT
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS ISLANDS TC
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIRATES AE
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR OUTLYING ISLANDS UM
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRITISH VG
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
ZAMBIA ZM
Country or Region Country or Region Code
Countries and Regions Supported by PayPal
B
364 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 365
CState and Province Codes
Canadian Province or U.S. State Abbreviation
Alberta AB
British Columbia BC
Manitoba MB
New Brunswick NB
Newfoundland and Labrador NL
Northwest Territories NT
Nova Scotia NS
Nunavut NU
Ontario ON
Prince Edward Island PE
Quebec QC
Saskatchewan SK
Yukon YT
Alabama AL
Alaska AK
American Samoa AS
Arizona AZ
Arkansas AR
California CA
Colorado CO
Connecticut CT
Delaware DE
District of Columbia DC
Federated States of Micronesia FM
Florida FL
Georgia GA
State and Province Codes
C
366 August 2012 SOAP API Developer Reference
Guam GU
Hawaii HI
Idaho ID
Illinois IL
Indiana IN
Iowa IA
Kansas KS
Kentucky KY
Louisiana LA
Maine ME
Marshall Islands MH
Maryland MD
Massachusetts MA
Michigan MI
Minnesota MN
Mississippi MS
Missouri MO
Montana MT
Nebraska NE
Nevada NV
New Hampshire NH
New Jersey NJ
New Mexico NM
New York NY
North Carolina NC
North Dakota ND
Northern Mariana Islands MP
Ohio OH
Oklahoma OK
Oregon OR
Palau PW
Canadian Province or U.S. State Abbreviation
SOAP API Developer Reference August 2012 367
State and Province Codes C
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
Canadian Province or U.S. State Abbreviation
State and Province Codes
C
368 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 369
DCurrency Codes
PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables.
Currencies and Currency Codes Supported by PayPal
Currency Currency Code
Australian Dollar AUD
Brazilian Real
NOTE: This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.
BRL
Canadian Dollar CAD
Czech Koruna CZK
Danish Krone DKK
Euro EUR
Hong Kong Dollar HKD
Hungarian Forint HUF
Israeli New Sheqel ILS
Japanese Yen JPY
Malaysian Ringgit
NOTE: This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.
MYR
Mexican Peso MXN
Norwegian Krone NOK
New Zealand Dollar NZD
Philippine Peso PHP
Polish Zloty PLN
Pound Sterling GBP
Singapore Dollar SGD
Swedish Krona SEK
Swiss Franc CHF
Taiwan New Dollar TWD
Currency Codes
D
370 August 2012 SOAP API Developer Reference
Currencies and Currency Codes Supported by Express Checkout and Direct Payment
Thai Baht THB
Turkish Lira
NOTE: This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.
TRY
U.S. Dollar USD
Express
Checkout
Currency
Cur-
rency
Code
Direct Payment
Currency for Specified
Card in United States
Direct Payment
Currency for Specified
Card in United Kingdom
Direct Payment
Currency for Specified
Card in Canada
Australian
Dollar
AUD Visa, MasterCard Visa, MasterCard Visa, MasterCard
Canadian
Dollar
CAD Visa, MasterCard Visa, MasterCard Visa, MasterCard
Czech Koruna CZK Visa, MasterCard Visa, MasterCard
Danish Krone DKK Visa, MasterCard Visa, MasterCard
Euro EUR Visa, MasterCard Visa, MasterCard Visa, MasterCard
Hong Kong
Dollar
HKD Visa, MasterCard Visa, MasterCard
Hungarian
Forint
HUF Visa, MasterCard Visa, MasterCard
Japanese Yen JPY Visa, MasterCard Visa, MasterCard Visa, MasterCard
Norwegian
Krone
NOK Visa, MasterCard Visa, MasterCard
New Zealand
Dollar
NZD Visa, MasterCard Visa, MasterCard
Polish Zloty PLN Visa, MasterCard Visa, MasterCard
Pound Sterling GBP Visa, MasterCard Visa, MasterCard, Maestro Visa, MasterCard
Singapore
Dollar
SGD Visa, MasterCard Visa, MasterCard
Swedish Krona SEK Visa, MasterCard Visa, MasterCard
Swiss Franc CHF Visa, MasterCard Visa, MasterCard
U.S. Dollar USD Visa, MasterCard,
Discover, American
Express
Visa, MasterCard Visa, MasterCard
Currency Currency Code
SOAP API Developer Reference August 2012 371
EAVS and CVV2 Response Codes
AVS Response Codes
Related information:
DoDirectPayment Response Fields
AVS Response Codes for Visa, MasterCard, Discover, and American
Express
AVS Code Meaning Matched Details
AAddress Address only (no ZIP code)
BInternational “A” Address only (no ZIP code)
CInternational “N” None
NOTE: The transaction is declined.
DInternational “X” Address and Postal Code
ENot allowed for MOTO
(Internet/Phone) transactions Not applicable
NOTE: The transaction is declined.
FUK-specific “X” Address and Postal Code
GGlobal Unavailable Not applicable
IInternational Unavailable Not applicable
MAddress Address and Postal Code
NNo None
NOTE: The transaction is declined.
PPostal (International “Z”) Postal Code only (no Address)
RRetry Not applicable
SService not Supported Not applicable
UUnavailable Not applicable
WWhole ZIP Nine-digit ZIP code (no Address)
AVS and CVV2 Response Codes
AVS Response Codes
E
372 August 2012 SOAP API Developer Reference
Related information:
DoDirectPayment Response Fields
AVS Response Codes for Maestro
Related information:
DoDirectPayment Response Fields
XExact match Address and nine-digit ZIP code
YYes Address and five-digit ZIP
ZZIP Five-digit ZIP code (no Address)
All others Error Not applicable
AVS Code Meaning Matched Details
0All the address information matched. All information matched
1None of the address information
matched. None
NOTE: The transaction is declined.
2Part of the address information
matched. Partial
3The merchant did not provide AVS
information. Not processed. Not applicable
4Address not checked, or acquirer had
no response. Service not available. Not applicable
Null No AVS response was obtained.
Default value of field. Not applicable
AVS Code Meaning Matched Details
SOAP API Developer Reference August 2012 373
AVS and CVV2 Response Codes
CVV2 Response Codes E
CVV2 Response Codes
CVV2 Response Codes for Visa, MasterCard, Discover, and American
Express
CVV2 Response Codes for Maestro
CVV2 Code Meaning Matched Details
EError - Unrecognized or Unknown
response Not applicable
IInvalid or Null Not applicable
MMatch CVV2CSC
NNo match None
PNot processed Not applicable
SService not supported Not applicable
UService not available Not applicable
XNo response Not applicable
CVV2 Code Meaning Matched Details
0Matched CVV2
1No match None
2The merchant has not implemented
CVV2 code handling Not applicable
3Merchant has indicated that CVV2 is
not present on card Not applicable
4Service not available Not applicable
All others Error Not applicable
AVS and CVV2 Response Codes
CVV2 Response Codes
E
374 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 375
About Previous Versions of the
API
Previous versions of the API can still be used; however, PayPal recommends using the latest
version whenever possible. Unless specifically specified, API operations default to the latest
version.
What’s New in Version 92.0
Updated for 92.0. Added new MsgSubID field for the following APIs for both requests and
responsees: RefundTransaction; DoReferenceTransaction; DoAuthorization; and DoCapture.
What’s New in Version 89.0
Updated for 89.0. Added new field to SetExpressCheckout and DoReferenceTransaction
Request APIs. Added new error to DoReferenceTransaction Request API.
What’s New in Version 88.0
Maintenance release, updated for 88.0.
What’s New in Version 85.0
No new features added; solely a maintenance release.
What’s New in Version 84.0
What’s New in Version 84.0
376 August 2012 SOAP API Developer Reference
New Field in RefundTransaction Response
New RefundInfoType in RefundTransaction Response
New Field in DoReferenceTransactionResponseDetailsType
Field Description
RefundInfo ebl:RefundInfoType
Contains refund payment status information.
This field is available since version 84.0.
Field Description
RefundStatus xs:PaymentStatusCodeType
Status of the refund. It is one of the following values:
-instant
-delayed
This field is available since version 84.0.
PendingReason xs:PendingStatusCodeType
Reason that the payment is delayed. It is one of the following values:
-none – The refund is instant.
-echeck – The refund is delayed.
This field is available since version 84.0.
Field Description
PaymentAdviceCode xs:string
Response code from the processor when a recurring transaction is declined.
For details on the meanings of the codes, see
https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-
content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.
SOAP API Developer Reference August 2012 377
What’s New in Version 82.0
New Field in DoDirectPaymentResponse
What’s New in Version 82.0
New Field in DoCapture Request
New MerchantStoreDetailsType in DoCapture Request
Field Description
PaymentAdviceCode xs:string
Response code from the processor when a recurring transaction is declined.
For details on the meanings of the codes, see
https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-
content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.
Field Description
MerchantStoreDetails ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.
Field Description
StoreID xs:string
ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 84.0.
TerminalID xs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
What’s New in Version 82.0
378 August 2012 SOAP API Developer Reference
New Fields in RefundTransaction Request
New MerchantStoreDetailsType in RefundTransaction Request
Field Description
MerchantStoreDetails ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.
RetryUntil xs:dateTime
(Optional) Maximum time until you must retry the refund.
NOTE: This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
RefundSource ebl:RefundSourceCodeType
(Optional)Type of PayPal funding source (balance or eCheck) that can be used for
auto refund. It is one of the following values:
-any – The merchant does not have a preference. Use any available funding
source.
-default – Use the merchant’s preferred funding source, as configured in the
merchant’s profile.
-instant – Use the merchant’s balance as the funding source.
-eCheck – The merchant prefers using the eCheck funding source. If the
merchant’s PayPal balance can cover the refund amount, use the PayPal
balance.
NOTE: This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
RefundType ebl:RefundPurposeTypeCodeType
Type of refund you are making. It is one of the following values:
-Full – Full refund (default).
-Partial – Partial refund.
-ExternalDispute – External dispute. (Value available since version 82.0)
-Other – Other type of refund. (Value available since version 82.0)
Field Description
StoreID xs:string
ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 84.0.
SOAP API Developer Reference August 2012 379
What’s New in Version 80.0
What’s New in Version 80.0
New Field in PaymentDetailsType in DoDirectPayment Request
New Fields in PaymentDetailsType in DoReferenceTransaction Request
TerminalID xs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
Recurring ns:RecurringFlagType
(Optional) Flag to indicate a recurring transaction. It is one of the following
values:
-Any value other than Y – This is not a recurring transaction (default).
-Y – This is a recurring transaction.
NOTE: To pass Y in this field, you must have established a billing agreement with
the buyer specifying the amount, frequency, and duration of the recurring
payment.
This field is introduced in version 80.0 of the API.
Field Description
Recurring ns:RecurringFlagType
(Optional) Flag to indicate a recurring transaction. It is one of the following
values:
-Any value other than Y – This is not a recurring transaction (default).
-Y – This is a recurring transaction.
NOTE: To pass Y in this field, you must have established a billing agreement with
the buyer specifying the amount, frequency, and duration of the recurring
payment.
This field is introduced in version 80.0 of the API.
Field Description
What’s New in Version 74.0
380 August 2012 SOAP API Developer Reference
What’s New in Version 74.0
New Behavior of DoExpressCheckoutPayment
By default, the DoExpressCheckoutPayment API operation is idempotent for all API
callers. You can call DoExpressCheckoutPayment up to a maximum of 10 times, and it
returns the same result. The exceptions are when DoExpressCheckoutPayment generates
an error or the token expires.
This functionality only works with version 74.0 or greater. There is no change to
DoExpressCheckoutPayment functionality if you are not updating to the latest version of
the API.
If you update to version 74.0 or higher but want to opt out of this functionality, contact PayPal.
New DoExpressCheckoutPayment Error Code
What’s New in Version 72.0
Changes to BuyerDetailsType in SetExpressCheckout Request
BuyerDetailsType Fields
Error
Code Short Message Long Message Correcting This Error...
13751 Could not retrieve the
original successful
response.
Transaction completed
successfully, but could not
retrieve the original successful
response.
Field Description
TaxIdDetails ebl:TaxIdDetailsType
Details about the buyer’s tax information. This field is required for Brazil and is
for Brazil use only.
SOAP API Developer Reference August 2012 381
What’s New in Version 72.0
New TaxIdDetailsType Structure in SetExpressCheckout Request
TaxIdDetailsType Fields
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response
TaxIdDetailsType Fields
Field Description
TaxIdType New field
xs:string
The buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
TaxId New field
xs:string
The buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte character for individuals and 14
single-byte characters for businesses.
Field Description
TaxIdType New field
xs:string
The buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
TaxId New field
xs:string
The buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte character for individuals and 14
single-byte characters for businesses.
What’s New in Version 69
382 August 2012 SOAP API Developer Reference
What’s New in Version 69
New PaymentDetailsItemType Structure in
CreateRecurringPaymentsProfile Request
PaymentDetailsItemType Fields
Field Description
ItemCategory New field
ns:ItemCategoryType
Indicates whether the item is digital or physical goods. For digital goods, this field
is required and you must set it to Digital to get the best rates. It is one of the
following values:
-Digital
-Physical
Name New field
xs:string
Item name.This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters
Description New field
xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
Amount New field
ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOTE: You must set the currencyID attribute to one of the 3-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 optional thousands separator must be a comma (,). Equivalent to nine
characters maximum for USD.
Number New field
xs:string
(Optional) Item number.
Quantity New field
xs:integer
Item quantity. This field is required when you pass a value for ItemCategory.
Character length and limitations: Any positive integer
SOAP API Developer Reference August 2012 383
What’s New in Version 69
Changes to PaymentDetailsItemType in DoReferenceTransaction Request
PaymentDetailsItemType Fields
Tax New field
ebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-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 optional thousands separator must be a comma (,). Equivalent to nine
characters maximum for USD.
Field Description
ItemCategory New field
ns:ItemCategoryType
Indicates whether the item is digital or physical goods. For digital goods, this
field is required and you must set it to Digital to get the best rates. It is one
of the following values:
-Digital
-Physical
Name xs:string
Item name. This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters
Amount ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOTE: You must set the currencyID attribute to one of the 3-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 optional thousands separator must be a comma (,).
Equivalent to nine characters maximum for USD.
Quantity xs:integer
Item quantity. This field is required when you pass a value for
ItemCategory.
Character length and limitations: Any positive integer
Field Description
What’s New in Version 66
384 August 2012 SOAP API Developer Reference
What’s New in Version 66
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests
PaymentDetailsType Fields
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests
PaymentDetailsItemType Fields
Field Description
ItemTotal ebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
PaymentAction ebl:PaymentActionCodeType
How you want to obtain payment. When implementing digital goods, this field
is required and you must set it to Sale.
Field Description
ItemCategory ns:ItemCategoryType
New field
Indicates whether the item is digital or physical goods. This field is available
since version 65.1. For digital goods this field is required and you must set it to
Digital. It is one of the following values:
-Digital
-Physical
Name xs:string
Item name. For digital goods, this field is required.
Character length and limitations: 127 single-byte characters
L_NAMEn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_NAMEm instead.
Description xs:string
Item description. For digital goods, this field is required.
Character length and limitations: 127 single-byte characters
SOAP API Developer Reference August 2012 385
What’s New in Version 66
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails
Response
Amount ebl:BasicAmountType
Cost of item. For digital goods, this field is required.
NOTE: 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 optional thousands separator must be a comma (,).
Equivalent to nine characters maximum for USD.
Quantity xs:integer
Item quantity. For digital goods, this field is required.
Character length and limitations: Any positive integer
Field Description
ItemCategory ns:ItemCategoryType
New field
Inicates whethe item is digital or physical goods. For digital goods this field is
required and you must set it to Digital. It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
What’s New in Version 66
386 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 387
Revision History
Date Description
10 August 2012 Maintenance release. Added CVV2 response codes E and I for Visa,
Mastercard, Discover and American Express.
7 August 2012 Maintenance release. New 10486 error code added for redirects when the
process declines the transaction: The transaction couldn’t be completed. Please
redirect your customer to PayPal.
10 July 2012 Updated for 92.0. Added new MsgSubID field for the following APIs for both
requests and responsees: RefundTransaction; DoReferenceTransaction;
DoAuthorization; and DoCapture.
12 June 2012 Maintenance release
22 May 2012 Maintenance release
2 May 2012 Updated for 89.0. Added new field to SetExpressCheckout and
DoReferenceTransaction Request APIs. Added new error to
DoReferenceTransaction Request API.
3 April 2012 Updated references to Website Payments Standard and Website Payments Pro to
PayPal Payments Standard and PayPal Payments Pro, respectively.
14 February 2012 Maintenance release
24 January 2012 Maintenance release, updated for 85.0.
1November 2011 Updated for 84.0. Added new field and a new type to RefundTransaction API
request. Added new field to DoDirectPayment API and
DoReferenceTransaction API responses. Edits to improve accuracy.
1 September 2011 General edits to improve consistency.
5 April 2011 Updated for 71.0. Added new fields to the DoExpressCheckout API response to
return information about funds that are being held and the seller’s encrypted
account number.
8 March 2011 Updated for 69.0. Added more digital goods support to the
CreateRecurringPaymentsProfile and DoReferenceTransaction APIs to enable
the merchant to obtain the best rates for digital goods.
26 January 2011 Updated for 66.0. Describes changes to the ExpressCheckout API for
implementing Digital Goods.
15 September 2010 Updated for 64.4, including addition of ProtectionEligibilityType field.
388 August 2012 SOAP API Developer Reference
11 May 2010 Updated for 63.0. Added new NVP API fields to use in version 63.0 Express
Checkout integrations. Deprecated old fields. Updated billing agreement API
with functionality to obtain the latest billing address and to skip billing
agreement creation. Added ReverseTransaction API.
10 March 2010 Updated information for 62.0: Describes Express Checkout fields recommended
to be used in applications that enable implementing parallel payments for a
marketplace.
21 January 2010 Updated information for 61.0: Added Express Checkout fields enabling you to
provide gift and insurance options to the PayPal checkout pages.
7 October 2009 Updated information for 60.0: updated currency table with new currencies, and
added Express Checkout API fields for Immediatee Payment and eBay.
16 June 2009 Updated information for 58.0: added GetPalDetails API and fields for payment
review.
22 May 2009 Minor update to version 57.0; added CreateBillingAgreement to
Enterprise edition.
08 April 2009 Updated information for 57.0: Express Checkout Callback API and error codes.
26 Nov. 2008 Updated information for 55.0.
23 Sept. 2008 Added information about using billing agreements with SetExpressCheckout.
3 Sept. 2008 Added information about payment review to GetTransactionDetails.
June 2008 Rearranged material, added error codes, and moved some material to the
Express Checkout Integration Guide.
April 2008 Added Fraud Management Filters information. Changed recurring payments
information.
February 2008 Added that ther VERSION parameter must be 50.0 in the API call to use
recurring payments.
January 2008 -Added billing agreement fields to SetExpressCheckout for recurring
payments
-Updated CreateRecurringPaymentsProfile for new recurring payments
features.
-Added new recurring payments APIs
-Added DoNonReferencedCredit API
September 2007 -Update eBay auctions for Express Checkout section
-Added fields for the giropay payment method to Express Checkout APIs
-Added Direct Payment error 10571.
August 2007 Added recurring payments concepts, modified SetExpressCheckout,
DoExpressCheckoutPayment, DoReferenceTransaction, and added
additional DoReferenceTransaction error codes.
Date Description
SOAP API Developer Reference August 2012 389
April 2007 Added Recurring Payments APIs: SetCustomerBillingAgreement,
GetBillingAgreementCustomerDetails, and
CreateRecurringPaymentsProfile.
February 2007 Bug fixes including updating Line Item Details for Direct Payment and Express
Checkout APIs, changing some parameters to optional in DoDirectPayment,
adding SHIPTOCOUNTRYCODE, and adding Switch/Solo codes for AVS and
CVV2.
December 2006 Updates for bug fixes.
October 2006 First public release.
11 May 2010 Added new NVP API fields to use in version 63.0 Express Checkout
integrations. Deprecated old fields. Updated billing agreement API with
functionality to obtain the latest billing address and to skip billing agreement
creation. Added ReverseTransaction API.
Date Description
390 August 2012 SOAP API Developer Reference
SOAP API Developer Reference August 2012 391
Index
A
AcceptFilters response field 68, 152, 273
Action request field 183, 217
ActivationDetails request field 194
ActivationDetailsType request fields 197
AdditionalBilling Cycles request field 225
Address Owner response field 172, 215
Address request field 59, 77, 88, 200, 231
Address response field 117, 172, 215, 243, 250
AddressOverride request field 89
AddressStatus response field 118, 172, 211, 216, 244
AddressType (Shipping) request fields 65, 95, 130, 198,
227, 258
AddressType (Shipping) response fields 118
AddressType request fields 60, 77, 201, 231
AddressType response fields 172, 211, 215, 244
AddressVerify API operation 27
AddressVerify request fields 27
AddressVerify request message 27
AddressVerify response fields 29
AddressVerify response message 28
AggregateAmount response field 210
AggregateOptionalAmount response field 210
AllowedPaymentMethod request field 102
AllowedPaymentMethodType request field 98, 122,
134
AllowNote request field 88
AllowPushFunding request field 102
American Express AVS response codes 371
American Express CVV2 response codes 373
Amount request field 32, 40, 45, 64, 73, 99, 136, 202,
220, 226, 261, 276, 382, 383, 385
Amount response field 41, 68, 78, 122, 180, 181, 213
Auction response field 179
AuctionInfoType response fields 180
AuctionItemNumber request field 283
AuctionTransaction Id request field 65, 101, 137, 262
AuctionTransaction Id response field 124
AUD 369, 370
Australian Dollar 369, 370
Authorization and Capture API Operation Reference 31
AuthorizationID request field 32, 45, 49
AuthorizationID response field 35, 45, 50
AuthorizationType response fields 42, 46
AuthStatus3ds request field 66
AutoBillOutstandingAmount request field 194, 226
AutoBillOutstandingAmount response field 210
AVS and CVV2 response codes 371
AVS response codes 371
AVSCode response field 68, 268
B
Balance response field 156
BalanceHoldings response field 156
BalanceTimeStamp response field 156
BanktxnPendingURL request field 92
BAUpdate API operation 245
BAUpdate request fields 245
BAUpdate request message 245
BAUpdate response fields 248
BAUpdate response message 246
BillingAgreement Details request field 92, 233
BillingAgreementCustom request field 104, 237, 246
BillingAgreementCustom response field 249
BillingAgreementDescription request field 104, 237,
246
BillingAgreementDescription response field 248
BillingAgreementDetails request fields 103, 236
BillingAgreementID response field 143, 239, 268
BillingAgreementMax response field 249
BillingAgreementStatus request field 245
BillingAgreementStatus response field 249
BillingFrequency response field 212
BillingPeriod response field 212
BillingPeriodDetailsType request fields 195, 228
BillingPeriodDetailsType response fields 212
BillingStartdate request field 193, 227
BillingStartdate response field 211
BillingType request field 103, 236
BillingType response field 248
BillOutstanding API operation 219
Index
392 August 2012 SOAP API Developer Reference
BillOutstandingAmount request fields 219
BillOutstandingAmount request message 219
BillOutstandingAmount response fields 220
BillOutstandingAmount response message 220
BrandName request field 93
Brazilian Real 369
BRL 369
Business response field 171
ButtonSource request field 63, 130, 133, 260
BuyerDetails request field 93
BuyerDetailsType request fields 102
BuyerEmail request field 91, 236
BuyerEmailOpti nEnable request field 94
BuyerId request field 102
BuyerID response field 180
BuyerMarketingEmail request field 129
BuyerMarketingEmail response field 116, 170
BuyerRegistrationDate request field 102
BuyerUserName request field 102
C
CAD 369, 370
CallbackTimeout request field 87
CallbackURL request field 87
Canadian Dollar 369, 370
CancelURL request field 87, 234
CardNumber request field 282
CardOwner request field 58, 75, 199, 230, 263
CardOwner response field 215
CartID request field 101, 137
CartID response field 124
Cavv request field 66
ChannelType request field 92
character encoding 24
CheckoutStatus response field 115
CHF 369, 370
CityName request field 60, 77, 201, 231
CityName response field 173, 211, 216, 244, 251
ClosingDate response field 180
Comment request field 74
CompleteType request f ield 32
ConfirmationCode response field 29
ContactPhone response field 115
CorrelationID 24
Country request field 60, 66, 77, 95, 130, 198, 201,
228, 231, 258
Country response field 118, 173, 212, 216, 244, 251
CountryCode response field 29
CountryCodeType 66, 95, 118, 130, 198, 228, 258
CountryName response field 173, 216
CouponAmount response field 179
CouponAmountCurrency 179
CouponID 179
cpp-header-back-color request field 91, 236
cpp-header-border request field 236
cpp-header-border-color request field 91
cpp-header-image request field 91, 236
cpp-payflow-color request field 91, 236
CreateBillingAgreement API operation 238
CreateBillingAgreement request fields 238
CreateBillingAgreement request message 238
CreateBillingAgreement response fields 239
CreateBillingAgreement response message 239
CreateRecurringPaymentsProfile API operation 187
CreateRecurringPaymentsProfile request fields 192
CreateRecurringPaymentsProfile request message 187
CreateRecurringPaymentsProfile response fields 203
CreateRecurringPaymentsProfile response
message 203
CreditCard request field 57, 74, 193, 227
CreditCard response field 210
CreditCardDetailsType request fields 58, 75, 199, 229,
263
CreditCardDetailsType response fields 214
CreditCardNumber request field 58, 75, 199, 230, 263
CreditCardNumber response field 214
CreditCardType request field 58, 75, 199, 229, 263
CreditCardType response field 214
currencies 24
currency codes 369, 370
CurrencyCode request field 283
CurrentRecurring PaymentsPeriod response field 210
Custom request field 63, 87, 98, 133, 260
Custom response field 114, 121, 178
CustomerServiceNumber request field 93
CVV2 request field 58, 75, 199, 230, 263
CVV2 response codes 373
CVV2Code response field 68, 268
Czech Koruna 369, 370
CZK 369, 370
SOAP API Developer Reference August 2012 393
Index
D
Danish Krone 369, 370
dateÚtime formats 24
DenyFilters response field 68, 152, 273
Description request field 64, 99, 135, 194, 202, 225,
261, 382, 384
Description response field 69, 122, 153, 209, 274
Discover AVS response codes 371
Discover CVV2 response codes 373
DKK 369, 370
Do Reauthorization request fields 45
Do Reauthorization response fields 45
DoAuthorization API operation 40
DoAuthorization request fields 40
DoAuthorization request message 40
DoAuthorization response fields 41
DoAuthorization response message 41
DoCapture API operation 31
DoCapture request fields 32
DoCapture request message 31
DoCapture response fields 35
DoCapture response message 34
DoDirectPayment API operation 51
DoDirectPayment request fields 56
DoDirectPayment request message 51
DoDirectPayment response fields 68
DoDirectPayment response message 67
DoExpressCheckoutPayment API operation 126
DoExpressCheckoutPayment request fields 128
DoExpressCheckoutPayment request message 126
DoExpressCheckoutPayment response fields 142
DoExpressCheckoutPayment response message 139
DoNonReferencedCredit API operation 71
DoNonReferencedCredit request fields 73
DoNonReferencedCredit request message 71
DoNonReferencedCredit response fields 78
DoNonReferencedCredit response message 78
DoReauthorization API operation 44
DoReauthorization request message 44
DoReauthorization response message 45
DoReferenceTransaction API operation 251
DoReferenceTransaction request fields 255
DoReferenceTransaction request message 251
DoReferenceTransaction response fields 267
DoReferenceTransaction response message 265
DoVoid API operation 48
DoVoid request fields 49
DoVoid request message 48
DoVoid response fields 50
DoVoid response message 49
E
EbayItemPayment DetailsItem request field 100, 137
EbayItemPayment DetailsItem response field 123
EbayItemPaymentDetailsItem request field 64
EbayItemPaymentDetailsItemType request fields 65,
101, 137, 262
EbayItemPaymentDetailsItemType response fields 124
EbayItemTxnId response field 179
EbayTransactionId response field 150
Eci3ds request field 66
EciSubmitted3ds response field 70
EffectiveDate response field 180
Email request field 27
EmailSubject request field 185
EndDate request field 282
Enhanced CheckoutData request field 92
EnhancedItemData request field 101, 137
EnhancedPaymentData request field 98, 134
EnhancedPaymentData response field 122
EnhancedPaymentInfo response field 150
error codes 287
error responses 22
ErrorCode response field 125, 152
ErrorParameters response field 125, 152
EUR 369, 370
Euro 369, 370
ExchangeRate response field 146, 175, 270
ExpMonth request field 58, 75, 199, 230, 263
ExpMonth response field 214
ExpressCheckout API Operatons 79
ExpYear request field 58, 75, 199, 230, 263
ExpYear response field 215
F
FailedInitialAmountAction request field 197
FailedPaymentCount response field 214
FeeAmount response field 146, 175, 270, 286
FeeRefundAmount response field 279
FinalPaymentDueDate response field 210
FirstName request field 60, 76, 201, 230, 264, 284
Index
394 August 2012 SOAP API Developer Reference
FirstName response field 117, 172, 215, 243, 250
FlatR ateShippingOptions request field 88
FMFDetails response field 68, 143, 150, 268
FMFDetailsType response fields 68, 152, 273
Forint 369, 370
FundingSourceDetails request field 93
FundingSourceDetailsType request fields 102
G
GBP 369, 370
Get ExpressCheckout Details request fields 106
GetBalance API operation 155
GetBalance request fields 155
GetBalance request message 155
GetBalance response fields 156
GetBalance response message 156
GetBillingAgreementCustomerDetails API
operation 240
GetBillingAgreementCustomerDetails request
fields 240
GetBillingAgreementCustomerDetails request
message 240
GetBillingAgreementCustomerDetails response
fields 242
GetBillingAgreementCustomerDetails response
message 241
GetExpressCheckoutDetails API operation 106
GetExpressCheckoutDetails request message 106
GetExpressCheckoutDetails response fields 114
GetExpressCheckoutDetails response message 107
GetPalDetails API operation 157
GetPalDetails request message 157
GetPalDetails response fields 158
GetPalDetails response message 158
GetRecurringPaymentsProfileDetails API
operation 204
GetRecurringPaymentsProfileDetails request fields 204
GetRecurringPaymentsProfileDetails request
message 204
GetRecurringPaymentsProfileDetails response
fields 209
GetRecurringPaymentsProfileDetails response
message 205
GetTransactionDetails API operation 161
GetTransactionDetails request fields 161
GetTransactionDetails request message 161
GetTransactionDetails response fields 168
GetTransactionDetails response message 162
GiftMessage requ est field 129
GiftMessage response field 115, 169
GiftMessageEnable request field 93
GiftReceiptEnable request field 93, 129
GiftReceiptEnable response field 116, 169
GiftWrapAmount request field 93, 129
GiftWrapAmount response field 116, 170
GiftWrapEnable request field 93
GiftWrapName request field 93, 129
GiftWrapName response field 116, 169
giropayCancelURL request field 92
giropaySuccessURL requ est field 92
GrossAmount response field 145, 174, 269, 286
GrossRefundAmount response field 279
H
HandlingTotal request field 62, 97, 132, 259
HandlingTotal response field 120
HKD 369
HoldDecision response field 149
Hong Kong Dollar 369
HUF 369, 370
Hungarian Forint 369, 370
I
ID response field 69, 153, 274
ILS 369
InitialAmount request field 197
InstrumentDetails response field 151
InsuranceOp tion Offered response field 120
InsuranceOptionOffered request field 97, 132
InsuranceOptionSelected request field 138
InsuranceOptionSelected response field 124, 151, 169
InsuranceTotal request field 62, 96, 132
InsuranceTotal response field 120
InvoiceID request field 32, 63, 87, 98, 133, 260, 276,
282
InvoiceID response field 114, 178
InvoiceID responsefield 121
IPAddress request field 57, 256
Israeli Sheqel 369
IssueNumber request field 59, 76, 200, 230, 264
IssueNumber response field 215
Ite mCategory 261
SOAP API Developer Reference August 2012 395
Index
ItemCategory 383
ItemCategory request field 101, 137, 202, 382
ItemCategory response field 123
ItemHeight request field 100, 137
ItemHeight response field 123
ItemLength request field 100, 136
ItemLength response field 123
ItemNumber request field 65, 101, 137, 262
ItemNumber response field 124
ItemTotal reque stfield 61
ItemTotal request field 96, 131, 259, 384
ItemTotal response field 119
ItemURL request field 100, 137
ItemWeight request field 100, 136
ItemWeight response field 123
ItemWidth request field 100, 123, 136
J
Japanese Yen 369, 370
JPY 369, 370
K
Koruna 369, 370
Krona 369, 370
Krone 369, 370
L
LandingPage request field 92
LastName request field 60, 76, 77, 201, 231, 264, 284
LastName response field 117, 172, 215, 244, 250
LastPaymentAmount response field 214
LastPaymentDate response field 214
Locale response field 159
LocaleCode request field 90, 235
LongMessage response field 125, 152
LoyaltyCardDiscountAmount 179
LoyaltyCardDiscountCurrency 180
M
Maestro AVS response codes 372
Maestro CVV2 response codes 373
Malaysian Ringgit 369
ManagePendingTransactionStatus API operation 183
ManagePendingTransactionStatus request fields 183
ManagePendingTransactionStatus request message 183
ManagePendingTransactionStatus response fields 184
ManagePendingTransactionStatus response
message 184
ManageRecurringPaymentsProfileStatus API
operation 217
ManageRecurringPaymentsProfileStatus request
fields 217
ManageRecurringPaymentsProfileStatus request
message 217
ManageRecurringPaymentsProfileStatus response
fields 218
ManageRecurringPaymentsProfileStatus response
message 218
Mass Payment response fields 186
MassPay API operation 185
MassPay request fields 185
MassPay request message 185
MassPay response message 186
MassPayItem request field 186
MasterCard AVS response codes 371
MasterCard CVV2 response codes 373
MaxAmount request field 86
MaxFailedPayments request field 194, 227
MaxFailedPayments response field 210
Memo response field 178
MerchantSessionId request field 57, 256
MerchantStoreDetails request field 33, 277
message style 21
Mexican Peso 369
MiddleName request field 60, 76, 201, 264, 284
MiddleName response field 117, 172, 243, 250
MpiVendor3ds request field 66
MsgSubID request field 33, 36, 41, 42, 257, 268, 277,
279
MultiItem response field 180
MXN 369
MYR 369
N
Name request field 64, 65, 95, 99, 130, 135, 198, 202,
227, 258, 261, 382, 383, 384
Name response field 69, 118, 122, 153, 172, 179, 211,
216, 244, 250, 274
NetAmount request field 74
NetAmount response field 286
Index
396 August 2012 SOAP API Developer Reference
NetRefundAmount response field 279
New Zealand Dollar 369, 370
NextBillingDate response field 213
NOK 369, 370
Norwegian Krone 369, 370
NoShipping request field 88
Note request field 32, 49, 217, 220, 225
Note response field 115, 142
NoteT ext request field 98
NoteText request field 134
NoteText response field 122
NoteToBuyer request field 94
Noti fyURL request field 63
NotifyURL request field 98, 134, 260
NotifyURL response field 121
NotToBuyer request field 94
Number request field 64, 100, 136, 202, 262, 382
Number response field 122, 179
NumberCycles Completed response field 213
NumberCycles Remaining response field 213
NZD 369, 370
O
OfferDetails response field 151
Opti ons response field 180
OrderDescription request field 62, 86, 97, 133, 260
OrderDescription response field 121
OrderID request field 65, 101, 137, 262
OrderID response field 124
OrderTotal request field 61, 86, 96, 131, 259
OrderTotal response field 119
OtherPaymentMethods request field 92
OutstandingBalance request field 226
OutstandingBalance response field 214
P
Pa yerStatus request field 59, 200
PageStyle request field 90, 235
Pal response field 158
Pare ntTransactionID response field 174, 269
Payer request field 59, 76, 200, 230, 282
Payer response field 116, 171, 215, 243, 249, 286
PayerBusiness request field 59, 200
PayerBusiness response field 117, 171, 243, 250
PayerCountry request field 59, 200
PayerCountry response field 117, 171, 243, 250
PayerDisplayName response field 286
PayerID request field 59, 129, 200
PayerID response field 116, 171, 243, 249
PayerInfo response field 114, 170, 242, 249
PayerInfoType request fields 59, 76, 200, 230
PayerInfoType response fields 116, 171, 215, 243, 249
PayerName request field 59, 200, 282
PayerName request fields 60, 76, 200, 264, 284
PayerName response field 117, 171, 243, 249
PayerName response fields 117, 172, 243, 250
PayerStatus response field 117
Paym entDetailsItem request field 134
Payment DetailsItem response field 121
PaymentAction request field 56, 91, 99, 128, 135, 255,
384
PaymentDate response field 145, 174, 269
PaymentDetai ls request field 88
PaymentDetails request field 57, 129, 255
PaymentDetails response field 115
PaymentDetailsItem request field 63, 98, 261
PaymentDetailsItemType request fields 64, 99, 135,
202, 261, 382, 383, 384
PaymentDetailsItemType response fields 122
PaymentDetailsType request fields 61, 96, 131, 259
PaymentDetailsType response fields 119
PaymentError response field 125, 150
PaymentErrorType response fields 125, 151
PaymentInfo respo nse field 35
PaymentInfo response field 142, 170, 267
PaymentInfoType response fields 145, 173, 268
PaymentItem response field 179
PaymentItemInfo response field 170
PaymentItemInfoType response fields 178
PaymentItemType response fields 179
PaymentPeriod request field 194, 227
PaymentPeriod.Amount request field 195, 196, 228
PaymentPeriod.BillingFrequency request field 195
PaymentPeriod.BillingPeriod request field 195
PaymentPeriod.TotalBillingCycles request field 195,
228
PaymentReason request field 94, 257
PaymentRequestID request field 99, 135
PaymentRequestID response field 122, 125, 150
PaymentRequestInfo response field 116
PaymentRequestInfoType response fields 125
PaymentStatus response field 42, 46, 147, 176, 271
SOAP API Developer Reference August 2012 397
Index
PaymentTransactionDetails response field 168
PaymentTransactionDetails response fields 170
PaymentType request field 104, 237
PaymentType response field 145, 174, 269
PayPalAccountID request field 101
PayPalAccountID response field 125, 152
PayPalAdjustment response field 115
PayPalToken response field 29
PendingFilters response field 68, 152, 273
PendingReason request field 280
PendingReason response field 43, 47, 148, 177, 272
Period response field 181
Peso 369
Philippine Peso 369
Phone request field 61, 66, 77, 95, 131, 198, 201, 228,
231, 258
Phone response field 118, 173, 216
PHP 369
PLN 369, 370
Polish Zloty 369, 370
PostalCode re sponse field 118
PostalCode request field 61, 65, 77, 95, 130, 198, 201,
228, 231, 258
PostalCode response field 173, 212, 216, 244, 251
Pound Sterling 369, 370
previous versions 375
ProfileID request field 204, 217, 219, 225, 284
ProfileID response field 203, 209, 218, 220, 232
ProfileReference request field 193, 225
ProfileReference response field 211
ProfileStatus response field 203, 209
ProtectionEligibility response field 43, 47, 149, 178,
273
ProtectionEligibilityType response field 44, 48, 150,
178, 273
Q
Quantity request field 64, 100, 136, 202, 262, 382, 383,
385
Quantity response field 123, 179
R
ReasonCode response field 149, 177, 272
reattempt response field 181
ReceiptID request field 282
ReceiptID response field 174, 269
Receiver request field 282
Receiver response field 171
ReceiverEmail request field 74
ReceiverID response field 171
ReceiverInfo response field 170
ReceiverInfoType response fields 171
ReceiverType request field 186
Recurrences response field 181
Recurring Payments API Operations 187
Recurring request field 63, 261, 379
recurring response field 181
RecurringPayments ProfileDetails response field 210
RecurringPayments Summary response field 210
RecurringPaymentsProfileDetails request field 193
RecurringPaymentsProfileDetailsType request
fields 193
RecurringPaymentsProfileDetailsType response
fields 211
RecurringPaymentsSummaryDetailsType response
fields 213
RedirectRequired response field 115, 142
Reference Transactions API Operations 187
ReferenceID request field 245, 255
RefundAdvice request field 277
RefundInfo request field 279
RefundItemDetails request field 277
RefundSource request field 277
RefundStatus request field 280
RefundTransaction API operation 275
RefundTransaction request fields 276
RefundTransaction request message 275
RefundTransaction response fields 278
RefundTransaction response message 278
RefundTransactionID response field 278
RefundType request field 276, 378
ReportsFilters response field 69, 152, 273
ReqConfirmShipping request field 88, 256
request structure 19
RequesterCredentials 17
response structure 21
RetryTime response field 180
RetryUntil request field 276
ReturnAllCurrencies request field 155
ReturnFMFDetails request field 57, 129, 256
ReturnURL request field 87, 234
RiskFilterListType response fields 69, 153, 274
Index
398 August 2012 SOAP API Developer Reference
S
SalesTax response field 178
Salutation request field 60, 76, 200, 264, 284
Salutation response field 117, 172, 243, 250
ScheduleDetails request field 193
ScheduleDetailsType request fields 194
SecureMerchantAccountID response field 152
security 17
SEK 369, 370
SellerDetails request field 98, 134
SellerDetails response field 150
SellerDetailsType request fields 138
SellerID request field 138
SellerRegistrationDate request field 138
SellerUserName request field 138
service architecture 15
service endpoints 18
SetCustomerBillingAgreement API operation 233
SetCustomerBillingAgreement request fields 233
SetCustomerBillingAgreement request message 233
SetCustomerBillingAgreement response fields 238
SetCustomerBillingAgreement response message 237
SetExpressCheckout API operation 79
SetExpressCheckout request message 79
SetExpressCheckout response fields 105
SetExpressCheckout response message 105
SettleAmount response field 146, 175, 270
SeverityCode response field 125, 152
SGD 369, 370
Sheqel 369
Shipp ingDiscountrequest field 132
ShippingAmount request field 74, 226, 229
ShippingAmount response field 213
ShippingCalculationMode response field 124, 151, 168
ShippingDiscount request field 62, 97
ShippingDiscount response field 120
ShippingOptionAmount request field 103, 138
ShippingOptionAmount response field 124, 151, 169
ShippingOptionIsDefault request field 103, 138
ShippingOptionIsDefault response field 124, 151, 169
ShippingOptionName request field 103, 138
ShippingOptionName response field 125, 151, 169
ShippingOptionsType request fields 103
ShippingTotal request field 61, 96, 132, 259
ShippingTotal response field 119
ShipToAddress request field 63, 98, 134, 261
ShipToAddress response field 121
ShortMessage response field 125, 151
Singapore Dollar 369, 370
SOAP API definitions 16
SOAP request envelope 18
SoftDescriptor request field 33, 134, 257
SolutionType request field 92
StartDate request field 282, 283
StartMonth request field 58, 75, 199, 230, 263
StartMonth response field 215
StartYear request fie ld 59, 76, 199, 230, 264
StartYear response field 215
state and proivince codes 365
StateOrProvince request field 60, 65, 77, 95, 130, 198,
201, 228, 231, 258
StateOrProvince respon se field 118
StateOrProvince response field 173, 212, 216, 244, 251
Status request field 284
Status response field 184, 286
StoreId 150, 178, 273
StoreID request field 34, 277, 377, 378
Street request field 28
Street1 request field 60, 65, 77, 95, 130, 198, 201, 227,
231, 258
Street1 response field 118, 173, 211, 216, 244, 250
Street2 request field 60, 65, 77, 95, 130, 198, 201, 227,
231, 258
Street2 response field 118, 173, 211, 216, 244, 251
StreetMatch response field 29
SubscriberName request field 193, 225
SubscriberName response field 211
SubscriberShipping Address request field 193, 225
SubscriberShipping Address response field 211
Subscription response field 179
SubscriptionDate response field 180
SubscriptionID response field 180, 181
SubscriptionInfoType response fields 180
SubscriptionTermsType response field 181
SubscriptionTermsType response fields 181
SuccessPageRedirectRequested response field 143
Suffix request field 60
Suffix requestfi eld 76, 201, 264, 284
Suffix response field 117, 172, 244, 250
SurveyChoice request field 94
SurveyChoiceSelected request field 130
SurveyChoiceSelected response field 116, 170
SurveyEnable request field 94
SOAP API Developer Reference August 2012 399
Index
SurveyQuestion request field 94, 130
SurveyQuestion response field 116
SurveyQuestionresponse field 170
Swedish Krona 369, 370
Swiss Franc 369, 370
T
Taiwan New Dollar 369
Tax request field 64, 100, 136, 203, 262, 383
Tax response field 123
TaxAmount request field 74, 197, 226, 229
TaxAmount response field 146, 175, 213, 270
TaxId request field 104
TaxId response field 126
TaxIdDetails request field 102
TaxIdDetailsType request fields 104
TaxIdDetailsType response fields 126
TaxIdType request field 104
TaxIdType response field 126
TaxTotal request field 62, 97, 133, 260
TaxTotal response field 121
TerminalId 150, 178, 273
TerminalID response field 34, 278, 377, 379
Thai Baht 370
THB 370
ThreeDSecure request fields 66
ThreeDSecure response fields 70
ThreeDSecureRequest request field 57
Timestamp response field 285
Timezone response field 286
Token request field 106, 128, 192, 238, 240
Token response field 105, 114, 142, 238
TotalBillingCycles response field 212
TotalRefundedAmount response field 279
TotalType request field 94
TransactionClass request field 283
TransactionEntity request field 40
TransactionID request field 40, 161, 183, 276, 282
TransactionId request field 98, 134
TransactionID response field 41, 68, 78, 145, 173, 184,
268, 286
TransactionId response field 122, 125
TransactionSearch API operation 281
TransactionSearch request fields 282
TransactionSearch request message 281
TransactionSearch response fields 285
TransactionSearch response message 285
TransactionTyp eresponse field 145
TransactionType response field 174, 269
TrialPeriod request field 194, 227
TrialPeriod.Amount request field 196, 229
TrialPeriod.BillingFrequency request field 196
TrialPeriod.BillingPeriod request field 196
TrialPeriod.TotalBillingCycles request field 196, 228
TRY 370
Turkish Lira 370
TWD 369
Type response field 286
U
U.S. Dollar 370
UpdateRecurringPaymentsProfile API operation 221
UpdateRecurringPaymentsProfile request fields 225
UpdateRecurringPaymentsProfile request message 221
UpdateRecurringPaymentsProfile response fields 232
UpdateRecurringPaymentsProfile response
message 232
USD 370
UserName response field 181
UserSelectedOptions request field 129
UserSelectedOptions response field 115
UserSelectedOptions response fields 124, 151
V
Visa AVS response codes 371
Visa CVV2 response codes 373
VPAS response field 70
W
WSDL/XSD schema definitions 16
X
XID request field 66
Y
Yen 369, 370
Index
400 August 2012 SOAP API Developer Reference
Z
Zip request field 28
ZipMatch response field 29
Zloty 369, 370

Navigation menu