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, L2449, 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 i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained 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 f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
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
SOAP API Developer Reference August 2012 3
Contents
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
4 August 2012 SOAP API Developer Reference
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
SOAP API Developer Reference August 2012 5
Contents
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
6 August 2012 SOAP API Developer Reference
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
SOAP API Developer Reference August 2012 7
Contents
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 DoReferenceTransactionResponseDetailsT ype . . . . . . . . . . . . .376
New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .377
What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
8 August 2012 SOAP API Developer Reference
Contents
New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
New MerchantStoreDeta ilsType 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
SOAP API Developer Reference August 2012 9
Contents
10 August 2012 SOAP API Developer Reference
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.
SOAP API Developer Reference August 2012 11
What’s New in Version 93.0
12 August 2012 SOAP API Developer Reference
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
SOAP API Developer Reference August 2012 13
Documentation Feedback
14 August 2012 SOAP API Developer Reference
PayPal SOAP API Basics
1
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.
SOAP API Developer Reference August 2012 15
PayPal SOAP API Basics
1
PayPal WSDL/XSD Schema Definitions
PayPal WSDL/XSD Schema Definitions
The PayPal Web Services schema and its underlying eBay Business Language (eBL) base and
core components are required for developing applications with the PayPal Web Services API.
The following are the locations of the WSDL and XSD files.
Location of PayPal WSDL and XSD Files
Development and Test with the PayPal Sandbox API Service
PayPal Schema https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and
Component Types
Production with Live PayPal Web Services API Service
PayPal Schema https://www.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
http://www.paypal.com/wsdl/eBLBaseComponents.xsd
http://www.paypal.com/wsdl/CoreComponentTypes.xsd
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.
16 August 2012 SOAP API Developer Reference
Security
PayPal SOAP API Basics
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.
1
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>
SOAP API Developer Reference August 2012 17
PayPal SOAP API Basics
1
SOAP Service Endpoints
RequesterCredentials Authentication Elements in SOAP Header
Element Value Description
<Username> api_username Your API usernam e, 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
API Access > API Certificate Information.
<Password> api_password Y our API password, which you specify when you apply for a digital
certificate to use the PayPal SOAP API.
<Signature> api_signature Your API si gnat ure, if you use one instead of an API Certificate.
https://www.paypal.com/ in your Profile under
<Subject> authorizing_
account_
emailaddress
The email address of a third-party for whom you are sending
requests to the PayPal SOAP API. Yo ur API username m ust have
been granted permission by this third-party to make any particular
PayPal API request.
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
Authentication
Mechanism
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/
Live Production Endpoint Test (Sandbox) Endpoint
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.
18 August 2012 SOAP API Developer Reference
Diagram of SOAP Request Envelope
PayPal SOAP API Basics
Request Structure
1
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”>
SOAP API Developer Reference August 2012 19
PayPal SOAP API Basics
1
Request Structure
<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
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.
Related information:
SOAP RequesterCredentials: Username, Password, Signature, and Subject
20 August 2012 SOAP API Developer Reference
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
SOAP Message Style: doc-literal
1
SOAP API Developer Reference August 2012 21
PayPal SOAP API Basics
1
Error Responses
applicationCorrelation
</CorrelationID>
<Build xmlns=”urn:ebay:apis:eBLBaseComponents”>
api_build_number
</Build>
<element s_for_specific_ap i_response> dat a
</elements_for_specific_api_response>
</specific_api_name_Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Annotation of Generic SOAP Response
Lines Comment
22 and 31 The specific_api_name_Response start and end elements.
23 Each API response contains a timestamp with its date and time in UTC/GMT.
24 The <Ack> element contains the string Success after the corresponding request has been
successfully processed.
In the case of errors, Ack is set to a value other than Success, and the response body contains
an <Errors> element with information to help you troubleshoot the cause of the error. See
“Error Responses” on page 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.
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:
22 August 2012 SOAP API Developer Reference
PayPal SOAP API Basics
Error Responses
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.
1
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>
SOAP API Developer Reference August 2012 23
PayPal SOAP API Basics
1
CorrelationID for Reporting Problems to PayPal
</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.
24 August 2012 SOAP API Developer Reference
PayPal SOAP API Basics
Core Currency Amount Data Type
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>
1
SOAP API Developer Reference August 2012 25
PayPal SOAP API Basics
1
Core Currency Amount Data Type
26 August 2012 SOAP API Developer Reference
AddressVerify API Operation
2
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: ?@?.??
SOAP API Developer Reference August 2012 27
AddressV erify API Operation
2
AddressVerify Response Message
Field Description
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.
AddressVerify Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
28 August 2012 SOAP API Developer Reference
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.
AddressVerify API Operation
AddressVerify Response Message
2
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
SOAP API Developer Reference August 2012 29
AddressV erify API Operation
2
AddressVerify Response Message
30 August 2012 SOAP API Developer Reference
Authorization and Capture API
3
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.
SOAP API Developer Reference August 2012 31
Authorization and Capture API Operation Reference
3
DoCapture API Operation
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
32 August 2012 SOAP API Developer Reference
Field Description
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)
* (ast erisk)
. (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
Authorization and Capture API Operation Reference
DoCapture API Operation
3
MerchantStoreDetailsns: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.
SOAP API Developer Reference August 2012 33
Authorization and Capture API Operation Reference
3
DoCapture API Operation
MerchantStoreDetailsTypeFields
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.
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
by using the reporting mechanism. Not applicable to point of sale transactions.
GetTransactionDetails or
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
34 August 2012 SOAP API Developer Reference
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.
SOAP API Developer Reference August 2012 35
Authorization and Capture API Operation Reference
3
DoCapture API Operation
Field Description
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.
PaymentInfoTypeFields
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
36 August 2012 SOAP API Developer Reference
Authorization and Capture API Operation Reference
Field Description
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.
DoCapture API Operation
3
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
SOAP API Developer Reference August 2012 37
Authorization and Capture API Operation Reference
3
DoCapture API Operation
Field Description
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
None – No status
Canceled-Reversal – This means a reversal has been canceled. For example,
Completed.
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-ofsale transactions.
Denied – You denied the paym ent. Th is ha ppens onl y 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.
38 August 2012 SOAP API Developer Reference
Authorization and Capture API Operation Reference
Field Description
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.
DoCapture API Operation
3
SOAP API Developer Reference August 2012 39
Authorization and Capture API Operation Reference
3
DoAuthorization API Operation
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.
40 August 2012 SOAP API Developer Reference
Authorization and Capture API Operation Reference
Field Description
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.
DoAuthorization Response Message
DoAuthorization API Operation
3
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoAuthorization Response Fields
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 (,).
SOAP API Developer Reference August 2012 41
Authorization and Capture API Operation Reference
3
DoAuthorization API Operation
Field Description
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.
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 th e 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 spec ifies the reason for the
reversal.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
42 August 2012 SOAP API Developer Reference
Authorization and Capture API Operation Reference
Field Description
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.
DoAuthorization API Operation
3
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.
SOAP API Developer Reference August 2012 43
Authorization and Capture API Operation Reference
3
DoReauthorization API Operation
Field Description
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.
DoReauthorization API Operation
DoReauthorization Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
44 August 2012 SOAP API Developer Reference
Authorization and Capture API Operation Reference
DoReauthorization Request 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 (,).
DoReauthorization Response Message
DoReauthorization API Operation
3
NOTE: Not all fields shown are available for use. Only use fields described in the
documentation.
DoReauthorization Response Fields
Field Description
AuthorizationID xs:string
New authorization identification number.
Character length and limits:19 single-byte characters
SOAP API Developer Reference August 2012 45
Authorization and Capture API Operation Reference
3
DoReauthorization API Operation
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 th e 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 spec ifies the reason for the
reversal.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
46 August 2012 SOAP API Developer Reference
Authorization and Capture API Operation Reference
Field Description
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.
DoReauthorization API Operation
3
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.
SOAP API Developer Reference August 2012 47
Authorization and Capture API Operation Reference
3
DoVoid API Operation
Field Description
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.
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.
48 August 2012 SOAP API Developer Reference
DoVoid Request Fields
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
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
DoVoid Response Message
Authorization and Capture API Operation Reference
DoVoid API Operation
from the original authorization, and not the reauthorization.
3
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer Reference August 2012 49
Authorization and Capture API Operation Reference
3
DoVoid API Operation
DoVoidResponse Fields
Field Description
AuthorizationID xs:string
Authorization identification number you specified in the request.
Character length and limitations: 19 single-byte characters
50 August 2012 SOAP API Developer Reference
DoDirectPayment API Operation
4
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.
SOAP API Developer Reference August 2012 51
DoDirectPayment API Operation
4
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
52 August 2012 SOAP API Developer Reference
DoDirectPayment API Operation
DoDirectPayment Request Message
4
SOAP API Developer Reference August 2012 53
DoDirectPayment API Operation
4
DoDirectPayment 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.
54 August 2012 SOAP API Developer Reference
DoDirectPayment API Operation
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
4
SOAP API Developer Reference August 2012 55
DoDirectPayment API Operation
4
DoDirectPayment Request Message
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
56 August 2012 SOAP API Developer Reference
Field Description
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
DoDirectPayment API Operation
DoDirectPayment Request Message
4
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).
SOAP API Developer Reference August 2012 57
DoDirectPayment API Operation
4
DoDirectPayment Request Message
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
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.
StartMonth and StartYear or
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
58 August 2012 SOAP API Developer Reference
Field Description
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
PayerInfoType Fields
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
DoDirectPayment API Operation
DoDirectPayment Request Message
4
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 twocharacter 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.
SOAP API Developer Reference August 2012 59
DoDirectPayment API Operation
4
DoDirectPayment Request Message
PayerNameType 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
AddressType Fields
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
60 August 2012 SOAP API Developer Reference
Field Description
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
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. This field must be set to a value
greater than 0.
DoDirectPayment API Operation
DoDirectPayment Request Message
4
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 (,).
SOAP API Developer Reference August 2012 61
DoDirectPayment API Operation
4
DoDirectPayment Request Message
Field Description
InsuranceTotal ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a nonnegative 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
62 August 2012 SOAP API Developer Reference
Field Description
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
DoDirectPayment API Operation
DoDirectPayment Request Message
4
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
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.
SetExpressCheckout or
SOAP API Developer Reference August 2012 63
DoDirectPayment API Operation
4
DoDirectPayment Request Message
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.
64 August 2012 SOAP API Developer Reference
EbayItemPaymentDetailsItemType Fields
Field Description
ItemNumber xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters
AuctionTransaction Idxs: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
AddressType (Shipping) Fields
DoDirectPayment API Operation
DoDirectPayment Request Message
4
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
SOAP API Developer Reference August 2012 65
DoDirectPayment API Operation
4
DoDirectPayment Request Message
Field Description
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
ThreeDSecureRequest Fields (U.K. Merchants Only)
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 th e
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 t his 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.
66 August 2012 SOAP API Developer Reference
DoDirectPayment Response Message
DoDirectPayment API Operation
DoDirectPayment Response Message
4
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 67
DoDirectPayment API Operation
4
DoDirectPayment Response Message
DoDirectPayment Response Fields
Field Description
TransactionID xs:string
Unique transaction ID of the payment.
NOTE: If the PaymentAction of the request was Authorization, the value of
TransactionID is your AuthorizationID for use with the Authorization 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=_rendercontent&content_ID=merchant/cc_compliance_error_codes
Related information:
AVS Response Codes
AVS Response Codes for Visa, MasterCard, Discover, and American Express
AVS Response Codes for Maestro
FMFDetailsType Fields
Field Description
AcceptFilters xs:RiskFilterListType
List of filters that recommend acceptance of the payment.
DenyFilters xs:RiskFilterListType
List of filters that recommend denial of the payment.
PendingFilters xs:RiskFilterListType
List of filters that caused the payment to become pending.
68 August 2012 SOAP API Developer Reference
Field Description
ReportsFilters xs:RiskFilterListType
List of filters that caused the payment to become flagged.
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 - Unconfirme d Add ress
7 - Country Monitor
8 - Large Order Number
9 - Billing/Ship ping A ddress Mism atch
10 - Risky ZIP Code
11 - Suspected Freight Forwarder Check
12 - Total Purchase Price Minimum
13 - IP Addr ess Velocity
14 - Risky Email Address Domain Check
15 - Risky Bank Identification Number (BIN) Check
16 - Risky IP Address Range
17 - PayPal Fraud Model
DoDirectPayment API Operation
DoDirectPayment Response Message
4
Name xs:string
Filter name.
Description xs:string
Filter description.
SOAP API Developer Reference August 2012 69
DoDirectPayment API Operation
4
DoDirectPayment Response Message
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
70 August 2012 SOAP API Developer Reference
DoNonReferencedCredit API
5
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.
SOAP API Developer Reference August 2012 71
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
72 August 2012 SOAP API Developer Reference
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 (,).
SOAP API Developer Reference August 2012 73
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
Field Description
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).
74 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
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.
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
StartMonth and StartYear or
5
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 75
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
Field Description
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
PayerNameType Fields
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
PayerInfoType Fields
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
76 August 2012 SOAP API Developer Reference
Field Description
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.
AddressType Fields
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
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
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
SOAP API Developer Reference August 2012 77
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Response Message
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 (,).
78 August 2012 SOAP API Developer Reference
ExpressCheckout API Operations
6
Express Checkout API operations include SetExpressCheckout,
GetExpressCheckoutDetails, and DoExpressCheckoutPayment.
SetExpressCheckout API Operation
The SetExpressCheckout API operation initiates an Express Checkout transaction.
SetExpressCheckout Request Message
SOAP API Developer Reference August 2012 79
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
80 August 2012 SOAP API Developer Reference
ExpressCheckout API Operations
SetExpressCheckout API Operation
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
6
SOAP API Developer Reference August 2012 81
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
82 August 2012 SOAP API Developer Reference
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
SOAP API Developer Reference August 2012 83
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
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.
84 August 2012 SOAP API Developer Reference
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.
SOAP API Developer Reference August 2012 85
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
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.
86 August 2012 SOAP API Developer Reference
Field Description
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
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
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
SOAP API Developer Reference August 2012 87
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
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
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 ship ping address on the PayPal pages.
1 – PayPal does not displ ay shippi ng address fields whatsoever.
2 – If you do not pass the shippin g address, PayPal ob tains it from the buyer’s
account profile.
Character length and limitations: 4 single-byte numeric characters
Account Profile.
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 respon se. It is one of th e followin g
values:
0 – The buyer is unable to enter a note to the merch ant.
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.
88 August 2012 SOAP API Developer Reference
Field Description
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 di splay th e shipping address.
1 – The PayPal pages should displ ay the sh ipping address.
Character length and limitations: 1 single-byte numeric character
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
SOAP API Developer Reference August 2012 89
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
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):
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
AU – Au st ralia
AT – Au stria
BE – Belg i um
BR – Brazil
CA – Canada
CH – Switzerland
CN – Chi na
DE – Germany
ES – Spain
GB – United Kingdom
FR – France
IT – It al y
NL – Netherlands
PL – Po land
PT – Po rt ugal
RU – Russia
US – Un ited States
The following 5-character codes are also supported for languages in specific
countries:
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
90 August 2012 SOAP API Developer Reference
Field Description
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
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
cpp-header-bordercolor
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-backcolor
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
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to
Authorization or Order in the
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
SOAP API Developer Reference August 2012 91
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
SolutionType ebl:SolutionTypeType
(Optional) Type of checkout flow. It is one of the following va lues:
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
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
Sole has no effect if PayPal Account Optional is turned off in your
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
Enhanced
CheckoutData
ns:BillingAgreementDetailsType
(Optional) Billing agreement details.
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.
92 August 2012 SOAP API Developer Reference
Field Description
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
FundingSourceDetailsns:FundingSourceDetailsType
(Optional) Funding source preferences.
CustomerServiceNumberxs: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.
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
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 (,).
SOAP API Developer Reference August 2012 93
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
BuyerEmailOptinEnablexs: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:
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:
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
0 – Do not enable buyer to provide email address.
1 – Enable the buyer to provide email address.
0 – Disables survey functio nality.
1 – Enables survey functionality.
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.
94 August 2012 SOAP API Developer Reference
AddressType 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
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
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
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.
SOAP API Developer Reference August 2012 95
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
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 nonnegative 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.
96 August 2012 SOAP API Developer Reference
Field Description
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.
InsuranceOptionOfferedxs: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.’
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
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
SOAP API Developer Reference August 2012 97
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
Custom xs:string
InvoiceID xs:string
NotifyURL 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
(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
(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.
98 August 2012 SOAP API Developer Reference
Field Description
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
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
ExpressCheckout API Operations
SetExpressCheckout API Operation
Authorization or Order in the
6
PaymentDetailsItemType Fields
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: Y ou 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.
SOAP API Developer Reference August 2012 99
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
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: Y ou 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 addi tional 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 addi tional 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 addi tional 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.
100 August 2012 SOAP API Developer Reference
Loading...