PayPal SOAP API Developer - 2013 Reference Manual
SOAP API Developer
Reference
Last updated: February 01, 2013
SOAP API Developer Reference
Document Number: 100002.en_US-201302
© 2013 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.ear
Contents
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 February 01, 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
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 February 01, 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . .105
GetExpressCheckoutDetails Request Message. . . . . . . . . . . . . . . . . . . . .106
GetExpressCheckoutDetails Response Message. . . . . . . . . . . . . . . . . . . .107
DoExpressCheckoutPayment API Operation . . . . . . . . . . . . . . . . . . . . . . . .126
DoExpressCheckoutPayment Request Message . . . . . . . . . . . . . . . . . . . .127
DoExpressCheckoutPayment Response Message . . . . . . . . . . . . . . . . . . .140
Chapter 7 GetBalance API Operation . . . . . . . . . . . . . . . . . 153
GetBalance Request Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
GetBalance Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
GetBalance Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
GetBalance Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Chapter 8 GetPalDetails API Operation . . . . . . . . . . . . . . . 155
GetPalDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
GetPalDetails Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
GetPalDetails Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Chapter 9 GetTransactionDetails API Operation . . . . . . . . . . . 159
GetTransactionDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . .159
GetTransactionDetails Request Fields. . . . . . . . . . . . . . . . . . . . . . . . . .159
GetTransactionDetails Response Message . . . . . . . . . . . . . . . . . . . . . . . . .160
GetTransactionDetails Response Fields. . . . . . . . . . . . . . . . . . . . . . . . .166
PaymentTransactionDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . .168
ReceiverInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
PayerInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
PayerName Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
PaymentInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
SOAP API Developer Reference February 01, 2013 5
Contents
PaymentItemInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
PaymentItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
AuctionInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
SubscriptionInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
SubscriptionTermsType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
Chapter 10 ManagePendingTransactionStatus API Operation . . . . . 181
ManagePendingTransactionStatus Request Message. . . . . . . . . . . . . . . . . . . .181
ManagePendingTransactionStatus Request Fields . . . . . . . . . . . . . . . . . . .181
ManagePendingTransactionStatus Response Message. . . . . . . . . . . . . . . . . . .182
ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .182
Chapter 11 MassPay API Operation . . . . . . . . . . . . . . . . . . 183
MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
MassPay Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
MassPay Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
Chapter 12 Recurring Payments and Reference Transactions API
Operations185
CreateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .185
CreateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .185
CreateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .201
GetRecurringPaymentsProfileDetails API Operation . . . . . . . . . . . . . . . . . . . .202
GetRecurringPaymentsProfileDetails Request Message . . . . . . . . . . . . . . . .202
GetRecurringPaymentsProfileDetails Response Message . . . . . . . . . . . . . . .203
ManageRecurringPaymentsProfileStatus API Operation . . . . . . . . . . . . . . . . . .214
ManageRecurringPaymentsProfileStatus Request Message . . . . . . . . . . . . . .215
ManageRecurringPaymentsProfileStatus Response Message . . . . . . . . . . . . .216
BillOutstandingAmount API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
BillOutstandingAmount Request Message . . . . . . . . . . . . . . . . . . . . . . .217
BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .218
UpdateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .218
UpdateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .219
UpdateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .230
SetCustomerBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . .230
SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .231
SetCustomerBillingAgreement Response Message. . . . . . . . . . . . . . . . . . .235
6 February 01, 2013 SOAP API Developer Reference
Contents
CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .236
CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .236
CreateBillingAgreement API Response Message . . . . . . . . . . . . . . . . . . . .237
GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .238
GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .238
GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .239
BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
DoReferenceTransaction API Operation. . . . . . . . . . . . . . . . . . . . . . . . . . .249
DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .249
DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .263
Chapter 13 RefundTransaction API Operation. . . . . . . . . . . . . 273
RefundTransaction Request Message. . . . . . . . . . . . . . . . . . . . . . . . . . . .273
RefundTransaction Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .274
MerchantStoreDetailsTypeFields . . . . . . . . . . . . . . . . . . . . . . . . . . . .276
RefundTransaction Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .277
RefundTransaction Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .277
RefundInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
SOAP API Developer Reference February 01, 2013 7
Contents
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .350
CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353
AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .362
ManagePendingTransactionStatus API Errors. . . . . . . . . . . . . . . . . . . . . . . .362
Appendix B Countries and Regions Supported by PayPal . . . . . . 365
Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 373
Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 377
Appendix E AVS and CVV2 Response Codes . . . . . . . . . . . . . 381
AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
AVS Response Codes for Visa, MasterCard, Discover, and American Express . . . .381
AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .382
CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
CVV2 Response Codes for Visa, MasterCard, Discover, and American Express. . . . 383
CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .383
Appendix About Previous Versions of the API. . . . . . . . . . . . 385
What’s New in Version 95.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
What’s New in Version 93.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
What’s New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
What’s New in Version 91.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
What’s New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
What’s New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
What’s New in Version 85.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
What’s New in Version 84.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .386
8 February 01, 2013 SOAP API Developer Reference
Contents
New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .386
New Field in DoReferenceTransactionResponseDetailsT ype . . . . . . . . . . . . .387
New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .387
What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
New MerchantStoreDeta ilsType in DoCapture Request. . . . . . . . . . . . . . . . .388
New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .388
New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .389
What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
New Field in PaymentDetailsType in DoDirectPayment Request . . . . . . . . . . . .389
New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .390
What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390
New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .390
New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .390
What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
Changes to BuyerDetailsType in SetExpressCheckout Request . . . . . . . . . . . .391
New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .391
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .391
What’s New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .392
New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request 392
Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .393
What’s New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .394
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .395
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .396
Appendix Revision History. . . . . . . . . . . . . . . . . . . . . . 397
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
SOAP API Developer Reference February 01, 2013 9
Contents
10 February 01, 2013 SOAP API Developer Reference
What’s New
Maintenance release. See the latest version of the PayPal Merchant API Release Notes for
more information:
notes#MerchantAPI
What’s New
https://www.x.com/developers/paypal/documentation-tools/release-
SOAP API Developer Reference February 01, 2013 11
What’s New
12 February 01, 2013 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 February 01, 2013 13
Documentation Feedback
14 February 01, 2013 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 February 01, 2013 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 February 01, 2013 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 February 01, 2013 17
PayPal SOAP API Basics
1
SOAP Service Endpoints
RequesterCredentials Authentication Elements in SOAP Header
Element Value Description
<Username> api_username Your API username, which is auto-generated by PayPal when you
apply for a digital certificate to use the PayPal SOAP API. You can
see this value on
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 signature, 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. Your API username must 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 February 01, 2013 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”>
<Username>api_username</Username>
SOAP API Developer Reference February 01, 2013 19
PayPal SOAP API Basics
1
Request Structure
<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 February 01, 2013 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 February 01, 2013 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> data
</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 February 01, 2013 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>
</Errors>
SOAP API Developer Reference February 01, 2013 23
PayPal SOAP API Basics
1
CorrelationID for Reporting Problems to PayPal
<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 February 01, 2013 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 February 01, 2013 25
PayPal SOAP API Basics
1
Core Currency Amount Data Type
26 February 01, 2013 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 February 01, 2013 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 February 01, 2013 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 February 01, 2013 29
AddressV erify API Operation
2
AddressVerify Response Message
30 February 01, 2013 SOAP API Developer Reference
Loading...