Paypal Soap Api Developer 2012 Reference Manual

2015-07-27

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

Open the PDF directly: View PDF .
Page Count: 400

Download
Open PDF In Browser	View PDF

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 in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Contents

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

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

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

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

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

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 DoReferenceTransactionResponseDetailsType

. . . . . . . . . . . . .376

New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .377
What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377

August 2012

SOAP API Developer Reference

Contents

New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
New MerchantStoreDetailsType in DoCapture Request . . . . . . . . . . . . . . . . .377
New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .378
New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .378
What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .379
New Field in PaymentDetailsType in DoDirectPayment Request . . . . . . . . . . . .379
New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .379
What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380
New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .380
New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .380
What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380
Changes to BuyerDetailsType in SetExpressCheckout Request . . . . . . . . . . . .380
New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .381
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .381
What’s New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request 382
Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .383
What’s New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .384
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .384
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .385

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

SOAP API Developer Reference

August 2012

Contents

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

What’s New in Version 93.0

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

Documentation Feedback

August 2012

SOAP API Developer Reference

PayPal SOAP API Basics

The PayPal SOAP API is based on open standards known collectively as web services, which
include the Simple Object Access Protocol (SOAP), Web Services Definition Language
(WSDL), and the XML Schema Definition language (XSD). A wide range of development
tools on a variety of platforms support web services.
Like many web services, PayPal SOAP is a combination of client-side and server-side
schemas, hardware and software servers, and core services.
PayPal SOAP High-level Diagram

In an object-oriented processing model, the interface to SOAP requests/responses is an object
in your application’s native programming language. Your third-party SOAP client generates
business-object interfaces and network stubs from PayPal-provided WSDL and XSD files that
specify the PayPal SOAP message structure, its contents, and the PayPal API service bindings.
A business application works with data in the form of object properties to send and receive
data by calling object methods. The SOAP client handles the details of building the SOAP
request, sending it to the PayPal service, and converting the response back to an object.

SOAP API Developer Reference

August 2012

PayPal SOAP API Basics
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

https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd
https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd

Production with Live PayPal Web Services API Service
PayPal Schema

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

eBL Base Components and
Component Types

http://www.paypal.com/wsdl/eBLBaseComponents.xsd
http://www.paypal.com/wsdl/CoreComponentTypes.xsd

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.

NOT E :

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.

August 2012

SOAP API Developer Reference

PayPal SOAP API Basics
Security

Security
The PayPal SOAP API service is protected to ensure that only authorized PayPal members use
it. There are four levels of security:
1. A required API username (Username field) and API password (Password field).
2. A third required authentication mechanism, which is either one of the following:
– Client-side request signing using a PayPal-issued API Certificate
– Request authentication using an API Signature included in the request (Signature
field)
3. An optional third-party authorization to make the API call on some other account’s behalf
(the optional Subject field).
4. Secure Sockets Layer (SSL) data transport.
A failure of authenticated security at any one of these levels denies access to the PayPal SOAP
API service.

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

api_username
api_password
api_signature
authorizing_account_emailaddress

SOAP API Developer Reference

August 2012

PayPal SOAP API Basics
SOAP Service Endpoints

RequesterCredentials Authentication Elements in SOAP Header
Element

Value

Description

api_username

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

api_password

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

api_signature

Your API signature, if you use one instead of an API Certificate.

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

Live Production Endpoint

Test (Sandbox) Endpoint

API Signature

https://api-3t.paypal.com/2.0/

https://api-3t.sandbox.paypal.com/2.0/

API Certificate

https://api.paypal.com/2.0/

https://api.sandbox.paypal.com/2.0/

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

August 2012

SOAP API Developer Reference

PayPal SOAP API Basics
Request Structure

Diagram of SOAP Request Envelope

Request Structure
The following annotated description of the SOAP request structure shows the elements
required by the PayPal SOAP API.
General Structure of PayPal API SOAP Request

SOAP API Developer Reference

August 2012

PayPal SOAP API Basics
Request Structure

api_username
api_password

service_version

data

Annotation of Generic SOAP Request
Lines

Comment

12, 13

The and fields are part of the PayPal SOAP API
security authentication mechanism you must construct for
every SOAP request header.

The element should include your API signature string if that is the kind of API
credential you are using.

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

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.

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

August 2012

SOAP API Developer Reference

PayPal SOAP API Basics
SOAP Message Style: doc-literal

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:

dateTime_in_UTC/GMT

Success

serviceVersion

SOAP API Developer Reference

August 2012

PayPal SOAP API Basics
Error Responses

applicationCorrelation

api_build_number

data

Annotation of Generic SOAP Response
Lines

Comment

22 and 31

The specific_api_name_Response start and end elements.

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

The 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 element with information to help you troubleshoot the cause of the error. See
“Error Responses” on page 22.

The 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.
N O TE :

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 element with other elements that can help you troubleshoot the cause
of the error.
The structure of error messages are as follows:

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.
NOT E :

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

... details not shown.

2005-02-09T21:51:26Z

Failure

Authentication/Authorization Failed

Username/Password is incorrect

10002

Error

SOAP API Developer Reference

August 2012

PayPal SOAP API Basics
CorrelationID for Reporting Problems to PayPal

debugging_info

1.000000

1.0006..
other elements in response.

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.

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

SOAP API Developer Reference

August 2012

PayPal SOAP API Basics
Core Currency Amount Data Type

August 2012

SOAP API Developer Reference

AddressVerify API Operation

The AddressVerify API operation confirms whether a postal address and postal code match
those of the specified PayPal account holder.

AddressVerify Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

AddressVerifyRequest Fields
Field

Description

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

AddressVerify API Operation
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

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

AddressVerify API Operation
AddressVerify Response Message

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.
N O TE :

The values Confirmed and Unconfirmed both indicate that the member
email address passed verification.

StreetMatch

ebl:MatchStatusCodeType
Indicates whether the street address matches address information on file at PayPal. It
is one of the following values:
 None – The request value of the Email element does not match any email address
on file at PayPal. No comparison of other request values was made.
 Matched – The request value of the Street element matches the first 3 single-byte
characters of a postal address on file for the PayPal member.
 Unmatched – The request value of the Street element does not match any
postal address on file for the PayPal member.

ZipMatch

ebl:MatchStatusCodeType
Indicates whether the zip address matches address information on file at PayPal. It is
one of the following values:
 None – The request value of the Street element was unmatched. No comparison
of the Zip element was made.
 Matched – The request value of the Zip element matches the zip code of the
postal address on file for the PayPal member.
 Unmatched – The request value of the Zip element does not match the zip code
of the postal address on file for the PayPal member.

CountryCode

ebl:CountryCodeType
Country code (ISO 3166) on file for the PayPal email address.
Character length and limitations: 2 single-byte characters

PayPalToken

xs:string
The token contains encrypted information about the member’s email address and
postal address. If you pass the value of the token in the HTML variable
address_api_token of Buy Now buttons, PayPal prevents the buyer from using
an email address or postal address other than those that PayPal verified with this API
call. The token is valid for 24 hours.
Character length and limitations: 94 single-byte characters

SOAP API Developer Reference

August 2012

AddressVerify API Operation
AddressVerify Response Message

August 2012

SOAP API Developer Reference

Authorization and Capture API
Operation Reference
The Authorization and Capture API operations describe the PayPal API operations related to
delayed payment settlement:

DoCapture API Operation
Captures an authorized payment.

DoCapture Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

Authorization and Capture API Operation Reference
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:

InvoiceID

If Complete, any remaining amount of the original authorized transaction is
automatically voided and all remaining open authorizations are voided.

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

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoCapture API Operation

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:
<1 space>
Character length and limitations: The soft descriptor can contain only the following
characters:
 Alphanumeric characters
 - (dash)
 * (asterisk)
 . (period)
 {space}

If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len() - len( + 1)
For example, assume the following conditions:
 The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
 The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
 The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow
MerchantStoreDetail
s

ns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.

MsgSubId

xs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.

SOAP API Developer Reference

August 2012

Authorization and Capture API Operation Reference
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

NOT E :

If you use version 56.0 or later of the DoCaptue API, only the authorization ID,
transaction ID, transaction type, payment date, gross amount, and payment status are
guaranteed to be returned. If you need the values of other fields and they are not
returned, you can obtain their values later by calling GetTransactionDetails or
by using the reporting mechanism. Not applicable to point of sale transactions.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoCapture API Operation

NOT E :

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

Authorization and Capture API Operation Reference
DoCapture API Operation

Field

Description

MsgSubId

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

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoCapture API Operation

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.

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

Authorization and Capture API Operation Reference
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 Completed.

None – No status
Canceled-Reversal – This means a reversal has been canceled. For example,
you won a dispute with the customer, and the funds for the transaction that was
reversed have been returned to you.
Completed – The payment has been completed, and the funds have been added
successfully to your account balance. This is the only value status for point-ofsale transactions.
Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the PendingReason
element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from your customer’s bank account.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoCapture API Operation

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.

SOAP API Developer Reference

August 2012

Authorization and Capture API Operation Reference
DoAuthorization API Operation

DoAuthorization API Operation
Authorize a payment.

DoAuthorization Request Message

NOT E :

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.

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoAuthorization API Operation

Field

Description

MsgSubId

DoAuthorization Response Message

NOT E :

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

Authorization and Capture API Operation Reference
DoAuthorization API Operation

Field

Description

MsgSubId

Field

Description

PaymentStatus

ebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
 None – No status.
 Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
 Completed – The payment has been completed, and the funds have been
added successfully to your account balance.
 Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
 Expired – The authorization period for this payment has been reached.
 Failed – The payment has failed. This happens only if the payment was made
from the buyer’s bank account.
 In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
 Partially-Refunded – The payment has been partially refunded.
 Pending – The payment is pending. See the PendingReason field for more
information.
 Refunded – You refunded the payment.
 Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element specifies the reason for the
reversal.
 Processed – A payment has been accepted.
 Voided – An authorization for this transaction has been voided.

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoAuthorization API Operation

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.
N O TE :

ProtectionEligibility

SOAP API Developer Reference

PendingReason is returned in the response only if PaymentStatus is
Pending.

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.

August 2012

Authorization and Capture API Operation Reference
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

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoReauthorization API Operation

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

NOT E :

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

Authorization and Capture API Operation Reference
DoReauthorization API Operation

AuthorizationInfo Fields

Field

Description

PaymentStatus

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoReauthorization API Operation

Field

Description

PendingReason

ProtectionEligibility

SOAP API Developer Reference

PendingReason is returned in the response only if PaymentStatus is
Pending.

August 2012

Authorization and Capture API Operation Reference
DoVoid API Operation

Field

Description

ProtectionEligibility
Type

DoVoid API Operation
Void an order or an authorization.

DoVoid Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Authorization and Capture API Operation Reference
DoVoid API Operation

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.
I MP O R T ANT :

If you are voiding a transaction that has been reauthorized, use the ID
from the original authorization, and not the reauthorization.

Character length and limitations: 19 single-byte characters
Note

xs:string
(Optional) Informational note about this void that is displayed to the buyer in email
and in their transaction history.
Character length and limitations: 255 single-byte characters

DoVoid Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

Authorization and Capture API Operation Reference
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

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation

The DoDirectPayment API Operation enables you to process a credit card payment.

DoDirectPayment Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
DoDirectPayment Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Request Message

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
DoDirectPayment Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
DoDirectPayment Request Message

NOT E :

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

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Request Message

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

DoDirectPayment API Operation
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 StartMonth and StartYear or
IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters

CreditCardNumber

xs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.

ExpMonth

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

ExpYear

xs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters

CVV2

xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.

CardOwner

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

StartMonth

xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment 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

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

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

DoDirectPayment API Operation
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

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Request Message

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

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

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.

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.

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
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.

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.

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.

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.

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

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Request Message

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

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.
I MP O R T ANT :

The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.

Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress

ns:AddressType
(Optional) Address to which the order is shipped.

PaymentDetailsItem

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

Recurring

ns:RecurringFlagType
(Optional) Flag to indicate a recurring transaction. It is one of the following values:
 Any value other than Y – This is not a recurring transaction (default).
 Y – This is a recurring transaction.
NOTE:

To pass Y in this field, you must have established a billing agreement with the
buyer specifying the amount, frequency, and duration of the recurring
payment.

This field is introduced in version 80.0 of the API.

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
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.

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.

eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Request Message

EbayItemPaymentDetailsItemType Fields
Field

Description

ItemNumber

xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters

AuctionTransaction
Id

xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters

OrderID

xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters

AddressType (Shipping) Fields
Field

Description

Name

xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters

Street1

xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address; may be required for other countries.
Character length and limitations: 20 single-byte characters

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
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 the
Enrolled value returned by cmpi_lookup.

Cavv

xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Cavv value returned by
cmpi_authenticate. Otherwise, set this field to blank.

Eci3ds

xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the EciFlag value returned
by cmpi_authenticate. Otherwise, set this field to the EciFlag value
returned by cmpi_lookup.

XID

xs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Xid value returned by
cmpi_authenticate. Otherwise, set this field to blank.

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Response Message

DoDirectPayment Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
DoDirectPayment Response Message

DoDirectPayment Response Fields
Field

Description

TransactionID

xs:string
Unique transaction ID of the payment.
N O TE :

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.

August 2012

SOAP API Developer Reference

DoDirectPayment API Operation
DoDirectPayment Response Message

Field

Description

ReportsFilters

xs:RiskFilterListType
List of filters that caused the payment to become flagged.

RiskFilterListType Fields
Field

Description

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

Name

xs:string
Filter name.

Description

xs:string
Filter description.

SOAP API Developer Reference

August 2012

DoDirectPayment API Operation
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

August 2012

SOAP API Developer Reference

DoNonReferencedCredit API
Operation
The DoNonReferencedCredit API issues a credit to a card not referenced by the original
transaction.

DoNonReferencedCredit Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message

NOT E :

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

DoNonReferencedCredit API Operation
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).

August 2012

SOAP API Developer Reference

DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message

CreditCardDetailsType Fields
Field

Description

CreditCardType

If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber

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

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

DoNonReferencedCredit API Operation
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

August 2012

SOAP API Developer Reference

DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message

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

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

DoNonReferencedCredit API Operation
DoNonReferencedCredit Response Message

DoNonReferencedCredit Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

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 (,).

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations

Express Checkout API operations include SetExpressCheckout,
GetExpressCheckoutDetails, and DoExpressCheckoutPayment.

SetExpressCheckout API Operation
The SetExpressCheckout API operation initiates an Express Checkout transaction.

SetExpressCheckout Request Message

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation
NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
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.

OrderDescription
(deprecated)

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.

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.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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

ExpressCheckout API Operations
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
Account Profile.

Character length and limitations: 1 single-byte numeric character
NoShipping

xs:string
Determines where or not PayPal displays shipping address fields on the PayPal pages.
For digital goods, this field is required, and you must set it to 1. It is one of the
following values:
 0 – PayPal displays the shipping address on the PayPal pages.
 1 – PayPal does not display shipping address fields whatsoever.
 2 – If you do not pass the shipping address, PayPal obtains it from the buyer’s
account profile.
Character length and limitations: 4 single-byte numeric characters

FlatRateShippingOpt
ions

ebl:ShippingOptionsType
Flat rate shipping options. This field is required if you are specifying the Callback
URL.

AllowNote

xs:string
(Optional) Enables the buyer to enter a note to the merchant on the PayPal page
during checkout. The note is returned in the GetExpressCheckoutDetails
response and the DoExpressCheckoutPayment response. It is one of the following
values:
 0 – The buyer is unable to enter a note to the merchant.
 1 – The buyer is able to enter a note to the merchant.
Character length and limitations: 1 single-byte numeric character
This field is available since version 53.0.

PaymentDetails

ebl:PaymentDetailsType
(Required) Information about the payment.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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 display the shipping address.
 1 – The PayPal pages should display the shipping address.

Character length and limitations: 1 single-byte numeric character

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
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):
 AU – Australia
 AT – Austria
 BE – Belgium
 BR – Brazil
 CA – Canada
 CH – Switzerland
 CN – China
 DE – Germany
 ES – Spain
 GB – United Kingdom
 FR – France
 IT – Italy
 NL – Netherlands
 PL – Poland
 PT – Portugal
 RU – Russia
 US – United States
 The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)
Character length and limitations: 2-character country code

PageStyle

xs:string
(Optional) Name of the Custom Payment Page Style for payment pages associated
with this button or link. It corresponds to the HTML variable page_style for
customizing payment pages. It is the same name as the Page Style Name you chose to
add or edit the page style in your PayPal Account profile.
Character length and limitations: 30 single-byte alphabetic characters

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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

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 Authorization or Order in the
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to Sale.

Character length and limitations: Up to 13 single-byte alphabetic characters
This field is deprecated. Use PaymentAction in PaymentDetailsType instead.
BuyerEmail

SOAP API Developer Reference

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

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

SolutionType

ebl:SolutionTypeType
(Optional) Type of checkout flow. It is one of the following values:
 Sole – Buyer does not need to create a PayPal account to check out. This is
referred to as PayPal Account Optional.
 Mark – Buyer must have a PayPal account to check out.
NOTE:

LandingPage

ebl:LandingPageType
(Optional) Type of PayPal page to display. It is one of the following values:
 Billing – Non-PayPal account
 Login – PayPal account login

ChannelType

ebl:ChannelType
(Optional) Type of channel. It is one of the following values:
 Merchant – Non-auction seller
 eBayItem – eBay auction

giropaySuccessURL

xs:string
(Optional) The URL on the merchant site to redirect to after a successful giropay
payment.
NOTE:

giropayCancelURL

BanktxnPendingURL

Use this field only if you are using giropay or bank transfer payment methods
in Germany.

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.

xs:string
(Optional) The URL on the merchant site to transfer to after a bank transfer payment.
NOTE:

You can pass Mark to selectively override the PayPal Account Optional
setting if PayPal Account Optional is turned on in your merchant account.
Passing Sole has no effect if PayPal Account Optional is turned off in your
account

Use this field only if you are using giropay or bank transfer payment methods
in Germany.

BillingAgreement
Details

ns:BillingAgreementDetailsType
(Optional) Billing agreement details.

Enhanced
CheckoutData

ed:EnhancedCheckoutDataType
(Optional) Enhanced data for different industry segments. This field is for eBay use
only.

OtherPaymentMethods

ns:OtherPaymentMethodDetailsType
(Optional) List of other payment methods with which the buyer can pay.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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

FundingSourceDetail
s

ns:FundingSourceDetailsType
(Optional) Funding source preferences.

CustomerServiceNumb
er

xs:string
(Optional) Merchant Customer Service number displayed on the PayPal pages.
Character length and limitations: 16 single-byte characters

GiftMessageEnable

xs:string
(Optional) Enables the gift message widget on the PayPal pages. It is one of the
following values:
 0 – Do not enable gift message widget.
 1 – Enable gift message widget.

GiftReceiptEnable

xs:string
(Optional) Enable gift receipt widget on the PayPal pages. It is one of the following
values:
 0 – Do not enable gift receipt widget.
 1 – Enable gift receipt widget.

GiftWrapEnable

xs:string
(Optional) Enable gift wrap widget on the PayPal pages. It is one of the following
values:
 0 – Do not enable gift wrap widget.
 1 – Enable gift wrap widget.
NOTE:

If you pass the value 1 in this field, values for the gift wrap amount and gift
wrap name are not passed, the gift wrap name is not displayed, and the gift
wrap amount displays as 0.00.

GiftWrapName

xs:string
(Optional) Label for the gift wrap option such as “Box with ribbon”.
Character length and limitations: 25 single-byte characters

GiftWrapAmount

ebl:BasicAmounttype
(Optional) Amount to be charged to the buyer for gift wrapping..
NOTE:

You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

BuyerEmailOptinEnab
le

xs:string
(Optional) Enables the buyer to provide their email address on the PayPal pages to be
notified of promotions or special events. Is one of the following values:
 0 – Do not enable buyer to provide email address.
 1 – Enable the buyer to provide email address.

SurveyQuestion

xs:string
(Optional) Text for the survey question on the PayPal pages. If the survey question is
present, at least 2 survey answer options must be present.
Character length and limitations: 50 single-byte characters

SurveyEnable

xs:string
(Optional) Enables survey functionality. It is one of the following values:
 0 – Disables survey functionality.
 1 – Enables survey functionality.

SurveyChoice

xs:string
(Optional) Possible options for the survey answers on the PayPal pages. Answers are
displayed only if a valid survey question is present.
Character length and limitations: 15 single-byte characters

TotalType

ns:TotalType
(Optional) Enables display of “Estimated Total” instead of “Total” in the cart review
area. It is one of the following values:
 Total
 EstimatedTotal
Character length and limitations: 14 single-byte characters
This field is available with API Version 64.0 or later.

NoteToBuyer

xs:string
(Optional) Displays a note to buyers in the cart review area below the total amount.
Use the note to tell buyers about items in the cart, such as your return policy or that
the total excludes shipping and handling.
Character length and limitations: 127 single-byte characters
This field is available with API Version 64.0 or later.

PaymentReason

ns:PaymentReasonType
Indicates the type of transaction. It is one of the following values:
 None – Transaction is not identified as a particular type.
 Refund – Identifies the transaction as a refund.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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

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

ExpressCheckout API Operations
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.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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

xs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. Is one of the following values:
 true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a positive
number.
 false – The Insurance option displays ‘No.’

HandlingTotal

ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE:

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
TaxTotal

ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE:

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
OrderDescription

xs:string
(Optional) Description of items the buyer is purchasing.
NOTE:

The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.

Character length and limitations: 127 single-byte alphanumeric characters

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

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
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.
I MP O R T ANT :

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:

AllowedPaymentMethod
Type

This field is only returned after a successful transaction for
DoExpressCheckout has occurred.

xs:string
(Optional) The payment method type. Specify the value InstantPaymentOnly.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

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 Authorization or Order in the
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to Sale.

Character length and limitations: Up to 13 single-byte alphabetic characters
PaymentRequestID

xs:string
A unique identifier of the specific payment request, which is required for parallel
payments.
Character length and limitations: Up to 127 single-byte characters

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.
NOT E :

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 53.0.

SOAP API Developer Reference

August 2012

ExpressCheckout API Operations
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.
NOT E :

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 (,).

100

ItemWeight

xs:integer
(Optional) Item weight corresponds to the weight of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer

ItemLength

xs:integer
(Optional) Item length corresponds to the length of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer

ItemWidth

xs:integer
(Optional) Item width corresponds to the width of the item. You can pass this data
to the shipping carrier as is without having to make an additional database query.
Character length and limitations: Any positive integer

ItemHeight

xs:integer
(Optional) Item height corresponds to the height of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query.
Character length and limitations: Any positive integer

EbayItemPayment
DetailsItem

eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.

ItemURL

xs:string
(Optional) URL for the item.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

EnhancedItemData

ed:EnhancedItemDataType
(Optional) Enhanced data for each item in the cart. For eBay use only.

ItemCategory

ns:ItemCategoryType
Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. It is one of the following values:
 Digital
 Physical

This field is available since version 65.1.
SellerDetailsType Fields
Field

Description

PayPalAccountID

xs:string
Unique identifier for the merchant. For parallel payments, this field is required and
must contain the Payer Id or the email address of the merchant.
Character length and limitations: 127 single-byte alphanumeric characters

EbayItemPaymentDetailsItemType Fields
Field

Description

ItemNumber

xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters

AuctionTransactionId

xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters

OrderID

xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters

CartID

xs:string
(Optional) The unique identifier provided by eBay for this order from the buyer.
Character length: 255 single-byte characters

SOAP API Developer Reference

August 2012

101

ExpressCheckout API Operations
SetExpressCheckout API Operation

BuyerDetailsType Fields
Field

Description

BuyerId

xs:string
(Optional) The unique identifier provided by eBay for this buyer. The value may or
may not be the same as the username. In the case of eBay, it is different.
Character length and limitations: 255 single-byte characters

BuyerUserName

xs:string
(Optional) The user name of the user at the marketplaces site.

BuyerRegistrationDa
te

xs:dateTime
(Optional) Date when the user registered with the marketplace.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z

TaxIdDetails

ebl:TaxIdDetailsType
Details about the buyer’s tax information. This field is required for Brazil and is for
Brazil use only.
This field is introduced in API version 72.0.

FundingSourceDetailsType Fields
Field

Description

AllowPushFunding

xs:string
(Optional) Indicates whether the merchant can accept push funding. It is one of the
following values:
 0 – Merchant can accept push funding.
 1 – Merchant cannot accept push funding.
N O TE :

AllowedPaymentMetho
d

102

This field overrides the setting in the merchant's PayPal account.

ns:AllowedPaymentMethodType
(Optional) The type of funding sources allowed. It is one of the following values:
 Default – Merchant supports all funding sources.
 InstantOnly – Merchant only supports instant payments.
 AnyFundingSource – All funding methods allowed, to be chosen by the buyer
irrespective of the merchant profile setting.
 InstantFundingSource – Only instant funding methods are allowed. Block
echeck, meft, elevecheck. This value overrides any merchant profile settings.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

ShippingOptionsType Fields
Field

Description

ShippingOptionIsDefau xs:boolean
lt
Default shipping optio displayed on the PayPal pages. This field is required if you
specify the Callback URL. It is one of the following values:
 true – This is the default flat-rate shipping option. PayPal displays this option
and its amount by default.
 false – This flat-rate shipping option and its amount are not displayed as the
default.
N O TE :

There must be ONE and ONLY ONE default. It is not OK to have no
default.

ShippingOptionName

xs:string
Internal name of the shipping option such as Air, Ground, Expedited, and so forth.
This field is required if you specify the Callback URL.
Character length and limitations: 50 character-string.

ShippingOptionAmount

ebl:BasicAmountType
Amount of the flat rate shipping option. This field is required if you specify the
Callback URL.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).

BillingAgreementDetailsType Fields
Field

Description

BillingType

ns:BillingCodeType
(Required) Type of billing agreement. For recurring payments, this field must be set
to RecurringPayments. In this case, you can specify up to ten billing agreements.
Other defined values are not valid.
Type of billing agreement for reference transactions. You must have permission from
PayPal to use this field. This field must be set to one of the following values:
 MerchantInitiatedBilling - PayPal creates a billing agreement for each
transaction associated with buyer. You must specify version 54.0 or higher to use
this option.
 MerchantInitiatedBillingSingleAgreement - PayPal creates a single
billing agreement for all transactions associated with buyer. Use this value unless
you need per-transaction billing agreements. You must specify version 58.0 or
higher to use this option.

SOAP API Developer Reference

August 2012

103

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

BillingAgreement
Description

xs:string
Description of goods or services associated with the billing agreement. This field is
required for each recurring payment billing agreement. PayPal recommends that the
description contain a brief summary of the billing agreement terms and conditions.
For example, buyer is billed at “9.99 per month for 2 years”.
Character length and limitations: 127 single-byte alphanumeric characters

PaymentType

ns:MerchantPullPaymentCodeType
(Optional) Type of PayPal payment you require for the billing agreement. It is one of
the following values:
 Any
 InstantOnly
NOTE:

BillingAgreement
Custom

For recurring payments, this field is ignored.

xs:string
(Optional) Custom annotation field for your own use.
NOTE:

For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric bytes
TaxIdDetailsType Type Fields

104

Field

Description

TaxIdType

xs:string
Buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
This field is introduced in API version 72.0.

TaxId

xs:string
Buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14
single-byte characters for businesses.
This field is introduced in API version 72.0.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
SetExpressCheckout API Operation

SetExpressCheckout Response Message

NOT E :

Not all fields shown are available for use. Only use fields described in the
documentation.

SetExpressCheckout Response Fields
Field

Description

Token

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

SOAP API Developer Reference

August 2012

105

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

G e t E x p r e s s C h e c k o u t D e ta i l s A P I O p e r a t i o n
The GetExpressCheckoutDetails API operation obtains information about an Express
Checkout transaction.

GetExpressCheckoutDetails Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetExpressCheckoutDetails Request Fields

106

Field

Description

Token

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

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

GetExpressCheckoutDetails Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

107

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

NOT E :

108

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

109

110

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

111

112

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

113

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetExpressCheckoutDetails Response Fields

114

Field

Description

Token

xs:string
The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters

PayerInfo

ebl:PayerInfoType
Information about the payer.

Custom

xs:string
A free-form field for your own use, as set by you in the Custom element of the
SetExpressCheckout request.
Character length and limitations: 256 single-byte alphanumeric characters

InvoiceID

xs:string
Your own invoice or tracking number, as set by you in the element of the same name
in the SetExpressCheckout request.
Character length and limitations: 127 single-byte alphanumeric characters

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

ContactPhone

xs:string
Buyer’s contact phone number.
N O TE :

PayPal returns a contact phone number only if your Merchant Account
Profile settings require that the buyer enter one.

Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers)
or +XXX XXXXXXXX (for international numbers)
PaymentDetails

ebl:PaymentDetailsType
Information about the payment.

PayPalAdjustment

cc:BasicAmountType
A discount or gift certificate offered by PayPal to the buyer. This amount is
represented by a negative amount. If the buyer has a negative PayPal account
balance, PayPal adds the negative balance to the transaction amount, which is
represented as a positive value.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).

Note

xs:string
Text entered by the buyer on the PayPal website if you set the AllowNote field to 1
in SetExpressCheckout.
Character length and limitations: 255 single-byte characters
This field is deprecated.

RedirectRequired

xs:boolean
Flag to indicate whether you need to redirect the buyer back to PayPal after
successfully completing the transaction.
N O TE :

Use this field only if you are using giropay or bank transfer payment methods
in Germany.

UserSelectedOptions

ebl:UserSelectedOptionsType
Shipping options and insurance.

CheckoutStatus

ebl:CheckoutStatusType
Status of the checkout session. If payment is completed, the transaction identification
number of the resulting transaction is returned. It is one of the following values:
 PaymentActionNotInitiated
 PaymentActionFailed
 PaymentActionInProgress
 PaymentCompleted

GiftMessage

xs:string
Gift message entered by the buyer on the PayPal checkout pages.
Character length and limitations: 150 single-byte characters

SOAP API Developer Reference

August 2012

115

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

GiftReceiptEnable

xs:string
Whether the buyer requested a gift receipt. It is one of the following values:
 true – The buyer requested a gift receipt.
 false – The buyer did not request a gift receipt.

GiftWrapName

xs:string
Returns the gift wrap name only if the buyer selects gift option on the PayPal pages.
Character length and limitations: 25 single-byte characters

GiftWrapAmount

ebl:BasicAmountType
Returns the gift wrap amount only if the buyer selects the gift option on the PayPal
pages.
N O TE :

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have two decimal places, decimal separator must be a period
(.), and the optional thousands separator must be a comma (,).
BuyerMarketingEmail

ebl:EmailAddressType
Buyer’s email address if the buyer provided it on the PayPal pages.
Character length and limitations: 127 single-byte characters

SurveyQuestion

xs:string
Survey question on the PayPal checkout pages.
Character length and limitations: 50 single-byte characters

SurveyChoiceSelecte
d

xs:string
Survey response the buyer selects on the PayPal pages.
Character length and limitations: 15 single-byte characters

PaymentRequestInfo

ns:PaymentRequestInfoType
Payment request information for each bucket in the cart.

PayerInfoType Fields

116

Field

Description

Payer

ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters

PayerID

ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations: 13 single-byte alphanumeric characters

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PayerStatus

ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
 verified
 unverified

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

ebl:PersonNameType
First and last name of buyer.

PayerCountry

ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: 2 single-byte characters

PayerBusiness

xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters

Address

xs:string
Buyer’s shipping address information.

TaxIdDetails

ns:TaxIdDetailsType
Details about the buyer’s tax information.
This field is introduced in API version 72.0.

PayerNameType Fields
Field

Description

Salutation

xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters

FirstName

ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters

MiddleName

ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters

LastName

ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters

Suffix

ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters

SOAP API Developer Reference

August 2012

117

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

AddressType Fields
Field

Description

Name

xs:string
Person’s name associated with this shipping address.
Character length and limitations: 32 single-byte characters

Street1

xs:string
First street address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city.
Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string
State or province.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters

Country

ebl:CountryCodeType
Country code.
Character length and limitations: 2 single-byte characters

Phone

xs:string
Phone number.
Character length and limitations: 20 single-byte characters

AddressStatus

ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
 none
 Confirmed
 Unconfirmed

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.

118

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

OrderTotal

ebl:BasicAmountType
The total cost of the transaction to the buyer. If shipping cost (not applicable to
digital goods) and tax charges are known, include them in this value. If not, this
value should be the current sub-total of the order. If the transaction includes one
or more one-time purchases, this field must be equal to the sum of the purchases.
Set this field to 0 if the transaction does not include a one-time purchase such as
when you set up a billing agreement for a recurring payment that is not
immediately charged. Purchase-specific fields are ignored. For digital goods, the
following must be true:
 total cost > 0
 total cost <= total cost passed in the call to SetExpressCheckout
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ItemTotal

ebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.
PayPal recommends that you pass the same value in the call to
DoExpressCheckoutPayment that you passed in the call to
SetExpressCheckout.
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ShippingTotal

ebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).

SOAP API Developer Reference

August 2012

119

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

InsuranceTotal

ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if you offer insurance options.
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
InsuranceTotal is available since version 53.0.
ShippingDiscount

ebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ShippingDiscount is available since version 53.0.
InsuranceOptionOffered

xs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal pages. Is one of the following values:
 true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a
positive number.
 false – The Insurance option displays ‘No.’

HandlingTotal

ebl:BasicAmountType
(Optional) Total handling costs for this order.
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).

120

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

TaxTotal

ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE:

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
OrderDescription

xs:string
(Optional) Description of items the buyer is purchasing.
NOTE:

The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.

Character length and limitations: 127 single-byte alphanumeric characters
Custom

xs:string
(Optional) A free-form field for your own use.
NOTE:

The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.

Character length and limitations: 256 single-byte alphanumeric characters
InvoiceID

xs:string
(Optional) Your own invoice or tracking number.
NOTE:

The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.

Character length and limitations: 256 single-byte alphanumeric characters
NotifyURL

xs:string
Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists.
I M POR T ANT :

The notify URL applies only to
DoExpressCheckoutPayment. This value is ignored when
set in SetExpressCheckout or
GetExpressCheckoutDetails.

Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress

ns:AddressType
Address the order is shipped to.

PaymentDetailsItem

ebl:PaymentDetailsItemType
Details about each individual item included in the order.

SOAP API Developer Reference

August 2012

121

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

EnhancedPaymentData

ed:EnhancedPaymentDataType
Enhanced Data section to accept channel-specific data.

NoteText

xs:string
Note to the merchant.
Character length and limitations: 255 single-byte characters

TransactionId

xs:string
Transaction identification number of the transaction that was created.
NOTE:

This field is only returned after a successful transaction for
DoExpressCheckout has occurred.

AllowedPaymentMethodTy
pe

xs:string
The payment method type. Specify the value InstantPaymentOnly.

PaymentRequestID

xs:string
A unique identifier of the specific payment request. Required when
implementing parallel payments.
Character length and limitations: Up to 127 single-byte characters

PaymentDetailsItemType Fields
Field

Description

Name

xs:string
Item name.
Character length and limitations: 127 single-byte characters

Description

xs:string
Item description.
Character length and limitations: 127 single-byte characters
This field is available since version 53.0.

Amount

ebl:BasicAmountType
Cost of item.
NOT E :

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

122

xs:string
Item number.
Character length and limitations: 127 single-byte characters

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

Quantity

xs:integer
Item quantity.
Character length and limitations: Any positive integer

Tax

ebl:BasicAmountType
Item sales tax.
NOT E :

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ItemWeight

xs:integer
Weight of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer

ItemLength

xs:integer
Length of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer

ItemWidth

xs:integer
Width of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer

ItemHeight

xs:integer
Height of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
Character length and limitations: Any positive integer

EbayItemPayment
DetailsItem

eBl:ebayItemPaymentDetailsItemType
Information relating to an auction sale on eBay.

ItemCategory

ns:ItemCategoryType
Indicates whether the item is digital or physical. For digital goods
(ItemCategory=Digital), this field is required. It is one of the following
values:
 Digital
 Physical
This field is available since version 65.1.

SOAP API Developer Reference

August 2012

123

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

EbayItemPaymentDetailsItemType Fields
Field

Description

ItemNumber

xs:string
Auction item number.
Character length: 765 single-byte characters

AuctionTransactionId

xs:string
Auction transaction identification number.
Character length: 255 single-byte characters

OrderID

xs:string
Auction order identification number.
Character length: 64 single-byte characters

CartID

xs:string
The unique identifier provided by eBay for this order from the buyer.
Character length: 255 single-byte characters
UserSelectedOptionsType Fields

Field

Description

ShippingCalculationM
ode

xs:string
Describes how the options that were presented to the buyer were determined. It is
one of the following values:
 API - Callback
 API - Flatrate

InsuranceOptionSelec
ted

xs:boolean
The option that the buyer chose for insurance. It is one of the following values:
 Yes – The buyer opted for insurance.
 No – The buyer did not opt for insurance.

ShippingOptionIsDefa
ult

xs:boolean
Indicates whether the buyer chose the default shipping option. It is one of the
following values:
 true – The buyer chose the default shipping option.
 false – The buyer did not choose the default shipping option.
Character length and limitations: true or false

ShippingOptionAmount

124

ebl:BasicAmountType
The shipping amount that the buyer chose.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

ShippingOptionName

xs:string
The name of the shipping option, such as air or ground.

SellerDetailsType Fields
Field

Description

PayPalAccountID

xs:string
Unique identifier for the merchant. For parallel payments, this field contains
either the Payer Id or the email address of the merchant.
Character length and limitations: 127 single-byte alphanumeric characters

PaymentRequestInfoType Fields
Field

Description

TransactionId

xs:string
Transaction ID for up to 10 parallel payment requests.
This field is available since version 64.0.

PaymentRequestID

xs:string
Payment request ID for up to 10 payment requests.
This field is available since version 64.0.

PaymentError

ns:ErrorType
Errors associated with the bucket of parallel payment requests.
This field is available since version 64.0.

PaymentErrorType Fields
Field

Description

ShortMessage

xs:string
Payment error short message.

LongMessage

xs:string
Payment error long message.

ErrorCode

xs:string
Payment error code.

SeverityCode

xs:string
Payment error severity code.

ErrorParameters

xs:string
Application-specific error values indicating more about the error condition.

SOAP API Developer Reference

August 2012

125

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

TaxIdDetailsType Fields
Field

Description

TaxIdType

TaxId

DoExpressCheckoutPayment API Operation
The DoExpressCheckoutPayment API operation completes an Express Checkout
transaction.
If you set up a billing agreement in your SetExpressCheckout API call, the billing
agreement is created when you call the DoExpressCheckoutPayment API operation.

DoExpressCheckoutPayment Request Message

NOT E :

126

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

127

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

DoExpressCheckoutPayment Request Fields
Field

Description

Token

xs:string
(Required) The timestamped token value that was returned in the
SetExpressCheckout response and passed in the
GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters

PaymentAction
(deprecated)

ebl:PaymentActionCodeType
(Required) How you want to obtain payment. It is one of the following values:
 Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
 Order – This payment is an order authorization subject to settlement with PayPal
Authorization and Capture.
 Sale – This is a final sale for which you are requesting payment.
NOTE:

You cannot set this value to Sale in the SetExpressCheckout request and
then change this value to Authorization in the
DoExpressCheckoutPayment request.

Character length and limitations: Up to 13 single-byte alphabetic characters
This field is deprecated. Use PaymentAction in PaymentDetailsType instead.

128

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PayerID

ebl:UserIDType
(Required) Unique PayPal buyer account identification number as returned in the
GetExpressCheckoutDetails response
Character length and limitations: 13 single-byte alphanumeric characters

PaymentDetails

ebl:PaymentDetailsType
(Required) Information about the payment.

UserSelectedOptions

ebl:UserSelectedOptionsType
(Optional) Shipping options and insurance selected by the buyer.

ReturnFMFDetails

GiftMessage

xs:string
(Optional) The gift message the buyer entered on the PayPal pages.
Character length and limitations: 150 single-byte characters

GiftReceiptEnable

xs:string
(Optional) Whether the buyer selected a gift receipt on the PayPal pages. It is one of
the following vaues:
 true – The buyer selected a gift message.
 false – The buyer did not select a gift message.

GiftWrapName

xs:string
(Optional) Return the gift wrap name only if the buyer selected the gift option on the
PayPal pages.
Character length and limitations: 25 single-byte characters

GiftWrapAmount

ebl:BasicAmounttType
(Optional) Amount only if the buyer selected the gift option on the PayPal pages.
NOTE:

You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.

SOAP API Developer Reference

ebl:EmailAddressType
(Optional) The buyer email address opted in by the buyer on the PayPal pages.
Character length and limitations: 127 single-byte characters

August 2012

129

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

SurveyQuestion

xs:string
(Optional) Survey question on the PayPal pages.
Limitations: 50 single-byte characters

SurveyChoiceSelecte
d

xs:string
(Optional) Survey response that the buyer selected on the PayPal pages.
Character length and limitations: 15 single-byte characters

ButtonSource

xs:string
(Optional) Identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters

AddressType Fields

130

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

Country

ebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

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

Description

OrderTotal

ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost (not
applicable to digital goods) and tax charges are known, include them in this
value. If not, this value should be the current sub-total of the order. If the
transaction includes one or more one-time purchases, this field must be equal
to the sum of the purchases. Set this field to 0 if the transaction does not
include a one-time purchase such as when you set up a billing agreement for a
recurring payment that is not immediately charged. When the field is set to 0,
purchase-specific fields are ignored. For digital goods, the following must be
true:
 total cost > 0
 total cost <= total cost passed in the call to SetExpressCheckout
N O TE :

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

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

131

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

ShippingTotal

ebl:BasicAmountType
(Optional) Total shipping costs for this order.
N O TE :

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
InsuranceTotal

ebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if you offer insurance options.
N O TE :

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.
N O TE :

You must set the currencyID attribute to one of the 3-character
currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a negative number. It includes no
currency symbol. It must have 2 decimal places, the decimal separator must be
a period (.), and the optional thousands separator must be a comma (,).
ShippingDiscount is available since version 53.0.
InsuranceOptionOffered

xs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. Is one of the following values:
 true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a
positive number.
 false – The Insurance option displays ‘No.’

HandlingTotal

ebl:BasicAmountType
(Optional) Total handling costs for this order.
N O TE :

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 (,).

132

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

TaxTotal

ebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
N O TE :

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.
N O TE :

The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.

Character length and limitations: 127 single-byte alphanumeric characters
Custom

xs:string
(Optional) A free-form field for your own use.
N O TE :

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.
N O TE :

The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.

Character length and limitations: 256 single-byte alphanumeric characters
ButtonSource (deprecated)

SOAP API Developer Reference

xs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
(Optional) An identification code for use by third-party applications to identify
transactions. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive.
Character length and limitations: 32 single-byte alphanumeric characters
ButtonSource is deprecated since version 63.0. Use ButtonSource in the
DoExpressCheckoutPayment request fields instead.

August 2012

133

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

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.
I MP O R TAN T :

The notify URL applies only to
DoExpressCheckoutPayment. This value is ignored when
set in SetExpressCheckout or
GetExpressCheckoutDetails.

Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddress

ns:AddressType
(Optional) Address to which the order is shipped.

PaymentDetailsItem

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

EnhancedPaymentData

ed:EnhancedPaymentDataType
(Optional) Enhanced Data section to accept channel-specific data (eBay).

NoteText

xs:string
(Optional) Note to the merchant.
Character length and limitations: 255 single-byte characters

SoftDescriptor

xs:string
A per transaction description of the payment that is passed to the buyer’s credit
card statement.
N O TE :

Ignore when PaymentAction=Order.

SellerDetails

ns:SellerDetailsType
(Optional) Details about the merchant. This information is used for emails sent
out for eBay transactions.

TransactionId

xs:string
(Optional) Transaction identification number of the transaction that was
created.
N O TE :

This field is only returned after a successful transaction for
DoExpressCheckout has occurred.

AllowedPaymentMethodType xs:string
(Optional) The payment method type. Specify the value
InstantPaymentOnly.

134

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

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.
N O TE :

You cannot set this field to Sale in SetExpressCheckout request
and then change the value to Authorization or Order in the
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set
the field to Sale.

Character length and limitations: Up to 13 single-byte alphabetic characters
PaymentRequestID

xs:string
A unique identifier of the specific payment request. Required when
implementing parallel payments.
Character length and limitations: Up to 127 single-byte characters

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.

SOAP API Developer Reference

August 2012

135

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

Amount

ebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOT E :

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 53.0.
Number

xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.

Quantity

Tax

ebl:BasicAmountType
(Optional) Item sales tax.
NOT E :

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 (,).

136

ItemWeight

ItemLength

ItemWidth

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

ItemHeight

EbayItemPayment
DetailsItem

eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.

ItemURL

xs:string
(Optional) URL for the item.

EnhancedItemData

ed:EnhancedItemDataType
(Optional) Enhanced data for each item in the cart. For eBay use only.

ItemCategory

ns:ItemCategoryType
Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. It is one of the following values:
 Digital
 Physical

This field is available since version 65.1.
EbayItemPaymentDetailsItemType Fields
Field

Description

ItemNumber

xs:string
(Optional) Auction item number.
Character length: 765 single-byte characters

AuctionTransactionId

xs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters

OrderID

xs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters

CartID

xs:string
(Optional) The unique identifier provided by eBay for this order from the buyer.
Character length: 255 single-byte characters

SOAP API Developer Reference

August 2012

137

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

UserSelectedOptions Fields
Field

Description

InsuranceOptionSelec
ted

xs:boolean
(Optional) The option that the buyer chose for insurance. It is one of the following
values:
 Yes – The buyer opted for insurance.
 No – The buyer did not opt for insurance.

ShippingOptionIsDefa
ult

xs:boolean
(Optional) Whether the buyer chose the default shipping option. It is one of the
following values:
 true – The buyer chose the default shipping option.
 false – The buyer did not choose the default shipping option.

ShippingOptionAmount

ebl:BasicAmountType
(Optional) The shipping amount that the buyer chose.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).

ShippingOptionName

xs:string
(Optional) The name of the shipping option, such as air or ground.

SellerDetailsType Fields

138

Field

Description

SellerID

xs:string
(Optional) Unique non-changing identifier for the merchant at the marketplace
site. This ID is not displayed.
Character length and limitations: 13 single-byte alphanumeric characters

SellerUserName

xs:string
(Optional) Current name of the merchant or business at the marketplace site. This
name may be shown to the buyer.

SellerRegistrationDat
e

xs:dateTime
(Optional) Date when the merchant registered with the marketplace.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

DoExpressCheckoutPayment Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

139

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

NOT E :

140

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

141

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

DoExpressCheckoutPayment Response Fields
Field

Description

Token

xs:string
The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters

PaymentInfo

ebl:PaymentInfoType
Information about the payment.

Note

xs:string
The text entered by the buyer on the PayPal website if you set the AllowNote field
to 1 in SetExpressCheckout.
This field is available since version 53.0.
Character length and limitations: 255 single-byte characters

RedirectRequired

xs:boolean
Flag to indicate whether you need to redirect the buyer back to PayPal after
successfully completing the transaction.
If set to true, you can redirect users to the following URL with the token value
appended:
https://www.paypal.com/cgi-bin/webscr?cmd=_complete-expresscheckout&token=(token)
N O TE :

142

Use this field only if you are using giropay or bank transfer payment methods
in Germany.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

SuccessPageRedirect
Requested

xs:boolean
Flag to indicate whether you would like to redirect the buyer to sign up for
PayPal after completing the transaction.
If set to true, you can redirect users to the following URL with the token value
appended::
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkoutsuccess&token=(token)

BillingAgreementID

xs:string
The ID of the billing agreement associated with the Express Checkout transaction.

FMFDetails
(deprecated)

ebl:FMFDetailsType
Fraud filter details.
This field is deprecated since version 63.0. Use FMFDetails in PaymentInfoType
instead.

ShipAmount

xs:string
Amount of shipping charged on this transaction.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator must be a period (.), and
the optional thousands separator must be a comma (,). Equivalent to nine characters
maximum for USD.

SellerId

xs:string
Unique, non-changing identifier for the merchant at the marketplace site. (Optional)
Character length and limitations: 13 single-byte alphanumeric characters.

SellerUserName

xs:string
Current name of the merchant or business at the marketplace site. This name may be
shown to the buyer.

SellerRegistrationD
ate

xs:dateTime
Date when the merchant registered with the marketplace.
Character length and limitations: Date and time are in UTC/GMT format. For
example: 2011-06-24T05:38:?48Z.

SOAP API Developer Reference

August 2012

143

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

ParentTransactionID

ns:TransactionId
Parent or related transaction identification number. This field is populated for the
following transaction types:
 Reversal
 Capture of an authorized transaction
 Reauthorization of a transaction
 Capture of an order. The value of ParentTransactionID is the original
OrderID.
 Authorization of an order. The value of ParentTransactionID is the original
OrderID.
 Capture of an order authorization
 Void of an order. The value of ParentTransactionID is the original OrderID.
Character length and limits: 19 single-byte characters maximum.

ReceiptID

ns:ReceiptID
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format.

ExpectedeCheckClear
Date

xs:dateTime
eCheck latest expected clear date.

ShippingMethod

xs:string
Shipping method selected by the user during check-out.

InstrumentCategory

xs:string
This field holds the category of the instrument only when it is promotional. Return
value 1 represents BML.

OfferCode

xs:string
Code used to identify the promotion offer.

OfferTrackingID

xs:string
Unique identification for merchant/buyer/offer combo.

PaymentInfoType Fields

When implementing parallel payments, up to 10 payment information type sets of payment
information type parameter fields can be returned, each representing one payment you are
hosting on your marketplace.

144

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

TransactionID

xs:string
Unique transaction ID of the payment.
Unique transaction ID of the payment. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive.
Store this number for tracking the order. It represents an order placeholder in the
PayPal system for a subsequent authorization by UATP.
NOTE:

If the PaymentAction of the request was Authorization or Order, this
value is your AuthorizationID for use with the Authorization & Capture
APIs.

Character length and limitations: 19 single-byte characters
TransactionType

ns:PaymentTransactionCodeType
Type of transaction. It is one of the following values:
Type of transaction. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive. It is one of the following values:
 cart
 express-checkout
Character length and limitations: 15 single-byte characters

PaymentType

ebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is
one of the following values:
 none
 echeck
 instant
Character length and limitations: 7 single-byte characters

PaymentDate

xs:dateTime
Time/date stamp of payment.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z

GrossAmount

ebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile.
The final amount charged, including any shipping and taxes from your Merchant
Profile. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

SOAP API Developer Reference

August 2012

145

146

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

FeeAmount

ebl:BasicAmountType
PayPal fee amount charged for the transaction.
PayPal fee amount charged for the transaction. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

SettleAmount

ebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
Amount deposited in your PayPal account after a currency conversion. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

TaxAmount

ebl:BasicAmountType
Tax charged on the transaction.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

ExchangeRate

xs:string
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account. You can specify
up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PaymentStatus

ebl:PaymentStatusCodeType
The status of the payment. It is one of the following values:
The status of the payment. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive. It is one of the following values:
 None – No status.
 Canceled-Reversal – A reversal has been canceled; for example, when you
win a dispute and the funds for the reversal have been returned to you.
 Completed – The payment has been completed, and the funds have been added
successfully to your account balance.
 Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
 Expired – the authorization period for this payment has been reached.
 Failed – The payment has failed. This happens only if the payment was made
from your buyer’s bank account.
 In-Progress – The transaction has not terminated, e.g. an authorization may be
awaiting completion.
 Partially-Refunded – The payment has been partially refunded.
 Pending – The payment is pending. See the PendingReason field for more
information.
 Refunded – You refunded the payment.
 Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
 Processed – A payment has been accepted.
 Voided – An authorization for this transaction has been voided.
 Completed-Funds-Held – The payment has been completed, and the funds
have been added successfully to your pending balance.
See the HoldDecision field for more information.

SOAP API Developer Reference

August 2012

147

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PendingReason

ebl:PendingStatusCodeType
Reason the payment is pending. It is one of the following values:
Reason the payment is pending. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive. It is one of the following values:
 none – No pending reason.
 address – The payment is pending because your buyer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
 authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
 echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
 intl – The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
 multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
 order – The payment is pending because it is part of an order that has been
authorized but not settled.
 paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
 unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
 verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
 other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal customer service.
NOTE:

148

PendingReason is returned in the response only if PaymentStatus is
Pending.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

ReasonCode

ebl:ReasonCodeType
Reason for a reversal if TransactionType is reversal. It is one of the following values:
Reason for a reversal if TransactionType is reversal. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive. It is one of the following
values:
 none – No reason code.
 chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
 guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
 buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
 refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
 other – A reversal has occurred on this transaction due to a reason not listed
above.

HoldDecision

xs:string
Reason that this payment is being held. It is one of the following values:
Reason that this payment is being held. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive. It is one of the following values:
 newsellerpaymenthold – This is a new merchant.
 paymenthold – A hold is placed on the merchant’s transaction for a reason not
listed.

This field is available since version 71.0 and is returned only if PaymentStatus is
Completed-Funds-Held.
This field is available since version 71.0 and is returned only if
PAYMENTINFO_n_PAYMENTSTATUS is Completed-Funds-Held.
ProtectionEligibili
ty

SOAP API Developer Reference

xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
Prior to version 64.4, the kind of seller protection in force for the transaction. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is one of
the following values:
 Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payments and Item Not Received.
 PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
 Ineligible – Merchant is not protected under the Seller Protection Policy.

August 2012

149

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

ProtectionEligibili
tyType

xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
Since version 64.4, the kind of seller protection in force for the transaction. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is one of
the following values:
 Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received
 ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received
 UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment
 Ineligible – Merchant is not protected under the Seller Protection Policy
This field is available since version 64.4.

150

StoreId

xs:string
StoreId as entered in the transaction

TerminalId

xs:string
TerminalId as entered in the transaction

EbayTransactionId

xs:string
eBay transaction identification number.
eBay transaction identification number. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive.
Character length and limitations: 255 single-byte characters

PaymentRequestID

xs:string
Unique identifier of the specific payment request. The value should match the one
you passed in the DoExpressCheckout request.
Unique identifier of the specific payment request. The value should match the one
you passed in the DoExpressCheckout request. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
Character length and limitations: Up to 127 single-byte characters

EnhancedPaymentInfo

xs:EnhancedPaymentInfoType
Enhanced payment information.

SellerDetails

xs:SellerDetailsType
Details about this merchant.

FMFDetails

xs:FMFDetailsType
List of fraud management filters.

PaymentError

ns:ErrorType
Indicates the payment status for an individual payment request in the case of parallel
payments.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

InstrumentDetails

ns:InstrumentDetailsType
Promotional instrument information.
This field is introduced in API version 71.0.

OfferDetails

ns:OfferDetailsType
Specific information for an offer.
This field is introduced in API version 71.0.

UserSelectedOptions Fields
Field

Description

ShippingCalculationM
ode

xs:string
Describes how the options that were presented to the buyer were determined. It is
one of the following values:
 API - Callback
 API - Flatrate

InsuranceOptionSelec
ted

xs:boolean
The option that the buyer chose for insurance. It is one of the following values:
 Yes – The buyer opted for insurance.
 No – The buyer did not opt for insurance.

ShippingOptionIsDefa
ult

ShippingOptionAmount

ShippingOptionName

xs:string
The name of the shipping option, such as air or ground.

PaymentErrorType Fields
Field

Description

ShortMessage

xs:string
Payment error short message.

SOAP API Developer Reference

August 2012

151

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

LongMessage

xs:string
Payment error long message.

ErrorCode

xs:string
Payment error code.

SeverityCode

xs:string
Payment error severity code.

ErrorParameters

xs:string
Application-specific error values indicating more about the error condition.

SellerDetailsType Fields
Field

Description

PayPalAccountID

SecureMerchantAccountID

xs:useridtype
Unique PayPal customer account number (of the merchant). This field is
returned in the response. It is ignored if passed in the request.

FMFDetailsType Fields

152

Field

Description

AcceptFilters

xs:RiskFilterListType
List of filters that recommend acceptance of the payment.

DenyFilters

xs:RiskFilterListType
List of filters that recommend denial of the payment.

PendingFilters

xs:RiskFilterListType
List of filters that caused the payment to become pending.

ReportsFilters

xs:RiskFilterListType
List of filters that caused the payment to become flagged.

August 2012

SOAP API Developer Reference

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

RiskFilterListType Fields
Field

Description

Name

xs:string
Filter name.

Description

xs:string
Filter description.

SOAP API Developer Reference

August 2012

153

154

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

August 2012

SOAP API Developer Reference

GetBalance API Operation

The GetBalance API Operation obtains the available balance for a PayPal account.

GetBalance Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetBalance Request Fields
Field

Description

ReturnAllCurrencies

xs:string
(Optional) Indicates whether to return all currencies. It is one of the following values:
 0 – Return only the balance for the primary currency holding.
 1 – Return the balance for each currency holding.
NOTE:

SOAP API Developer Reference

This field is availalble since version 51. Prior versions return only the
balance for the primary currency holding.

August 2012

155

GetBalance API Operation
GetBalance Response Message

GetBalance Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetBalance Response Fields

156

Field

Description

Balance

ebl:BasicAmountType
Available balance and associated currency code for the primary currency holding.

BalanceTimeStamp

xs:dateTime
Time that the balance was reported.

BalanceHoldings

ebl:BasicAmountType
Available balance and associated currency code for each currency held, including the
primary currency. The first currency is the primary currency.

August 2012

SOAP API Developer Reference

GetPalDetails API Operation

The GetPalDetails API operation obtains your Pal ID, which is the PayPal-assigned
merchant account number, and other information about your account. You need the account
number when working with dynamic versions of PayPal buttons and logos.

GetPalDetails Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

157

GetPalDetails API Operation
GetPalDetails Response Message

G e t P a l D e ta i l s R e s p o n s e M e s s a g e

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetPalDetails Response Fields

158

Field

Description

Pal

xs:string
PayPal-assigned merchant account number.

August 2012

SOAP API Developer Reference

GetPalDetails API Operation
GetPalDetails Response Message

Field

Description

Locale

xs:string
Country code representing the merchant’s default locale. It is one of the following
locales:
 AU – Australia
 AT – Austria
 BE – Belgium
 BR – Brazil
 CA – Canada
 CH – Switzerland
 CN – China
 DE – Germany
 ES – Spain
 GB – United Kingdom
 FR – France
 IT – Italy
 NL – Netherlands
 PL – Poland
 PT – Portugal
 RU – Russia
 US – United States
 The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)

Character length and limitations: 2 single-byte characters

SOAP API Developer Reference

August 2012

159

160

GetPalDetails API Operation
GetPalDetails Response Message

August 2012

SOAP API Developer Reference

GetTransactionDetails API
Operation
The GetTransactionDetails API operation obtains information about a specific
transaction.

GetTransactionDetails Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetTransactionDetails Request Fields
Field

Description

TransactionID

xs:string
(Required) Unique identifier of a transaction.
NOTE:

The details for some kinds of transactions cannot be retrieved with
GetTransactionDetails. You cannot obtain details of bank transfer
withdrawals, for example.

Character length and limitations: 17 single-byte alphanumeric characters

SOAP API Developer Reference

August 2012

161

GetTransactionDetails API Operation
GetTransactionDetails Response Message

GetTransactionDetails Response Message

162

NOT E :

All fields defined in the formal structure of GetTransactionDetailsResponse
are not necessarily returned. Data are returned in a response only if PayPal has
recorded data that corresponds to the field.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

SOAP API Developer Reference

August 2012

163

GetTransactionDetails API Operation
GetTransactionDetails Response Message

NOT E :

164

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

165

GetTransactionDetails API Operation
GetTransactionDetails Response Message

NOT E :

166

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

167

GetTransactionDetails API Operation
GetTransactionDetails Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetTransactionDetails Response Fields

168

Field

Description

PaymentTransaction
Details

Wrapper structure.

ShippingCalculation
Mode

xs:string
Describes how the options that were presented to the buyer were determined.
It is one of the following values:
 Callback – Shipping option rates are based on the buyer’s location.
 FlatRate – Shipping options are flat rates.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

InsuranceOptionSele
cted

xs:boolean
Whether the buyer selected the insurance option. It is one of the following values:
 true – The buyer selected Yes for the insurance option.
 false – The buyer did not select the insurance option. The option is No.

The value true is returned if the buyer selected the option. Otherwise false is
returned.
ShippingOptionIsDef
ault

xs:boolean
Default shipping option displayed on the PayPal pages. This field is required if you
specify the Callback URL. It is one of the following values:
 true – This is the default flat-rate shipping option. PayPal displays this option by
default.
 false – This flat-rate shipping option is not displayed as the default.
N O TE :

There must be ONE and ONLY ONE default. It is not OK to have no default.

ShippingOptionName

ShippingOptionAmoun
t

ebl:BasicAmountType
Amount of the flat rate shipping option. This field is required if you specify the
Callback URL.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

GiftMessage

xs:string
The gift message the buyer entered on the PayPal pages.
Limitations: 100 single-byte characters

GiftReceiptEnable

xs:string
Indicates whether a gift receipt widget is enabled on the PayPal pages. It is one of the
following values:
 0 – Do not enable gift receipt widget.
 1 – Enable gift receipt widget.

GiftWrapName

xs:string
Label for the gift wrap option such as “Blue box with ribbon”.
Limitations: 25 single-byte characters

SOAP API Developer Reference

August 2012

169

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

GiftWrapAmount

ebl:BasicAmounttype
Amount to be charged to the buyer for the gift wrap.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
N O TE :

You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.

BuyerMarketingEmail

ebl:EmailAddressType
The email address the buyer entered on the PayPal pages to be notified of promotions
or special events.
Limitations: 127 single-byte characters

SurveyQuestion

xs:string
Text for the survey question on the PayPal pages. If the survey question is present, at
least 2 survey answer options need to be present.
Limitations: 50 single-byte characters

SurveyChoiceSelecte
d

xs:string
Survey response the buyer selected on the PayPal pages.
Limitations: 15 single-byte characters

PaymentTransactionDetailsType Fields

170

Field

Description

ReceiverInfo

ebl:ReceiverInfoType
Information about the merchant, such as details of a single transaction, primary email
address, and unique account ID.

PayerInfo

ebl:PayerInfoType
Information about the buyer, such as the buyer’s email address, customer account
identification number, shipping address, and country of residence.

PaymentInfo

ebl:PaymentInfoType
Information about the transaction, such as the transaction ID, the type of transaction,
and whether the payment is instant or delayed.

PaymentItemInfo

ebl:PaymentItemInfoType
Information about the payment item, such as the sales tax, the invoice number, and
whether the buyer left a note to the merchant.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

ReceiverInfoType Fields
Field

Description

Business

xs:string
Details about a single transaction. This field is not application for point-of-sale
transactions.

Receiver

xs:string
Primary email address of the payment recipient (the merchant).
If you are the recipient of the payment and the payment is sent to your non-primary
email address, the value of Receiver is still your primary email address.
Character length and limitations: 127 single-byte alphanumeric characters

ReceiverID

xs:string
Unique account ID of the payment recipient (the merchant). This value is the same as
the value of the recipient's referral ID.

PayerInfoType Fields
Field

Description

Payer

ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters

PayerID

ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters

PayerStatus

ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
 verified
 unverified
Character length and limitations: 10 single-byte alphabetic characters

PayerName

ebl:PersonNameType
First and last name of buyer.

PayerCountry

ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 2-character country
codes.
Character length and limitations: 2 single-byte characters

PayerBusiness

xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters

SOAP API Developer Reference

August 2012

171

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

Address

ns:AddressType
Buyer’s shipping address information.

PayerName Fields
Field

Description

Salutation

xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters

FirstName

ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters

MiddleName

ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters

LastName

ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters

Suffix

ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters

AddressType Fields

172

Field

Description

AddressOwner

ebl:AddressOwnerTypeCode
eBay company that maintains this address. It is one of the following values:
 eBay
 PayPal

AddressStatus

ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
 none
 Confirmed
 Unconfirmed

Name

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

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

Street1

xs:string
First street address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city.
Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters

Country

ns:CountryCode
Country code.
Character length and limitations: 2 single-byte characters

CountryName

xs:string
Expanded name of country.
Character length and limitations: 64 single-byte alphanumeric characters

Phone

xs:string
Phone number.
Character length and limitations: 20 single-byte characters

PaymentInfoType Fields
Field

Description

TransactionID

xs:string
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters

SOAP API Developer Reference

August 2012

173

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

ParentTransactionID

xs:string
Parent or related transaction identification number. This value in this field is for the
following transaction types:
 Reversal – Capture of an authorized transaction.
 Reversal – Reauthorization of a transaction.
 Capture of an order – The value of ParentTransactionID is the original
OrderID.
 Authorization of an order – The value of ParentTransactionID is the original
OrderID.
 Capture of an order authorization.
 Void of an order – The value of ParentTransactionID is the original
OrderID.
Character length and limitations: 16 digits

ReceiptID

xs:string
Receipt identification number
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format

TransactionType

ns:PaymentTransactionCodeType
The type of transaction. It is one of the following values:
 cart
 express-checkout
Character length and limitations:15 single-byte characters

PaymentType

ebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
 none
 echeck
 instant
Character length and limitations: 7 single-byte characters

174

PaymentDate

xs:dateTime
Time/date stamp of payment,
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z

GrossAmount

ebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

FeeAmount

SettleAmount

TaxAmount

ExchangeRate

SOAP API Developer Reference

August 2012

175

176

GetTransactionDetails API Operation
GetTransactionDetails Response Message

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 and the funds for the reversal have been returned to you.
 Completed – The payment has been completed, and the funds have been added
successfully to your account balance.
 Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
 Expired – The authorization period for this payment has been reached.
 Failed – The payment has failed. This happens only if the payment was made
from your buyer’s bank account.
 In-Progress – The transaction has not terminated, for example, an
authorization may be awaiting completion.
 Partially-Refunded – The payment has been partially refunded.
 Pending – The payment is pending. See the PendingReason field for more
information.
 Refunded – You refunded the payment.
 Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
 Processed – A payment has been accepted.
 Voided – An authorization for this transaction has been voided.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

PendingReason

ebl:PendingStatusCodeType
The reason the payment is pending. It is one of the following values:
 none – No pending reason.
 address – The payment is pending because your buyer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
 authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
 echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
 intl – The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
 multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
 order – The payment is pending because it is part of an order that has been
authorized but not settled.
 paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
 unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
 verify –The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
 other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE:

ReasonCode

SOAP API Developer Reference

PendingReason is returned in the response only if PaymentStatus is
Pending.

ebl:ReasonCodeType
The reason for a reversal if the transaction type is reversal. It is one of the following
values:
 none – No reason code.
 chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
 guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
 buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
 refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
 other – A reversal has occurred on this transaction due to a reason not listed
above.

August 2012

177

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

ProtectionEligibili
ty

xs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
 Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payments and Item Not Received.
 PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
 Ineligible – Merchant is not protected under the Seller Protection Policy.

ProtectionEligibili
tyType

xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
 Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received.
 ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
 UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment.
 Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is introduced in API version 64.4.

StoreId

xs:string
StoreId as entered in the transaction.

TerminalId

xs:string
TerminalId as entered in the transaction.

PaymentItemInfoType Fields

178

Field

Description

InvoiceID

xs:string
Invoice number you set in the original transaction.
Character length and limitations: 256 single-byte alphanumeric characters

Custom

xs:string
Custom field you set in the original transaction.
Character length and limitations: 127 single-byte alphanumeric characters

Memo

xs:string
Memo entered by your customer in PayPal Website Payments note field.
Character length and limitations: 255 single-byte alphanumeric characters

SalesTax

xs:string
Amount of tax charged on payment.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

PaymentItem

ebl:PaymentItemType
Amount of tax charged on payment.

Subscription

ebl:SubscriptionInfoType
Subscription information.

Auction

ebl:AuctionInfoType
Subscription information.

PaymentItemType Fields
Field

Description

EbayItemTxnId

xs:string
(Optional) The eBay auction transaction ID of the item that you use to identify items
that the buyer purchased.
Character length and limitations: 255 single-byte characters

Name

xs:string
Item name set by you or entered by the customer.
NOTE:

Character length and limitations: 127 single-byte alphanumeric characters.

Number

xs:string
Item number set by you. If this was a shopping cart transaction, PayPal appends the
number of the item to the HTML item_number variable, for example,
item_number1, item_number2, and so forth.
Character length and limitations: 127 single-byte alphanumeric characters

Quantity

xs:string
Quantity set by you or entered by the buyer.
Character length and limitations: no limit

CouponID

xs:string
(Optional) Coupon identification number.

CouponAmount

xs:string
(Optional) Amount (value) of the coupon.

CouponAmountCurrenc
y

xs:string
(Optional) Currency of the coupon amount, e.g., a 3-character currency code.

LoyaltyCardDiscount
Amount

xs:string
(Optional) Amount of discount associated with this Loyalty Card incentive.
NOTE:

SOAP API Developer Reference

Use character string as shown.

August 2012

179

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

LoyaltyCardDiscount
Currency

xs:string
(Optional) Currency of the loyalty card discount, for example, a 3-character currency
code.
NOTE:

Use character string as shown.

Amount

ebl:BasicAmountType
Cost of item.

Options

ns:OptionType
name: xs:string
value: xs:string
PayPal item options for shopping cart.

AuctionInfoType Fields
Field

Description

BuyerID

xs:string
Buyer’s auction ID.

ClosingDate

xs:string
Auction’s close date.

MultiItem

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

SubscriptionInfoType Fields

180

Field

Description

SubscriptionID

xs:string
ID generated by PayPal for the subscriber.
Character length and limitations: No limit

SubscriptionDate

xs:dateTime
Subscription start date.

EffectiveDate

xs:dateTime
Date when the subscription modification is effective.

RetryTime

xs:dateTime
Date PayPal retrys a failed subscription payment.

August 2012

SOAP API Developer Reference

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

UserName

xs:string
Username that PayPal generates and gives to the subscriber to access the subscription.
Character length and limitations: 64 alphanumeric single-byte characters

Password

xs:string
Password that PayPal generates and gives to the subscriber to access the subscription.
For security, the value of the password is hashed.
Character length and limitations: 128 alphanumeric single-byte characters

Recurrences

xs:string
The number of payment installments that occur at the regular rate.
Character length and limitations: No limit

reattempt

xs:string
Indicates whether reattempts should occur upon payment failures.

recurring

xs:string
Indicates whether regular rate recurs. It is one of the following values:
 1 – Yes

SubscriptionTermsTy
pe

ns:SubscriptionTermsType
Subscription terms.

SubscriptionTermsType Fields
Field

Description

Amount

eb:BasicAmountType
Amount subscriber is to be charged in 1 payment.
Character length and limitations: No limit

Period

xs:string
Period of time that the subscriber is charged.
Character length and limitations: No limit

SOAP API Developer Reference

August 2012

181

182

GetTransactionDetails API Operation
GetTransactionDetails Response Message

August 2012

SOAP API Developer Reference

ManagePendingTransactionStatus
API Operation
The ManagePendingTransactionStatus API operation accepts or denys a pending transaction
held by Fraud Management Filters.

ManagePendingTransactionStatus Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

ManagePendingTransactionStatus Request Fields
Field

Description

TransactionID

(Required) The transaction ID of the payment transaction.

Action

(Required) The operation you want to perform on the transaction. It is one of the
following values:
 Accept – Accepts the payment
 Deny – Rejects the payment

SOAP API Developer Reference

August 2012

183

ManagePendingTransactionStatus API Operation
ManagePendingTransactionStatus Response Message

ManagePendingTransactionStatus Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

ManagePendingTransactionStatus Response Fields

184

Field

Description

TransactionID

The transaction ID of the transaction whose payment has been denied or accepted.

Status

Displays in the following message:
“The Status of the transaction after running your action (accept/deny) is
TransactionStatus.”
TransactionStatus is one of the following values:
 Pending
 Processing
 Completed
 Denied
 Reversed
 Display Only
 Partially Refunded
 Created Refunded

August 2012

SOAP API Developer Reference

MassPay API Operation

The MassPay API operation makes a payment to one or more PayPal account holders.

MassPay Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

MassPay Request Fields
Field

Description

EmailSubject

xs:string
(Optional) The subject line of the email that PayPal sends when the transaction
completes. The subject line is the same for all recipients.
Character length and limitations: 255 single-byte alphanumeric characters

SOAP API Developer Reference

August 2012

185

MassPay API Operation
MassPay Response Message

Field

Description

MassPayItem

ebl:MassPayItemType
(Required) Details of each payment.
NOTE:

ReceiverType

A single MassPayRequest can include up to 250 MassPayItems.

ebl:ReceiverInfoCodeType
(Optional) How you identify the recipients of payments in this call to MassPay. It is
one of the following values:
 EmailAddress
 UserID
 PhoneNumber

MassPay Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

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

186

August 2012

SOAP API Developer Reference

Recurring Payments and
Reference Transactions API
Operations

The PayPal API includes the following API operations supporting recurring payments and
reference transactions:

CreateRecurringPaymentsProfile API Operation
The CreateRecurringPaymentsProfile API operation creates a recurring payments
profile.
You must invoke the CreateRecurringPaymentsProfile API operation for each profile
you want to create. The API operation creates a profile and an associated billing agreement.
NOT E :

There is a one-to-one correspondence between billing agreements and recurring
payments profiles. To associate a recurring payments profile with its billing
agreement, you must ensure that the description in the recurring payments profile
matches the description of a billing agreement. For version 54.0 and later, use
SetExpressCheckout to initiate creation of a billing agreement.

CreateRecurringPaymentsProfile Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

187

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

NOT E :

188

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

189

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

NOT E :

190

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

191

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

CreateRecurringPaymentsProfile Request Fields
Field

Description

Token

xs:string
A timestamped token, the value of which was returned in the response to the first call
to SetExpressCheckout. You can also use the token returned in the
SetCustomerBillingAgreement response. Either this token or a credit card
number is required. If you include both token and credit card number, the token is
used and credit card number is ignored Call CreateRecurringPaymentsProfile
once for each billing agreement included in SetExpressCheckout request and use
the same token for each call. Each CreateRecurringPaymentsProfile request
creates a single recurring payments profile.
NOTE:

192

Tokens expire after approximately 3 hours.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

CreditCard

ns:CreditCardDetailsType
Credit card information for recurring payments using direct payments. Either a token
or a credit card number is required. If you include both token and credit card number,
the token is used and credit card number is ignored.

RecurringPayments
ProfileDetails

ns:RecurringPaymentsProfileDetails
(Required) You can include up to 10 recurring payments profiles per request. The
order of the profile details must match the order of the billing agreement details
specified in the SetExpressCheckout request.

ScheduleDetails

ns:ScheduleDetailsType
(Required) Describes the recurring payments schedule, including the regular payment
period, whether there is a trial period, and the number of payments that can fail before
a profile is suspended.

RecurringPaymentsProfileDetailsType Fields
Field

Description

SubscriberName

xs:string
(Optional) Full name of the person receiving the product or service paid for by the
recurring payment. If not present, the name in the buyer’s PayPal account is used.
Character length and limitations: 32 single-byte characters

SubscriberShipping
Address

ns:AddressType
(Optional) The subscriber’s shipping address associated with this profile, if
applicable. If not specified, the ship-to address from buyer’s PayPal account is used.
NOTE:

BillingStartdate

Shipping Address is optional, but if you include it, certain fields are required.

xs:dateTime
(Required) The date when billing for this profile begins.
NOTE:

The profile may take up to 24 hours for activation.

Character length and limitations: Must be a valid date, in UTC/GMT format
ProfileReference

SOAP API Developer Reference

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

August 2012

193

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

ScheduleDetailsType Fields
Field

Description

xs:string
(Required) Description of the recurring payment.
NOTE:

You must ensure that this field matches the corresponding billing agreement
description included in the SetExpressCheckout request.

Character length and limitations: 127 single-byte alphanumeric characters

194

ActivationDetails

ns:ActivationDetailsType
(Optional) Information about activating a profile, such as whether there is an initial
non-recurring payment amount immediately due upon profile creation and how to
override a pending profile PayPal suspends when the initial payment amount fails.

TrialPeriod

ns:BillingPeriodDetailsType
(Optional) Trial period for this schedule.

PaymentPeriod

ns:BillingPeriodDetailsType
(Required) Regular payment period for this schedule.

MaxFailedPayments

xs:int
(Optional) Number of scheduled payments that can fail before the profile is
automatically suspended. An IPN message is sent to the merchant when the specified
number of failed payments is reached.
Character length and limitations: Number string representing an integer

AutoBillOutstanding
Amount

ns:AutoBillType
(Optional) Indicates whether you would like PayPal to automatically bill the
outstanding balance amount in the next billing cycle. The outstanding balance is the
total amount of any previously failed scheduled payments that have yet to be
successfully paid. It is one of the following values:
 NoAutoBill – PayPal does not automatically bill the outstanding balance.
 AddToNextBilling – PayPal automatically bills the outstanding balance.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

BillingPeriodDetailsType Fields
Field

Description

PaymentPeriod.Billi
ngPeriod

ns:BillingPeriodType
(Required) Unit for billing during this subscription period. It is one of the following
values:
 Day
 Week
 SemiMonth
 Month
 Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:

PaymentPeriod.Billi
ngFrequency

The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

xs:int
(Required) Number of billing periods that make up one billing cycle.
The combination of billing frequency and billing period must be less than or equal to
one year. For example, if the billing cycle is Month, the maximum value for billing
frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing
frequency is 52.
NOTE:

If the billing period is SemiMonth., the billing frequency must be 1.

PaymentPeriod.Total
BillingCycles

xs:int
(Optional) Number of billing cycles for payment period.
 For the regular payment period, if no value is specified or the value is 0, the
regular payment period continues until the profile is canceled or deactivated.
 For the regular payment period, if the value is greater than 0, the regular payment
period will expire after the trial period is finished and continue at the billing
frequency for TotalBillingCycles cycles.

PaymentPeriod.Amoun
t

cc:BasicAmountType
(Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE:

All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.

SOAP API Developer Reference

August 2012

195

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

TrialPeriod.Billing
Period

ns:BillingPeriodType
Unit for billing during this subscription period; required if you specify an optional
trial period. It is one of the following values:
 Day
 Week
 SemiMonth
 Month
 Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:

TrialPeriod.Billing
Frequency

The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

xs:int
Number of billing periods that make up one billing cycle; required if you specify an
optional trial period.
The combination of billing frequency and billing period must be less than or equal to
one year. For example, if the billing cycle is Month, the maximum value for billing
frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing
frequency is 52.
NOTE:

If the billing period is SemiMonth., the billing frequency must be 1.

TrialPeriod.TotalBi
llingCycles

xs:int
(Optional) Number of billing cycles for trial payment period.

TrialPeriod.Amount

cc:BasicAmountType
Billing amount for each billing cycle during this payment period; required if you
specify an optional trial period. This amount does not include shipping and tax
amounts.
NOTE:

All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.

cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during this payment period.
NOTE:

All amounts in the request must have the same currency.

196

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

TaxAmount

cc:BasicAmountType
(Optional) Taxamount for each billing cycle during this payment period.
NOTE:

All amounts in the request must have the same currency.

Description

InitialAmount

cc:BasicAmountType
(Optional) Initial non-recurring payment amount due immediately upon profile
creation. Use an initial amount for enrolment or set-up fees.
NOTE:

All amounts included in the request must have the same currency.

SOAP API Developer Reference

ns:FailedPaymentAction
(Optional) Action you can specify when a payment fails. It is one of the following
values:
 ContinueOnFailure – By default, PayPal suspends the pending profile in the
event that the initial payment amount fails. You can override this default behavior
by setting this field to ContinueOnFailure. Then, if the initial payment amount
fails, PayPal adds the failed payment amount to the outstanding balance for this
recurring payment profile.
When you specify ContinueOnFailure, a success code is returned to you in the
CreateRecurringPaymentsProfile response and the recurring payments
profile is activated for scheduled billing immediately. You should check your IPN
messages or PayPal account for updates of the payment status.
 CancelOnFailure – If this field is not set or you set it to CancelOnFailure,
PayPal creates the recurring payment profile, but places it into a pending status
until the initial payment completes. If the initial payment clears, PayPal notifies
you by IPN that the pending profile has been activated. If the payment fails,
PayPal notifies you by IPN that the pending profile has been canceled.

August 2012

197

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

AddressType (Shipping) Fields

198

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

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

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

CreditCardDetailsType Fields
Field

Description

CreditCardType

If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumber

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

CardOwner

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

StartMonth

xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary

StartYear

xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits

SOAP API Developer Reference

August 2012

199

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

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

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

200

Field

Description

Salutation

xs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

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

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

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

201

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

PaymentDetailsItemType Fields
Field

Description

ItemCategory

ns:ItemCategoryType
Indicates whether the item is digital or physical. For digital goods, this field is
required and must be set to Digital to get the best rates. Is one of the following
values:
 Digital
 Physical
This field is introduced in version 69.0.

Name

xs:string
Item name. This field is required when ItemCategory is passed.
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.

Description

xs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.

Amount

ebl:BasicAmountType
Cost of item. This field is required when ItemCategory is passed.
NOT E :

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.

202

Number

xs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.

Quantity

xs:integer
Item quantity. This field is required when ItemCategory is passed.
Character length and limitations: Any positive integer
This field is introduced in version 69.0.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

Tax

ebl:BasicAmountType
(Optional) Item sales tax.
NOT E :

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.

CreateRecurringPaymentsProfile Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

CreateRecurringPaymentsProfile Response Fields
Field

Description

ProfileID

xs:string
A unique identifier for future reference to the details of this recurring payment.
Character length and limitations: Up to 14 single-byte alphanumeric characters.

ProfileStatus

ns:RecurringPaymentsProfileStatusType
Status of the recurring payment profile.
 ActiveProfile – The recurring payment profile has been successfully created
and activated for scheduled payments according the billing instructions from the
recurring payments profile.
 PendingProfile – The system is in the process of creating the recurring
payment profile. Please check your IPN messages for an update.

SOAP API Developer Reference

August 2012

203

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

GetRecurringPaymentsProfileDetails API Operation
The GetRecurringPaymentsProfileDetails API operation obtains information about a
recurring payments profile.

GetRecurringPaymentsProfileDetails Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetRecurringPaymentsProfileDetails Request Fields

204

Field

Description

ProfileID

xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. 19-character profile IDs are
supported for compatibility with previous versions of the PayPal API.
Character length and limitations: 14 single-byte alphanumeric characters

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

GetRecurringPaymentsProfileDetails Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

205

206

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

207

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

NOT E :

208

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetRecurringPaymentsProfileDetails Response Fields
Field

Description

ProfileID

xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.

ProfileStatus

ns:RecurringPaymentsProfileStatusType
Status of the recurring payment profile. It is one of the following values:
 Active
 Pending
 Cancelled
 Suspended
 Expired

Description

xs:string
Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters

SOAP API Developer Reference

August 2012

209

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

AutoBillOutstanding
Amount

ns:AutoBillType
Indicates whether you would like PayPal to automatically bill the outstanding balance
amount in the next billing cycle. The outstanding balance is the total amount of any
previously failed scheduled payments that have yet to be successfully paid. It is one
of the following values:
 NoAutoBill – PayPal does not automatically bill the outstanding balance
amount.
 AddToNextBilling – PayPal automatically bills the outstanding balance amount.

MaxFailedPayments

xs:int
Number of scheduled payments that can fail before the profile is automatically
suspended.
Character length and limitations: Number string representing an integer

RecurringPayments
ProfileDetails

ns:RecurringPaymentsProfileDetailsType
Buyer information for this recurring payments profile.

CurrentRecurring
PaymentsPeriod

ns:BillingPeriodDetailsType
Details of the current subscription period. This field is not returned if the profile is
canceled or expired.

RecurringPayments
Summary

ns:RecurringPaymentsSummaryDetailsType
Payment summary for this recurring payments profile.

AggregateAmount

ns:AmountType
Total amount collected thus far for scheduled payments.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

AggregateOptionalAm
ount

ns:AmountType
Total amount collected thus far for optional payments.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

FinalPaymentDueDate

ns:DateTime
Final scheduled payment due date before the profile expires.

CreditCard

ns:CreditCardDetailsType
If this is a recurring payments profile using direct payments, this field contains the
credit card information for this profile.
N O TE :

210

Only the last 4 digits of the credit card account number are returned. The
CVV2 value is not returned.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

RecurringPaymentsProfileDetailsType Fields
Field

Description

SubscriberName

xs:string
Full name of the person receiving the product or service paid for by the recurring
payment. If not present, the name in the buyer’s PayPal account is used.
Character length and limitations: 32 single-byte characters.

SubscriberShipping
Address

ns:AddressType
The subscriber’s shipping address associated with this profile, if applicable. If you do
not specify it, the ship-to address from buyer’s PayPal account is used.
NOTE:

BillingStartdate

xs:dateTime
The date when billing for this profile begins.
Must be a valid date, in UTC/GMT format.
NOTE:

ProfileReference

Shipping Address is optional, but if you include it, you are required to pass
certain fields.

The profile may take up to 24 hours for activation.

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

AddressType (Shipping) Fields
Field

Description

AddressStatus

ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
 none
 Confirmed
 Unconfirmed

Name

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

Street1

xs:string
First street address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city.
Character length and limitations: 40 single-byte characters

SOAP API Developer Reference

August 2012

211

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

StateOrProvince

xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters

Country

ebl:CountryCode
Country code.
Character length and limitations: 2 single-byte characters
BillingPeriodDetailsType Fields

Field

Description

BillingPeriod

ns:BillingPeriodType
Unit for billing during this subscription period. It is one of the following values:
 Day
 Week
 SemiMonth
 Month
 Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:

BillingFrequency

xs:int
Number of billing periods that make up one billing cycle. The combination of billing
frequency and billing period must be less than or equal to one year. For example, if
the billing cycle is Month, the maximum value for billing frequency is 12. Similarly,
if the billing cycle is Week, the maximum value for billing frequency is 52.
NOTE:

TotalBillingCycles

212

The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

If the billing period is SemiMonth., the billing frequency must be 1.

xs:int
Number of billing cycles for payment period (either the regular payment period or the
trial period).
 For the trial period, the value must be greater than 0.
 For the regular payment period, if no value is specified or the value is 0, the
regular payment period continues until the profile is canceled or deactivated.
 For the regular payment period, if the value is greater than 0, the regular payment
period will expire after the trial period is finished and continue at the billing
frequency for TotalBillingCycles cycles.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

Amount

cc:BasicAmountType
Billing amount for each billing cycle during this payment period. This amount does
not include shipping and tax amounts.
NOTE:

All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.

cc:BasicAmountType
Shipping amount for each billing cycle during this payment period.
NOTE:

All amounts in the request must have the same currency.

cc:BasicAmountType
Tax amount for each billing cycle during this payment period.
NOTE:

All amounts in the request must have the same currency.

Description

NextBillingDate

xs:dateTime
The next scheduled billing date, in YYYY-MM-DD format.

NumberCycles
Completed

xs:int
The number of billing cycles completed in the current active subscription period. A
billing cycle is considered completed when payment is collected or after retry
attempts to collect payment for the current billing cycle have failed.

NumberCycles
Remaining

xs:int
The number of billing cycles remaining in the current active subscription period.

SOAP API Developer Reference

August 2012

213

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

OutstandingBalance

cc:BasicAmountType
The current past due or outstanding balance for this profile.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.

FailedPaymentCount

xs:int
The total number of failed billing cycles for this profile.

LastPaymentDate

xs:dateTime
The date of the last successful payment received for this profile, in YYYY-MM-DD
format.

LastPaymentAmount

cc:BasicAmountType
The amount of the last successful payment received for this profile.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.

CreditCardDetailsType Fields
Field

Description

CreditCardType

ebl:CreditCardType
Type of credit card. Is one of the following values:
 Visa
 MasterCard
 Discover
 Amex
 Maestro – See note.
NOTE:

If the credit card type is Maestro, you must set the currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters

214

CreditCardNumber

xs:string
Credit card number. Only the last 4 digits of the credit card number are returned.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.

ExpMonth

xs:int
Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

ExpYear

xs:int
Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters

CardOwner

ns:PayerInfoType
Details about the owner of the credit card.

StartMonth

xs:int
Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary

StartYear

xs:int
Year that Maestro card was issued.
Character length and limitations: 4 digits

IssueNumber

xs:string
Issue number of Maestro card.
Character length and limitations: 2 numeric digits

PayerInfoType Fields
Field

Description

Payer

ns:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters

FirstName

ns:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters

LastName

ns:PersonNameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters

Address

ns:AddressType
Buyer’s billing address information.
AddressType Fields

Field

Description

AddressOwner

ebl:AddressOwnerTypeCode
eBay company that maintains this address. It is one of the following values:
 eBay
 PayPal

SOAP API Developer Reference

August 2012

215

216

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

AddressStatus

ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
 none
 Confirmed
 Unconfirmed

Name

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

Street1

xs:string
First street address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city.
Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters

Country

ns:CountryCode
Country code.
Character length and limitations: 2 single-byte characters

CountryName

xs:string
Expanded name of country.
Character length and limitations: 64 single-byte alphanumeric characters

Phone

xs:string
Phone number.
Character length and limitations: 20 single-byte characters

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API Operation

M a n a g e R e c u r r i n g P a y m e n ts P r o f i l e Sta t u s A P I O p e r a t i o n
The ManageRecurringPaymentsProfileStatus API operation cancels, suspends, or
reactivates a recurring payments profile.

ManageRecurringPaymentsProfileStatus Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

ManageRecurringPaymentsProfileStatus Request Fields
Field

Description

ProfileID

xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
Character length and limitations: 14 single-byte alphanumeric characters. 19
character profile IDs are supported for compatibility with previous versions of the
PayPal API.

Action

ns:StatusChangeActionType
(Required) The action to be performed to the recurring payments profile. Must be one
of the following:
 Cancel – Only profiles in Active or Suspended state can be canceled.
 Suspend – Only profiles in Active state can be suspended.
 Reactivate – Only profiles in a suspended state can be reactivated.

Note

xs:string
(Optional) The reason for the change in status. For profiles created using Express
Checkout, this message is included in the email notification to the buyer when the
status of the profile is successfully changed, and can also be seen by both you and the
buyer on the Status History page of the PayPal account.

SOAP API Developer Reference

August 2012

217

Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API Operation

ManageRecurringPaymentsProfileStatus Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

ManageRecurringPaymentsProfileStatus Response Fields

218

Field

Description

ProfileID

xs:string
Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. For each action, an error is
returned if the recurring payments profile has a status that is not compatible with the
action. Errors are returned in the following cases:
 Cancel – Profile status is not Active or Suspended.
 Suspend – Profile status is not Active.
 Reactivate – Profile status is not Suspended.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API Operation

B i l l O u ts ta n d i n g A m o u n t A P I O p e r a t i o n
The BillOutstandingAmount API operation bills the buyer for the outstanding balance
associated with a recurring payments profile.

BillOutstandingAmount Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

BillOutstandingAmount Request Fields
Field

Description

ProfileID

xs:string
(Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
NOTE:

The profile must have a status of either Active or Suspended.

Character length and limitations: 14 single-byte alphanumeric characters. 19
character profile IDs are supported for compatibility with previous versions of the
PayPal API.

SOAP API Developer Reference

August 2012

219

Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API Operation

Field

Description

Amount

cc:BasicAmountType
(Optional) The amount to bill. The amount must be less than or equal to the current
outstanding balance of the profile. If no value is specified, PayPal attempts to bill the
entire outstanding balance amount.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

Note

xs:string
(Optional) The reason for the non-scheduled payment. For profiles created using
Express Checkout, this message is included in the email notification to the buyer for
the non-scheduled payment transaction, and can also be seen by both you and the
buyer on the Status History page of the PayPal account.

BillOutstandingAmount Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

BillOutstandingAmount Response Fields

220

Field

Description

ProfileID

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

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

UpdateRecurringPaymentsProfile API Operation
The UpdateRecurringPaymentsProfile API operation updates a recurring payments profile.

UpdateRecurringPaymentsProfile Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

221

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

NOT E :

222

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

223

224

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

UpdateRecurringPaymentsProfile Request Fields
Field

Description

ProfileID

Note

xs:string
(Optional) The reason for the update to the recurring payments profile. This message
is included in the email notification to the buyer for the recurring payments profile
update. This note can also be seen by both you and the buyer on the Status History
page of the PayPal account.

Description

xs:string
(Optional) Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters

SubscriberName

SubscriberShipping
Address

ns:AddressType
(Optional) The subscriber’s shipping address associated with this profile, if
applicable. If you do not specify it, the ship-to address from buyer’s PayPal account is
used.
NOTE:

Shipping Address is optional, but if you update any of the address fields, you
must enter all of them. For example, if you want to update the subsriber’s
street address, you must specify all of the fields listed in
ShipTo: AddressType, not just the field for the street address.

ProfileReference

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

AdditionalBilling
Cycles

xs:int
(Optional) The number of additional billing cycles to add to this profile.

SOAP API Developer Reference

August 2012

225

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

Amount

cc:BasicAmountType
(Optional) Billing amount for each cycle in the subscription period, not including
shipping and tax amounts.
NOTE:

For recurring payments with Express Checkout, the payment amount can be
increased by no more than 20% every 180 days (starting when the profile is
created).

cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during the regular payment period.
NOTE:

All amounts in the request must have the same currency.

cc:BasicAmountType
(Optional) Tax amount for each billing cycle during the regular payment period.
NOTE:

All amounts in the request must have the same currency.

226

OutstandingBalance

cc:BasicAmountType
(Optional) The current past due or outstanding amount for this profile. You can only
decrease the outstanding amount. It cannot be increased.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

AutoBillOutstanding
Amount

ns:AutoBillType
(Optional) This field indicates whether you would like PayPal to automatically bill
the outstanding balance amount in the next billing cycle. It is one of the following
values:
 NoAutoBill – PayPal does not automatically bill the outstanding balance.
 AddToNextBilling – PayPal automatically bills the outstanding balance

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

MaxFailedPayments

xs:int
(Optional) The number of failed payments allowed before the profile is automatically
suspended. The specified value cannot be less than the current number of failed
payments for this profile.
Character length and limitations: Number string representing an integer

BillingStartdate

xs:dateTime
(Optional) The date when billing for this profile begins.
NOTE:

The profile may take up to 24 hours for activation.

Character length and limitations: Must be a valid date, in UTC/GMT format
TrialPeriod

ns:BillingPeriodDetailsType
(Optional) The trial period for this schedule.

PaymentPeriod

ns:BillingPeriodDetailsType
(Optional) The regular payment period for this schedule.

CreditCard

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

Only enter credit card details for recurring payments with direct payments.

AddressType (Shipping) Fields
Field

Description

Name

xs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters

Street1

xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters

SOAP API Developer Reference

August 2012

227

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

StateOrProvince

xs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters

PostalCode

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

Field

Description

PaymentPeriod.Total
BillingCycles

PaymentPeriod.Amoun
t

cc:BasicAmountType
(Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE:

All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.

228

xs:int
(Optional) Number of billing cycles for trial payment period.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

TrialPeriod.Amount

cc:BasicAmountType
Billing amount for each billing cycle during this payment period; required if you
specify an optional trial period. This amount does not include shipping and tax
amounts.
NOTE:

All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.

cc:BasicAmountType
(Optional) Shipping amount for each billing cycle during this payment period.
NOTE:

All amounts in the request must have the same currency.

cc:BasicAmountType
(Optional) Tax amount for each billing cycle during this payment period.
NOTE:

All amounts in the request must have the same currency.

Description

CreditCardType

If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either StartMonth and StartYear or
IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters

SOAP API Developer Reference

August 2012

229

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

CreditCardNumber

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

CardOwner

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

StartMonth

xs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary

StartYear

xs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits

IssueNumber

xs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum

PayerInfoType Fields

230

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

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

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

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

231

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

UpdateRecurringPaymentsProfile Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

UpdateRecurringPaymentsProfile Response Fields

232

Field

Description

ProfileID

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

SetCustomerBillingAgreement API Operation
The SetCustomerBillingAgreement API operation initiates the creation of a billing
agreement.
NOT E :

If you are using Express Checkout with version 54.0 or later of the API, do not use the
SetCustomerBillingAgreement API operation to set up a billing agreement. Use
the SetExpressCheckout API operation instead.

SetCustomerBillingAgreement Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SetCustomerBillingAgreement Request Fields
Field

Description

BillingAgreement
Details

ns:BillingAgreementDetailsType
(Required) Details of the billing agreement such as the billing type, billing agreement
description, and payment type.

SOAP API Developer Reference

August 2012

233

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

ReturnURL

xs:string
(Required) URL to which the buyer’s browser is returned after choosing to pay with
PayPal.
NOTE:

PayPal recommends that the value be the final review page on which the
buyer confirms the billing agreement.

Character length and limitations: no limit
CancelURL

xs:string
(Required) URL to which the customer is returned if he does not approve the use of
PayPal to pay you.
NOTE:

PayPal recommends that the value be the original page on which the
customer chose to pay with PayPal or establish a billing agreement.

Character length and limitations: no limit

234

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

LocaleCode

xs:string
(Optional) Locale of pages displayed by PayPal during checkout. PayPal supports the
following 2-character country codes:
 AU – Australia
 AT – Austria
 BE – Belgium
 BR – Brazil
 CA – Canada
 CH – Switzerland
 CN – China
 DE – Germany
 ES – Spain
 GB – United Kingdom
 FR – France
 IT – Italy
 NL – Netherlands
 PL – Poland
 PT – Portugal
 RU – Russia
 US – United States
 The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)

Any other value defaults to US.
Character length and limitations: 2 single-byte characters
PageStyle

SOAP API Developer Reference

xs:string
(Optional) Sets the Custom Payment Page Style for payment pages associated with
this button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name you chose
when adding or editing the page style in your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters

August 2012

235

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

cpp-header-image

xs:string
(Optional) A URL for the image you want to appear at the top left of the payment
page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored on a secure (https) server.
Character length and limitations: 127 single-byte alphanumeric characters

cpp-header-border

xs:string
(Optional) Sets the border color around the header of the payment page. The border is
a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels
high.
Character length and limitations: 6-character HTML hexadecimal color code in
ASCII

cpp-header-backcolor

xs:string
(Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII

cpp-payflow-color

xs:string
(Optional) Sets the background color for the payment page.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII

BuyerEmail

ns:EmailAddressType
(Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion of the PayPal login page.
Character length and limit: 127 single-byte alphanumeric characters

BillingAgreementDetails Fields

236

Field

Description

BillingType

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

BillingAgreement
Description

PaymentType

ns:MerchantPullPaymentCodeType
(Optional) Type of PayPal payment you require for the billing agreement. It is one of
the following values:
 Any
 InstantOnly
NOTE:

BillingAgreement
Custom

For recurring payments, this field is ignored.

xs:string
(Optional) Custom annotation field for your own use.
NOTE:

For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric bytes

SetCustomerBillingAgreement Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

237

Recurring Payments and Reference Transactions API Operations
CreateBillingAgreement API Operation

SetCustomerBillingAgreement Response Fields
Field

Description

Token

xs:string
A unique time-stamped token, which uniquely identifies this transaction in
subsequent API calls.
N O TE :

The token expires after 3 hours.

Character length and limitations: 20 single-byte characters

CreateBillingAgreement API Operation
The CreateBillingAgreement API operation creates a billing agreement with a PayPal
account holder. CreateBillingAgreement is only valid for reference transactions.

CreateBillingAgreement Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

CreateBillingAgreement Request Fields
Field

Description

Token

xs:string
(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE:

The token expires after 3 hours.

Character length and limitations: 20 single-byte characters

238

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
CreateBillingAgreement API Operation

CreateBillingAgreement API Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

CreateBillingAgreement Response Fields
Field

Description

BillingAgreementID

xs:string
Identification number of the billing agreement.

SOAP API Developer Reference

August 2012

239

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

G e t B i l l i n g A g r e e m e n t C u s t o m e r D e ta i l s A P I O p e r a t i o n
The GetBillingAgreementCustomerDetails API operation obtains information about a billing
agreement’s PayPal account holder.

GetBillingAgreementCustomerDetails Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

GetBillingAgreementCustomerDetails Request Fields
Field

Description

Token

xs:string
(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE:

The token expires after 3 hours.

Character length and limitations: 20 single-byte characters

240

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

GetBillingAgreementCustomerDetails Response Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Only use fields described in the
documentation.

SOAP API Developer Reference

August 2012

241

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

NOT E :

Not all fields shown are available for use. Only use fields described in the
documentation.

GetBillingAgreementCustomerDetails Response Fields

242

Field

Description

PayerInfo

ns:PayerInfoType
Information about the buyer such as the buyer’s name, email address, and country of
residence.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

PayerInfoType Fields
Field

Description

Payer

ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters

PayerID

ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters

PayerStatus

ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
 verified
 unverified
Character length and limitations: 10 single-byte alphabetic characters

PayerName

ebl:PersonNameType
First and last name of buyer.

PayerCountry

ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 2-character country
codes.
Character length and limitations: 2 single-byte characters

PayerBusiness

xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters

Address

ns:AddressType
Buyer’s shipping address information.
PayerNameType Fields

Field

Description

Salutation

xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters

FirstName

ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters

MiddleName

ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters

SOAP API Developer Reference

August 2012

243

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

Field

Description

LastName

ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters

Suffix

ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters
AddressType Fields

244

Field

Description

AddressStatus

ebl:AddressStatusTypeCode
Status of street address on file with PayPal. It is one of the following values:
 none
 Confirmed
 Unconfirmed

Name

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

Street1

xs:string
First street address.
Character length and limitations: 100 single-byte characters

Street2

xs:string
Second street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of city.
Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string
State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters

Country

ebl:CountryCode
Country code.
Character length and limitations: 2 single-byte characters

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

BAUpdate API Operation
The BAUpdate API operation updates or deletes a billing agreement.

BAUpdate Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

BAUpdate Request Fields
Field

Description

ReferenceID

xs:string
(Required) An ID, such as a billing agreement ID or a reference transaction ID that is
associated with a billing agreement.

BillingAgreementSta
tus

ebl:MerchantPullStatusCodeType
(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
NOTE:

SOAP API Developer Reference

If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.

August 2012

245

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

Field

Description

BillingAgreement
Description

xs:string
(Optional) Description of goods or services associated with the billing agreement.
This field is required for each recurring payment billing agreement. PayPal
recommends that the description contain a brief summary of the billing agreement
terms and conditions. For example, buyer will be billed at “9.99 per month for 2
years”.
Character length and limitations: 127 single-byte alphanumeric characters

BillingAgreement
Custom

xs:string
(Optional) Custom annotation field for your own use.
NOTE:

For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric characters

BAUpdate Response Message

246

NOT E :

Not all fields show are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

247

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

BAUpdate Response Fields

248

Field

Description

BillingType

ns:BillingCodeType
Type of billing agreement.

BillingAgreement
Description

xs:string
Description of goods or services associated with the billing agreement. This field is
required for each recurring payment billing agreement.
Character length and limitations: 127 single-byte alphanumeric characters

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

Field

Description

BillingAgreement
Custom

xs:string
Custom annotation field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters

BillingAgreementSta
tus

ebl:MerchantPullStatusCodeType
(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
N O TE :

BillingAgreementMax

If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.

cc:BasicAmountType
Maximum amount for this billing agreement.
N O TE :

This field only has a value if the buyer signed up for PayPal using
Preapproved Payments; it is included for backwards compatibility with
legacy systems.

ns:PayerInfoType
Information about the buyer such as the buyer’s name, email address, and country of
residence.

PayerInfoType Fields
Field

Description

Payer

ebl:EmailAddressType
Email address of buyer.
Character length and limitations: 127 single-byte characters

PayerID

ebl:UserIDType
Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters

PayerStatus

ebl:PayPalUserStatusCodeType
Status of buyer. It is one of the following values:
 verified
 unverified
Character length and limitations: 10 single-byte alphabetic characters

PayerName

SOAP API Developer Reference

ebl:PersonNameType
First and last name of buyer.

August 2012

249

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

Field

Description

PayerCountry

ebl:CountryCodeType
Buyer’s country of residence in the form of ISO standard 3166 2-character country
codes.
Character length and limitations: 2 single-byte characters

PayerBusiness

xs:string
Buyer’s business name.
Character length and limitations: 127 single-byte characters

Address

ns:AddressType
Buyer’s shipping address information.
PayerNameType Fields

Field

Description

Salutation

xs:string
Buyer’s salutation.
Character length and limitations: 20 single-byte characters

FirstName

ebl:PersonNameType
Buyer’s first name.
Character length and limitations: 25 single-byte characters

MiddleName

ebl:NameUser
Buyer’s middle name.
Character length and limitations: 25 single-byte characters

LastName

ebl:NameType
Buyer’s last name.
Character length and limitations: 25 single-byte characters

Suffix

ebl:SuffixType
Buyer’s suffix.
Character length and limitations: 12 single-byte characters
AddressType Fields

250

Field

Description

Name

xs:string
Billing name associated with this billing address.
Character length and limitations: 32 single-byte characters

Street1

xs:string
First billing street address.
Character length and limitations: 100 single-byte characters

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

Street2

xs:string
Second billing street address.
Character length and limitations: 100 single-byte characters

CityName

xs:string
Name of billing city.
Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string
Billing state or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters

PostalCode

xs:string
U.S. billing ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters

Country

ebl:CountryCode
Billing country code.
Character length and limitations: 2 single-byte characters

DoReferenceTransaction API Operation
The DoReferenceTransaction API operation processes a payment from a buyer’s account,
which is identified by a previous transaction.

DoReferenceTransaction Request Message

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

SOAP API Developer Reference

August 2012

251

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

NOT E :

252

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

SOAP API Developer Reference

August 2012

253

254

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

NOT E :

Not all fields shown are available for use. Use only the fields described in the
documentation.

DoReferenceTransaction Request Fields
Field

Description

ReferenceID

xs:string
(Required) A transaction ID from a previous purchase, such as a credit card charge
using the DoDirectPayment API, or a billing agreement ID.

PaymentAction

xs:string
(Optional) How you want to obtain payment. It is one of the following values:
 Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
 Sale – This is a final sale for which you are requesting payment.

PaymentDetails

ebl:PaymentDetailsType
(Required) Information about the payment.

SOAP API Developer Reference

August 2012

255

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

IPAddress

xs:string
(Optional) IP address of the buyer’s browser.
NOTE:

PayPal records this IP addresses as a means to detect possible fraud.

Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
ReqConfirmShipping

Whether you require that the buyer’s shipping address on file with PayPal be a
confirmed address. You must have permission from PayPal to not require a confirmed
address. It is one of the following values:
 0 – You do not require that the buyer’s shipping address be a confirmed address.
 1 – You require that the buyer’s shipping address be a confirmed address.
NOTE:

Setting this field overrides the setting you have specified in your Merchant
Account Profile.

Character length and limitations: 1 single-byte numeric character
MerchantSessionId

xs:string
(Optional) Your buyer session identification token.
NOTE:

PayPal records this optional session identification token as an additional
means to detect possible fraud.

Character length and limitations: 64 single-byte numeric characters
ReturnFMFDetails

256

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

SoftDescriptor

xs:string
(Optional) Per transaction description of the payment that is passed to the consumer’s
credit card statement.
If the API request provides a value for the soft descriptor field, the full descriptor
displayed on the buyer’s statement has the following format:
<1 space>
The soft descriptor can contain only the following characters:
 Alphanumeric characters
 - (dash)
 * (asterisk)
 . (period)
 {space}

If you use any other characters (such as “,”), PayPal returns an error code. The soft
descriptor does not include the phone number, which can be toggled between the
merchant’s customer service number and PayPal’s customer service number. The
maximum length of the total soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters shown in the data format. Thus, the maximum length of
the soft descriptor passed in the API request is:
22 - len() - len( + 1)
For example, assume the following conditions:
 The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
 The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
 The soft descriptor is passed in as JanesFlowerGifts LLC
The resulting descriptor string on the credit card would be:
PAYPAL *EBAY JanesFlow
PaymentReason

MsgSubId

SOAP API Developer Reference

August 2012

257

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

AddressType (Shipping) Fields

258

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

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

August 2012

SOAP API Developer Reference

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

PaymentDetailsType Fields
Field

Description

OrderTotal

ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. Set this field to 0 if the transaction
does not include a one-time purchase such as when you set up a billing agreement for
a recurring payment that is not immediately charged. When the field is set to 0,
purchase-specific fields are ignored.
NOTE:

You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.

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.

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.

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.

SOAP API Developer Reference

August 2012

259